Skip to content

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

45.1 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/parameters.rs`: those that manage the
//! design's user parameters by name (#11941), `parameters.add`, `.rename`, `.delete`, `.comment`,
//! `.favorite` and `.move`, and the rest (#12497): `parameters.change`, `.list`, `.users`,
//! `.graph`, `.export`, `.import`, `.complete` and `expr.evaluate`.
//!
//! The handlers read their parameters from the raw JSON, so each key here reads as its handler
//! reads it and fails with the handler's message. Whether a parameter exists, and whether a new
//! name, unit or expression is valid, stays the document's to check, with its messages.

use std::borrow::Cow;
use std::collections::BTreeMap;

use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Map, Value, json};
use solidcraft_doc::expr::Kind;
use solidcraft_doc::{ParamRow, ParamUser};

use super::check::{located, whole};

/// A parameter's name, as `cmd/parameters.rs`'s `param_name` reads `name`: text that isn't blank,
/// with its message for anything else. Spaces at either end are dropped.
fn param_name<'de, D: Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(name) if !name.trim().is_empty() => Ok(name),
        _ => Err(D::Error::custom(whole("`name` is required"))),
    }
}

/// Add a user parameter: a named number with a unit, or a named text. Features, sketches and
/// other parameters can use it by name. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = expression_or_value)]
pub struct ParamAddParams {
    /// The new parameter's name: a letter or `_`, then letters, digits or `_`; not a unit's,
    /// function's or constant's name, nor another parameter's.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
    #[serde(default, deserialize_with = "expression")]
    #[schemars(schema_with = "expression_schema")]
    pub expression: Option<Value>,
    /// Another name for `expression`, read when `expression` isn't a number or text.
    #[serde(default, deserialize_with = "expression")]
    #[schemars(schema_with = "expression_schema")]
    pub value: Option<Value>,
    /// The unit: `mm`, `cm`, `m`, `in`, `ft`, `deg`, `rad`, `""` (no unit) or `text` (a text
    /// parameter, whose expression is its text). Default: the expression's own unit, a length
    /// in the design's units.
    #[serde(default)]
    pub unit: Option<String>,
    /// A note to show with it.
    #[serde(default)]
    pub comment: Option<String>,
    /// List it with the favourites, first. Default: false.
    #[serde(default)]
    pub favorite: Option<bool>,
}

/// `expression` and `value`: a number or text, as `expr_arg` reads them. `null` is left out, as
/// the reader reads it; anything else gets the handler's message.
fn expression<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Value>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        v @ (Value::String(_) | Value::Number(_)) => Ok(Some(v)),
        _ => Err(D::Error::custom(whole("`expression` must be a number or text"))),
    }
}

fn expression_schema(_: &mut schemars::SchemaGenerator) -> Schema {
    schemars::json_schema!({
        "description": "The value: a number, or an expression as text (`25 mm`, `W / 2`). For a text parameter, its text; quotes round it are optional.",
        "type": ["number", "string", "null"]
    })
}

/// `parameters.add` needs `expression`, or `value` in its place, as a number or text. Given
/// isn't enough: `expr_arg` reads a `null` one as left out, so each alternative also needs its
/// key's type.
fn expression_or_value(schema: &mut Schema) {
    schema.insert(
        "anyOf".into(),
        serde_json::json!([
            {"required": ["expression"], "properties": {"expression": {"type": ["number", "string"]}}},
            {"required": ["value"], "properties": {"value": {"type": ["number", "string"]}}}
        ]),
    );
}

/// Rename a parameter, a user parameter or a feature's named input. The expressions, feature
/// inputs and dimensions that use it follow. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamRenameParams {
    /// The parameter, by name.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
    /// Its new name, as for a new parameter. Spaces at either end are dropped.
    #[serde(deserialize_with = "new_name")]
    pub new_name: String,
}

/// `new_name`: text, with the handler's message for anything else.
fn new_name<'de, D: Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    match Value::deserialize(d)? {
        Value::String(name) => Ok(name),
        _ => Err(D::Error::custom(whole("`new_name` is required"))),
    }
}

/// Delete a user parameter. It's refused while an expression, a feature input or a dimension
/// uses it; the message lists them. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamNameParams {
    /// The parameter, by name.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
}

/// Set a parameter's comment, a note shown with it. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = comment_required)]
pub struct ParamCommentParams {
    /// The parameter, by name.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
    /// The comment; empty text clears it.
    // Optional in the type and required in the schema (`comment_required`): left out, the
    // handler refuses it with its own message ("`comment` must be text"), not the check's "is
    // required". `skip_serializing_if` keeps schemars from publishing `default: null`, which
    // the schema refuses.
    #[serde(default, deserialize_with = "comment_text", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "String")]
    pub comment: Option<String>,
}

/// `parameters.comment` needs `comment`, though its type has it optional.
fn comment_required(schema: &mut Schema) {
    if let Some(Value::Array(required)) = schema.get_mut("required")
        && !required.contains(&Value::from("comment"))
    {
        required.push("comment".into());
    }
}

/// `comment`: text, with the handler's message for anything else, `null` included.
fn comment_text<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    match Value::deserialize(d)? {
        Value::String(comment) => Ok(Some(comment)),
        _ => Err(D::Error::custom(whole("`comment` must be text"))),
    }
}

/// Mark a parameter as a favourite, listed first, or unmark it. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamFavoriteParams {
    /// The parameter, by name.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
    /// Whether it's a favourite. Default: true.
    #[serde(default)]
    pub favorite: Option<bool>,
}

/// Move a user parameter just before or after another, in the order the user parameters are
/// listed. Give exactly one of `before` and `after`. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = before_or_after)]
pub struct ParamMoveParams {
    /// The user parameter, by name.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
    /// Another user parameter, by name: the parameter is listed just before it.
    #[serde(default, deserialize_with = "neighbour")]
    pub before: Option<String>,
    /// Another user parameter, by name: the parameter is listed just after it.
    #[serde(default, deserialize_with = "neighbour")]
    pub after: Option<String>,
}

/// `before` and `after`: text; `null` is left out, as the handler reads it. Anything else gets
/// the message the handler gives when it finds neither.
fn neighbour<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::String(name) => Ok(Some(name)),
        _ => Err(D::Error::custom(whole("give one of `before` or `after`: another user parameter"))),
    }
}

/// `parameters.move` needs exactly one of `before` and `after` as text. Each alternative needs
/// its key to be text, so a `null` one, which the handler reads as left out, matches neither:
/// `oneOf` then counts the keys as the handler does, and both or neither is refused.
fn before_or_after(schema: &mut Schema) {
    schema.insert(
        "oneOf".into(),
        serde_json::json!([
            {"required": ["before"], "properties": {"before": {"type": "string"}}},
            {"required": ["after"], "properties": {"after": {"type": "string"}}}
        ]),
    );
}

/// What `parameters.add` returns: the new parameter.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamAdded {
    pub name: String,
    #[serde(flatten)]
    pub value: AddedValue,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// A new parameter's value: a number's, or a text parameter's text.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum AddedValue {
    /// A text parameter.
    Text {
        /// Always `text`.
        unit: String,
        /// Its text.
        text: String,
        /// Always `null`: a text has no number.
        value: Option<f64>,
    },
    /// A number.
    Number {
        /// Its unit; `""` for none.
        unit: Option<String>,
        /// Its value in mm for a length and degrees for an angle, as in every reply; `null` if
        /// it can't be worked out.
        value: Option<f64>,
        /// Its value in its own unit; `null` if it can't be worked out.
        display_value: Option<f64>,
    },
}

/// What `parameters.rename` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamRenamed {
    /// The old name.
    pub from: String,
    /// The new name.
    pub to: String,
    /// How many expressions, feature inputs and dimensions were changed to use the new name.
    pub references_updated: usize,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `parameters.delete` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamDeleted {
    /// The deleted parameter's name.
    pub deleted: String,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `parameters.comment` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamCommented {
    pub name: String,
    /// The comment as given.
    pub comment: String,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `parameters.favorite` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamFavorited {
    pub name: String,
    /// Whether it's now a favourite.
    pub favorite: bool,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `parameters.move` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamMoved {
    pub name: String,
    /// The user parameters' names, in their new order.
    pub order: Vec<String>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

// ---------------------------------------------------------------------------------------------
// #12497: `parameters.change`, `.list`, `.users`, `.graph`, `.export`, `.import`, `.complete`
// and `expr.evaluate`.
// ---------------------------------------------------------------------------------------------

/// Adds `key` to the schema's `required` list: for a key the type has optional so that the
/// handler, not the check, refuses it when it's left out.
fn require(schema: &mut Schema, key: &str) {
    match schema.get_mut("required") {
        Some(Value::Array(required)) => {
            if !required.iter().any(|k| k == key) {
                required.push(key.into());
            }
        }
        _ => {
            schema.insert("required".into(), Value::Array(vec![key.into()]));
        }
    }
}

/// `key` as text: `null` is left out, as `str_` reads it. Anything else is refused, though the
/// handler would read it as left out; `message` is the handler's for that case, if it has one.
fn text_or_null<'de, D: Deserializer<'de>>(d: D, message: &str) -> Result<Option<String>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::String(s) => Ok(Some(s)),
        _ => Err(D::Error::custom(whole(message))),
    }
}

/// What `parameters.change` takes, in the form it's read in: see [`ParamChangeParams`].
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = change_forms)]
pub struct ParamChangeKeys {
    /// Several existing parameters at once, `{name: expression}`: they are checked together and
    /// the design is rebuilt once, all or nothing. Renaming isn't done this way. When given,
    /// no other key is read.
    #[serde(default, deserialize_with = "changes_map", skip_serializing_if = "Option::is_none")]
    #[schemars(schema_with = "changes_schema")]
    pub changes: Option<Map<String, Value>>,
    /// Delete this user parameter (refused while something uses it). When given as text, no
    /// other key but `changes` is read.
    #[serde(default, deserialize_with = "delete_text")]
    pub delete: Option<String>,
    /// The parameter to change, by name: a user parameter, a sketch dimension or a feature's
    /// named input. Spaces at either end are dropped.
    #[serde(default, deserialize_with = "change_name", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "String", length(min = 1))]
    pub name: Option<String>,
    /// The new value: a number, or an expression as text (`25 mm`, `W / 2`). A text
    /// parameter's expression is its text, quotes round it optional. `name = value` renames
    /// the parameter to `name` and sets the value (or sets `name` when the value is just
    /// `name`). Needed unless `new_name`, `favorite` or `comment` is given.
    #[serde(default, deserialize_with = "expression")]
    #[schemars(schema_with = "expression_schema")]
    pub expression: Option<Value>,
    /// Another name for `expression`, read when `expression` isn't a number or text.
    #[serde(default, deserialize_with = "expression")]
    #[schemars(schema_with = "expression_schema")]
    pub value: Option<Value>,
    /// The unit: `mm`, `cm`, `m`, `in`, `ft`, `deg`, `rad`, `""` (no unit) or `text`. Default:
    /// the parameter's own, or for a new one its value's unit, a length in the design's units.
    #[serde(default, deserialize_with = "unit_text")]
    pub unit: Option<String>,
    /// A note to show with the parameter.
    #[serde(default, deserialize_with = "comment_key")]
    pub comment: Option<String>,
    /// List it with the favourites, first, or not.
    #[serde(default, deserialize_with = "favorite_flag")]
    pub favorite: Option<bool>,
    /// Rename the parameter: the expressions, feature inputs and dimensions that use it follow.
    /// With an `expression` the new value is set too.
    #[serde(default, deserialize_with = "new_name_key")]
    pub new_name: Option<String>,
}

fn changes_map<'de, D: Deserializer<'de>>(d: D) -> Result<Option<Map<String, Value>>, D::Error> {
    let Value::Object(map) = Value::deserialize(d)? else {
        return Err(D::Error::custom(whole("`changes` must be an object of name: expression")));
    };
    if map.is_empty() {
        return Err(D::Error::custom(whole("`changes` is empty")));
    }
    for (name, e) in &map {
        // `expr_arg`: text, or a number.
        if !matches!(e, Value::String(_) | Value::Number(_)) {
            return Err(D::Error::custom(whole(format!("`changes.{name}` must be a number or text"))));
        }
    }
    Ok(Some(map))
}

fn changes_schema(_: &mut SchemaGenerator) -> Schema {
    json_schema!({
        "description": "Several existing parameters at once, `{name: expression}`: they are checked together and the design is rebuilt once, all or nothing. Renaming isn't done this way (`name = value` is refused). When given, no other key is read.",
        "type": "object",
        "minProperties": 1,
        "additionalProperties": {"type": ["number", "string"]}
    })
}

fn delete_text<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`delete` must be text")
}

fn unit_text<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`unit` must be text")
}

fn comment_key<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`comment` must be text")
}

fn new_name_key<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`new_name` must be text")
}

fn favorite_flag<'de, D: Deserializer<'de>>(d: D) -> Result<Option<bool>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::Bool(b) => Ok(Some(b)),
        _ => Err(D::Error::custom(whole("`favorite` must be true or false"))),
    }
}

/// `name` of a single change, as `param_name` reads it: text that isn't blank, `null` included
/// in what is refused.
fn change_name<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    param_name(d).map(Some)
}

/// `parameters.change` takes one of three forms: `changes`, `delete` or `name` with what to
/// change about it.
fn change_forms(schema: &mut Schema) {
    let name_with = json!({
        "required": ["name"],
        "properties": {"name": {"type": "string"}},
        "anyOf": [
            {"required": ["expression"], "properties": {"expression": {"type": ["number", "string"]}}},
            {"required": ["value"], "properties": {"value": {"type": ["number", "string"]}}},
            {"required": ["new_name"]},
            {"required": ["favorite"]},
            {"required": ["comment"]}
        ]
    });
    schema.insert(
        "anyOf".into(),
        json!([
            {"required": ["changes"]},
            {"required": ["delete"], "properties": {"delete": {"type": "string"}}},
            name_with
        ]),
    );
}

/// Change a parameter: set its expression, unit, comment or favourite, rename it (references
/// follow), delete it, or set several existing parameters at once. The design is rebuilt once
/// and the features that changed are named in the reply. One undo step.
///
/// The handler reads `changes` alone when it is given, else `delete` alone when that is text,
/// else the keys of a single change; the keys of a form it doesn't read are left unchecked.
#[derive(Debug)]
pub struct ParamChangeParams(pub ParamChangeKeys);

impl<'de> Deserialize<'de> for ParamChangeParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        if let Some(keys) = value.as_object_mut() {
            let only = if keys.contains_key("changes") {
                Some("changes")
            } else if matches!(keys.get("delete"), Some(Value::String(_))) {
                Some("delete")
            } else {
                None
            };
            // Otherwise a single change: `changes` isn't there, and `delete` isn't text.
            if let Some(only) = only {
                keys.retain(|k, _| k == only || !CHANGE_KEYS.contains(&k.as_str()));
            }
            // `value` is read only when `expression` isn't a number or text.
            else if matches!(keys.get("expression"), Some(Value::String(_) | Value::Number(_))) {
                keys.remove("value");
            }
        }
        serde_path_to_error::deserialize(&value).map(ParamChangeParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

const CHANGE_KEYS: [&str; 9] = ["changes", "delete", "name", "expression", "value", "unit", "comment", "favorite", "new_name"];

impl JsonSchema for ParamChangeParams {
    fn schema_name() -> Cow<'static, str> {
        "ParamChangeParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        ParamChangeKeys::json_schema(generator)
    }
}

/// A feature that failed to rebuild: its name and error.
#[derive(Debug, Serialize, JsonSchema)]
pub struct FailedFeature {
    /// The feature's name.
    pub feature: String,
    /// Why it failed.
    pub error: String,
}

impl FailedFeature {
    /// The features of `results` that failed.
    pub fn of(results: &[solidcraft_doc::FeatureResult]) -> Vec<FailedFeature> {
        results.iter().filter_map(|r| r.error.as_ref().map(|e| FailedFeature { feature: r.name.clone(), error: e.clone() })).collect()
    }
}

/// A feature a configuration rule switched on or off.
#[derive(Debug, Serialize, JsonSchema)]
pub struct SwitchedFeature {
    /// The feature's id.
    pub feature: u64,
    /// Its name; `null` if it is gone.
    pub name: Option<String>,
    /// Whether it is suppressed now.
    pub suppressed: bool,
}

/// A parameter that was renamed.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamRename {
    /// The old name.
    pub from: String,
    /// The new name.
    pub to: String,
    /// How many expressions, feature inputs and dimensions were changed to use the new name.
    pub references_updated: usize,
}

/// What `parameters.change` returns: one of three shapes, by what was asked.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamChanged {
    #[serde(flatten)]
    pub body: ParamChangedBody,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// The shapes of a `parameters.change` reply.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum ParamChangedBody {
    /// A parameter was deleted (`delete`).
    Deleted {
        /// The deleted parameter's name.
        deleted: String,
    },
    /// Several parameters were set (`changes`).
    Many {
        /// Each changed parameter's value, in mm for a length and degrees for an angle; `null`
        /// where it can't be worked out.
        changed: BTreeMap<String, Option<f64>>,
        /// How many features were rebuilt.
        recomputed: usize,
        /// How many features reused an earlier result for the same inputs (a value set back).
        restored: usize,
        /// The features that failed to rebuild.
        errors: Vec<FailedFeature>,
        /// The features the configuration rules switched, when they did.
        #[serde(skip_serializing_if = "Vec::is_empty")]
        switched: Vec<SwitchedFeature>,
    },
    /// One parameter was changed.
    One(Box<ParamChangedOne>),
}

/// What changing one parameter returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamChangedOne {
    /// Set when the parameter was renamed (`new_name`, or `name = expression`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub renamed: Option<ParamRename>,
    /// Set when `name = expression` set the parameter that the changed value's expression named:
    /// the name asked for.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub changed_through: Option<String>,
    /// The features the configuration rules switched, when they did.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub switched: Vec<SwitchedFeature>,
    /// The parameter's name now.
    pub name: String,
    /// The expression it has now; `null` when only its name, comment or favourite changed.
    pub expression: Option<String>,
    /// A text parameter's text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
    /// Its value in mm for a length and degrees for an angle, as in every reply; `null` if it
    /// can't be worked out.
    pub value: Option<f64>,
    /// Its value in its own unit; `null` if it can't be worked out.
    pub display_value: Option<f64>,
    /// How many features were rebuilt.
    pub recomputed: usize,
    /// How many features reused an earlier result for the same inputs (a value set back).
    pub restored: usize,
    /// The features that failed to rebuild.
    pub errors: Vec<FailedFeature>,
}

/// List the parameters: the user's, the sketch dimensions' and the feature inputs', favourites
/// first, with each one's expression, value, uses and users, and any cycles. Changes nothing.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamListKeys {
    /// Only the favourites. When true, `filter` isn't read. Default: false.
    #[serde(default, deserialize_with = "list_favorites")]
    pub favorites: Option<bool>,
    /// Which parameters, ignoring case: `all`, `user`, `sketch` (dimensions), `feature` (inputs),
    /// `model` (every one but the user's) or `favorites`. Anything else lists all. Default: all.
    #[serde(default, deserialize_with = "list_filter")]
    pub filter: Option<String>,
}

fn list_favorites<'de, D: Deserializer<'de>>(d: D) -> Result<Option<bool>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::Bool(b) => Ok(Some(b)),
        _ => Err(D::Error::custom(whole("`favorites` must be true or false"))),
    }
}

fn list_filter<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`filter` must be text")
}

/// `parameters.list`'s parameters: [`ParamListKeys`], with `filter` left unread when
/// `favorites` is true, as the handler leaves it.
#[derive(Debug)]
pub struct ParamListParams(pub ParamListKeys);

impl<'de> Deserialize<'de> for ParamListParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        if let Some(keys) = value.as_object_mut().filter(|o| o.get("favorites") == Some(&Value::Bool(true))) {
            keys.remove("filter");
        }
        serde_path_to_error::deserialize(&value).map(ParamListParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for ParamListParams {
    fn schema_name() -> Cow<'static, str> {
        "ParamListParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        ParamListKeys::json_schema(generator)
    }
}

/// One row of the parameters table.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParameterRow {
    pub name: String,
    pub expression: String,
    /// Its unit; `""` for none, `text` for a text parameter.
    pub unit: String,
    /// Its value in mm for a length and degrees for an angle, whatever its own unit; `null` if
    /// it can't be worked out (a text parameter has none).
    pub value: Option<f64>,
    /// Its value in its own unit, as the Parameters window shows it.
    pub display_value: Option<f64>,
    /// Why it can't be worked out, when it can't.
    pub error: Option<String>,
    pub comment: String,
    /// `user`, `sketch` (a dimension) or `feature` (a feature's named input).
    pub source: String,
    /// For a feature input: the feature.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub feature: Option<String>,
    /// For a feature input: the input's label.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub input: Option<String>,
    pub favorite: bool,
    /// The names its expression uses.
    pub uses: Vec<String>,
    /// The names whose expressions use it.
    pub used_by: Vec<String>,
    /// A text parameter's text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
}

impl From<ParamRow> for ParameterRow {
    fn from(r: ParamRow) -> Self {
        ParameterRow {
            name: r.name,
            expression: r.expression,
            unit: r.unit,
            value: r.value,
            display_value: r.display_value,
            error: r.error,
            comment: r.comment,
            source: r.source.to_string(),
            feature: r.feature,
            input: r.input.map(str::to_string),
            favorite: r.favorite,
            uses: r.uses,
            used_by: r.used_by,
            text: r.text,
        }
    }
}

/// What `parameters.list` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamListResult {
    /// The parameters listed, favourites first.
    pub parameters: Vec<ParameterRow>,
    /// How many there are.
    pub count: usize,
    /// The names whose expressions refer to themselves, directly or through others.
    pub cycles: Vec<String>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// List what uses a parameter: other parameters, feature inputs, sketch dimensions,
/// configurations, joints, rules and canvases, and the features it drives. Changes nothing.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamUsersParams {
    /// The parameter, by name: a user parameter, a dimension or a feature's named input.
    #[serde(deserialize_with = "param_name")]
    #[schemars(length(min = 1))]
    pub name: String,
}

/// Something that uses a parameter.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ParameterUser {
    /// Another parameter's expression (a stored one or a feature input).
    Parameter { name: String },
    /// A feature input (`input` is its label, e.g. `Distance`).
    Feature { feature: u64, name: String, input: String },
    /// A sketch dimension (`constraint` is its id).
    Dimension { feature: u64, name: String, constraint: String },
    /// A configured column or an expression saved in a configuration row.
    Configuration { row: Option<String>, column: String },
    /// A joint's offset, angle or value, or a motion link's gear, rack or screw length (`input`
    /// says which).
    Joint { joint: u64, name: String, input: String },
    /// A sheet metal or plastic rule's value (`kind` says which, `field` which value).
    Rule { kind: String, name: String, field: String },
    /// The plane a canvas lies on (`input` is its label, e.g. `Offset`).
    Canvas { canvas: u64, name: String, input: String },
}

impl From<ParamUser> for ParameterUser {
    fn from(u: ParamUser) -> Self {
        match u {
            ParamUser::Parameter { name } => ParameterUser::Parameter { name },
            ParamUser::Feature { feature, name, input } => ParameterUser::Feature { feature, name, input },
            ParamUser::Dimension { feature, name, constraint } => ParameterUser::Dimension { feature, name, constraint },
            ParamUser::Configuration { row, column } => ParameterUser::Configuration { row, column },
            ParamUser::Joint { joint, name, input } => ParameterUser::Joint { joint, name, input },
            ParamUser::Rule { kind, name, field } => ParameterUser::Rule { kind, name, field },
            ParamUser::Canvas { canvas, name, input } => ParameterUser::Canvas { canvas, name, input },
        }
    }
}

/// A feature a parameter drives.
#[derive(Debug, Serialize, JsonSchema)]
pub struct DrivenFeature {
    /// The feature's id.
    pub id: u64,
    pub name: String,
}

/// What `parameters.users` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamUsersResult {
    /// The parameter's name, spaces at either end dropped.
    pub name: String,
    /// What uses it directly.
    pub users: Vec<ParameterUser>,
    /// The features it drives, directly or through other parameters.
    pub drives: Vec<DrivenFeature>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// `parameters.graph` takes no parameters.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamGraphParams {}

/// What `parameters.graph` returns: the dependency graph of the parameters.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamGraphResult {
    /// Every parameter name: the user's, the dimensions' and the feature inputs'.
    pub nodes: Vec<String>,
    /// `[user, used]`: the first's expression uses the second; a user may be `Feature:<name>`.
    pub edges: Vec<[String; 2]>,
    /// The names whose expressions refer to themselves, directly or through others.
    pub cycles: Vec<String>,
    /// The parameters that can't be worked out, with why, by name.
    pub errors: BTreeMap<String, String>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// Export the user parameters as CSV or JSON text, and write it to a file when a path is
/// given. Changes nothing in the design.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ParamExportParams {
    /// `csv` or `json`, ignoring case. Default: `json` when `path` ends in `.json`, else `csv`.
    #[serde(default)]
    pub format: Option<String>,
    /// A file to write the text to. Default: none is written.
    #[serde(default)]
    pub path: Option<String>,
}

/// What `parameters.export` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamExportResult {
    /// The format used, `csv` or `json`.
    pub format: String,
    /// The file written; `null` if none was.
    pub path: Option<String>,
    /// The exported text.
    pub text: String,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `parameters.import` takes, as the handler reads it: see [`ParamImportParams`].
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = import_forms)]
pub struct ParamImportKeys {
    /// The table as text: CSV with a header (`name`, `expression`, and optionally `unit` and
    /// `comment`), or JSON `[{name, expression, unit?, comment?}]`. When given, `path` isn't
    /// read.
    #[serde(default, deserialize_with = "import_text", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "String")]
    pub text: Option<String>,
    /// A file to read the table from, in the same forms. Read when `text` isn't given.
    #[serde(default, deserialize_with = "import_text", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "String")]
    pub path: Option<String>,
}

/// `text` and `path`: text; `null` is left out, as `str_` reads it. Anything else gets the
/// message the handler gives when it finds neither.
fn import_text<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "give `text` or `path`")
}

/// `parameters.import` needs `text` or `path` as text.
fn import_forms(schema: &mut Schema) {
    schema.insert(
        "anyOf".into(),
        json!([
            {"required": ["text"], "properties": {"text": {"type": "string"}}},
            {"required": ["path"], "properties": {"path": {"type": "string"}}}
        ]),
    );
}

/// Add the parameters in a CSV or JSON table, all or nothing. A name that exists is refused.
/// One undo step.
///
/// `path` is not read when `text` is text, as the handler leaves it.
#[derive(Debug)]
pub struct ParamImportParams(pub ParamImportKeys);

impl<'de> Deserialize<'de> for ParamImportParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        if let Some(keys) = value.as_object_mut() {
            match keys.get("text") {
                Some(Value::String(_)) => {
                    keys.remove("path");
                }
                // Not text, so the handler reads `path`: when that works, this is the one thing
                // wrong; when it doesn't, the handler's message says what is needed.
                Some(Value::Number(_) | Value::Bool(_) | Value::Array(_) | Value::Object(_))
                    if matches!(keys.get("path"), Some(Value::String(_))) =>
                {
                    return Err(D::Error::custom(whole("`text` must be text")));
                }
                _ => {}
            }
        }
        serde_path_to_error::deserialize(&value).map(ParamImportParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for ParamImportParams {
    fn schema_name() -> Cow<'static, str> {
        "ParamImportParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        ParamImportKeys::json_schema(generator)
    }
}

/// What `parameters.import` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ParamImportResult {
    /// The names of the parameters added, in order.
    pub imported: Vec<String>,
    /// The features that failed to rebuild with them.
    pub errors: Vec<FailedFeature>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// What `expr.evaluate` takes, as the handler reads it: see [`ExprEvaluateParams`].
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = expression_required)]
pub struct ExprEvaluateKeys {
    /// The expression: text (`25 mm`, `W / 2`, `name = 3 * W`) or a number. With unit `text`, the
    /// text a text parameter would hold.
    // Optional in the type and required in the schema (`expression_required`): left out, the
    // handler refuses it with its own message.
    #[serde(default, deserialize_with = "evaluate_expression", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ExpressionText")]
    pub expression: Option<ExpressionText>,
    /// The unit the answer is shown in, and what bare numbers mean: `mm`, `cm`, `m`, `in`, `ft`,
    /// `deg`, `rad`, `""` (none) or `text` (a text parameter's text). Default: none; bare numbers
    /// follow the design's length unit.
    #[serde(default, deserialize_with = "evaluate_unit")]
    pub unit: Option<String>,
    /// What it must evaluate to: `length`, `angle` or `unitless` (`number` too). Default: the
    /// unit's kind, or what the expression is. Not read when `unit` is `text`.
    #[serde(default, deserialize_with = "evaluate_kind")]
    pub kind: Option<String>,
}

/// An expression given as text or as a number, as `expr_arg` reads it.
#[derive(Debug, Clone, PartialEq)]
pub struct ExpressionText(pub String);

impl JsonSchema for ExpressionText {
    fn schema_name() -> Cow<'static, str> {
        "ExpressionText".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({"description": "An expression as text, or a number.", "type": ["number", "string"]})
    }
}

fn evaluate_expression<'de, D: Deserializer<'de>>(d: D) -> Result<Option<ExpressionText>, D::Error> {
    match Value::deserialize(d)? {
        Value::String(s) => Ok(Some(ExpressionText(s))),
        Value::Number(n) => n
            .as_f64()
            .filter(|v| v.is_finite())
            .map(|v| Some(ExpressionText(format!("{v}"))))
            .ok_or_else(|| D::Error::custom(whole("`expression` must be text or a number"))),
        _ => Err(D::Error::custom(whole("`expression` must be text or a number"))),
    }
}

fn evaluate_unit<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`unit` must be text")
}

fn evaluate_kind<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`kind` must be text")
}

fn expression_required(schema: &mut Schema) {
    require(schema, "expression");
}

/// Evaluate an expression against the design's parameters, without changing anything: its
/// value (in mm for a length, radians for an angle), its value in the unit asked for, what it
/// names, or why it fails. `name = expression` is worth its expression and says what it would
/// define.
///
/// `kind` is not read when `unit` is `text`, as the handler leaves it.
#[derive(Debug)]
pub struct ExprEvaluateParams(pub ExprEvaluateKeys);

impl<'de> Deserialize<'de> for ExprEvaluateParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let mut value = Value::deserialize(d)?;
        if let Some(keys) = value.as_object_mut()
            && keys.get("unit").and_then(Value::as_str).is_some_and(solidcraft_doc::text_params::is_text_unit)
        {
            keys.remove("kind");
        }
        serde_path_to_error::deserialize(&value).map(ExprEvaluateParams).map_err(|e| D::Error::custom(located(&e)))
    }
}

impl JsonSchema for ExprEvaluateParams {
    fn schema_name() -> Cow<'static, str> {
        "ExprEvaluateParams".into()
    }
    fn json_schema(generator: &mut SchemaGenerator) -> Schema {
        ExprEvaluateKeys::json_schema(generator)
    }
}

/// What an evaluated expression is.
#[derive(Clone, Copy, Debug, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum EvalKind {
    Length,
    Angle,
    Unitless,
}

impl From<Kind> for EvalKind {
    fn from(k: Kind) -> Self {
        match k {
            Kind::Length => EvalKind::Length,
            Kind::Angle => EvalKind::Angle,
            Kind::Unitless => EvalKind::Unitless,
        }
    }
}

impl EvalKind {
    /// The word for it, as it's serialized.
    pub fn word(self) -> &'static str {
        match self {
            EvalKind::Length => "length",
            EvalKind::Angle => "angle",
            EvalKind::Unitless => "unitless",
        }
    }
}

/// What `expr.evaluate` returns: one of three shapes.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExprEvaluated {
    #[serde(flatten)]
    pub body: ExprEvaluatedBody,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// The shapes of an `expr.evaluate` reply.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum ExprEvaluatedBody {
    /// With unit `text`: the text a text parameter would hold.
    Text {
        /// Always true.
        ok: bool,
        /// Always `text`.
        kind: String,
        /// The text, without the quotes round it.
        text: String,
        /// Always empty.
        references: Vec<String>,
    },
    /// The expression evaluated.
    Value {
        /// Always true.
        ok: bool,
        /// Its value: mm for a length, radians for an angle.
        value: f64,
        /// What it is.
        kind: EvalKind,
        /// Its value in the unit asked for; with none, degrees for an angle and the value itself
        /// otherwise.
        display_value: f64,
        /// The parameters it names.
        references: Vec<String>,
        /// For `name = expression`: the name it would define.
        #[serde(skip_serializing_if = "Option::is_none")]
        defines: Option<String>,
    },
    /// The expression didn't evaluate.
    Failed {
        /// Always false.
        ok: bool,
        /// Why.
        error: String,
        /// The parameters it names.
        references: Vec<String>,
        /// For `name = expression`: the name it would define.
        #[serde(skip_serializing_if = "Option::is_none")]
        defines: Option<String>,
    },
}

/// Suggest completions for the word at the end of some expression text: parameters (by name,
/// anywhere in it), functions, constants and units. Changes nothing.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ExprCompleteParams {
    /// The text before the cursor; the word being typed is its trailing letters, digits and
    /// underscores. Default: empty, which lists every parameter, function and constant.
    #[serde(default, deserialize_with = "complete_prefix")]
    pub prefix: Option<String>,
}

fn complete_prefix<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    text_or_null(d, "`prefix` must be text")
}

/// What a completion is.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum CompletionKind {
    Parameter,
    Function,
    Unit,
    Constant,
}

/// One suggestion.
#[derive(Debug, Serialize, JsonSchema)]
pub struct Completion {
    /// The text to insert: a parameter's name, a function's name and `(`, a constant or a unit.
    pub text: String,
    pub kind: CompletionKind,
    /// A parameter's expression and value, a function's signature, or a unit's kind.
    pub detail: String,
}

/// What `parameters.complete` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExprCompletions {
    /// The word being completed; empty when the text ends in something else.
    pub word: String,
    /// Parameters first (names that start with the word, then the rest; favourites and user
    /// parameters first, at most 200), then functions, the constant `pi` and units.
    pub suggestions: Vec<Completion>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

#[cfg(test)]
#[path = "parameters_tests.rs"]
mod tests;