openscad-parser 2.3.4__tar.gz → 2.4.1__tar.gz

{openscad_parser-2.3.4 → openscad_parser-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_parser
-Version: 2.3.4
+Version: 2.4.1
 Summary: A PEG parser to read OpenSCAD language source code, with optional AST tree generation.
 Keywords: openscad,openscad parser,parser
 Author: Revar Desmera
@@ -14,6 +14,9 @@ Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Artistic Software
 Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
 Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
@@ -62,6 +65,8 @@ Features
 - AST tree can contain comment nodes (single-line and multi-line)
 - AST tree uses dataclasses and can be pickled/unpickled for caching/serialization
 - JSON and YAML serialization/deserialization of AST trees
+- Pretty-printer that converts an AST back to formatted OpenSCAD source (``to_openscad()``)
+- Command-line interface (``openscad-parser``) for JSON/YAML/formatted output
 
 Installation
 ------------
@@ -355,107 +360,129 @@ Parsing Library Files
 AST Node Types
 --------------
 
-The AST includes comprehensive node types for all OpenSCAD language constructs:
+The AST includes comprehensive node types for all OpenSCAD language constructs.
+All nodes inherit from ``ASTNode`` and carry ``position: Position`` and ``scope: Scope | None`` attributes.
 
 Base Classes
 ~~~~~~~~~~~~
 
-- ``ASTNode``: Base class for all AST nodes (includes ``position`` attribute)
+- ``ASTNode(position: Position, scope: Scope | None)``: Base class for all AST nodes
 - ``Expression``: Base class for all expression nodes
-- ``Primary``: Base class for atomic value types
+- ``Primary``: Base class for atomic value types (extends ``Expression``)
 - ``ModuleInstantiation``: Base class for module-related statements
+- ``VectorElement``: Base class for list comprehension elements
 
 Literals
 ~~~~~~~~
 
-- ``Identifier``: Variable, function, or module names
-- ``StringLiteral``: String values
-- ``NumberLiteral``: Numeric values
-- ``BooleanLiteral``: true/false values
-- ``UndefinedLiteral``: undef value
-- ``RangeLiteral``: Range expressions [start:end:step]
+- ``Identifier(name: str)``: Variable, function, or module names
+- ``StringLiteral(val: str)``: String values
+- ``NumberLiteral(val: float)``: Numeric values
+- ``BooleanLiteral(val: bool)``: true/false values
+- ``UndefinedLiteral``: The ``undef`` value (no additional fields)
+- ``RangeLiteral(start: Expression, end: Expression, step: Expression)``: Range expressions ``[start:step:end]``
 
 Operators
 ~~~~~~~~~
 
+All operators inherit from ``Expression`` and represent their respective operations with typed fields for operands. The AST preserves operator precedence and associativity as defined in OpenSCAD.
+
 Arithmetic:
-- ``AdditionOp``, ``SubtractionOp``, ``MultiplicationOp``, ``DivisionOp``
-- ``ModuloOp``, ``ExponentOp``, ``UnaryMinusOp``
+
+- ``AdditionOp(left: Expression, right: Expression)``:  represents ``left + right``
+- ``SubtractionOp(left: Expression, right: Expression)``:  represents ``left - right``
+- ``MultiplicationOp(left: Expression, right: Expression)``:  represents ``left * right``
+- ``DivisionOp(left: Expression, right: Expression)``:  represents ``left / right``
+- ``ModuloOp(left: Expression, right: Expression)``:  represents ``left % right``
+- ``ExponentOp(left: Expression, right: Expression)``:  represents ``left ^ right``
+- ``UnaryMinusOp(expr: Expression)``:  represents ``-expr``
 
 Logical:
-- ``LogicalAndOp``, ``LogicalOrOp``, ``LogicalNotOp``
+
+- ``LogicalAndOp(left: Expression, right: Expression)``:  represents ``left && right``
+- ``LogicalOrOp(left: Expression, right: Expression)``:  represents ``left || right``
+- ``LogicalNotOp(expr: Expression)``:  represents ``!expr``
 
 Comparison:
-- ``EqualityOp``, ``InequalityOp``
-- ``GreaterThanOp``, ``GreaterThanOrEqualOp``
-- ``LessThanOp``, ``LessThanOrEqualOp``
+
+- ``EqualityOp(left: Expression, right: Expression)``: represents ``left == right``
+- ``InequalityOp(left: Expression, right: Expression)``: represents ``left != right``
+- ``GreaterThanOp(left: Expression, right: Expression)``: represents ``left > right``
+- ``GreaterThanOrEqualOp(left: Expression, right: Expression)``: represents ``left >= right``
+- ``LessThanOp(left: Expression, right: Expression)``: represents ``left < right``
+- ``LessThanOrEqualOp(left: Expression, right: Expression)``: represents ``left <= right``
 
 Bitwise:
-- ``BitwiseAndOp``, ``BitwiseOrOp``, ``BitwiseNotOp``
-- ``BitwiseShiftLeftOp``, ``BitwiseShiftRightOp``
+
+- ``BitwiseAndOp(left: Expression, right: Expression)``: represents ``left & right``
+- ``BitwiseOrOp(left: Expression, right: Expression)``: represents ``left | right``
+- ``BitwiseShiftLeftOp(left: Expression, right: Expression)``: represents ``left << right``
+- ``BitwiseShiftRightOp(left: Expression, right: Expression)``: represents ``left >> right``
+- ``BitwiseNotOp(expr: Expression)``: represents ``~expr``
 
 Other:
-- ``TernaryOp``: condition ? true_expr : false_expr
+
+- ``TernaryOp(condition: Expression, true_expr: Expression, false_expr: Expression)``: Represents ``condition ? true_expr : false_expr``
 
 Expressions
 ~~~~~~~~~~~
 
-- ``LetOp``: let(assignments) body
-- ``EchoOp``: echo(arguments) body
-- ``AssertOp``: assert(arguments) body
-- ``FunctionLiteral``: function(parameters) body
-- ``PrimaryCall``: function calls
-- ``PrimaryIndex``: array indexing [index]
-- ``PrimaryMember``: member access .member
+- ``LetOp(assignments: list[Assignment], body: Expression)``: let clause  ``let(assignments) body``
+- ``EchoOp(arguments: list[Argument], body: Expression)``: echo clause  ``echo(arguments) body``
+- ``AssertOp(arguments: list[Argument], body: Expression)``: assert clause  ``assert(arguments) body``
+- ``FunctionLiteral(parameters: list[ParameterDeclaration], body: Expression)``: Anonymous function expression  ``function(parameters) body``
+- ``PrimaryCall(left: Expression, arguments: list[Argument])``: Function calls  ``left(arguments)``
+- ``PrimaryIndex(left: Expression, index: Expression)``: Array indexing ``left[index]``
+- ``PrimaryMember(left: Expression, member: Identifier)``: Member access ``left.member``
 
 List Comprehensions
 ~~~~~~~~~~~~~~~~~~~
 
-- ``ListComprehension``: Vector/list literals
-- ``ListCompFor``: for loops in list comprehensions
-- ``ListCompCFor``: C-style for loops
-- ``ListCompIf``, ``ListCompIfElse``: Conditionals
-- ``ListCompLet``: let expressions
-- ``ListCompEach``: each expressions
+- ``ListComprehension(elements: list[VectorElement])``: Vector/list literals ``[elements]``
+- ``ListCompFor(assignments: list[Assignment], body: VectorElement)``: for loops in list comprehensions ``for(assignments) body``
+- ``ListCompCFor(inits: list[Assignment], condition: Expression, incrs: list[Assignment], body: VectorElement)``: C-style for loops in list comprehensions ``for(inits; condition; incrs) body``
+- ``ListCompIf(condition: Expression, true_expr: VectorElement)``: Conditional inclusion without else ``if(condition) true_expr``
+- ``ListCompIfElse(condition: Expression, true_expr: VectorElement, false_expr: VectorElement)``: Conditional inclusion with else ``if(condition) true_expr else false_expr``
+- ``ListCompLet(assignments: list[Assignment], body: VectorElement)``: let expressions in list comprehensions ``let(assignments) body``
+- ``ListCompEach(body: VectorElement)``: each expressions (flattens nested lists) ``each body``
 
 Module Instantiations
 ~~~~~~~~~~~~~~~~~~~~~
 
-- ``ModularCall``: Module calls with arguments and children
-- ``ModularFor``: for loops
-- ``ModularCFor``: C-style for loops
-- ``ModularIntersectionFor``: intersection_for loops
-- ``ModularIntersectionCFor``: C-style intersection_for loops
-- ``ModularLet``: let statements
-- ``ModularEcho``: echo statements
-- ``ModularAssert``: assert statements
-- ``ModularIf``, ``ModularIfElse``: if/else statements
-- ``ModularModifierShowOnly``: ``!`` modifier
-- ``ModularModifierHighlight``: ``#`` modifier
-- ``ModularModifierBackground``: ``%`` modifier
-- ``ModularModifierDisable``: ``*`` modifier
+- ``ModularCall(name: Identifier, arguments: list[Argument], children: list[ModuleInstantiation])``: Module calls ``name(arguments) { children }``
+- ``ModularFor(assignments: list[Assignment], body: ModuleInstantiation)``: for loops in module bodies ``for(assignments) body``
+- ``ModularIntersectionFor(assignments: list[Assignment], body: ModuleInstantiation)``: intersection_for loops ``intersection_for(assignments) body``
+- ``ModularLet(assignments: list[Assignment], children: list[ModuleInstantiation])``: let statements in module bodies ``let(assignments) { children }``
+- ``ModularEcho(arguments: list[Argument], children: list[ModuleInstantiation])``: echo statements in module bodies ``echo(arguments) { children }``
+- ``ModularAssert(arguments: list[Argument], children: list[ModuleInstantiation])``: assert statements in module bodies ``assert(arguments) { children }``
+- ``ModularIf(condition: Expression, true_branch: ModuleInstantiation)``: if statements in module bodies, with no else ``if(condition) true_branch``
+- ``ModularIfElse(condition: Expression, true_branch: ModuleInstantiation, false_branch: ModuleInstantiation)``: if/else statements in module bodies ``if(condition) true_branch else false_branch``
+- ``ModularModifierShowOnly(child: ModuleInstantiation)``: Show-Only modifier ``!child``
+- ``ModularModifierHighlight(child: ModuleInstantiation)``: Highlight modifier ``#child``
+- ``ModularModifierBackground(child: ModuleInstantiation)``: Background modifier ``%child``
+- ``ModularModifierDisable(child: ModuleInstantiation)``: Disabler modifier ``*child``
 
 Declarations
 ~~~~~~~~~~~~
 
-- ``ModuleDeclaration``: module definitions
-- ``FunctionDeclaration``: function definitions
-- ``ParameterDeclaration``: function/module parameters
-- ``Assignment``: variable assignments
+- ``ModuleDeclaration(name: Identifier, parameters: list[ParameterDeclaration], children: list[ModuleInstantiation | Assignment | FunctionDeclaration | ModuleDeclaration])``: Module definitions ``module name(parameters) { children }``
+- ``FunctionDeclaration(name: Identifier, parameters: list[ParameterDeclaration], expr: Expression)``: Function definitions ``function name(parameters) = expr;``
+- ``ParameterDeclaration(name: Identifier, default: Expression | None)``: Function/module parameter with optional default value  ``name=default`` or ``name``
+- ``Assignment(name: Identifier, expr: Expression)``: Variable assignments ``name = expr;``
 
 Statements
 ~~~~~~~~~~
 
-- ``UseStatement``: use <filepath>
-- ``IncludeStatement``: include <filepath>
-- ``PositionalArgument``: Function call positional arguments
-- ``NamedArgument``: Function call named arguments (name=value)
+- ``UseStatement(filepath: StringLiteral)``: Represents ``use <filepath>``
+- ``IncludeStatement(filepath: StringLiteral)``: Represents ``include <filepath>``
+- ``PositionalArgument(expr: Expression)``: Function call positional arguments ``expr``
+- ``NamedArgument(name: Identifier, expr: Expression)``: Function call named arguments ``name=expr``
 
 Comments
 ~~~~~~~~
 
-- ``CommentLine``: Single-line comments //
-- ``CommentSpan``: Multi-line comments ``/* */``
+- ``CommentLine(text: str)``: Single-line comments ``// str``
+- ``CommentSpan(text: str)``: Multi-line comments ``/* str */``
 
 All AST node classes are fully documented with docstrings that include:
 - Description of what the node represents
@@ -552,6 +579,13 @@ Main Functions
     - ``scope.lookup_module(name)`` — search this scope and its parents
     - ``scope.parent`` — the enclosing scope (``None`` for root)
 
+``to_openscad(nodes: list[ASTNode], indent_width: int = 4)``
+    Convert a list of AST nodes to formatted OpenSCAD source code.
+
+    :param nodes: Top-level AST nodes as returned by the ``getAST*`` functions.
+    :param indent_width: Spaces per indentation level (default: 4).
+    :returns: Formatted OpenSCAD source as a string.
+
 Serialization Functions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -759,6 +793,100 @@ They are also available from ``openscad_parser.ast.serialization``::
         ast_from_yaml,
     )
 
