SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! The command registry's parameter notation, read into the rows of a parameter table.
//!
//! The engine writes a command's parameters as one line: `name: type (what it does)`,
//! separated by `;`, with `,` between a name and the next. A `?` marks a parameter
//! optional, a `|` between names offers alternative names for one parameter, and a `|`
//! after the colon lists the types a parameter accepts. Text after `→` is the reply the
//! command gives, not a parameter.
/// One parameter of a command, as the registry's notation describes it.
pub struct Param {
/// The name the command takes the parameter under.
pub name: String,
/// The type the registry writes after the colon, empty when it writes none.
pub kind: String,
/// Whether the command needs the parameter.
pub required: bool,
/// What the registry writes in parentheses, empty when it writes none.
pub description: String,
}
/// Words that join two parameters in one clause, as in `thin?: true (...) with curves?: [...]`.
const CONNECTORS: &[&str] = &["and", "or", "with", "then", "also", "plus"];
/// The parameters of a command, in the order the registry lists them.
pub fn parse(notation: &str) -> Vec<Param> {
let mut params = Vec::new();
for clause in split_top(cut_at_reply(notation), ';') {
let entries = clause_entries(clause);
let shared = shared_kind(&entries);
for entry in entries {
let kind = if entry.kind.is_empty() { shared.clone().unwrap_or_default() } else { entry.kind.clone() };
for (name, optional) in entry.names {
params.push(Param { name: name.to_string(), kind: kind.clone(), required: !optional, description: entry.description.clone() });
}
}
}
params
}
/// One clause of the notation: the names it lists, the type they share and what it says.
struct Entry<'a> {
/// The names the parameter goes by, and whether the command needs it.
names: Vec<(&'a str, bool)>,
/// The type written after the colon, empty when the clause writes none.
kind: String,
/// What the clause writes in parentheses.
description: String,
}
/// The type a clause gives to the bare names it lists with it, as in `length, width, height: expr`.
fn shared_kind(entries: &[Entry<'_>]) -> Option<String> {
let (last, rest) = entries.split_last()?;
if last.kind.is_empty() || rest.iter().any(|entry| !entry.kind.is_empty() || !entry.description.is_empty()) {
return None;
}
Some(last.kind.clone())
}
/// The entries of one clause, or none when the clause is prose rather than parameters.
fn clause_entries(clause: &str) -> Vec<Entry<'_>> {
let mut entries = Vec::new();
for piece in split_top(clause, ',') {
let mut parsed = piece_entries(piece);
if parsed.is_empty() {
// A clause that reads as prose names no parameter.
return Vec::new();
}
entries.append(&mut parsed);
}
entries
}
/// The entries of one comma-separated piece of a clause.
fn piece_entries(piece: &str) -> Vec<Entry<'_>> {
let mut entries = Vec::new();
let mut i = 0;
while i < piece.len() {
i = skip_ws(piece, i);
if i >= piece.len() {
break;
}
if piece[i..].starts_with('|') {
i += 1;
continue;
}
if let Some(next) = connector_before(piece, i) {
i = next;
continue;
}
let Some((name, optional, after)) = read_name(piece, i) else { break };
let mut names = vec![(name, optional)];
let mut cursor = after;
// A pipe between names offers alternative names for one parameter.
loop {
let k = skip_ws(piece, cursor);
if !piece[k..].starts_with('|') {
break;
}
let k = skip_ws(piece, k + 1);
match read_name(piece, k) {
Some((other, other_optional, other_after)) => {
names.push((other, other_optional));
cursor = other_after;
}
None => break,
}
}
// The group is optional when any of its names is.
let optional = names.iter().any(|(_, optional)| *optional);
let names: Vec<(&str, bool)> = names.into_iter().map(|(name, _)| (name, optional)).collect();
let mut kind = String::new();
let mut description = String::new();
let k = skip_ws(piece, cursor);
if piece[k..].starts_with(':') {
let (types, descriptions, after) = read_type(piece, k + 1);
kind = types;
description = descriptions.join("; ");
cursor = after;
} else if piece[k..].starts_with('(') {
let Some((content, after)) = read_group(piece, k) else { break };
description = content.trim().to_string();
cursor = after;
} else {
// A bare name: the piece must end here, or it is prose.
let end = skip_ws(piece, cursor);
if end < piece.len() && !piece[end..].starts_with('|') {
break;
}
}
entries.push(Entry { names, kind, description });
i = cursor;
}
entries
}
/// The index of the parameter a connector word introduces, when there is one.
fn connector_before(text: &str, i: usize) -> Option<usize> {
let (word, after) = read_ident(text, i)?;
if !CONNECTORS.contains(&word) {
return None;
}
let next = skip_ws(text, after);
spec_head(text, next).then_some(next)
}
/// The type a clause writes after its colon, the descriptions it writes with it, and the
/// index after them. The type keeps the notation's own spelling.
fn read_type(text: &str, start: usize) -> (String, Vec<String>, usize) {
let mut kind = String::new();
let mut descriptions = Vec::new();
let mut segment = start;
let mut i = start;
loop {
let (stop, at) = scan_type(text, i);
kind.push_str(&text[segment..at]);
match stop {
Stop::Description => {
let Some((content, after)) = read_group(text, at) else {
return (kind.trim().to_string(), descriptions, at);
};
descriptions.push(content.trim().to_string());
// The description ends the type, unless another alternative follows it.
let next = skip_ws(text, after);
if next < text.len() && text[next..].starts_with('|') {
let following = skip_ws(text, next + 1);
if spec_head(text, following) {
return (kind.trim().to_string(), descriptions, next);
}
kind = kind.trim_end().to_string();
segment = next;
i = next;
continue;
}
return (kind.trim().to_string(), descriptions, after);
}
Stop::Parameter | Stop::End => return (kind.trim().to_string(), descriptions, at),
}
}
}
/// Where the type text of a clause ends.
enum Stop {
/// A parenthesis opens the description of the parameter.
Description,
/// A pipe introduces the next parameter.
Parameter,
/// The clause ends.
End,
}
/// The next stop in the type text, and where it is.
fn scan_type(text: &str, from: usize) -> (Stop, usize) {
let mut i = from;
let mut depth = 0usize;
while i < text.len() {
let c = char_at(text, i);
match c {
'"' => {
i = skip_quoted(text, i);
continue;
}
'(' | ')' if depth == 0 => return (Stop::Description, i),
'.' if depth == 0 && ends_sentence(text, i) => return (Stop::End, i),
'|' if depth == 0 => {
let following = skip_ws(text, i + 1);
if spec_head(text, following) {
return (Stop::Parameter, i);
}
}
'(' | '[' | '{' => depth += 1,
')' | ']' | '}' => depth = depth.saturating_sub(1),
_ => {}
}
i += c.len_utf8();
}
(Stop::End, i)
}
/// Whether the full stop at `i` ends a sentence: a space, then a capital letter.
fn ends_sentence(text: &str, i: usize) -> bool {
text[i + 1..].starts_with(' ') && text[i + 1..].chars().nth(1).is_some_and(|c| c.is_ascii_uppercase())
}
/// The name at `i`, whether it is optional, and the index after it.
fn read_name(text: &str, i: usize) -> Option<(&str, bool, usize)> {
let (name, after) = read_ident(text, i)?;
if text[after..].starts_with('?') { Some((name, true, after + 1)) } else { Some((name, false, after)) }
}
/// Whether a parameter starts at `i`.
fn spec_head(text: &str, i: usize) -> bool {
let Some((_, _, after)) = read_name(text, i) else { return false };
text[skip_ws(text, after)..].starts_with(':')
}
/// The identifier at `i`, and the index after it.
fn read_ident(text: &str, i: usize) -> Option<(&str, usize)> {
if !char_at(text, i).is_ascii_lowercase() {
return None;
}
let mut end = i + 1;
while end < text.len() {
let c = char_at(text, end);
if c.is_ascii_alphanumeric() || c == '_' {
end += 1;
} else {
break;
}
}
Some((&text[i..end], end))
}
/// The text of the group at `i`, and the index after it.
fn read_group(text: &str, i: usize) -> Option<(&str, usize)> {
let opener = char_at(text, i);
let closer = match opener {
'(' => ')',
'[' => ']',
'{' => '}',
_ => return None,
};
let mut depth = 1usize;
let mut j = i + opener.len_utf8();
while j < text.len() {
let c = char_at(text, j);
if c == '"' {
j = skip_quoted(text, j);
continue;
}
if c == opener {
depth += 1;
} else if c == closer {
depth -= 1;
if depth == 0 {
return Some((&text[i + opener.len_utf8()..j], j + closer.len_utf8()));
}
}
j += c.len_utf8();
}
None
}
/// The pieces of `text` split at the top level on `sep`.
fn split_top(text: &str, sep: char) -> Vec<&str> {
let mut pieces = Vec::new();
let mut depth = 0usize;
let mut start = 0usize;
let mut i = 0usize;
while i < text.len() {
let c = char_at(text, i);
match c {
'"' => {
i = skip_quoted(text, i);
continue;
}
'(' | '[' | '{' => depth += 1,
')' | ']' | '}' => depth = depth.saturating_sub(1),
_ if depth == 0 && c == sep => {
pieces.push(&text[start..i]);
start = i + c.len_utf8();
}
_ => {}
}
i += c.len_utf8();
}
pieces.push(&text[start..]);
pieces
}
/// The text before the reply arrow, which names no parameter.
fn cut_at_reply(text: &str) -> &str {
let mut depth = 0usize;
let mut i = 0usize;
while i < text.len() {
let c = char_at(text, i);
match c {
'(' | '[' | '{' => depth += 1,
')' | ']' | '}' => depth = depth.saturating_sub(1),
'→' if depth == 0 => return &text[..i],
_ => {}
}
i += c.len_utf8();
}
text
}
/// The index after the quoted text at `i`.
fn skip_quoted(text: &str, i: usize) -> usize {
let mut j = i + 1;
while j < text.len() {
let c = char_at(text, j);
if c == '"' {
return j + 1;
}
j += c.len_utf8();
}
j
}
/// The first index at or after `i` that is not whitespace.
fn skip_ws(text: &str, i: usize) -> usize {
let mut j = i;
while j < text.len() {
let c = char_at(text, j);
if !c.is_whitespace() {
break;
}
j += c.len_utf8();
}
j
}
/// The character at `i`.
fn char_at(text: &str, i: usize) -> char {
text.get(i..).and_then(|rest| rest.chars().next()).unwrap_or(char::REPLACEMENT_CHARACTER)
}
#[cfg(test)]
mod tests {
use super::*;
fn rows(notation: &str) -> Vec<(String, String, bool, String)> {
parse(notation).into_iter().map(|p| (p.name, p.kind, p.required, p.description)).collect()
}
#[test]
fn names_written_apart_share_the_type_that_follows_them() {
assert_eq!(
rows("length, width, height: expr"),
[
("length".into(), "expr".into(), true, String::new()),
("width".into(), "expr".into(), true, String::new()),
("height".into(), "expr".into(), true, String::new()),
]
);
}
#[test]
fn a_question_mark_marks_a_parameter_optional() {
assert_eq!(
rows("distance: expr; taper?: angle expr"),
[("distance".into(), "expr".into(), true, String::new()), ("taper".into(), "angle expr".into(), false, String::new()),]
);
}
#[test]
fn a_pipe_between_names_offers_alternative_names_for_one_parameter() {
assert_eq!(
rows("radius | diameter: expr"),
[("radius".into(), "expr".into(), true, String::new()), ("diameter".into(), "expr".into(), true, String::new()),]
);
}
#[test]
fn a_pipe_after_the_colon_lists_the_types_a_parameter_accepts() {
assert_eq!(
rows("direction?: positive|negative|symmetric"),
[("direction".into(), "positive|negative|symmetric".into(), false, String::new())]
);
}
#[test]
fn a_parenthesis_says_what_the_parameter_does() {
assert_eq!(
rows("center?: [x,y,z] (numbers in mm or length expressions; default: the origin)"),
[("center".into(), "[x,y,z]".into(), false, "numbers in mm or length expressions; default: the origin".into())]
);
}
#[test]
fn a_reply_after_an_arrow_names_no_parameter() {
assert_eq!(rows("cloud: id or name → deleted"), [("cloud".into(), "id or name".into(), true, String::new())]);
}
#[test]
fn prose_between_parameters_is_not_a_parameter() {
assert_eq!(rows("distance: expr; corners are mitred, crossing walls are one"), [("distance".into(), "expr".into(), true, String::new())]);
}
#[test]
fn a_type_stops_at_the_end_of_the_sentence_that_follows_it() {
// crates/engine/src/cmd/sketch.rs: `construction?: bool. Returns sides {bottom, right, top, left} (line ids)`.
let notation = concat!(
"center, corner: [x,y] (a coordinate may be an expression over the design's parameters: the point follows them); ",
"construction?: bool. Returns sides {bottom, right, top, left} (line ids) ",
"and corners {bottom_left, bottom_right, top_right, top_left} (point ids)"
);
let rows = rows(notation);
let construction = rows.iter().find(|(name, ..)| name == "construction").expect("the construction parameter");
assert_eq!(construction.1, "bool", "the type is the parameter's own type");
assert!(!construction.1.contains("Returns sides"), "the type does not run into the sentence that follows it: {}", construction.1);
}
#[test]
fn a_connector_word_introduces_the_next_parameter() {
assert_eq!(
rows("thin?: true (a wall along the sketch) with curves?: [curve ids]"),
[("thin".into(), "true".into(), false, "a wall along the sketch".into()), ("curves".into(), "[curve ids]".into(), false, String::new()),]
);
}
}