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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_parser
-Version: 2.3.4
+Version: 2.4.0
 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
 ------------
@@ -552,6 +557,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 +771,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.0}/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
 ------------
@@ -512,6 +514,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 +728,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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "openscad_parser"
-version = "2.3.4"
+version = "2.4.0"
 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",

{openscad_parser-2.3.4 → openscad_parser-2.4.0}/src/openscad_parser/ast/__init__.py

@@ -87,6 +87,9 @@ from .builder import ASTBuilderVisitor, Position
 # Import scope classes
 from .scope import Scope, build_scopes
 
+# Import pretty-printer
+from .pretty_print import to_openscad
+
 # Import serialization functions
 from .serialization import (
     ast_to_dict,

{openscad_parser-2.3.4 → openscad_parser-2.4.0}/src/openscad_parser/ast/nodes.py

@@ -333,7 +333,7 @@ class RangeLiteral(Primary):
     step: Expression
 
     def __str__(self):
-        return f"{self.start}:{self.end}:{self.step}"
+        return f"[{self.start}:{self.end}:{self.step}]"
 
     def build_scope(self, parent_scope: "Scope") -> None:
         self.scope = parent_scope
@@ -1208,7 +1208,7 @@ class ListCompLet(VectorElement):
     body: Expression
 
     def __str__(self):
-        return f"let ({self.assignments}) {self.body}"
+        return f"let ({', '.join(str(a) for a in self.assignments)}) {self.body}"
 
     def build_scope(self, parent_scope: "Scope") -> None:
         self.scope = parent_scope
@@ -1267,7 +1267,7 @@ class ListCompFor(VectorElement):
     body: VectorElement
 
     def __str__(self):
-        return f"for ({self.assignments}) {self.body}"
+        return f"for ({', '.join(str(a) for a in self.assignments)}) {self.body}"
 
     def build_scope(self, parent_scope: "Scope") -> None:
         self.scope = parent_scope
@@ -1308,7 +1308,7 @@ class ListCompCFor(VectorElement):
     body: VectorElement
 
     def __str__(self):
-        return f"for ({self.initial}; {self.condition}; {self.increment}) {self.body}"
+        return f"for ({', '.join(str(a) for a in self.initial)}; {self.condition}; {', '.join(str(a) for a in self.increment)}) {self.body}"
 
     def build_scope(self, parent_scope: "Scope") -> None:
         self.scope = parent_scope

openscad_parser-2.4.0/src/openscad_parser/ast/pretty_print.py

@@ -0,0 +1,169 @@
+"""Pretty-printer: convert an OpenSCAD AST back to formatted source code."""
+from __future__ import annotations
+from .nodes import (
+    ASTNode, Assignment, FunctionDeclaration, ModuleDeclaration,
+    UseStatement, IncludeStatement,
+    ModuleInstantiation,
+    ModularCall, ModularFor, ModularCFor,
+    ModularIntersectionFor, ModularIntersectionCFor,
+    ModularLet, ModularEcho, ModularAssert,
+    ModularIf, ModularIfElse,
+    ModularModifierShowOnly, ModularModifierHighlight,
+    ModularModifierBackground, ModularModifierDisable,
+    CommentLine, CommentSpan,
+)
+
+
+def to_openscad(nodes: list[ASTNode], indent_width: int = 4) -> str:
+    """Convert a list of AST nodes to formatted OpenSCAD source code.
+
+    Args:
+        nodes: The AST nodes to format (top-level statements).
+        indent_width: Number of spaces per indentation level (default: 4).
+
+    Returns:
+        Formatted OpenSCAD source code as a string.
+    """
+    parts = []
+    prev_complex = False
+    for node in nodes:
+        is_complex = isinstance(node, (ModuleDeclaration, FunctionDeclaration))
+        if parts and (is_complex or prev_complex):
+            parts.append("")
+        parts.append(_fmt_node(node, 0, indent_width))
+        prev_complex = is_complex
+    return "\n".join(parts)
+
+
+# --- helpers ---
+
+def _as_list(val) -> list:
+    if isinstance(val, list):
+        return val
+    if val is None:
+        return []
+    return [val]
+
+
+def _join_str(items) -> str:
+    return ", ".join(str(i) for i in items)
+
+
+def _fmt_node(node: ASTNode, indent: int, w: int) -> str:
+    """Format any top-level or block-body node."""
+    pad = " " * indent
+
+    if isinstance(node, CommentLine):
+        return f"{pad}//{node.text}"
+    if isinstance(node, CommentSpan):
+        return f"{pad}/*{node.text}*/"
+    if isinstance(node, UseStatement):
+        return f"{pad}use <{node.filepath.val}>"
+    if isinstance(node, IncludeStatement):
+        return f"{pad}include <{node.filepath.val}>"
+    if isinstance(node, Assignment):
+        return f"{pad}{node.name} = {node.expr};"
+    if isinstance(node, FunctionDeclaration):
+        params = _join_str(node.parameters)
+        return f"{pad}function {node.name}({params}) = {node.expr};"
+    if isinstance(node, ModuleDeclaration):
+        params = _join_str(node.parameters)
+        block = _fmt_block(node.children, indent, w)
+        return f"{pad}module {node.name}({params}) {block}"
+    if isinstance(node, ModuleInstantiation):
+        return _fmt_inst(node, indent, w)
+    return f"{pad}{node}"
+
+
+def _fmt_block(nodes: list, indent: int, w: int) -> str:
+    """Format a list of nodes as a braced block."""
+    pad = " " * indent
+    if not nodes:
+        return "{}"
+    inner = "\n".join(_fmt_node(n, indent + w, w) for n in nodes)
+    return "{\n" + inner + "\n" + pad + "}"
+
+
+def _fmt_child(body, indent: int, w: int) -> str:
+    """Format the child body of a module instantiation.
+
+    Returns the tail string appended after the header:
+      - ``";"`` when there are no children
+      - ``"\\n    child;"`` for a single inline child
+      - ``" {\\n    ...\\n}"`` for a block of multiple children
+    """
+    nodes = _as_list(body)
+    pad = " " * indent
+
+    if not nodes:
+        return ";"
+    if len(nodes) == 1:
+        return "\n" + _fmt_inst(nodes[0], indent + w, w)
+    inner = "\n".join(_fmt_inst(n, indent + w, w) for n in nodes)
+    return " {\n" + inner + "\n" + pad + "}"
+
+
+def _fmt_inst(node: ModuleInstantiation, indent: int, w: int, prefix: str = "") -> str:
+    """Format a ModuleInstantiation node.
+
+    ``prefix`` accumulates modifier characters (``!``, ``#``, ``%``, ``*``)
+    so nested modifiers produce e.g. ``!#cube(10);``.
+    """
+    pad = " " * indent
+
+    # Modifiers: push prefix down to the wrapped node
+    if isinstance(node, ModularModifierShowOnly):
+        return _fmt_inst(node.child, indent, w, "!" + prefix)
+    if isinstance(node, ModularModifierHighlight):
+        return _fmt_inst(node.child, indent, w, "#" + prefix)
+    if isinstance(node, ModularModifierBackground):
+        return _fmt_inst(node.child, indent, w, "%" + prefix)
+    if isinstance(node, ModularModifierDisable):
+        return _fmt_inst(node.child, indent, w, "*" + prefix)
+
+    if isinstance(node, ModularCall):
+        args = _join_str(node.arguments)
+        return f"{pad}{prefix}{node.name}({args})" + _fmt_child(node.children, indent, w)
+
+    if isinstance(node, ModularFor):
+        assigns = _join_str(_as_list(node.assignments))
+        return f"{pad}{prefix}for ({assigns})" + _fmt_child(node.body, indent, w)
+
+    if isinstance(node, ModularCFor):
+        init = _join_str(_as_list(node.initial))
+        inc = _join_str(_as_list(node.increment))
+        return f"{pad}{prefix}for ({init}; {node.condition}; {inc})" + _fmt_child(node.body, indent, w)
+
+    if isinstance(node, ModularIntersectionFor):
+        assigns = _join_str(_as_list(node.assignments))
+        return f"{pad}{prefix}intersection_for ({assigns})" + _fmt_child(node.body, indent, w)
+
+    if isinstance(node, ModularIntersectionCFor):
+        init = _join_str(_as_list(node.initial))
+        inc = _join_str(_as_list(node.increment))
+        return f"{pad}{prefix}intersection_for ({init}; {node.condition}; {inc})" + _fmt_child(node.body, indent, w)
+
+    if isinstance(node, ModularLet):
+        assigns = _join_str(_as_list(node.assignments))
+        return f"{pad}{prefix}let ({assigns})" + _fmt_child(node.children, indent, w)
+
+    if isinstance(node, ModularEcho):
+        args = _join_str(node.arguments)
+        return f"{pad}{prefix}echo({args})" + _fmt_child(node.children, indent, w)
+
+    if isinstance(node, ModularAssert):
+        args = _join_str(node.arguments)
+        return f"{pad}{prefix}assert({args})" + _fmt_child(node.children, indent, w)
+
+    if isinstance(node, ModularIf):
+        header = f"{pad}{prefix}if ({node.condition})"
+        return header + _fmt_child(node.true_branch, indent, w)
+
+    if isinstance(node, ModularIfElse):
+        header = f"{pad}{prefix}if ({node.condition})"
+        true_tail = _fmt_child(node.true_branch, indent, w)
+        false_tail = _fmt_child(node.false_branch, indent, w)
+        connector = " else" if true_tail.startswith(" {") else f"\n{pad}else"
+        return header + true_tail + connector + false_tail
+
+    return f"{pad}{prefix}{node};"

openscad_parser-2.4.0/src/openscad_parser/cli.py

@@ -0,0 +1,84 @@
+"""Command-line interface for openscad_parser."""
+import sys
+import argparse
+from openscad_parser.ast import getASTfromString, getASTfromFile, ast_to_json
+from openscad_parser.ast.pretty_print import to_openscad
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="openscad-parser",
+        description=(
+            "Parse an OpenSCAD file and dump its AST as JSON (default), "
+            "YAML, or reformatted OpenSCAD source."
+        ),
+    )
+    ap.add_argument(
+        "file",
+        nargs="?",
+        metavar="FILE",
+        help="OpenSCAD source file to parse. Omit or use '-' to read from stdin.",
+    )
+    output = ap.add_mutually_exclusive_group()
+    output.add_argument(
+        "--json", action="store_true", default=True,
+        help="Output AST as JSON (default).",
+    )
+    output.add_argument(
+        "--yaml", action="store_true",
+        help="Output AST as YAML (requires PyYAML).",
+    )
+    output.add_argument(
+        "--format", action="store_true",
+        help="Output reformatted OpenSCAD source code.",
+    )
+    ap.add_argument(
+        "--include-comments", action="store_true",
+        help="Include comment nodes in the AST.",
+    )
+    ap.add_argument(
+        "--no-includes", action="store_true",
+        help="Do not expand include <...> statements (keeps IncludeStatement nodes).",
+    )
+    ap.add_argument(
+        "--indent", type=int, default=4, metavar="N",
+        help="Indentation width in spaces (default: 4). Applies to --format and --json.",
+    )
+    args = ap.parse_args()
+
+    # --yaml and --format clear the --json default
+    if args.yaml or args.format:
+        args.json = False
+
+    try:
+        if args.file is None or args.file == "-":
+            code = sys.stdin.read()
+            ast = getASTfromString(code, include_comments=args.include_comments)
+        else:
+            ast = getASTfromFile(
+                args.file,
+                include_comments=args.include_comments,
+                process_includes=not args.no_includes,
+            )
+    except FileNotFoundError as e:
+        print(f"openscad-parser: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if ast is None:
+        sys.exit(1)
+
+    if args.format:
+        print(to_openscad(ast, indent_width=args.indent))
+    elif args.yaml:
+        try:
+            from openscad_parser.ast import ast_to_yaml
+        except ImportError:
+            print("openscad-parser: --yaml requires PyYAML (pip install openscad_parser[yaml])", file=sys.stderr)
+            sys.exit(1)
+        print(ast_to_yaml(ast))
+    else:
+        print(ast_to_json(ast, indent=args.indent))
+
+
+if __name__ == "__main__":
+    main()