+Pretty-Printing
+---------------
+
+The ``to_openscad()`` function converts an AST back to formatted OpenSCAD source code::
+
+    from openscad_parser.ast import getASTfromString, to_openscad
+
+    code = "module box(w,h){cube([w,h,1]);}"
+    ast = getASTfromString(code)
+
+    formatted = to_openscad(ast)
+    # module box(w, h) {
+    #     cube([w, h, 1.0]);
+    # }
+    print(formatted)
+
+The pretty-printer normalises whitespace and indentation while preserving the logical
+structure of the code. It supports all AST node types including modules, functions,
+control structures, modifiers, list comprehensions, and comments.
+
+``to_openscad(nodes, indent_width=4)``
+    Convert a list of AST nodes to formatted OpenSCAD source.
+
+    :param nodes: Top-level AST nodes (as returned by ``getAST*`` functions).
+    :param indent_width: Spaces per indentation level (default: 4).
+    :returns: Formatted OpenSCAD source code as a string.
+
+    - Blank lines are inserted before and after module/function declarations.
+    - Single-child module instantiations are formatted inline; multiple children use a block.
+    - Comments are preserved when the AST was parsed with ``include_comments=True``.
+
+Controlling indentation::
+
+    from openscad_parser.ast import getASTfromString, to_openscad
+
+    ast = getASTfromString("module m() { cube(1); }")
+    print(to_openscad(ast, indent_width=2))
+    # module m() {
+    #   cube(1.0);
+    # }
+
+Command-Line Interface
+-----------------------
+
+The ``openscad-parser`` CLI is installed alongside the package::
+
+    pip install openscad-parser
+
+Usage::
+
+    openscad-parser [OPTIONS] [FILE]
+
+Read from a file or ``-`` for stdin. Default output is JSON.
+
+**Options:**
+
+``--json``
+    Output AST as JSON (default).
+
+``--yaml``
+    Output AST as YAML (requires ``pip install openscad_parser[yaml]``).
+
+``--format``
+    Output reformatted OpenSCAD source code.
+
+``--indent N``
+    Indentation width in spaces (default: 4). Applies to ``--format`` and ``--json``.
+
+``--include-comments``
+    Include comment nodes in the output.
+
+``--no-includes``
+    Do not expand ``include <...>`` statements; keep ``IncludeStatement`` nodes instead.
+
+**Examples:**
+
+Dump AST as JSON::
+
+    openscad-parser model.scad
+    openscad-parser - < model.scad         # stdin
+
+Reformat OpenSCAD source::
+
+    openscad-parser --format model.scad
+    openscad-parser --format --indent 2 model.scad
+
+Output YAML::
+
+    openscad-parser --yaml model.scad
+
+Include comments in the AST::
+
+    openscad-parser --include-comments --json model.scad
+
 Error Handling
 --------------
 

