nadata 0.1.0__py3-none-any.whl

nadata/parser/nastruct_parser/parse_callables.py

@@ -0,0 +1,436 @@
+"""
+Callable definition parsing for .nastruct schema files.
+
+Provides the parsers for struct method declarations and standalone function
+declarations, which share the same 'name(params) -> ReturnType' header grammar.
+Bodies are stored as raw text spans; statement parsing happens in the
+resolution phase.
+"""
+
+# Import Modules
+from __future__ import annotations
+from typing import Optional
+
+from nadata.core.expressions.expression import Expression
+from nadata.core.expressions.statement import Statement
+from nadata.parser.expressions.dependencies import (
+    collect_declared_names,
+    collect_dependencies,
+    collect_statement_dependencies,
+)
+from nadata.parser.expressions.expression_parser import ExpressionParser
+from nadata.parser.expressions.splitter import split_top_level
+from nadata.parser.expressions.statement_parser import StatementParser
+from nadata.parser.expressions.tokenizer import Token, TokenType, Tokenizer
+from nadata.parser.expressions.type_parser import TmpType, TypeParser
+from nadata.parser.utils.brackets import BracketTree
+from nadata.parser.utils.identifiers import IdentifierExtractor
+from nadata.parser.nastruct_parser.declaration import parse_declaration_text
+from nadata.parser.nastruct_parser.tmp_structs import TmpAttribute, TmpFunction, TmpStruct
+from nadata.parser.nastruct_parser.parser_state import NaStructParserState
+
+
+def parse_struct_method(
+    parser_state: NaStructParserState,
+    struct_name: str,
+    struct_method_name: str,
+    header: str,
+    method_start: int,
+    method_end: int,
+    content: str,
+    brackets_inside: list[BracketTree]
+) -> None:
+    """
+    Parses a struct method definition block.
+
+    Args:
+        parser_state (NaStructParserState): Shared parsing session state.
+        struct_name (str): Name of the struct owning the method.
+        struct_method_name (str): Name of the method (without '@').
+        header (str): Full header text between '@' and the opening brace
+            (e.g. 'age(now: DateTime) -> DateTime').
+        method_start (int): Index of the first content character inside the braces.
+        method_end (int): Index of the closing brace of the method body.
+        content (str): Text of the file.
+        brackets_inside (list[Token]): Nested bracket trees in the body.
+    """
+
+    # Parse the shared header grammar (parameters and return type)
+    fn_arguments: dict[str, TmpAttribute]
+    fn_output_type: TmpType
+    fn_arguments, fn_output_type = _parse_callable_header(header_text=header)
+
+    # Parse the raw body text into statement AST nodes
+    fn_body: list[Statement] = StatementParser.parse_body(
+        text=content[method_start:method_end]
+    )
+
+    # Check the owning struct exists in the intermediate representation
+    tmp_struct: Optional[TmpStruct] = parser_state.tmp_structs.get(struct_name)
+
+    if tmp_struct is None:
+        raise SyntaxError(f"Method '{struct_method_name}' refers to unknown struct '{struct_name}'")
+
+    # Check the method is not already declared on the struct
+    # (merge mode allows re-declaration: the resolved body replaces)
+    if (
+        struct_method_name in tmp_struct.methods
+        and not parser_state.merge
+    ):
+        raise SyntaxError(
+            f"Method '{struct_method_name}' is already defined on struct '{struct_name}'"
+        )
+
+    # Register the method in the tmp struct
+    tmp_struct.methods[struct_method_name] = TmpFunction(
+        fn_name=struct_method_name,
+        fn_output_type=fn_output_type,
+        fn_argument=fn_arguments,
+        fn_body=fn_body,
+        dependencies=_collect_callable_dependencies(
+            fn_arguments=fn_arguments,
+            fn_output_type=fn_output_type,
+            fn_body=fn_body
+        )
+    )
+
+
+def parse_fn(
+    parser_state: NaStructParserState,
+    name: str,
+    fn_start: int,
+    fn_end: int,
+    brackets_inside: list[BracketTree],
+    content: str
+) -> None:
+    """
+    Parses a standalone function definition block.
+
+    Args:
+        parser_state (NaStructParserState): Shared parsing session state.
+        name (str): Full header text of the function
+            (e.g. 'fn is_adult(h: Human) -> Bool').
+        fn_start (int): Index of the first content character inside the braces.
+        fn_end (int): Index of the closing brace of the block.
+        brackets_inside (list[Token]): Nested bracket trees in the body.
+        content (str): Text of the file.
+    """
+
+    # Strip the 'fn' keyword from the header
+    header_body: str = name[len("fn"):].strip()
+
+    # Parse the shared header grammar (function name, parameters, return type)
+    fn_name: str
+    fn_arguments: dict[str, TmpAttribute]
+    fn_output_type: TmpType
+    fn_name, fn_arguments, fn_output_type = _parse_fn_header(header_text=header_body)
+
+    # Parse the raw body text into statement AST nodes
+    fn_body: list[Statement] = StatementParser.parse_body(
+        text=content[fn_start:fn_end]
+    )
+
+    # Check the function is not already defined
+    # (merge mode allows re-declaration: the resolved body replaces)
+    if fn_name in parser_state.tmp_functions and not parser_state.merge:
+        raise SyntaxError(f"Function '{fn_name}' is already defined")
+
+    # Register the function in the parser state
+    parser_state.tmp_functions[fn_name] = TmpFunction(
+        fn_name=fn_name,
+        fn_output_type=fn_output_type,
+        fn_argument=fn_arguments,
+        fn_body=fn_body,
+        dependencies=_collect_callable_dependencies(
+            fn_arguments=fn_arguments,
+            fn_output_type=fn_output_type,
+            fn_body=fn_body
+        )
+    )
+
+
+def _parse_fn_header(
+    header_text: str
+) -> tuple[str, dict[str, TmpAttribute], TmpType]:
+    """
+    Parses a standalone function header into its name, parameters, and return type.
+
+    Args:
+        header_text (str): Header text without the 'fn' keyword
+            (e.g. 'is_adult(h: Human) -> Bool').
+
+    Returns:
+        tuple[str, dict[str, TmpAttribute], TmpType]: The function name, the
+            parameters by name, and the raw return type annotation.
+
+    Raises:
+        SyntaxError: If the header is malformed.
+    """
+
+    # Check the header is present
+    if not header_text:
+        raise SyntaxError("Empty function header")
+
+    # Locate the parameter list opening parenthesis
+    paren_index: int = header_text.find("(")
+
+    # Check the parameter list is present
+    if paren_index == -1:
+        raise SyntaxError(f"Missing parameter list in function header: '{header_text}'")
+
+    # The function name is the text before the parameter list
+    fn_name: str = header_text[:paren_index].strip()
+
+    # Check the function name is a single token
+    if len(fn_name.split()) != 1:
+        raise SyntaxError(f"Malformed function name in header: '{header_text}'")
+
+    # Parse the shared parameter list and return type
+    fn_arguments: dict[str, TmpAttribute]
+    fn_output_type: TmpType
+    fn_arguments, fn_output_type = _parse_callable_header(header_text=header_text)
+
+    return fn_name, fn_arguments, fn_output_type
+
+
+def _parse_callable_header(
+    header_text: str
+) -> tuple[dict[str, TmpAttribute], TmpType]:
+    """
+    Parses the '(...)' parameter list and '-> ReturnType' of a callable header.
+
+    Args:
+        header_text (str): Header text containing the parameter list
+            (e.g. 'age(now: DateTime) -> DateTime').
+
+    Returns:
+        tuple[dict[str, TmpAttribute], TmpType]: The parameters by name and
+            the parsed return type tree.
+
+    Raises:
+        SyntaxError: If the header is malformed.
+    """
+
+    tokens: list[Token] = Tokenizer(content=header_text).tokenize()
+
+    # Locate the parameter list boundaries at the token level
+    open_index: int
+    close_index: int
+    open_index, close_index = _find_param_list_boundaries(
+        tokens=tokens,
+        header_text=header_text
+    )
+
+    # Parse the comma separated parameter declarations
+    param_tokens: list[Token] = tokens[open_index + 1:close_index]
+    fn_arguments: dict[str, TmpAttribute] = _parse_parameter_tokens(
+        param_tokens=param_tokens,
+        header_text=header_text
+    )
+
+    # Parse the return type annotation after the closing parenthesis
+    fn_output_type: TmpType = _parse_return_type(
+        tokens=tokens,
+        close_index=close_index,
+        header_text=header_text
+    )
+
+    return fn_arguments, fn_output_type
+
+
+def _find_param_list_boundaries(
+    tokens: list[Token],
+    header_text: str
+) -> tuple[int, int]:
+    """
+    Finds the token indexes of the parameter list opening and closing parens.
+
+    Args:
+        tokens (list[Token]): Tokenized header text (terminated by EOF).
+        header_text (str): Original header text (for error messages).
+
+    Returns:
+        tuple[int, int]: Indexes of the '(' and matching ')' tokens.
+
+    Raises:
+        SyntaxError: If the parameter list is missing or unbalanced.
+    """
+
+    # Locate the opening parenthesis token
+    open_index: int = -1
+
+    for index, token in enumerate(tokens):
+
+        if token.token_type == TokenType.PUNCTUATION and token.value == "(":
+            open_index = index
+            break
+
+    # Check the opening parenthesis is present
+    if open_index == -1:
+        raise SyntaxError(f"Missing parameter list in header: '{header_text}'")
+
+    # Scan for the matching closing parenthesis with depth tracking
+    depth: int = 0
+
+    for index in range(open_index, len(tokens)):
+        loop_token: Token = tokens[index]
+
+        if loop_token.token_type == TokenType.EOF:
+            break
+
+        if loop_token.token_type == TokenType.PUNCTUATION:
+            if loop_token.value == "(":
+                depth += 1
+
+            elif loop_token.value == ")":
+                depth -= 1
+
+                # Matching closing parenthesis found
+                if depth == 0:
+                    return open_index, index
+
+    raise SyntaxError(f"Unbalanced parameter list in header: '{header_text}'")
+
+
+def _parse_parameter_tokens(
+    param_tokens: list[Token],
+    header_text: str
+) -> dict[str, TmpAttribute]:
+    """
+    Parses the parameter declaration tokens into TmpAttribute entries.
+
+    Args:
+        param_tokens (list[Token]): Tokens between the parameter parentheses.
+        header_text (str): Original header text (for error messages).
+
+    Returns:
+        dict[str, TmpAttribute]: Parameters by name.
+
+    Raises:
+        SyntaxError: On empty or duplicated parameter declarations.
+    """
+
+    fn_arguments: dict[str, TmpAttribute] = {}
+
+    # Split on top-level commas (nested calls / defaults are kept intact)
+    segments: list[list[Token]] = split_top_level(tokens=param_tokens, separator=",")
+
+    # An empty parameter list is a single empty segment
+    if len(segments) == 1 and not segments[0]:
+        return fn_arguments
+
+    for segment in segments:
+
+        # Check the parameter declaration is not empty
+        if not segment:
+            raise SyntaxError(f"Empty parameter declaration in header: '{header_text}'")
+
+        # Rebuild the raw declaration text from the source span
+        param_text: str = header_text[segment[0].position:segment[-1].end_position]
+
+        param_name: str
+        param_type: TmpType
+        param_default: Optional[Expression]
+        param_name, param_type, param_default = parse_declaration_text(
+            declaration_text=param_text
+        )
+
+        # Check the parameter is not duplicated
+        if param_name in fn_arguments:
+            raise SyntaxError(
+                f"Parameter '{param_name}' is declared twice in header: '{header_text}'"
+            )
+
+        # Collect dependencies from the type tree and the default expression
+        dependencies: set[str] = param_type.collect_names()
+
+        if param_default is not None:
+            dependencies |= collect_dependencies(expression=param_default)
+
+        fn_arguments[param_name] = TmpAttribute(
+            attribute_name=param_name,
+            attribute_type=param_type,
+            attribute_default_value=param_default,
+            dependencies=dependencies
+        )
+
+    return fn_arguments
+
+
+def _parse_return_type(
+    tokens: list[Token],
+    close_index: int,
+    header_text: str
+) -> TmpType:
+    """
+    Parses the '-> ReturnType' annotation following the parameter list.
+
+    Args:
+        tokens (list[Token]): Tokenized header text (terminated by EOF).
+        close_index (int): Token index of the parameter list closing paren.
+        header_text (str): Original header text (for slicing and errors).
+
+    Returns:
+        str: The raw return type annotation ('' if absent).
+
+    Raises:
+        SyntaxError: If the annotation arrow is present but the type is missing.
+    """
+
+    rest_tokens: list[Token] = tokens[close_index + 1:]
+
+    # No return type annotation is not allowed (kept explicit for clarity)
+    if not rest_tokens or rest_tokens[0].token_type == TokenType.EOF:
+        raise SyntaxError(f"Missing return type in header: '{header_text}'")
+
+    # The annotation must start with the '->' arrow operator
+    arrow_token: Token = rest_tokens[0]
+
+    if not (arrow_token.token_type == TokenType.OPERATOR and arrow_token.value == "->"):
+        raise SyntaxError(f"Malformed return type in header: '{header_text}'")
+
+    # Check the return type is present
+    if len(rest_tokens) < 2 or rest_tokens[1].token_type == TokenType.EOF:
+        raise SyntaxError(f"Missing return type after '->' in header: '{header_text}'")
+
+    return_type_text: str = header_text[arrow_token.end_position:].strip()
+
+    return TypeParser.parse_text(text=return_type_text)
+
+
+def _collect_callable_dependencies(
+    fn_arguments: dict[str, TmpAttribute],
+    fn_output_type: TmpType,
+    fn_body: list[Statement]
+) -> set[str]:
+    """
+    Collects the dependency identifiers of a callable declaration.
+
+    Args:
+        fn_arguments (dict[str, TmpAttribute]): Parameters by name.
+        fn_output_type (TmpType): Parsed return type tree.
+        fn_body (list[Statement]): Parsed body statements.
+
+    Returns:
+        set[str]: Union of the parameter, return type, and free body
+            dependencies (parameters and local variables excluded).
+    """
+
+    dependencies: set[str] = set()
+
+    # Union the dependencies of every parameter
+    for fn_argument in fn_arguments.values():
+        dependencies |= fn_argument.dependencies
+
+    # Add the return type dependencies
+    dependencies |= fn_output_type.collect_names()
+
+    # Add the free body dependencies (subtract parameters and locals)
+    body_dependencies: set[str] = collect_statement_dependencies(statements=fn_body)
+    bound_names: set[str] = set(fn_arguments.keys()) | collect_declared_names(
+        statements=fn_body
+    )
+
+    dependencies |= body_dependencies - bound_names
+
+    return dependencies

