Files
solidcraft/crates/doc/src/persistent_name.rs
T
JIJINBEIandClaude Opus 5.5 cdde7d62b2 Persistent names read by one parser; four misreadings fixed (#5814) (#5966)
* doc: persistent names read as their structure; joint.inspect splits an edge with a blend face first

`persistent_name::{FaceName, EdgeName}` parse a face or edge name once (blends, inner walls,
copies, pieces, numbered pieces, `~k`) and write it back as the same text, bounded against
hostile input. A suffix after a blend's edge naming a later feature belongs to the blend face.

joint.inspect split an edge at its first `|`, so an edge whose first face is a blend
(`F4:blend:F3:+x|F3:+z#[…]|F5:-y`) came back as a cut-off blend name and a string that is no
face. It now uses `EdgeName::parse`.

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

* doc: persistent names as typed values: features, roles, suffixes, a lexer and errors that say where

`FaceName` is a base (made by a feature in a role, a blend and the edge it rounds, an inner
wall, a body's face by index, other text) and its suffixes (copy, piece, numbered piece).
Roles are typed where the vocabulary is known (top, side:<curve>, +x, face:<k>, …) and kept as
written otherwise. The text form is lexed into tokens and read by the grammar in the module's
doc; a name that doesn't read says where and what was expected.

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

* names: read what made a face, its kind and its feature ids through persistent_name

The places that took a name apart by hand to find the feature that made a face, whether it is
a blend, a copy, a numbered piece or a wall, or to remap feature ids on copy, now ask the typed
name (`made_by`, `split_feature`, `is_blend`, `is_copy`, `is_numbered_piece`, `is_wall`,
`features`, `map`). A name that doesn't read falls back to the old text check.

- An offset of a face that only names a blend inside it (`F2:top#[F5:blend:…]`) is no longer
  taken for a fillet's.
- Copying a component remaps feature ids inside a piece's `#[…]` too.
- A shell's inner wall split by a later cut keeps the qualifier on the wall.
- joint.inspect finds the sketch curve of a copied side (`side:l1@F7.2`).

Finding a face by name (strip_piece, parent_piece) is unchanged: it reads a trailing
qualifier as the whole name's and moves once the text form says where it belongs.

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

* engine: regression tests for press-pull on a wall that only names a fillet and joint.inspect on a copied side

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

* names: an edge holds one face or more; made_by reads only the leading token

An open boundary's edge has one face and an edge several faces meet at has more, so an edge name
is a list of faces (a blend's own edge still takes two at most, as before). `made_by` reads just
the leading `F<n>:`, which every name a feature made starts with, so asking it of every face
each frame stays cheap. Names are read up to 1 MiB: a face engraved with text has piece names
past 4 KiB.

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

* persistent_name: split into lexer, parser, write, text and tests

No code changed; callers' paths stay the same (`pub use text::*`).

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 01:48:26 +00:00

311 lines
11 KiB
Rust

//! Persistent face and edge names as values, and their text form.
//!
//! A face name says what made the face: a feature and its role there (`F2:top`, `F2:side:l4`), a
//! fillet or chamfer and the edge it rounds (`F5:blend:<edge>`), a shell and the face it offsets
//! (`F3:inner:<face>`), or, without history, a body and an index (`Body1:face:3`). Suffixes
//! follow: a pattern copy (`@F7.2`), a piece of a split face told apart by the faces around it
//! (`#[<face>,…]`, `#k` after it for a tie), an older design's numbered piece (`#k`). An edge is
//! the two faces it separates, `~k` for one of several between them.
//!
//! The text form, read by [`FaceName::parse`] and [`EdgeName::parse`] and written by `Display`:
//!
//! ```text
//! edge = face { "|" face } [TIE] one face for an open boundary, more where several meet
//! face = base { suffix }
//! base = FEATURE ":" "blend" ":" ( edge | NUMBER )
//! | FEATURE ":" "inner" ":" face
//! | FEATURE ":" role
//! | text (`<body>:face:<k>`, or any other text)
//! suffix = COPY | "#[" face { "," face } "]" [HASH] | HASH
//! FEATURE = "F" NUMBER COPY = "@F" NUMBER "." NUMBER
//! HASH = "#" NUMBER TIE = "~" NUMBER
//! ```
//!
//! Suffixes after a nested name are ambiguous in the text: in `F5:blend:A|B#[…]` the qualifier
//! may split `B` (the fillet rounds an edge of a piece made before it) or the fillet face itself
//! (a later cut split it), and so for a shell's inner wall `F3:inner:X#[…]`. A suffix naming a
//! feature later than the outer face's belongs to the outer face; any other stays inside, so a
//! later cut told apart only by older faces reads as a piece of the inner name. A `~k` ending an
//! edge numbers that edge, not a blend's edge inside it.
//!
//! Finding a face by name still goes through `naming::strip_piece` and `parent_piece`, which
//! read a trailing qualifier as the whole name's; they move here once the text form says where a
//! qualifier belongs.
//!
//! Reading is bounded in length and depth and never panics; whatever it reads writes back as the
//! same text.
/// The longest name read.
/// The longest name read. Names of pieces list their neighbours and grow with every split: a face
/// engraved with text passes 4 KiB.
pub const MAX_NAME_LEN: usize = 1 << 20;
/// The deepest nesting read (blends of blends, pieces of pieces).
const MAX_DEPTH: usize = 32;
/// A feature of the timeline, as names refer to it (`F12`).
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct FeatureId(pub u64);
/// A persistent face name.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FaceName {
pub base: Base,
/// Innermost first.
pub suffixes: Vec<Suffix>,
}
/// What made a face.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Base {
/// `F<feature>:<role>`.
Made { feature: FeatureId, role: Role },
/// `F<feature>:blend:…`: a fillet or chamfer face.
Blend { feature: FeatureId, rounds: Rounds },
/// `F<feature>:inner:<face>`: a shell's inner wall.
Inner { feature: FeatureId, offsets: Box<FaceName> },
/// `<body>:face:<k>`: a face of a body without history, by index.
BodyFace { body: String, index: u32 },
/// Text of no form above.
Other(String),
}
/// What a blend face rounds.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Rounds {
/// The edge, by name.
Edge(Box<EdgeName>),
/// The edge's index among the feature's edges (no name was known).
Index(u32),
}
/// A face's role in the feature that made it.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Role {
Top,
Bottom,
Start,
End,
Base,
Section,
/// `side`: a cylinder's wall, or a tool's faces swept from its whole profile.
Wall,
/// `side:<curve>`, `side:s<k>.<curve>` for profile `k`: swept from a sketch curve.
Side {
profile: Option<u32>,
curve: String,
},
/// `+x`, `-z`, …: a box's face.
BoxFace {
axis: Axis,
high: bool,
},
/// `face:<k>`: the feature's face `k`, named from geometry.
Index(u32),
/// A role of another form (a cap's, a tool part's, a sheet's), as written.
Other(String),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Axis {
X,
Y,
Z,
}
/// What follows a face's base.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Suffix {
/// `@F<feature>.<instance>`: a pattern or mirror copy.
Copy { feature: FeatureId, instance: u32 },
/// `#[…]`, `#k` after it: a piece of a split face.
Piece(Qualifier),
/// `#k`: a numbered piece of a design saved before format 14.
Numbered(u32),
}
/// The faces only one piece of a split face touches, and its number among pieces they don't
/// tell apart.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Qualifier {
around: Vec<FaceName>,
pub tie: Option<u32>,
}
/// A persistent edge name.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct EdgeName {
/// The faces it separates, in order: two, one for an open boundary, more where several
/// faces meet.
pub faces: Vec<FaceName>,
pub tie: Option<u32>,
}
/// Why a name could not be read.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum NameError {
TooLong,
TooDeep,
/// At byte `at`, something else was expected.
Expected {
at: usize,
what: &'static str,
},
}
impl FaceName {
/// The feature that made the face: its base's, a copy's when it is one.
pub fn feature(&self) -> Option<FeatureId> {
let copied = self.suffixes.iter().rev().find_map(|s| match s {
Suffix::Copy { feature, .. } => Some(*feature),
_ => None,
});
copied.or(match &self.base {
Base::Made { feature, .. } | Base::Blend { feature, .. } | Base::Inner { feature, .. } => Some(*feature),
Base::BodyFace { .. } | Base::Other(_) => None,
})
}
/// The face this one is a piece of: the trailing piece suffixes off.
pub fn stem(&self) -> FaceName {
let keep = self.suffixes.iter().rposition(|s| matches!(s, Suffix::Copy { .. })).map_or(0, |i| i + 1);
FaceName { base: self.base.clone(), suffixes: self.suffixes.get(..keep).unwrap_or_default().to_vec() }
}
}
impl Qualifier {
/// A qualifier listing `around`, at least one face.
pub fn new(around: Vec<FaceName>, tie: Option<u32>) -> Option<Qualifier> {
(!around.is_empty()).then_some(Qualifier { around, tie })
}
pub fn around(&self) -> &[FaceName] {
&self.around
}
}
/// Where a feature id sits in a name.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Place {
/// It names what made a face: a base, a nested face's base, a copy.
Name,
/// It names a face around a piece (`#[…]`).
Qualifier,
}
impl FaceName {
/// The feature whose `F<n>:` starts the name.
pub fn made_by(&self) -> Option<FeatureId> {
match &self.base {
Base::Made { feature, .. } | Base::Blend { feature, .. } | Base::Inner { feature, .. } => Some(*feature),
Base::BodyFace { .. } | Base::Other(_) => None,
}
}
/// Every feature id in the name, in the order the text gives them.
pub fn features(&self) -> Vec<FeatureId> {
let mut out = Vec::new();
self.push_features(&mut out);
out
}
fn push_features(&self, out: &mut Vec<FeatureId>) {
match &self.base {
Base::Made { feature, .. } | Base::Blend { feature, rounds: Rounds::Index(_) } => out.push(*feature),
Base::Blend { feature, rounds: Rounds::Edge(e) } => {
out.push(*feature);
e.faces.iter().for_each(|f| f.push_features(out));
}
Base::Inner { feature, offsets } => {
out.push(*feature);
offsets.push_features(out);
}
Base::BodyFace { .. } | Base::Other(_) => {}
}
for s in &self.suffixes {
match s {
Suffix::Copy { feature, .. } => out.push(*feature),
Suffix::Piece(q) => q.around.iter().for_each(|f| f.push_features(out)),
Suffix::Numbered(_) => {}
}
}
}
/// A fillet's or chamfer's face (a piece or copy of one too).
pub fn is_blend(&self) -> bool {
matches!(self.base, Base::Blend { .. })
}
/// A pattern's or mirror's copy of a face (a piece of one too).
pub fn is_copy(&self) -> bool {
self.suffixes.iter().any(|s| matches!(s, Suffix::Copy { .. }))
}
/// A piece told apart by a number: an older design's numbered piece, or a tie.
pub fn is_numbered_piece(&self) -> bool {
self.suffixes.iter().any(|s| matches!(s, Suffix::Numbered(_) | Suffix::Piece(Qualifier { tie: Some(_), .. })))
}
/// The name with each feature id mapped by `f` (given where it sits) and each body face's
/// body by `body`; `None` when `f` refuses one. A role's text is left as written.
pub fn map(&self, f: &mut impl FnMut(FeatureId, Place) -> Option<FeatureId>, body: &mut impl FnMut(&str) -> Option<String>) -> Option<FaceName> {
self.map_in(Place::Name, f, body)
}
fn map_in(
&self,
place: Place,
f: &mut impl FnMut(FeatureId, Place) -> Option<FeatureId>,
body: &mut impl FnMut(&str) -> Option<String>,
) -> Option<FaceName> {
let base = match &self.base {
Base::Made { feature, role } => Base::Made { feature: f(*feature, place)?, role: role.clone() },
Base::Blend { feature, rounds } => {
let rounds = match rounds {
Rounds::Edge(e) => Rounds::Edge(Box::new(e.map_in(place, f, body)?)),
Rounds::Index(k) => Rounds::Index(*k),
};
Base::Blend { feature: f(*feature, place)?, rounds }
}
Base::Inner { feature, offsets } => {
let offsets = Box::new(offsets.map_in(place, f, body)?);
Base::Inner { feature: f(*feature, place)?, offsets }
}
Base::BodyFace { body: b, index } => Base::BodyFace { body: body(b).unwrap_or_else(|| b.clone()), index: *index },
Base::Other(t) => Base::Other(t.clone()),
};
let mut suffixes = Vec::with_capacity(self.suffixes.len());
for s in &self.suffixes {
suffixes.push(match s {
Suffix::Copy { feature, instance } => Suffix::Copy { feature: f(*feature, place)?, instance: *instance },
Suffix::Piece(q) => {
let around = q.around.iter().map(|a| a.map_in(Place::Qualifier, f, body)).collect::<Option<Vec<_>>>()?;
Suffix::Piece(Qualifier { around, tie: q.tie })
}
Suffix::Numbered(k) => Suffix::Numbered(*k),
});
}
Some(FaceName { base, suffixes })
}
}
impl EdgeName {
fn map_in(
&self,
place: Place,
f: &mut impl FnMut(FeatureId, Place) -> Option<FeatureId>,
body: &mut impl FnMut(&str) -> Option<String>,
) -> Option<EdgeName> {
let faces = self.faces.iter().map(|x| x.map_in(place, f, body)).collect::<Option<Vec<_>>>()?;
Some(EdgeName { faces, tie: self.tie })
}
}
mod lexer;
mod parser;
#[cfg(test)]
mod tests;
mod text;
mod write;
pub use text::*;