{openscad_parser-2.3.4 → openscad_parser-2.4.1}/README.rst

@@ -22,6 +22,8 @@ Features
 - AST tree can contain comment nodes (single-line and multi-line)
 - AST tree uses dataclasses and can be pickled/unpickled for caching/serialization
 - JSON and YAML serialization/deserialization of AST trees
+- Pretty-printer that converts an AST back to formatted OpenSCAD source (``to_openscad()``)
+- Command-line interface (``openscad-parser``) for JSON/YAML/formatted output
 
 Installation
 ------------
@@ -315,107 +317,129 @@ Parsing Library Files
 AST Node Types
 --------------
 
-The AST includes comprehensive node types for all OpenSCAD language constructs:
+The AST includes comprehensive node types for all OpenSCAD language constructs.
+All nodes inherit from ``ASTNode`` and carry ``position: Position`` and ``scope: Scope | None`` attributes.
 
 Base Classes
 ~~~~~~~~~~~~
 
-- ``ASTNode``: Base class for all AST nodes (includes ``position`` attribute)
+- ``ASTNode(position: Position, scope: Scope | None)``: Base class for all AST nodes
 - ``Expression``: Base class for all expression nodes
-- ``Primary``: Base class for atomic value types
+- ``Primary``: Base class for atomic value types (extends ``Expression``)
 - ``ModuleInstantiation``: Base class for module-related statements
