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.rsindex 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(¶meter_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.<tag>&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.rsindex 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.rsnew file mode 100644index 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()),]+ );+ }+}