1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
//! # FerroCAD core (`ferrocad_core`)
//!
//! The pure-Rust document model behind the `FreeCAD` Python package: typed
//! properties, a document object model with a dependency graph, transactions with
//! undo/redo, observers, expressions, and FreeCAD's geometry and unit types. No
//! Python and no UI.
//!
//! This crate is the *engine*. [`ferrocad_py`](https://crates.io/crates/ferrocad_py)
//! binds it to Python, and the pure-Python `FreeCAD` facade (the `ferrocad`
//! distribution) presents it as the drop-in `import FreeCAD` package.
//!
//! The documentation is organised following [Diátaxis](https://diataxis.fr):
//! a tutorial to get started, how-to guides for common tasks, an explanation of
//! the design, and a reference (the item pages).
//!
//! # Tutorial
//!
//! Build a document, wire a dependency with an expression, and recompute it.
//!
//! ```
//! use ferrocad_core::{Document, Property};
//!
//! let mut doc = Document::new();
//! let width = doc.add_object("Width", "App::Feature");
//! let area = doc.add_object("Area", "App::Feature");
//!
//! // A value on one object…
//! doc.set_property(width, "Value", Property::Float(10.0)).unwrap();
//! // …an expression on another (dependencies are tracked automatically)…
//! doc.set_expression(area, "Result", "Width.Value * 2").unwrap();
//!
//! // …and a recompute in dependency order (returns the objects executed).
//! assert_eq!(doc.recompute().unwrap().len(), 2);
//! assert_eq!(
//! doc.object(area).unwrap().properties.get("Result"),
//! Some(&Property::Float(20.0)),
//! );
//! ```
//!
//! # How-to guides
//!
//! - **Add a typed property with flags**: [`Document::add_property`] takes a value
//! and a `PropertyType` bitmask (see [`prop_status`]); unlike [`Document::set_property`]
//! it does not touch the object. Setting a property touches it unless it is
//! `Output`/`NoRecompute`.
//! - **Undo a change**: wrap edits in [`Document::open_transaction`] …
//! [`Document::commit_transaction`], then [`Document::undo`] / [`Document::redo`].
//! - **Persist a document**: [`format::read`] / [`format::write`] select the
//! serializer by suffix (`.ferrocad` native JSON, `.FCStd` upstream);
//! [`Document::save_to_file`] / [`Document::load_from_file`] are the native
//! JSON shortcut. Properties flagged `NoPersist` are dropped from the saved form.
//! The `.FCStd` writer is [`fcstd_write::write_fcstd`], a direct-call API that
//! is not yet wired into [`format::write`].
//! - **React to changes**: register an [`Observer`] with [`Document::add_observer`].
//! - **Report a failed rebuild**: an [`object_registry::ObjectType::execute`] marks the
//! object with [`Document::mark_invalid`]; recompute keeps the flag until a later
//! execute succeeds.
//! - **Name objects**: [`Document::add_object_with`] applies FreeCAD's rules — names
//! are sanitized ([`sanitize_name`]) and made unique, labels are unique unless
//! duplicates are allowed.
//!
//! # Explanation
//!
//! A [`Document`] owns a set of [`DocumentObject`]s and a dependency graph over
//! them. Each object is a [`PropertyContainer`] — a name → value map where every
//! property also carries a status bitmask ([`prop_status`]). Recompute walks the
//! graph in dependency order and evaluates each object's expressions.
//!
//! Editing goes through transactions: [`Document::set_property`] records a
//! reversible change so a whole edit can be undone or redone. Assigning a property
//! *touches* the object (sets its `must_execute` flag) so a later recompute knows
//! what is dirty; `Output`/`NoRecompute` properties opt out.
//!
//! The value types mirror FreeCAD's `Base` module: [`Quantity`]/[`Unit`] for values
//! with units, and [`Vector3`]/[`Matrix4`]/[`Rotation`]/[`Placement`] for geometry.
//! Names are FreeCAD-compatible: internal names are sanitized and made unique,
//! display labels are a separate, user-facing string.
//!
//! # Implemented capabilities
//!
//! The crate grew milestone by milestone (see the repository `docs/record/milestones.md`):
//!
//! - **M2** — the core model: [`Property`]/[`PropertyContainer`], [`Quantity`]/[`Unit`],
//! the `petgraph` recompute DAG, transaction-backed undo/redo, [`Observer`]s,
//! and the expression parser/evaluator.
//! - **M4 (slices 1–16)** — the `Base`/`App` surface bound to Python: geometry helpers,
//! persistence (`SavedDocument`), document metadata, extensions/groups, links,
//! observers that fire, Python-object/`Proxy` persistence, expressions, and
//! matrix decomposition / rotation numerics.
//! - **MVP slice A1** — object state and per-property status flags; touch-on-assign.
//! - **MVP slice B1** — name/label semantics ([`sanitize_name`], [`Document::unique_name`]).
//! - **MVP slice A2** — [`Property::Enumeration`] and type-registry validation.
//! - **MVP slice B2** — a general reversible undo/redo change set (property edits,
//! object add/remove, expressions) with named, id-carrying transactions, an active-object
//! pointer, and FreeCAD's undo metadata ([`Document::undo_names`],
//! [`Document::getAvailableUndos`](Document::available_undos),
//! [`Document::active_object`]).
//!
//! # Reference
//!
//! The item pages (`Document`, `DocumentObject`, `Property`, the geometry and unit
//! types, and the supporting modules) are the reference. The `mod` items below are
//! the module-level documentation.
// The base value types (`Quantity`/`Unit`/geometry) live in `ferrocad_types`, a
// lower leaf crate, and are re-exported here so `ferrocad_core::Quantity` and the
// `crate::geometry::…` paths inside this crate keep working.
pub use ;
pub use ;
pub use ;
pub use fcstd;
pub use fcstd_write;
pub use format;
pub use DocumentFormat;
pub use native;
pub use ;
pub use ;
pub use Observer;
pub use ;
pub use ;
pub use ;
pub use Unit;