+- ``VectorElement``: Base class for list comprehension elements
 
 Literals
 ~~~~~~~~
 
-- ``Identifier``: Variable, function, or module names
-- ``StringLiteral``: String values
-- ``NumberLiteral``: Numeric values
-- ``BooleanLiteral``: true/false values
-- ``UndefinedLiteral``: undef value
-- ``RangeLiteral``: Range expressions [start:end:step]
+- ``Identifier(name: str)``: Variable, function, or module names
+- ``StringLiteral(val: str)``: String values
+- ``NumberLiteral(val: float)``: Numeric values
+- ``BooleanLiteral(val: bool)``: true/false values
+- ``UndefinedLiteral``: The ``undef`` value (no additional fields)
+- ``RangeLiteral(start: Expression, end: Expression, step: Expression)``: Range expressions ``[start:step:end]``
 
 Operators
 ~~~~~~~~~
 
+All operators inherit from ``Expression`` and represent their respective operations with typed fields for operands. The AST preserves operator precedence and associativity as defined in OpenSCAD.
+
 Arithmetic:
-- ``AdditionOp``, ``SubtractionOp``, ``MultiplicationOp``, ``DivisionOp``
-- ``ModuloOp``, ``ExponentOp``, ``UnaryMinusOp``
+
+- ``AdditionOp(left: Expression, right: Expression)``:  represents ``left + right``
+- ``SubtractionOp(left: Expression, right: Expression)``:  represents ``left - right``
+- ``MultiplicationOp(left: Expression, right: Expression)``:  represents ``left * right``
+- ``DivisionOp(left: Expression, right: Expression)``:  represents ``left / right``
+- ``ModuloOp(left: Expression, right: Expression)``:  represents ``left % right``
+- ``ExponentOp(left: Expression, right: Expression)``:  represents ``left ^ right``
+- ``UnaryMinusOp(expr: Expression)``:  represents ``-expr``
 
 Logical:
