feat!: add form grouping, labels, and named references (CDL v1.3) (#1)

Phase 3 of CDL v2 implementation. Adds FormGroup for parenthesized form
grouping with shared features, form labels, @name/$name definitions and
references, flat_forms() backwards-compatible flattening, and 43 new
tests (163 total).

BREAKING CHANGE: CrystalDescription.forms type changed from
list[CrystalForm] to list[FormNode]. Use flat_forms() for
backwards-compatible flat list access.

Author: Bissbert

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gemmology-cdl-parser"
-version = "1.0.1"
+version = "1.3.0"
 description = "Crystal Description Language (CDL) parser for crystallographic visualization"
 readme = "README.md"
 license = { text = "MIT" }

src/cdl_parser/__init__.py

@@ -22,7 +22,7 @@
         cubic[m3m]:{111} | twin(spinel)     # Spinel-law twin
 """
 
-__version__ = "1.0.0"
+__version__ = "1.3.0"
 __author__ = "Fabian Schuh"
 __email__ = "fabian@gemmology.dev"
 
@@ -32,8 +32,10 @@
     ALL_POINT_GROUPS,
     CRYSTAL_SYSTEMS,
     DEFAULT_POINT_GROUPS,
+    FEATURE_NAMES,
     MODIFICATION_TYPES,
     NAMED_FORMS,
+    PHENOMENON_TYPES,
     POINT_GROUPS,
     TWIN_LAWS,
     TWIN_TYPES,
@@ -46,13 +48,18 @@
 from .models import (
     CrystalDescription,
     CrystalForm,
+    Definition,
+    Feature,
+    FormGroup,
+    FormNode,
     MillerIndex,
     Modification,
+    PhenomenonSpec,
     TwinSpec,
 )
 
 # Lexer/Parser internals (for advanced use)
-from .parser import Lexer, Parser, Token, TokenType, parse_cdl, validate_cdl
+from .parser import Lexer, Parser, Token, TokenType, parse_cdl, strip_comments, validate_cdl
 
 __all__ = [
     # Version
@@ -63,8 +70,13 @@
     # Data classes
     "CrystalDescription",
     "CrystalForm",
+    "Definition",
+    "Feature",
+    "FormGroup",
+    "FormNode",
     "MillerIndex",
     "Modification",
+    "PhenomenonSpec",
     "TwinSpec",
     # Exceptions
     "CDLError",
@@ -74,8 +86,10 @@
     "ALL_POINT_GROUPS",
     "CRYSTAL_SYSTEMS",
     "DEFAULT_POINT_GROUPS",
+    "FEATURE_NAMES",
     "MODIFICATION_TYPES",
     "NAMED_FORMS",
+    "PHENOMENON_TYPES",
     "POINT_GROUPS",
     "TWIN_LAWS",
     "TWIN_TYPES",
@@ -84,4 +98,5 @@
     "Parser",
     "Token",
     "TokenType",
+    "strip_comments",
 ]

src/cdl_parser/constants.py

@@ -120,6 +120,7 @@
     "truncate",  # Cut off corners/edges
     "taper",  # Make narrower in one direction
     "bevel",  # Add beveled edges
+    "flatten",  # Compress along an axis
 }
 
 # =============================================================================
@@ -131,3 +132,29 @@
     "penetration",  # Penetration twin (interpenetrating)
     "cyclic",  # Cyclic twin (multiple individuals)
 }
+
+# =============================================================================
+# Feature Names (CDL v1.2)
+# =============================================================================
+
+FEATURE_NAMES: set[str] = {
+    # Growth features
+    "phantom", "sector", "zoning", "skeletal", "dendritic",
+    # Surface features
+    "striation", "trigon", "etch_pit", "growth_hillock",
+    # Inclusion features
+    "inclusion", "needle", "silk", "fluid", "bubble",
+    # Color features
+    "colour", "colour_zone", "pleochroism",
+    # Other
+    "lamellar", "banding",
+}
+
+# =============================================================================
+# Phenomenon Types (CDL v1.2)
+# =============================================================================
+
+PHENOMENON_TYPES: set[str] = {
+    "asterism", "chatoyancy", "adularescence", "labradorescence",
+    "play_of_color", "colour_change", "aventurescence", "iridescence",
+}