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()),] + ); + } +}