-- ``LogicalAndOp``, ``LogicalOrOp``, ``LogicalNotOp``
+
+- ``LogicalAndOp(left: Expression, right: Expression)``:  represents ``left && right``
+- ``LogicalOrOp(left: Expression, right: Expression)``:  represents ``left || right``
+- ``LogicalNotOp(expr: Expression)``:  represents ``!expr``
 
 Comparison:
-- ``EqualityOp``, ``InequalityOp``
-- ``GreaterThanOp``, ``GreaterThanOrEqualOp``
-- ``LessThanOp``, ``LessThanOrEqualOp``
+
+- ``EqualityOp(left: Expression, right: Expression)``: represents ``left == right``
+- ``InequalityOp(left: Expression, right: Expression)``: represents ``left != right``
+- ``GreaterThanOp(left: Expression, right: Expression)``: represents ``left > right``
+- ``GreaterThanOrEqualOp(left: Expression, right: Expression)``: represents ``left >= right``
+- ``LessThanOp(left: Expression, right: Expression)``: represents ``left < right``
+- ``LessThanOrEqualOp(left: Expression, right: Expression)``: represents ``left <= right``
 
 Bitwise:
-- ``BitwiseAndOp``, ``BitwiseOrOp``, ``BitwiseNotOp``
-- ``BitwiseShiftLeftOp``, ``BitwiseShiftRightOp``
+
+- ``BitwiseAndOp(left: Expression, right: Expression)``: represents ``left & right``
+- ``BitwiseOrOp(left: Expression, right: Expression)``: represents ``left | right``
+- ``BitwiseShiftLeftOp(left: Expression, right: Expression)``: represents ``left << right``
+- ``BitwiseShiftRightOp(left: Expression, right: Expression)``: represents ``left >> right``
+- ``BitwiseNotOp(expr: Expression)``: represents ``~expr``
 
 Other:
