Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

The command reference: the parameters as a table, with their type and whether they are required (#5237) (#11074)

Homero Thompson49ab9179a7da
diff --git a/xtask/src/book.rs b/xtask/src/book.rs
index b5c03e847c..a4a5d35d38 100644
--- a/xtask/src/book.rs
+++ b/xtask/src/book.rs
@@ -141,6 +141,7 @@ fn reference(cmds: &[Value], guides: &BTreeMap<String, String>) -> String {
} else if let Some((label, path)) = guide(c) {
md.push_str(&format!("Read the [{label}]({path}).\n\n"));
}
+ md.push_str(&parameter_table(command_text(c, "params")));
md.push_str("<details>\n<summary>Automation details</summary>\n\n");
md.push_str(&format!("<p><strong>Command ID:</strong> <code>{}</code></p>\n\n", html(command_text(c, "id"))));
let p = command_text(c, "params");
@@ -160,6 +161,49 @@ fn reference(cmds: &[Value], guides: &BTreeMap<String, String>) -> String {
md
}
+/// The parameters of a command as a table a reader can scan: name, type and whether the
+/// command needs them. The complete parameter text stays in the automation details.
+fn parameter_table(params: &str) -> String {
+ let rows = crate::params::parse(params);
+ if rows.is_empty() {
+ return String::new();
+ }
+ let mut md = String::from("| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n");
+ for row in rows {
+ let cells =
+ [table_cell(&row.name), table_cell(&row.kind), if row.required { "Yes".to_string() } else { "No".to_string() }, prose(&row.description)];
+ md.push('|');
+ for cell in cells {
+ // An empty cell keeps the column, with a single space between the bars.
+ if cell.is_empty() {
+ md.push(' ');
+ } else {
+ md.push(' ');
+ md.push_str(&cell);
+ md.push(' ');
+ }
+ md.push('|');
+ }
+ md.push('\n');
+ }
+ md.push('\n');
+ md
+}
+
+/// One cell of a parameter table: literal text that cannot break the table or the page.
+fn table_cell(text: &str) -> String {
+ let mut escaped = String::new();
+ for ch in text.chars() {
+ match ch {
+ '\r' | '\n' => escaped.push(' '),
+ '\\' => escaped.push_str("\\\\"),
+ '|' => escaped.push_str("\\|"),
+ _ => escaped.push(ch),
+ }
+ }
+ html(escaped.trim())
+}
+
/// Hand-authored Markdown is reviewed documentation, separate from registry metadata.
/// Unknown filenames fail the build rather than silently dropping a renamed command's guide.
fn load_guides(dir: &Path, cmds: &[Value]) -> Result<BTreeMap<String, String>, String> {
@@ -338,6 +382,62 @@ mod tests {
assert!(md.contains("<code>odd.&lt;tag&gt;&amp;id</code>"));
}
+ #[test]
+ fn command_parameters_are_listed_as_a_table_with_their_type_and_whether_they_are_required() {
+ // The registry's own notation, as crates/engine/src/cmd/features.rs writes it.
+ let params = "length, width, height: expr; corner?: [x,y,z] | center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?";
+ let md = reference(&[json!({"id":"solid.box","label":"Box","tab":"SOLID","params":params})]);
+ assert!(md.contains("| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n"));
+ for row in [
+ "| length | expr | Yes | |",
+ "| width | expr | Yes | |",
+ "| height | expr | Yes | |",
+ "| corner | [x,y,z] | No | |",
+ "| center | [x,y,z] | No | numbers in mm or length expressions; default: the origin |",
+ "| operation | | No | |",
+ "| targets | [body] | No | |",
+ "| name | | No | |",
+ "| body_name | | No | |",
+ ] {
+ assert!(md.contains(row), "missing row {row}");
+ }
+ }
+
+ #[test]
+ fn a_description_with_inline_markdown_stays_literal_in_the_table() {
+ // crates/engine/src/cmd/sketch.rs: a description may carry backticks and emphasis.
+ let md = reference(&[json!({"id":"solid.box","label":"Box","params":"size: expr (a parameter with `backticks` and *bold* text)"})]);
+ let row = md.lines().find(|line| line.starts_with("| size |")).expect("a row for the size parameter");
+ assert!(
+ row.contains(r"| size | expr | Yes | a parameter with \`backticks\` and \*bold\* text |"),
+ "the description shows its Markdown literally: {row}"
+ );
+ assert!(!row.contains("`backticks`"), "the backticks must not open a code span: {row}");
+ assert!(!row.contains("*bold*"), "the emphasis markers must not start emphasis: {row}");
+ }
+
+ #[test]
+ fn a_pipe_in_the_name_position_lists_alternative_names_and_one_after_the_colon_is_a_type() {
+ // crates/engine/src/cmd/features.rs: `radius | diameter: expr` and `direction?: positive|negative|symmetric`.
+ let md = reference(&[
+ json!({"id":"solid.sphere","label":"Sphere","params":"radius | diameter: expr; center?: [x,y,z] (numbers in mm or length expressions; default: the origin)"}),
+ json!({"id":"solid.extrude","label":"Extrude","params":"direction?: positive|negative|symmetric (distance is total thickness, split evenly around the start plane)"}),
+ ]);
+ assert!(md.contains("| radius | expr | Yes | |\n"));
+ assert!(md.contains("| diameter | expr | Yes | |\n"));
+ assert!(
+ md.contains("| direction | positive\\|negative\\|symmetric | No | distance is total thickness, split evenly around the start plane |\n")
+ );
+ }
+
+ #[test]
+ fn a_reply_after_an_arrow_is_not_a_parameter() {
+ // crates/engine/src/cmd/parts.rs: `cloud: id or name → deleted`.
+ let md = reference(&[json!({"id":"pointcloud.delete","label":"Delete","params":"cloud: id or name → deleted"})]);
+ assert!(md.contains("| cloud | id or name | Yes | |\n"));
+ assert!(!md.contains("| deleted |"));
+ }
+
#[test]
fn missing_optional_metadata_does_not_invent_a_toolbar_shortcut_or_guide() {
for cmd in [
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 126965ccf3..c3f4a009b7 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -18,6 +18,7 @@ mod layers;
mod licences;
mod lists;
mod mesh_decisions;
+mod params;
mod pending;
mod render_assets;
mod skills;
diff --git a/xtask/src/params.rs b/xtask/src/params.rs
new file mode 100644
index 0000000000..e5e3fe3f1c
--- /dev/null
+++ b/xtask/src/params.rs
@@ -0,0 +1,441 @@
+//! 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()),]
+ );
+ }
+}