Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Update firmament-language-shape.md

Yuechen Lifcb5af61578e
diff --git a/docs/firmament-language-shape.md b/docs/firmament-language-shape.md
index d93e3a45..3637a2ee 100644
--- a/docs/firmament-language-shape.md
+++ b/docs/firmament-language-shape.md
@@ -8,12 +8,24 @@ The syntax style is **TOON-shaped indentation syntax**, not JSON.
---
-# Top-Level File Structure
+# Minimal Valid Firmament File
-Every `.firmament` file follows this section order:
+```
+firmament:
+ version: 1
+model:
+ name: demo
+ units: mm
+
+ops[0]:
```
+---
+# Top-Level File Structure
+
+Every `.firmament` file follows this section order:
+```
firmament:
version: 1
@@ -27,9 +39,7 @@ schema:
ops[0]:
pmi[0]:
-
```
-
Rules:
1. `firmament`, `model`, and `ops` are required.
@@ -37,6 +47,7 @@ Rules:
3. Section order is fixed.
4. Unknown top-level sections are not allowed.
5. All indentation is two spaces.
+6. Tabs must never be used.
---
@@ -46,34 +57,17 @@ Empty arrays must use **explicit array-length syntax**.
### Correct
-```
-
-ops[0]:
-
-```
-```
-
-pmi[0]:
+`ops[0]:`
-```
+`pmi[0]:`
### Incorrect
-```
+`ops: []`
-ops: []
+`ops:`
-```
-```
-
-ops:
-
-```
-```
-
-pmi: []
-
-```
+`pmi: []`
---
@@ -84,12 +78,12 @@ Example primitive feature:
```
ops[1]:
-
- op: box
- id: base_plate
- size[3]:
- 100
- 50
- 10
+ op: box
+ id: base_plate
+ size[3]:
+ 100
+ 50
+ 10
```
Rules:
@@ -103,24 +97,24 @@ Rules:
# Canonical Multiple Operations
Example with two operations:
-
```
-## ops[2]:
+ops[2]:
-
- op: box
- id: b1
- size[3]:
- 100
- 50
- 10
+ op: box
+ id: b1
+ size[3]:
+ 100
+ 50
+ 10
+
-
- op: subtract
- id: cut1
- from: b1
- with: {op: cylinder}
+ op: subtract
+ id: cut1
+ from: b1
+ with:
+ op: cylinder
```
-
Rules:
- Each op entry begins with `-`
@@ -132,7 +126,6 @@ Rules:
# Primitive Operation Shapes
## box
-
```
op: box
id: base
@@ -141,59 +134,47 @@ size[3]:
50
10
```
-
## cylinder
-
```
op: cylinder
id: hole
radius: 5
height: 20
```
-
## sphere
-
```
op: sphere
id: ball
radius: 12
```
-
---
# Boolean Operation Shapes
## add
-
```
-
op: add
id: join1
to: base
-with: {op: cylinder}
-
+with:
+ op: cylinder
```
-
## subtract
-
```
-
op: subtract
id: cut1
from: base
-with: {op: cylinder}
-
+with:
+ op: cylinder
```
-
## intersect
-
```
op: intersect
id: clip1
left: base
-with: {op: sphere}
+with:
+ op: sphere
```
-
Notes:
- `with` contains the tool operation
@@ -206,30 +187,20 @@ Notes:
Validation operations do not create geometry.
## expect_exists
-
```
-
op: expect_exists
target: base
-
```
-
## expect_selectable
-
```
-
op: expect_selectable
target: hole
count: 4
-
```
-
## expect_manifold
-
```
op: expect_manifold
```
-
---
# Scalar Style
@@ -237,23 +208,17 @@ op: expect_manifold
Use simple scalars wherever possible.
### Correct
-
```
version: 1
units: mm
radius: 10
```
-
### Avoid unnecessary quoting
Incorrect:
-```
-
-units: "mm"
-version: "1"
-
-```
+`units: "mm"`
+`version: "1"`
---
@@ -263,22 +228,14 @@ Selectors reference previously created features.
Format:
-```
-
-feature_id
-feature_id.sub_element
-
-```
+`feature_id`
+`feature_id.sub_element`
Examples:
-```
-
-base
-base.top_face
-hole.entry_face
-
-````
+`base`
+`base.top_face`
+`hole.entry_face`
Selector resolution is handled by the compiler.
@@ -288,16 +245,14 @@ Selector resolution is handled by the compiler.
`.firmament` source files must **never** be written as JSON.
-### Forbidden
-
-```json
+Example of forbidden format:
+```
{
"firmament": { "version": "1" },
"model": { "name": "demo", "units": "mm" },
"ops": []
}
-````
-
+```
Firmament source is always written using canonical indentation syntax.
---
@@ -306,9 +261,7 @@ Firmament source is always written using canonical indentation syntax.
All `.firmament` fixtures under:
-```
-testdata/firmament/fixtures/
-```
+`testdata/firmament/fixtures/`
must follow this canonical format exactly.