nadata/parser/nastruct_parser/parse_expression.py

@@ -0,0 +1,59 @@
+"""
+Default value expression parsing for .nastruct attributes.
+
+Provides the parse_expression helper converting an attribute default value
+source span into an Expression AST using the shared expression parser.
+"""
+
+# Import Modules
+from __future__ import annotations
+from typing import Optional
+
+from nadata.core.expressions.expression import Expression
+from nadata.parser.expressions.expression_parser import ExpressionParser
+from nadata.parser.nastruct_parser.parser_state import NaStructParserState
+from nadata.parser.utils.brackets import BracketTree
+
+
+def parse_expression(
+    parser_state: NaStructParserState,
+    struct_name: str,
+    attr_start: int,
+    attr_end: int,
+    content: str,
+    bracket_inside: Optional[BracketTree]
+) -> Expression:
+    """
+    Parses the default value expression of an attribute into an AST.
+
+    Args:
+        parser_state (NaStructParserState): Shared parsing session state
+            (unused for now, kept for signature parity with the other
+            attribute parsers).
+        struct_name (str): Name of the struct owning the attribute
+            (unused for now, kept for signature parity).
+        attr_start (int): Index of the first character of the expression span.
+        attr_end (int): Index just after the last character of the span.
+        content (str): Text of the file.
+        bracket_inside (Optional[BracketTree]): Bracket tree contained in the
+            declaration (unused for now, kept for signature parity).
+
+    Returns:
+        Expression: Parsed expression AST.
+
+    Raises:
+        SyntaxError: If the expression span is empty or malformed.
+    """
+
+    # Extract the raw expression text between the span boundaries
+    expression_text: str = content[attr_start:attr_end].strip()
+
+    # Check the expression text is present
+    if not expression_text:
+        raise SyntaxError(
+            f"Empty expression for struct '{struct_name}' "
+            f"between indexes {attr_start} and {attr_end}"
+        )
+
+    # Delegate to the shared recursive descent expression parser
+    return ExpressionParser.parse_text(text=expression_text)

