From 49ab9179a7da498cbb3ea40ba6f94eb8be4e831b Mon Sep 17 00:00:00 2001 From: Homero Thompson Date: Thu, 5 Nov 2026 19:52:16 +0000 Subject: [PATCH] The command reference: the parameters as a table, with their type and whether they are required (#5237) (#11074) * The command reference: the parameters as a table, with their type and whether they are required (#5237) The command reference shows each command's parameters as one raw line of registry notation, so a reader has to read it as code to learn what a command takes. The generated page now lists the same parameters as a table: the name, the type, whether the command needs it, and what the registry says about it. The complete parameter text stays in the automation details, so nothing is lost for the scripts that read it. The table is generated from the command registry, like the rest of the page, so it cannot drift from the commands. The notation is read by a small parser that knows what the registry writes: names written apart share the type that follows them, a question mark marks a parameter optional, a pipe between names offers alternative names for one parameter, a pipe after the colon lists the types it accepts, a parenthesis says what the parameter does, and the text after an arrow is the reply the command gives, not a parameter. Co-Authored-By: Claude * test: the parameter table keeps its description literal The parameter table shows registry text, so a description that carries inline Markdown must be shown literally: backticks, emphasis and links are characters, not syntax. The type of a parameter ends where its sentence ends, so the sentence that follows it is not part of the type. Both tests fail on the current code. * fix: render the parameter description as prose The description cell of the parameter table is registry text, and the rest of the file already renders registry text with prose(): backticks, emphasis and links are characters, not syntax. table_cell() only kept the table and the page intact, so a description like `#name = expression` came out as a code span and a description with `*bold*` came out as emphasis. The name and the type keep table_cell(): they are identifiers and notation, and they are not Markdown prose. * fix: cut the parameter type at the end of the sentence A type runs to the end of the clause, so the sentence that follows it belongs to the command, not to the type: `construction?: bool. Returns sides {bottom, right, top, left}` showed the whole sentence as the type of `construction`, and the description of `sides` with it. The type now ends at a full stop followed by a space and a capital letter. A dotted or multiword type such as `sketch.rectangle` or `number or expression` does not match that pattern, so it keeps its current handling. --------- Co-authored-by: Claude --- xtask/src/book.rs | 100 ++++++++++ xtask/src/main.rs | 1 + xtask/src/params.rs | 441 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 542 insertions(+) create mode 100644 xtask/src/params.rs diff --git a/xtask/src/book.rs b/xtask/src/book.rs index b5c03e847..a4a5d35d3 100644 --- a/xtask/src/book.rs +++ b/xtask/src/book.rs @@ -141,6 +141,7 @@ fn reference(cmds: &[Value], guides: &BTreeMap) -> 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("
\nAutomation details\n\n"); md.push_str(&format!("

Command ID: {}

\n\n", html(command_text(c, "id")))); let p = command_text(c, "params"); @@ -160,6 +161,49 @@ fn reference(cmds: &[Value], guides: &BTreeMap) -> 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, String> { @@ -338,6 +382,62 @@ mod tests { assert!(md.contains("odd.<tag>&id")); } + #[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 126965ccf..c3f4a009b 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 000000000..e5e3fe3f1 --- /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 { + 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 { + 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> { + 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> { + 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 { + 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, 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()),] + ); + } +}