-- ``TernaryOp``: condition ? true_expr : false_expr
+
+- ``TernaryOp(condition: Expression, true_expr: Expression, false_expr: Expression)``: Represents ``condition ? true_expr : false_expr``
 
 Expressions
 ~~~~~~~~~~~
 
-- ``LetOp``: let(assignments) body
-- ``EchoOp``: echo(arguments) body
-- ``AssertOp``: assert(arguments) body
-- ``FunctionLiteral``: function(parameters) body
-- ``PrimaryCall``: function calls
-- ``PrimaryIndex``: array indexing [index]
-- ``PrimaryMember``: member access .member
+- ``LetOp(assignments: list[Assignment], body: Expression)``: let clause  ``let(assignments) body``
+- ``EchoOp(arguments: list[Argument], body: Expression)``: echo clause  ``echo(arguments) body``
+- ``AssertOp(arguments: list[Argument], body: Expression)``: assert clause  ``assert(arguments) body``
+- ``FunctionLiteral(parameters: list[ParameterDeclaration], body: Expression)``: Anonymous function expression  ``function(parameters) body``
+- ``PrimaryCall(left: Expression, arguments: list[Argument])``: Function calls  ``left(arguments)``
+- ``PrimaryIndex(left: Expression, index: Expression)``: Array indexing ``left[index]``
+- ``PrimaryMember(left: Expression, member: Identifier)``: Member access ``left.member``
 
 List Comprehensions
 ~~~~~~~~~~~~~~~~~~~
 
-- ``ListComprehension``: Vector/list literals
-- ``ListCompFor``: for loops in list comprehensions
-- ``ListCompCFor``: C-style for loops
-- ``ListCompIf``, ``ListCompIfElse``: Conditionals
-- ``ListCompLet``: let expressions
-- ``ListCompEach``: each expressions
+- ``ListComprehension(elements: list[VectorElement])``: Vector/list literals ``[elements]``
+- ``ListCompFor(assignments: list[Assignment], body: VectorElement)``: for loops in list comprehensions ``for(assignments) body``
+- ``ListCompCFor(inits: list[Assignment], condition: Expression, incrs: list[Assignment], body: VectorElement)``: C-style for loops in list comprehensions ``for(inits; condition; incrs) body``
+- ``ListCompIf(condition: Expression, true_expr: VectorElement)``: Conditional inclusion without else ``if(condition) true_expr``
+- ``ListCompIfElse(condition: Expression, true_expr: VectorElement, false_expr: VectorElement)``: Conditional inclusion with else ``if(condition) true_expr else false_expr``
+- ``ListCompLet(assignments: list[Assignment], body: VectorElement)``: let expressions in list comprehensions ``let(assignments) body``
+- ``ListCompEach(body: VectorElement)``: each expressions (flattens nested lists) ``each body``
 
 Module Instantiations
 ~~~~~~~~~~~~~~~~~~~~~
 