nadata/parser/nastruct_parser/parse_structs.py

@@ -0,0 +1,206 @@
+"""
+Struct definition parsing for .nastruct schema files.
+
+Provides the struct header parsing, the struct body scanning loop, and the
+case dispatchers detecting attribute and method declarations.
+"""
+
+# Import Modules
+from __future__ import annotations
+from typing import Optional
+
+from nadata.parser.utils.brackets import BracketTree
+from nadata.parser.nastruct_parser.tmp_structs import TmpStruct
+from nadata.parser.nastruct_parser.struct_body_state import StructBodyScanState
+from nadata.parser.nastruct_parser.parser_state import NaStructParserState
+from nadata.parser.nastruct_parser.parse_attributes import parse_struct_attribute_case
+from nadata.parser.nastruct_parser.parse_callables import parse_struct_method
+
+
+def parse_struct_header(
+    header_text: str
+) -> tuple[str, Optional[str]]:
+    """
+    Extracts the struct name and optional parent name from a class header.
+
+    Args:
+        header_text (str): Full header text (e.g. 'class Human(Entity)').
+
+    Returns:
+        tuple[str, Optional[str]]: The struct name and the parent name
+            (None if the struct has no parent).
+
+    Raises:
+        SyntaxError: If the header is malformed.
+    """
+
+    # Strip the 'class' keyword
+    header_body: str = header_text[len("class"):].strip()
+
+    # Case 1: inheritance 'class Human(Entity)'
+    if header_body.endswith(")"):
+        paren_index: int = header_body.find("(")
+
+        # Check the opening parenthesis is present and well placed
+        if paren_index == -1:
+            raise SyntaxError(f"Malformed class header: '{header_text}'")
+
+        struct_name: str = header_body[:paren_index].strip()
+        struct_parent: str = header_body[paren_index + 1:-1].strip()
+
+        # Check both names are present
+        if not struct_name or not struct_parent:
+            raise SyntaxError(f"Malformed class header: '{header_text}'")
+
+        return struct_name, struct_parent
+
+    # Case 2: no inheritance 'class Human'
+    if "(" in header_body or ")" in header_body:
+        raise SyntaxError(f"Malformed class header: '{header_text}'")
+
+    # Check the struct name is present
+    if not header_body:
+        raise SyntaxError(f"Missing struct name in header: '{header_text}'")
+
+    # Check the struct name is a single token
+    if len(header_body.split()) != 1:
+        raise SyntaxError(f"Malformed class header: '{header_text}'")
+
+    return header_body, None
+
+
+def parse_struct(
+    parser_state: NaStructParserState,
+    struct_name: str,
+    struct_parent: Optional[str],
+    struct_start: int,
+    struct_end: int,
+    brackets_inside: list[BracketTree],
+    content: str
+) -> None:
+    """
+    Parses a struct definition block.
+
+    Args:
+        parser_state (NaStructParserState): Shared parsing session state.
+        struct_name (str): Name of the struct.
+        struct_parent (Optional[str]): Name of the parent struct, if any.
+        struct_start (int): Index of the first content character inside the braces.
+        struct_end (int): Index of the closing brace of the block.
+        brackets_inside (list[BracketTree]): Nested bracket trees inside the block.
+        content (str): Text of the file.
+    """
+
+    # Check if struct name already exists (tmp and resolved namespaces).
+    # In merge mode (session schema re-merge), re-declaring a struct that
+    # already lives in the database is allowed and replaces its members
+    if (
+        struct_name in parser_state.tmp_structs
+        or (
+            not parser_state.merge
+            and struct_name in parser_state.database.tables_by_struct_name
+        )
+    ):
+        raise SyntaxError(f"Struct '{struct_name}' is already defined")
+
+    # Prepare the tmp struct
+    parser_state.tmp_structs[struct_name] = TmpStruct(
+        struct_name=struct_name,
+        struct_parent=struct_parent
+    )
+
+    # Initialize the mutable scanning state of the struct body
+    # (struct_start is only used to initialize the cursor)
+    scan_state: StructBodyScanState = StructBodyScanState(
+        struct_name=struct_name,
+        struct_end=struct_end,
+        content=content,
+        cursor=struct_start,
+        brackets_inside=brackets_inside
+    )
+    scan_state.next_bracket = scan_state.pop_next_bracket()
+
+    # While we have something in the struct brackets
+    while scan_state.cursor < scan_state.struct_end:
+
+        # Manage white spaces (spaces, tabs, newlines, and blanked comments)
+        if scan_state.content[scan_state.cursor].isspace():
+            scan_state.cursor += 1
+            continue
+
+        # Class method declaration
+        if scan_state.content[scan_state.cursor] == "@":
+            parse_struct_method_case(
+                parser_state=parser_state,
+                scan_state=scan_state
+            )
+
+        # Else, it is an attribut definition
+        else:
+            parse_struct_attribute_case(
+                parser_state=parser_state,
+                scan_state=scan_state
+            )
+
+
+def parse_struct_method_case(
+    parser_state: NaStructParserState,
+    scan_state: StructBodyScanState
+) -> None:
+    """
+    Detects and dispatches a single method declaration of a struct body.
+
+    Args:
+        parser_state (NaStructParserState): Shared parsing session state.
+        scan_state (StructBodyScanState): Mutable scanning state (updated in place).
+    """
+
+    # Check bracket
+    if scan_state.next_bracket is None:
+        raise SyntaxError(
+            f"Method declaration at index {scan_state.cursor} has no body '{{...}}'"
+        )
+
+    # Get text before (the full method header: name, params, return type)
+    method_header: str = (
+        scan_state.content[scan_state.cursor + 1:scan_state.next_bracket.open_index].strip()
+    )
+
+    # Check the text is present
+    if not method_header:
+        raise SyntaxError(f"Empty method declaration at index {scan_state.cursor}")
+
+    # A method declaration requires a parameter list '(...)'
+    paren_index: int = method_header.find("(")
+
+    # If there are no parenthesis, it is a syntax error
+    if paren_index == -1:
+        raise SyntaxError(
+            f"Method declaration at index {scan_state.cursor} is missing its "
+            f"parameter list '(...)': '@{method_header[:20]}...'"
+        )
+
+    # The method name is the text before the parameter list
+    method_name: str = method_header[:paren_index].strip()
+
+    # Check the method name is present
+    if not method_name:
+        raise SyntaxError(f"Missing method name at index {scan_state.cursor}")
+
+    # Parse the struct method
+    parse_struct_method(
+        parser_state=parser_state,
+        struct_name=scan_state.struct_name,
+        struct_method_name=method_name,
+        header=method_header,
+        method_start=scan_state.next_bracket.open_index + 1,
+        method_end=scan_state.next_bracket.close_index,
+        content=scan_state.content,
+        brackets_inside=scan_state.next_bracket.inside
+    )
+
+    # Advance the cursor
+    scan_state.cursor = scan_state.next_bracket.close_index + 1
+
+    # Advance the next bracket
+    scan_state.next_bracket = scan_state.pop_next_bracket()