openscad-parser 2.3.1__tar.gz → 2.3.3__tar.gz

{openscad_parser-2.3.1 → openscad_parser-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_parser
-Version: 2.3.1
+Version: 2.3.3
 Summary: A PEG parser to read OpenSCAD language source code, with optional AST tree generation.
 Keywords: openscad,openscad parser,parser
 Author: Revar Desmera
@@ -22,6 +22,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: arpeggio>=2.0.3
 Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
 Requires-Dist: pytest-cov>=7.1.0 ; extra == 'dev'
+Requires-Dist: pyyaml>=6.0 ; extra == 'dev'
+Requires-Dist: coverage-badge>=1.1.0 ; extra == 'dev'
 Requires-Dist: pyyaml>=6.0 ; extra == 'yaml'
 Maintainer: Revar Desmera
 Maintainer-email: Revar Desmera <revarbat@gmail.com>
@@ -39,6 +41,9 @@ Description-Content-Type: text/x-rst
 OpenSCAD Parser
 ===============
 
+.. image:: https://raw.githubusercontent.com/BelfrySCAD/openscad_parser/main/coverage-badge.svg
+   :alt: Coverage
+
 A PEG parser for the OpenSCAD language that can parse OpenSCAD source code and optionally generate an Abstract Syntax Tree (AST) for programmatic analysis and manipulation.
 
 Features
@@ -231,7 +236,7 @@ All AST nodes inherit from ``ASTNode`` and have a ``position`` attribute for sou
 
     # Access source position
     print(assignment.position.line)      # Line number (1-indexed)
-    print(assignment.position.char)      # Column number (1-indexed)
+    print(assignment.position.column)    # Column number (1-indexed)
 
 Examples
 --------
@@ -408,7 +413,7 @@ List Comprehensions
 
 - ``ListComprehension``: Vector/list literals
 - ``ListCompFor``: for loops in list comprehensions
-- ``ListCompCStyleFor``: C-style for loops
+- ``ListCompCFor``: C-style for loops
 - ``ListCompIf``, ``ListCompIfElse``: Conditionals
 - ``ListCompLet``: let expressions
 - ``ListCompEach``: each expressions
@@ -418,8 +423,9 @@ Module Instantiations
 
 - ``ModularCall``: Module calls with arguments and children
 - ``ModularFor``: for loops
-- ``ModularCLikeFor``: C-style 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
@@ -470,10 +476,12 @@ Main Functions
     :param debug: If True, enables debug output
     :returns: ParserPython instance
 
-``getASTfromString(code: str)``
+``getASTfromString(code: str, include_comments: bool = False, origin: str = "<string>")``
     Parse OpenSCAD code from a string and return its AST.
 
     :param code: The OpenSCAD source code to be parsed
+    :param include_comments: If True, include comment nodes in the AST (default: False)
+    :param origin: Origin identifier used in source position tracking (default: "<string>")
     :returns: AST node or list of AST nodes (for top-level statements)
     :rtype: ASTNode | list[ASTNode] | None
 
@@ -514,12 +522,13 @@ Main Functions
 
     **Note:** The ``process_includes`` parameter affects the AST structure (see ``getASTfromFile`` documentation).
 
-``parse_ast(parser, code, file="")``
+``parse_ast(parser, code, file="", source_map=None)``
     Parse OpenSCAD code and generate an AST (lower-level API).
 
     :param parser: Arpeggio parser instance from getOpenSCADParser()
     :param code: OpenSCAD code string to parse
     :param file: Optional file path for source location tracking
+    :param source_map: Optional ``SourceMap`` for multi-origin position tracking
     :returns: AST node or list of AST nodes (for top-level statements)
 
 ``clear_ast_cache()``
@@ -528,6 +537,21 @@ Main Functions
 
     This function removes all cached AST trees from memory.
 
+``build_scopes(ast: list[ASTNode]) -> Scope``
+    Build a scope tree over an AST and attach a ``scope`` attribute to every node.
+
+    :param ast: A list of top-level AST nodes (as returned by the ``getAST*`` functions)
+    :returns: The root ``Scope`` object
+
+``Scope``
+    Represents a lexical scope with three independent namespaces (variables, functions,
+    modules), mirroring OpenSCAD's scoping rules.
+
+    - ``scope.lookup_variable(name)`` — search this scope and its parents
+    - ``scope.lookup_function(name)`` — search this scope and its parents
+    - ``scope.lookup_module(name)`` — search this scope and its parents
+    - ``scope.parent`` — the enclosing scope (``None`` for root)
+
 Serialization Functions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -636,12 +660,15 @@ All AST nodes include source position information::
     assignment = ast[0]
 
     position = assignment.position
-    print(position.file)      # "example.scad"
-    print(position.line)      # 1 (1-indexed)
-    print(position.char)      # 1 (1-indexed, column number)
-    print(position.position)  # 0 (0-indexed character position)
+    print(position.origin)        # "example.scad" (origin identifier)
+    print(position.line)          # 1 (1-indexed line number)
+    print(position.column)        # 1 (1-indexed column number)
+    print(position.start_offset)  # 0 (0-based byte offset of token start within origin)
+    print(position.end_offset)    # N (0-based exclusive byte offset of token end)
 
-The ``Position`` class provides lazy evaluation of line/column numbers from character positions.
+The ``Position`` dataclass carries both line/column coordinates and byte offsets relative
+to the origin's content. For single-file parses these equal file byte offsets; for
+multi-origin parses (e.g. after include expansion) they are relative to each included file.
 
 Serialization
 -------------
@@ -825,12 +852,42 @@ The AST is a tree structure that can be traversed recursively::
     for node in ast:
         visit_node(node)
 
+Scope Tracking
+--------------
+
+The parser can build a scope tree over the AST, resolving variable, function, and module
+names according to OpenSCAD's three-namespace scoping rules::
+
+    from openscad_parser.ast import getASTfromString, build_scopes
+
+    ast = getASTfromString("""
+        x = 10;
+        module box(size = x) { cube(size); }
+        box();
+    """)
+
+    root_scope = build_scopes(ast)
+
+    # Look up names in the root scope
+    print(root_scope.lookup_variable("x"))   # Assignment node
+    print(root_scope.lookup_module("box"))   # ModuleDeclaration node
+
+    # Each AST node has a .scope attribute pointing to its enclosing scope
+    box_decl = ast[1]
+    cube_call = box_decl.children[0]
+    print(cube_call.scope.lookup_variable("size"))  # ParameterDeclaration node
+
+``build_scopes(ast)`` returns the root ``Scope`` object and attaches a ``scope`` attribute
+to every node in the tree. Scopes form a parent chain so lookups fall through to enclosing
+scopes automatically. Declarations (variables, functions, modules) inside a block are
+hoisted to the top of that block's scope before child nodes are visited.
+
 Testing
 -------
 
 The project includes a comprehensive test suite. Run tests with::
 
-    pytest tests/
+    uv run pytest tests/
 
 Development
 -----------

{openscad_parser-2.3.1 → openscad_parser-2.3.3}/README.rst

@@ -1,6 +1,9 @@
 OpenSCAD Parser
 ===============
 
+.. image:: https://raw.githubusercontent.com/BelfrySCAD/openscad_parser/main/coverage-badge.svg
+   :alt: Coverage
+
 A PEG parser for the OpenSCAD language that can parse OpenSCAD source code and optionally generate an Abstract Syntax Tree (AST) for programmatic analysis and manipulation.
 
 Features
@@ -193,7 +196,7 @@ All AST nodes inherit from ``ASTNode`` and have a ``position`` attribute for sou
 
     # Access source position
     print(assignment.position.line)      # Line number (1-indexed)
-    print(assignment.position.char)      # Column number (1-indexed)
+    print(assignment.position.column)    # Column number (1-indexed)
 
 Examples
 --------
@@ -370,7 +373,7 @@ List Comprehensions
 
 - ``ListComprehension``: Vector/list literals
 - ``ListCompFor``: for loops in list comprehensions
-- ``ListCompCStyleFor``: C-style for loops
+- ``ListCompCFor``: C-style for loops
 - ``ListCompIf``, ``ListCompIfElse``: Conditionals
 - ``ListCompLet``: let expressions
 - ``ListCompEach``: each expressions
@@ -380,8 +383,9 @@ Module Instantiations
 
 - ``ModularCall``: Module calls with arguments and children
 - ``ModularFor``: for loops
-- ``ModularCLikeFor``: C-style 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
@@ -432,10 +436,12 @@ Main Functions
     :param debug: If True, enables debug output
     :returns: ParserPython instance
 
-``getASTfromString(code: str)``
+``getASTfromString(code: str, include_comments: bool = False, origin: str = "<string>")``
     Parse OpenSCAD code from a string and return its AST.
 
     :param code: The OpenSCAD source code to be parsed
+    :param include_comments: If True, include comment nodes in the AST (default: False)
+    :param origin: Origin identifier used in source position tracking (default: "<string>")
     :returns: AST node or list of AST nodes (for top-level statements)
     :rtype: ASTNode | list[ASTNode] | None
 
@@ -476,12 +482,13 @@ Main Functions
 
     **Note:** The ``process_includes`` parameter affects the AST structure (see ``getASTfromFile`` documentation).
 
-``parse_ast(parser, code, file="")``
+``parse_ast(parser, code, file="", source_map=None)``
     Parse OpenSCAD code and generate an AST (lower-level API).
 
     :param parser: Arpeggio parser instance from getOpenSCADParser()
     :param code: OpenSCAD code string to parse
     :param file: Optional file path for source location tracking
+    :param source_map: Optional ``SourceMap`` for multi-origin position tracking
     :returns: AST node or list of AST nodes (for top-level statements)
 
 ``clear_ast_cache()``
@@ -490,6 +497,21 @@ Main Functions
 
     This function removes all cached AST trees from memory.
 
+``build_scopes(ast: list[ASTNode]) -> Scope``
+    Build a scope tree over an AST and attach a ``scope`` attribute to every node.
+
+    :param ast: A list of top-level AST nodes (as returned by the ``getAST*`` functions)
+    :returns: The root ``Scope`` object
+
+``Scope``
+    Represents a lexical scope with three independent namespaces (variables, functions,
+    modules), mirroring OpenSCAD's scoping rules.
+
+    - ``scope.lookup_variable(name)`` — search this scope and its parents
+    - ``scope.lookup_function(name)`` — search this scope and its parents
+    - ``scope.lookup_module(name)`` — search this scope and its parents
+    - ``scope.parent`` — the enclosing scope (``None`` for root)
+
 Serialization Functions
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -598,12 +620,15 @@ All AST nodes include source position information::
     assignment = ast[0]
 
     position = assignment.position
-    print(position.file)      # "example.scad"
-    print(position.line)      # 1 (1-indexed)
-    print(position.char)      # 1 (1-indexed, column number)
-    print(position.position)  # 0 (0-indexed character position)
+    print(position.origin)        # "example.scad" (origin identifier)
+    print(position.line)          # 1 (1-indexed line number)
+    print(position.column)        # 1 (1-indexed column number)
+    print(position.start_offset)  # 0 (0-based byte offset of token start within origin)
+    print(position.end_offset)    # N (0-based exclusive byte offset of token end)
 
-The ``Position`` class provides lazy evaluation of line/column numbers from character positions.
+The ``Position`` dataclass carries both line/column coordinates and byte offsets relative
+to the origin's content. For single-file parses these equal file byte offsets; for
+multi-origin parses (e.g. after include expansion) they are relative to each included file.
 
 Serialization
 -------------
@@ -787,12 +812,42 @@ The AST is a tree structure that can be traversed recursively::
     for node in ast:
         visit_node(node)
 
+Scope Tracking
+--------------
+
+The parser can build a scope tree over the AST, resolving variable, function, and module
+names according to OpenSCAD's three-namespace scoping rules::
+
+    from openscad_parser.ast import getASTfromString, build_scopes
+
+    ast = getASTfromString("""
+        x = 10;
+        module box(size = x) { cube(size); }
+        box();
+    """)
+
+    root_scope = build_scopes(ast)
+
+    # Look up names in the root scope
+    print(root_scope.lookup_variable("x"))   # Assignment node
+    print(root_scope.lookup_module("box"))   # ModuleDeclaration node
+
+    # Each AST node has a .scope attribute pointing to its enclosing scope
+    box_decl = ast[1]
+    cube_call = box_decl.children[0]
+    print(cube_call.scope.lookup_variable("size"))  # ParameterDeclaration node
+
+``build_scopes(ast)`` returns the root ``Scope`` object and attaches a ``scope`` attribute
+to every node in the tree. Scopes form a parent chain so lookups fall through to enclosing
+scopes automatically. Declarations (variables, functions, modules) inside a block are
+hoisted to the top of that block's scope before child nodes are visited.
+
 Testing
 -------
 
 The project includes a comprehensive test suite. Run tests with::
 
-    pytest tests/
+    uv run pytest tests/
 
 Development
 -----------

{openscad_parser-2.3.1 → openscad_parser-2.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "openscad_parser"
-version = "2.3.1"
+version = "2.3.3"
 description = "A PEG parser to read OpenSCAD language source code, with optional AST tree generation."
 readme = "README.rst"
 authors = [
@@ -39,6 +39,8 @@ dependencies = [
 dev = [
     "pytest>=7.0.0",
     "pytest-cov>=7.1.0",
+    "PyYAML>=6.0",
+    "coverage-badge>=1.1.0",
 ]
 yaml = [
     "PyYAML>=6.0",

{openscad_parser-2.3.1 → openscad_parser-2.3.3}/src/openscad_parser/ast/builder.py

@@ -972,9 +972,9 @@ class ASTBuilderVisitor(PTNodeVisitor):
             for op in reversed(ops):
                 if op == '-':
                     result = UnaryMinusOp(expr=result, position=self._get_node_position(node))
-                elif op == '!':
+                elif op == '!':  # pragma: no cover
                     result = LogicalNotOp(expr=result, position=self._get_node_position(node))
-                elif op == '~':
+                elif op == '~':  # pragma: no cover
                     result = BitwiseNotOp(expr=result, position=self._get_node_position(node))
         
         return result
@@ -1048,8 +1048,6 @@ class ASTBuilderVisitor(PTNodeVisitor):
     
     def visit_vector_expr(self, node, children):
         elements = children if children else []
-        if not isinstance(elements, list):
-            elements = [elements]
         return ListComprehension(elements=elements, position=self._get_node_position(node))
     
     def visit_funclit_def(self, node, children):
@@ -1065,7 +1063,7 @@ class ASTBuilderVisitor(PTNodeVisitor):
         return children[0]
 
     def visit_listcomp_paren_expr(self, node, children):
-        return children[0] if children else None
+        return children[0]
     
     def visit_listcomp_let(self, node, children):
         return ListCompLet(assignments=children[0], body=children[1], position=self._get_node_position(node))
@@ -1118,8 +1116,6 @@ class ASTBuilderVisitor(PTNodeVisitor):
         mods = children.get_rule("child_statement") if hasattr(children, "get_rule") else (children[2] if len(children) > 2 else [])
         if mods is None:  # pragma: no cover
             mods = []
-        if not isinstance(mods, list):
-            mods = [mods]
         return ModularCall(
             name=name,
             arguments=arguments,
@@ -1131,8 +1127,6 @@ class ASTBuilderVisitor(PTNodeVisitor):
         initial = children[0] if isinstance(children[0], list) else [children[0]]
         increment = children[2] if isinstance(children[2], list) else [children[2]]
         body = children.get_rule('child_statement')
-        if not isinstance(body, list):
-            body = [body]
         return ModularCFor(
             initial=initial,
             condition=children[1],
@@ -1144,8 +1138,6 @@ class ASTBuilderVisitor(PTNodeVisitor):
     def visit_modular_for(self, node, children):
         assignments = children[0] if isinstance(children[0], list) else [children[0]]
         body = children.get_rule('child_statement')
-        if not isinstance(body, list):
-            body = [body]
         return ModularFor(
             assignments=assignments,
             body=body,
@@ -1156,8 +1148,6 @@ class ASTBuilderVisitor(PTNodeVisitor):
         initial = children[0] if isinstance(children[0], list) else [children[0]]
         increment = children[2] if isinstance(children[2], list) else [children[2]]
         body = children.get_rule('child_statement')
-        if not isinstance(body, list):
-            body = [body]
         return ModularIntersectionCFor(
             initial=initial,
             condition=children[1],
@@ -1169,46 +1159,32 @@ class ASTBuilderVisitor(PTNodeVisitor):
     def visit_modular_intersection_for(self, node, children):
         assignments = children[0] if isinstance(children[0], list) else [children[0]]
         body = children.get_rule('child_statement')
-        if not isinstance(body, list):
-            body = [body]
         return ModularIntersectionFor(assignments=assignments, body=body, position=self._get_node_position(node))
     
     def visit_modular_let(self, node, children):
         assignments = children[0] if isinstance(children[0], list) else [children[0]]
         mods = children.get_rule('child_statement')
-        if not isinstance(mods, list):
-            mods = [mods]
         return ModularLet(assignments=assignments, children=mods, position=self._get_node_position(node))
     
     def visit_modular_echo(self, node, children):
         arguments = children[0] if isinstance(children[0], list) else [children[0]]
         mods = children.get_rule('child_statement')
-        if not isinstance(mods, list):
-            mods = [mods]
         return ModularEcho(arguments=arguments, children=mods, position=self._get_node_position(node))
     
     def visit_modular_assert(self, node, children):
         arguments = children[0] if isinstance(children[0], list) else [children[0]]
         mods = children.get_rule('child_statement')
-        if not isinstance(mods, list):
-            mods = [mods]
         return ModularAssert(arguments=arguments, children=mods, position=self._get_node_position(node))
     
     def visit_if_statement(self, node, children):
         condition = children[0]
         true_branch = children.get_rule('child_statement')
-        if not isinstance(true_branch, list):
-            true_branch = [true_branch]
         return ModularIf(condition=condition, true_branch=true_branch, position=self._get_node_position(node))
 
     def visit_ifelse_statement(self, node, children):
         condition = children[0]
         true_branch = children.get_rule('child_statement')
         false_branch = children.get_rule('child_statement', index=1)
-        if not isinstance(true_branch, list):
-            true_branch = [true_branch]
-        if not isinstance(false_branch, list):
-            false_branch = [false_branch]
         return ModularIfElse(condition=condition, true_branch=true_branch, false_branch=false_branch, position=self._get_node_position(node))
     
     def visit_modifier_show_only(self, node, children):

{openscad_parser-2.3.1 → openscad_parser-2.3.3}/src/openscad_parser/ast/source_map.py

@@ -118,9 +118,6 @@ class SourceMap:
             start_pos: Starting position in the combined string (0-indexed)
             length: Number of characters to replace
         """
-        if length <= 0:
-            return
-        
         end_pos = start_pos + length
         
         # Collect segments to modify and new segments to add (for splits)
@@ -330,12 +327,6 @@ class SourceMap:
             else:
                 left = mid + 1
         
-        # Check if position is in the last segment
-        if self._segments:
-            last_segment = self._segments[-1]
-            if last_segment.combined_start <= position < last_segment.combined_start + len(last_segment.content):
-                return last_segment
-        
         return None
     
     def _calculate_location_in_segment(self, segment: SourceSegment, offset: int,