-- ``ModularCall``: Module calls with arguments and children
-- ``ModularFor``: for loops
-- ``ModularCFor``: C-style for loops
-- ``ModularIntersectionFor``: intersection_for loops
-- ``ModularIntersectionCFor``: C-style intersection_for loops
-- ``ModularLet``: let statements
-- ``ModularEcho``: echo statements
-- ``ModularAssert``: assert statements
-- ``ModularIf``, ``ModularIfElse``: if/else statements
-- ``ModularModifierShowOnly``: ``!`` modifier
-- ``ModularModifierHighlight``: ``#`` modifier
-- ``ModularModifierBackground``: ``%`` modifier
-- ``ModularModifierDisable``: ``*`` modifier
+- ``ModularCall(name: Identifier, arguments: list[Argument], children: list[ModuleInstantiation])``: Module calls ``name(arguments) { children }``
+- ``ModularFor(assignments: list[Assignment], body: ModuleInstantiation)``: for loops in module bodies ``for(assignments) body``
+- ``ModularIntersectionFor(assignments: list[Assignment], body: ModuleInstantiation)``: intersection_for loops ``intersection_for(assignments) body``
+- ``ModularLet(assignments: list[Assignment], children: list[ModuleInstantiation])``: let statements in module bodies ``let(assignments) { children }``
+- ``ModularEcho(arguments: list[Argument], children: list[ModuleInstantiation])``: echo statements in module bodies ``echo(arguments) { children }``
+- ``ModularAssert(arguments: list[Argument], children: list[ModuleInstantiation])``: assert statements in module bodies ``assert(arguments) { children }``
+- ``ModularIf(condition: Expression, true_branch: ModuleInstantiation)``: if statements in module bodies, with no else ``if(condition) true_branch``
+- ``ModularIfElse(condition: Expression, true_branch: ModuleInstantiation, false_branch: ModuleInstantiation)``: if/else statements in module bodies ``if(condition) true_branch else false_branch``
+- ``ModularModifierShowOnly(child: ModuleInstantiation)``: Show-Only modifier ``!child``
+- ``ModularModifierHighlight(child: ModuleInstantiation)``: Highlight modifier ``#child``
+- ``ModularModifierBackground(child: ModuleInstantiation)``: Background modifier ``%child``
+- ``ModularModifierDisable(child: ModuleInstantiation)``: Disabler modifier ``*child``
 
 Declarations
 ~~~~~~~~~~~~
 
-- ``ModuleDeclaration``: module definitions
-- ``FunctionDeclaration``: function definitions
-- ``ParameterDeclaration``: function/module parameters
-- ``Assignment``: variable assignments
+- ``ModuleDeclaration(name: Identifier, parameters: list[ParameterDeclaration], children: list[ModuleInstantiation | Assignment | FunctionDeclaration | ModuleDeclaration])``: Module definitions ``module name(parameters) { children }``
+- ``FunctionDeclaration(name: Identifier, parameters: list[ParameterDeclaration], expr: Expression)``: Function definitions ``function name(parameters) = expr;``
+- ``ParameterDeclaration(name: Identifier, default: Expression | None)``: Function/module parameter with optional default value  ``name=default`` or ``name``
+- ``Assignment(name: Identifier, expr: Expression)``: Variable assignments ``name = expr;``
 
 Statements
 ~~~~~~~~~~
 
-- ``UseStatement``: use <filepath>
-- ``IncludeStatement``: include <filepath>
-- ``PositionalArgument``: Function call positional arguments
-- ``NamedArgument``: Function call named arguments (name=value)
+- ``UseStatement(filepath: StringLiteral)``: Represents ``use <filepath>``
+- ``IncludeStatement(filepath: StringLiteral)``: Represents ``include <filepath>``
+- ``PositionalArgument(expr: Expression)``: Function call positional arguments ``expr``
+- ``NamedArgument(name: Identifier, expr: Expression)``: Function call named arguments ``name=expr``
 
 Comments
 ~~~~~~~~
 
-- ``CommentLine``: Single-line comments //
-- ``CommentSpan``: Multi-line comments ``/* */``
+- ``CommentLine(text: str)``: Single-line comments ``// str``
+- ``CommentSpan(text: str)``: Multi-line comments ``/* str */``
 
 All AST node classes are fully documented with docstrings that include:
 - Description of what the node represents
