Files
solidcraft/crates/doc/src/text_params.rs
T
phanoobandClaude Opus 5.5 634f0a2308 Sketch text: number parameters in the words, and = for a formula in Edit Text (#9281) (#9386)
* claim: #9281

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Sketch text: a number parameter in the words shows its value (#9281)

A text's words expression can now name a number parameter: `'W' + Width`
reads "W85 mm" (lengths in the design's units, angles in degrees, up to
three decimals). `number(Width)` drops the unit and `number(Width, 2)`
fixes the decimals. The words and the cut follow a parameter edit in the
same rebuild, a rename reaches inside number(), and deleting the parameter
is refused while a text shows it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Sketch text: a Text starting with = builds its words from parameters (#9281)

In Edit Text, a Text that starts with = is the words' expression
(='W' + number(Width)): OK keeps it, the dialog shows it again with its =,
and an untouched OK no longer turns it into typed words. Typed words still
replace it, and a saved text that happens to start with = stays typed
until it is edited. The field's tooltip says how.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Sketch text: the formula hint in every complete catalog (#9281)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 17:28:31 +00:00

397 lines
16 KiB
Rust

//! Text parameters: named texts (`Label` = `TAG-1`) that the words of a sketch text can be built
//! from, by an expression that joins them and quoted texts with `+` (`Label + '-L'`). They are
//! kept apart from the number parameters: a text has no unit and no number expression reads it.
//! A parameter edit or a configuration row that sets one relabels every text built from it, and
//! the features that use those texts follow in the same rebuild.
//!
//! The words can show a number parameter's value too (#9281): `'Width: ' + Width` reads
//! `Width: 85 mm`, a length in the design's units, an angle in degrees (`30°`), up to three
//! decimals without trailing zeros. `number(Width)` is the number alone (`85`) and
//! `number(Width, 2)` gives it two decimals (`85.00`).
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use crate::expr::Value;
use crate::{DocError, Document, FeatureKind, MAX_PARAMS, Result};
/// The unit that marks a text parameter where parameters are listed, added or imported.
pub const TEXT_UNIT: &str = "text";
/// Longest text a text parameter holds, and longest words expression.
const MAX_LEN: usize = 4096;
/// A named text.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct TextParam {
pub name: String,
pub text: String,
#[serde(default, skip_serializing_if = "String::is_empty")]
pub comment: String,
}
/// Is `unit` the text unit, ignoring ASCII case and surrounding whitespace?
pub fn is_text_unit(unit: &str) -> bool {
unit.trim().eq_ignore_ascii_case(TEXT_UNIT)
}
/// A text as typed for a text parameter: inside matching quotes, what they hold (a quote doubled
/// inside stands for one); else the text itself, without surrounding spaces.
pub fn unquote(s: &str) -> String {
let t = s.trim();
for q in ['\'', '"'] {
if t.len() >= 2 && t.starts_with(q) && t.ends_with(q) {
let inner = t.get(1..t.len() - 1).unwrap_or_default();
let doubled = format!("{q}{q}");
// Only a text whose inner quotes all come in pairs is one quoted text.
if inner.replace(&doubled, "").contains(q) {
break;
}
return inner.replace(&doubled, &q.to_string());
}
}
t.to_string()
}
enum Term {
Text(String),
Name(String),
/// `number(name)` or `number(name, decimals)`, with the name's byte range.
Number {
name: String,
at: (usize, usize),
decimals: Option<u8>,
},
}
/// How the words show a number parameter.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Show {
/// As named: its value and unit, up to three decimals.
Named,
/// In `number(...)`: the number alone, with these decimals or up to three.
Number(Option<u8>),
}
/// The function that shows a number parameter's value without its unit.
const NUMBER: &str = "number";
/// Most decimals `number(name, decimals)` takes.
const MAX_DECIMALS: u8 = 8;
/// The terms of a words expression with their byte ranges: quoted texts (single or double
/// quotes, a quote doubled inside stands for one) and parameter names, joined by `+`.
fn terms(s: &str) -> Result<Vec<(Term, usize, usize)>> {
if s.len() > MAX_LEN {
return Err(DocError::Expr("text expression too long".into()));
}
let cs: Vec<(usize, char)> = s.char_indices().collect();
let at = |i: usize| cs.get(i).map_or(s.len(), |x| x.0);
let mut out = Vec::new();
let mut i = 0;
let mut want_term = true;
while let Some(&(_, c)) = cs.get(i) {
if c.is_whitespace() {
i += 1;
} else if !want_term {
if c != '+' {
return Err(DocError::Expr(format!("unexpected `{c}`: a text expression joins quoted texts and text parameters with +")));
}
want_term = true;
i += 1;
} else if c == '\'' || c == '"' {
let start = i;
let mut text = String::new();
i += 1;
loop {
match cs.get(i).map(|x| x.1) {
None => return Err(DocError::Expr(format!("a text in quotes ({c}) is not closed"))),
Some(d) if d == c && cs.get(i + 1).is_some_and(|x| x.1 == c) => {
text.push(c);
i += 2;
}
Some(d) if d == c => {
i += 1;
break;
}
Some(d) => {
text.push(d);
i += 1;
}
}
}
out.push((Term::Text(text), at(start), at(i)));
want_term = false;
} else if c.is_alphabetic() || c == '_' {
let start = i;
i = word_end(&cs, i);
let word = s.get(at(start)..at(i)).unwrap_or_default().to_string();
let open = skip_blanks(&cs, i);
if word == NUMBER && cs.get(open).is_some_and(|x| x.1 == '(') {
let (term, end) = number_call(s, &cs, open + 1)?;
i = end;
out.push((term, at(start), at(i)));
} else {
out.push((Term::Name(word), at(start), at(i)));
}
want_term = false;
} else {
return Err(DocError::Expr(format!("unexpected `{c}`: a text expression joins quoted texts and text parameters with +")));
}
}
if want_term {
let what = if out.is_empty() { "the text expression is empty" } else { "the text expression ends with +" };
return Err(DocError::Expr(what.into()));
}
Ok(out)
}
fn word_end(cs: &[(usize, char)], mut i: usize) -> usize {
while cs.get(i).is_some_and(|x| x.1.is_alphanumeric() || x.1 == '_') {
i += 1;
}
i
}
fn skip_blanks(cs: &[(usize, char)], mut i: usize) -> usize {
while cs.get(i).is_some_and(|x| x.1.is_whitespace()) {
i += 1;
}
i
}
/// `number(` has been read up to `i`: the name, optional decimals and `)`; the term and where
/// it ends.
fn number_call(s: &str, cs: &[(usize, char)], i: usize) -> Result<(Term, usize)> {
let at = |i: usize| cs.get(i).map_or(s.len(), |x| x.0);
let usage = || DocError::Expr("number() takes a number parameter and, if wanted, its decimals: number(Width, 2)".into());
let start = skip_blanks(cs, i);
if !cs.get(start).is_some_and(|x| x.1.is_alphabetic() || x.1 == '_') {
return Err(usage());
}
let end = word_end(cs, start);
let name = s.get(at(start)..at(end)).unwrap_or_default().to_string();
let mut i = skip_blanks(cs, end);
let mut decimals = None;
if cs.get(i).is_some_and(|x| x.1 == ',') {
let from = skip_blanks(cs, i + 1);
let mut to = from;
while cs.get(to).is_some_and(|x| x.1.is_ascii_digit()) {
to += 1;
}
let digits = s.get(at(from)..at(to)).unwrap_or_default();
let n: u8 = digits.parse().map_err(|_| usage())?;
if n > MAX_DECIMALS {
return Err(DocError::Expr(format!("number() shows at most {MAX_DECIMALS} decimals")));
}
decimals = Some(n);
i = skip_blanks(cs, to);
}
if !cs.get(i).is_some_and(|x| x.1 == ')') {
return Err(usage());
}
Ok((Term::Number { name, at: (at(start), at(end)), decimals }, i + 1))
}
/// A number parameter's value as the words show it: `v` in millimetres, radians or no unit
/// (`len`, `ang`: its dimension), lengths in `units`.
pub fn show_number(v: f64, len: i8, ang: i8, units: &str, show: Show) -> Result<String> {
let (value, unit) = match (len, ang) {
(0, 0) => (v, ""),
(1, 0) => {
let (scale, name) = crate::display_units::unit_scale(units);
(v * scale, name)
}
(0, 1) => (v.to_degrees(), "°"),
_ => return Err(DocError::Expr("a text shows lengths, angles and plain numbers only".into())),
};
if !value.is_finite() || value.abs() > 1e12 {
return Err(DocError::Expr("the number is out of range for a text".into()));
}
let digits = match show {
Show::Number(Some(d)) => format!("{value:.*}", usize::from(d)),
Show::Named | Show::Number(None) => {
let t = format!("{value:.3}");
let t = t.trim_end_matches('0').trim_end_matches('.');
if t == "-0" { "0".to_string() } else { t.to_string() }
}
};
Ok(match (show, unit) {
(Show::Number(_), _) | (_, "") => digits,
(Show::Named, "°") => format!("{digits}°"),
(Show::Named, unit) => format!("{digits} {unit}"),
})
}
/// The parameters a words expression names (none when it does not parse).
pub fn references(s: &str) -> Vec<String> {
let mut out: Vec<String> = Vec::new();
for (t, _, _) in terms(s).unwrap_or_default() {
if let Term::Name(n) | Term::Number { name: n, .. } = t
&& !out.contains(&n)
{
out.push(n);
}
}
out
}
/// The words expression with every reference to `old` renamed to `new` (quoted texts kept).
pub fn rename_reference(s: &str, old: &str, new: &str) -> String {
let Ok(terms) = terms(s) else { return s.to_string() };
let mut out = String::with_capacity(s.len());
let mut last = 0;
for (t, a, b) in terms {
let at = match &t {
Term::Name(n) if n == old => (a, b),
Term::Number { name, at, .. } if name == old => *at,
_ => continue,
};
out.push_str(s.get(last..at.0).unwrap_or_default());
out.push_str(new);
last = at.1;
}
out.push_str(s.get(last..).unwrap_or_default());
out
}
/// The words an expression comes to, each parameter's text from `lookup`.
pub fn eval(s: &str, lookup: &dyn Fn(&str, Show) -> Result<String>) -> Result<String> {
let mut out = String::new();
for (t, _, _) in terms(s)? {
match t {
Term::Text(text) => out.push_str(&text),
Term::Name(n) => out.push_str(&lookup(&n, Show::Named)?),
Term::Number { name, decimals, .. } => out.push_str(&lookup(&name, Show::Number(decimals))?),
}
if out.len() > MAX_LEN {
return Err(DocError::Expr("the text is too long".into()));
}
}
Ok(out)
}
impl Document {
pub fn text_param(&self, name: &str) -> Option<&TextParam> {
self.text_params.iter().find(|p| p.name == name)
}
/// The words a words expression comes to in this design, number parameters from `vals`.
pub fn eval_words(&self, e: &str, vals: &BTreeMap<String, Value>) -> Result<String> {
eval(e, &|n, show| match (self.text_param(n), vals.get(n)) {
(Some(_), _) if show != Show::Named => Err(DocError::Expr(format!("`{n}` is a text parameter: number() takes a number parameter"))),
(Some(p), _) => Ok(p.text.clone()),
(None, Some(v)) => show_number(v.v, v.len, v.ang, &self.units, show).map_err(|error| DocError::Expr(format!("`{n}`: {error}"))),
(None, None) if self.name_taken(n) => Err(DocError::Expr(format!("`{n}` has no value"))),
(None, None) => Err(DocError::Expr(format!("unknown parameter `{n}`"))),
})
}
/// Set text parameter `name` to `text` (as typed: [`unquote`]), adding it when new.
pub fn set_text_param(&mut self, name: &str, text: &str, comment: Option<&str>) -> Result<()> {
if let Some(p) = Self::param_name_problem(name) {
return Err(DocError::Invalid(p));
}
if text.len() > MAX_LEN {
return Err(DocError::Expr("text too long".into()));
}
if comment.is_some_and(|c| c.len() > 4096) {
return Err(DocError::Invalid("comment too long".into()));
}
let text = unquote(text);
if let Some(p) = self.text_params.iter_mut().find(|p| p.name == name) {
p.text = text;
if let Some(c) = comment {
p.comment = c.to_string();
}
return Ok(());
}
if self.name_taken(name) {
return Err(DocError::Invalid(format!("`{name}` is a number parameter")));
}
if self.params.len() + self.text_params.len() >= MAX_PARAMS {
return Err(DocError::Invalid("too many parameters".into()));
}
self.text_params.push(TextParam { name: name.to_string(), text, comment: comment.unwrap_or_default().to_string() });
Ok(())
}
/// Remove text parameter `name`; refused while a text uses it.
pub(crate) fn remove_text_param(&mut self, name: &str) -> Result<()> {
let users = self.param_users(name);
if !users.is_empty() {
let list: Vec<String> = users.iter().map(crate::ParamUser::describe).collect();
return Err(DocError::Invalid(format!("`{name}` is used by {}", list.join(", "))));
}
self.text_params.retain(|p| p.name != name);
self.favorites.remove(name);
Ok(())
}
/// The sketches whose texts' words read one of `names`.
pub(crate) fn features_reading_texts(&self, names: &std::collections::BTreeSet<String>) -> Vec<u64> {
self.features
.iter()
.filter(|f| match &f.kind {
FeatureKind::Sketch { sketch, .. } => sketch.text_word_exprs().iter().any(|e| references(e).iter().any(|r| names.contains(r))),
_ => false,
})
.map(|f| f.id)
.collect()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn words_expressions_join_quoted_texts_and_parameters() {
let look = |n: &str, _: Show| match n {
"Label" => Ok("TAG-1".to_string()),
_ => Err(DocError::Expr(format!("unknown text parameter `{n}`"))),
};
assert_eq!(eval("Label + '-L'", &look).unwrap(), "TAG-1-L");
assert_eq!(eval("\"it's \" + Label", &look).unwrap(), "it's TAG-1");
assert_eq!(eval("'it''s'", &look).unwrap(), "it's");
assert_eq!(eval("'a+b' + 'c'", &look).unwrap(), "a+bc");
for bad in ["", "Label +", "+ 'a'", "Label 'a'", "'open", "Label - 'a'", "Other"] {
assert!(eval(bad, &look).is_err(), "{bad}");
}
assert_eq!(references("Label + 'Label' + Other + Label"), ["Label", "Other"]);
assert_eq!(rename_reference("Label+'Label-' + Label", "Label", "Tag"), "Tag+'Label-' + Tag");
assert_eq!(unquote(" 'A B' "), "A B");
assert_eq!(unquote("\"it''s\""), "it''s");
assert_eq!(unquote("'it''s'"), "it's");
assert_eq!(unquote("'a' + 'b'"), "'a' + 'b'");
assert_eq!(unquote("TAG-1"), "TAG-1");
}
/// #9281: a number parameter in the words shows its value; `number()` drops the unit and
/// can fix the decimals; a rename reaches inside `number()`.
#[test]
fn number_parameters_show_their_value_in_the_words() {
let look = |n: &str, show: Show| match n {
"Width" => show_number(85.0, 1, 0, "mm", show),
"Gap" => show_number(12.7, 1, 0, "in", show),
"Tilt" => show_number(30f64.to_radians(), 0, 1, "mm", show),
"Count" => show_number(4.0, 0, 0, "mm", show),
"Area" => show_number(1.0, 2, 0, "mm", show),
_ => Err(DocError::Expr(format!("unknown parameter `{n}`"))),
};
assert_eq!(eval("'Width: ' + Width", &look).unwrap(), "Width: 85 mm");
assert_eq!(eval("Gap", &look).unwrap(), "0.5 in");
assert_eq!(eval("Tilt + ' / ' + Count", &look).unwrap(), "30° / 4");
assert_eq!(eval("number(Width) + 'x' + number( Width , 2 )", &look).unwrap(), "85x85.00");
assert_eq!(eval("number(Tilt, 1)", &look).unwrap(), "30.0");
for bad in ["number(Width", "number()", "number(Width, x)", "number(Width, 9)", "number(Width 2)", "Area", "number('a')"] {
assert!(eval(bad, &look).is_err(), "{bad}");
}
assert_eq!(references("number(Width, 1) + Count"), ["Width", "Count"]);
assert_eq!(rename_reference("number(Width, 1) + Width + 'Width'", "Width", "W"), "number(W, 1) + W + 'Width'");
assert_eq!(show_number(-0.0001, 1, 0, "mm", Show::Named).unwrap(), "0 mm");
assert!(show_number(f64::NAN, 0, 0, "mm", Show::Named).is_err());
}
}