@@ -512,6 +536,13 @@ Main Functions
     - ``scope.lookup_module(name)`` — search this scope and its parents
     - ``scope.parent`` — the enclosing scope (``None`` for root)
 
+``to_openscad(nodes: list[ASTNode], indent_width: int = 4)``
+    Convert a list of AST nodes to formatted OpenSCAD source code.
+
+    :param nodes: Top-level AST nodes as returned by the ``getAST*`` functions.
+    :param indent_width: Spaces per indentation level (default: 4).
+    :returns: Formatted OpenSCAD source as a string.
+
 Serialization Functions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -719,6 +750,100 @@ They are also available from ``openscad_parser.ast.serialization``::
         ast_from_yaml,
     )
 
+Pretty-Printing
+---------------
+
+The ``to_openscad()`` function converts an AST back to formatted OpenSCAD source code::
+
+    from openscad_parser.ast import getASTfromString, to_openscad
+
+    code = "module box(w,h){cube([w,h,1]);}"
+    ast = getASTfromString(code)
+
+    formatted = to_openscad(ast)
+    # module box(w, h) {
+    #     cube([w, h, 1.0]);
+    # }
+    print(formatted)
+
+The pretty-printer normalises whitespace and indentation while preserving the logical
+structure of the code. It supports all AST node types including modules, functions,
+control structures, modifiers, list comprehensions, and comments.
+
+``to_openscad(nodes, indent_width=4)``
+    Convert a list of AST nodes to formatted OpenSCAD source.
+
+    :param nodes: Top-level AST nodes (as returned by ``getAST*`` functions).
+    :param indent_width: Spaces per indentation level (default: 4).
+    :returns: Formatted OpenSCAD source code as a string.
+
+    - Blank lines are inserted before and after module/function declarations.
+    - Single-child module instantiations are formatted inline; multiple children use a block.
+    - Comments are preserved when the AST was parsed with ``include_comments=True``.
+
+Controlling indentation::
+
+    from openscad_parser.ast import getASTfromString, to_openscad
+
+    ast = getASTfromString("module m() { cube(1); }")
+    print(to_openscad(ast, indent_width=2))
+    # module m() {
+    #   cube(1.0);
+    # }
+
+Command-Line Interface
+-----------------------
+
+The ``openscad-parser`` CLI is installed alongside the package::
+
+    pip install openscad-parser
+
+Usage::
+
+    openscad-parser [OPTIONS] [FILE]
+
+Read from a file or ``-`` for stdin. Default output is JSON.
+
+**Options:**
+
+``--json``
+    Output AST as JSON (default).
+
+``--yaml``
+    Output AST as YAML (requires ``pip install openscad_parser[yaml]``).
+
+``--format``
+    Output reformatted OpenSCAD source code.
+
+``--indent N``
+    Indentation width in spaces (default: 4). Applies to ``--format`` and ``--json``.
+
+``--include-comments``
+    Include comment nodes in the output.
+
+``--no-includes``
+    Do not expand ``include <...>`` statements; keep ``IncludeStatement`` nodes instead.
+
+**Examples:**
+
+Dump AST as JSON::
+
+    openscad-parser model.scad
+    openscad-parser - < model.scad         # stdin
+
+Reformat OpenSCAD source::
+
+    openscad-parser --format model.scad
+    openscad-parser --format --indent 2 model.scad
+
+Output YAML::
+
+    openscad-parser --yaml model.scad
+
+Include comments in the AST::
+
+    openscad-parser --include-comments --json model.scad
+
 Error Handling
 --------------
 

{openscad_parser-2.3.4 → openscad_parser-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "openscad_parser"
-version = "2.3.4"
+version = "2.4.1"
 description = "A PEG parser to read OpenSCAD language source code, with optional AST tree generation."
 readme = "README.rst"
 authors = [
@@ -24,6 +24,9 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Artistic Software",
     "Topic :: Multimedia :: Graphics :: 3D Modeling",
     "Topic :: Multimedia :: Graphics :: 3D Rendering",
@@ -35,6 +38,9 @@ dependencies = [
     "arpeggio>=2.0.3",
 ]
 
+[project.scripts]
+openscad-parser = "openscad_parser.cli:main"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0.0",