ransacklib 0.1.10__py3-none-any.whl

ransack/transformer.py

@@ -0,0 +1,846 @@
+"""
+transformer.py - Provides transformers for converting Lark's AST into more
+usable Python objects.
+
+This module contains the `ExpressionTransformer` class,
+which extend Lark's `Transformer` to convert the parse tree
+generated by the Lark parser into more useful Python objects.
+`ExpressionTransformer` handles the interpretation of parsed structures
+like IP addresses, ranges, datetime objects, and arithmetic expressions,
+transforming them into Python data structures.
+
+Classes:
+    - TokenWrapper: A wrapper for Lark Token to provide a `real_value`
+                    attribute.
+    - ExpressionTransformer: Converts nodes from the Lark parse tree
+                             into Python objects (e.g., IP addresses,
+                             datetime objects, timedelta, lists,
+                             strings).
+"""
+
+import re
+from collections.abc import Mapping, MutableSequence
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional, Tuple
+
+from ipranges import IP4, IP6, IP4Net, IP4Range, IP6Net, IP6Range
+from lark import Token, Transformer, Tree, v_args
+from lark.tree import Meta
+from lark.visitors import Interpreter
+
+from .exceptions import EvaluationError
+from .function import predefined_functions
+from .operator import binary_operation
+
+
+class TokenWrapper:
+    """A wrapper of Lark Token to provide a real_value attribute."""
+
+    def __init__(self, token: Token, value: Any):
+        """
+        Initializes the TokenWrapper with a token and a value.
+
+        Parameters:
+            token: The Lark Token to be wrapped.
+            value: The value to associate with the token.
+        """
+        self.token = token
+        self._real_value = value
+
+    @property
+    def real_value(self) -> Any:
+        """Returns the stored value."""
+        return self._real_value
+
+    def __repr__(self) -> str:
+        return f"TokenWrapper({self._real_value})"
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Delegates attribute access to the wrapped token.
+
+        Parameters:
+            name: The attribute name.
+
+        Returns:
+            The value of the attribute from the wrapped token.
+        """
+        return getattr(self.token, name)
+
+
+def _add_tokens(token1: Token, token2: Token) -> Token:
+    """
+    Concatenates two tokens, creating a new token with combined
+    value and updated positions.
+
+    Parameters:
+        token1: The first token.
+        token2: The second token.
+
+    Returns:
+        A new token with concatenated values and correctly calculated positions.
+    """
+    concatenated_value = token1.value + " " + token2.value
+    return Token(
+        type="CONCAT",
+        value=concatenated_value,
+        start_pos=token1.start_pos,
+        end_pos=token2.end_pos,
+        line=token1.line,
+        column=token1.column,
+        end_line=token2.end_line,
+        end_column=token2.end_column,
+    )
+
+
+def _create_meta(token: Token | TokenWrapper) -> Meta:
+    meta = Meta()
+    meta.empty = False
+    meta.line = token.line if token.line else 1
+    meta.column = token.column if token.column else 1
+    meta.start_pos = token.start_pos if token.start_pos else 0
+    meta.end_line = token.end_line if token.end_line else -1
+    meta.end_column = token.end_column if token.end_column else -1
+    meta.end_pos = token.end_pos if token.end_pos else -1
+    return meta
+
+
+def _get_data_value(
+    path: str, data: Optional[Mapping | MutableSequence]
+) -> Tuple[Any, bool]:
+    """
+    Retrieves a value from the data structure (dictionary-like or list-like)
+    based on a dotted path.
+
+    This method can handle nested dictionaries and lists recursively. If the
+    path leads to a list, it aggregates values from matching keys across all
+    items in the list.
+
+    Parameters:
+        path: A string representing a path of keys, separated by dots.
+        data: The current level of the data structure being processed.
+
+    Returns:
+        A tuple containing:
+        - The value found at the specified path within the data structure,
+          aggregated if the path includes lists.
+        - A boolean indicating whether the variable name was found in the
+          data structure.
+
+    Example:
+        Given the data:
+        {
+            "Source": [
+                {"IP4": [1.1.1.1]},
+                {"IP4": [2.2.2.2]}
+            ]
+        }
+        Querying "Source.IP4" will return ([1.1.1.1, 2.2.2.2], True).
+    """
+    if not path:
+        return data, True  # Return the current data when path is empty
+
+    key, *remaining_list = path.split(".", 1)
+    remaining_path = remaining_list[0] if remaining_list else ""
+
+    if isinstance(data, Mapping):
+        # Navigate dictionary
+        if key not in data:
+            return None, False
+        return _get_data_value(remaining_path, data[key])
+
+    elif isinstance(data, MutableSequence):
+        # Aggregate results from all list elements
+        aggregated: Any = []
+        for item in data:
+            if isinstance(item, (Mapping, MutableSequence)):
+                result, _ = _get_data_value(path, item)
+                if result is not None:
+                    if isinstance(result, MutableSequence):
+                        aggregated.extend(result)
+                    else:
+                        aggregated.append(result)
+        if aggregated:
+            return aggregated, True
+        return None, False
+    return None, False
+
+
+def get_values(data: Optional[Mapping | MutableSequence], path: str) -> list:
+    """
+    Public API method to retrieve values from a nested data structure
+    using a dotted path. Returns a flat list of values or an empty list
+    if nothing is found.
+
+    Parameters:
+        path: A string representing a path of keys, separated by dots.
+        data: The data to search within.
+
+    Returns:
+        A list of values found at the specified path.
+    """
+    result, found = _get_data_value(path, data)
+    if not found or result is None:
+        return []
+    if isinstance(result, MutableSequence):
+        return list(result)
+    return [result]
+
+
+@v_args(inline=True)
+class ExpressionTransformer(Transformer):
+    """
+    A transformer that converts various nodes from the Lark parse tree
+    into appropriate objects (ipranges, datetime, list, ...).
+    """
+
+    def __init__(self, context: dict[str, Any] | None = None) -> None:
+        """
+        Initializes the ExpressionTransformer with a context dictionary
+        for constants.
+
+        Parameters:
+            context: A dictionary containing constant values that can be
+                     accessed by variable names within expressions.
+                     Defaults to an empty dictionary if none is provided.
+        """
+        self.context = context if context is not None else {}
+
+    def number(self, data: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a token representing a number into an integer or float.
+
+        Parameters:
+            data: A token representing a number (can be an integer or
+                  float in string form).
+
+        Returns:
+            A tree node wrapping the number as int or float.
+        """
+        value = int(data) if data.isdigit() else float(data)
+        return Tree("number", [TokenWrapper(data, value)], _create_meta(data))
+
+    def ipv4_single(self, data: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a single IPv4 address into an IP4 object.
+
+        Parameters:
+            data: A token representing a single IPv4 address.
+        Returns:
+            A tree node wrapping an IP4 object.
+        """
+        try:
+            return Tree("ip", [TokenWrapper(data, IP4(data))], _create_meta(data))
+        except ValueError as e:
+            raise ValueError(f"Invalid IPv4 address '{data}'") from e
+
+    def ipv4_cidr(self, net: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms an IPv4 CIDR (network address and prefix) into
+        an IP4Net object.
+
+        Parameters:
+            net: The CIDR network.
+        Returns:
+            A tree node wrapping an IP4Net object.
+        """
+        try:
+            return Tree("ip", [TokenWrapper(net, IP4Net(net))], _create_meta(net))
+        except ValueError as e:
+            raise ValueError(f"Invalid IPv4 CIDR '{net}'") from e
+
+    def ipv4_range(self, range_: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms an IPv4 range (start IP to end IP) into an IP4Range object.
+
+        Parameters:
+            range_: The IPv4 range in a format start-end.
+        Returns:
+            A tree node wrapping an IP4Range object
+        """
+        return Tree(
+            "ip", [TokenWrapper(range_, IP4Range(range_))], _create_meta(range_)
+        )
+
+    def ipv6_single(self, data: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a single IPv6 address into an IP6 object.
+
+        Parameters:
+            data: A token representing a single IPv6 address.
+        Returns:
+            A tree node wrapping an IP6 object.
+        """
+        try:
+            return Tree("ip", [TokenWrapper(data, IP6(data))], _create_meta(data))
+        except ValueError as e:
+            raise ValueError(f"Invalid IPv6 address '{data}'") from e
+
+    def ipv6_cidr(self, net: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms an IPv6 CIDR (network address and prefix) into
+        an IP6Net object.
+
+        Parameters:
+            net: The CIDR network.
+        Returns:
+            A tree node wrapping an IP6Net object.
+        """
+        try:
+            return Tree("ip", [TokenWrapper(net, IP6Net(net))], _create_meta(net))
+        except ValueError as e:
+            raise ValueError(f"Invalid IPv6 CIDR '{net}'") from e
+
+    def ipv6_range(self, range_: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms an IPv6 range (start IP to end IP) into an IP6Range object.
+
+        Parameters:
+            range_: The IPv6 range in a format start-end.
+        Returns:
+            A tree node wrapping an IP6Range object.
+        """
+        return Tree(
+            "ip", [TokenWrapper(range_, IP6Range(range_))], _create_meta(range_)
+        )
+
+    def datetime_full(self, date: Token, time: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a full datetime string into a datetime object.
+
+        Parameters:
+            date: A token representing the date.
+            time: A token representing the time (can include timezone).
+        Returns:
+            A tree node wrapping a datetime object.
+        """
+        datetime_str = f"{date} {time}"
+
+        # Convert z/Z to '+00:00', as it works with both 'T' and ' '
+        if datetime_str.upper().endswith("Z"):
+            datetime_str = datetime_str.upper().replace("Z", "+00:00")
+
+        # Convert to datetime object
+        dtime = datetime.fromisoformat(datetime_str)
+
+        # If no time zone was specified, then set to UTC
+        if dtime.tzinfo is None:
+            dtime = dtime.replace(tzinfo=timezone.utc)
+
+        tw = TokenWrapper(_add_tokens(date, time), dtime)
+
+        return Tree("datetime", [tw], _create_meta(tw))
+
+    def datetime_only_date(self, date: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a date string into a datetime object set to midnight UTC.
+
+        Parameters:
+            date: A token representing the date.
+        Returns:
+            A tree node wrapping a datetime object set to midnight UTC.
+        """
+        return Tree(
+            "datetime",
+            [TokenWrapper(date, datetime.fromisoformat(date + "T00:00:00+00:00"))],
+            _create_meta(date),
+        )
+
+    def timedelta(self, duration: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a token representing a duration into a timedelta object.
+
+        Parameters:
+            duration: A token representing the duration in the format
+                      [days]D HH:MM:SS, e.g., '2D12:34:56'.
+        Returns:
+            A tree node wrapping a timedelta object.
+        """
+        # Match against the regular expression to parse the duration
+        DURATION_RE = re.compile(
+            r"^((?P<days>[0-9]+)[Dd])?"  # Optional days part with 'D' or 'd'
+            r"(?P<hrs>[0-9]{2}):"  # Hours part (exactly 2 digits)
+            r"(?P<mins>[0-9]{2}):"  # Minutes part (exactly 2 digits)
+            r"(?P<secs>[0-9]{2})$"  # Seconds part (exactly 2 digits)
+        )
+        match = DURATION_RE.match(duration)
+
+        # Raise an exception if the duration format is invalid
+        if not match:
+            raise ValueError(f"Invalid duration format: {duration}")
+
+        # Extract days, hours, minutes, and seconds, defaulting to 0 if missing
+        days = int(match.group("days") or 0)
+        hours = int(match.group("hrs") or 0)
+        minutes = int(match.group("mins") or 0)
+        seconds = int(match.group("secs") or 0)
+
+        # Return a timedelta object
+        delta = timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds)
+        return Tree(
+            "timedelta_", [TokenWrapper(duration, delta)], _create_meta(duration)
+        )
+
+    def string(self, data: Token) -> Tree[TokenWrapper]:
+        """
+        Transforms a string (enclosed in quotes) into a regular string.
+
+        Parameters:
+            data: A token representing a string (enclosed in single
+                  or double quotes).
+
+        Returns:
+            A tree node wrapping the string with quotes stripped.
+        """
+        stripped_string = data[1:-1]  # Strip quotes
+        return Tree(
+            "string_", [TokenWrapper(data, stripped_string)], _create_meta(data)
+        )
+
+    def function(self, name: Token, args: Tree[TokenWrapper]) -> Tree[TokenWrapper]:
+        """
+        Transforms a function token and its arguments into a function tree node.
+
+        Parameters:
+            name: A token representing the function name, including an opening bracket.
+            args: A Tree object containing function arguments.
+
+        Returns:
+            A tree node representing the function call.
+        """
+        func = name[:-1]  # Remove opening bracket
+        return Tree("function_", [TokenWrapper(name, func), args], _create_meta(name))
+
+    def variable(self, var: Token) -> Tree:
+        """
+        Resolves a variable token to either a context value or data-driven variable.
+
+        Parameters:
+            var: The variable token to resolve. If prefixed by '.', it is
+                 interpreted as coming directly from data; otherwise, it
+                 checks the context for predefined constants.
+
+        Returns:
+            A tree node representing the variable's resolved value, either
+            from `context` or as a raw variable name from data.
+        """
+        is_from_data = var.startswith(".")
+        if is_from_data:
+            # Strip the '.' prefix for data-driven vars
+            return Tree(
+                "var_from_data", [TokenWrapper(var, var[1:])], _create_meta(var)
+            )
+        if var in self.context:
+            # Resolve from context constants
+            return Tree("var_from_context", [self.context[var]], _create_meta(var))
+        return Tree("var_from_data", [TokenWrapper(var, var)], _create_meta(var))
+
+    def range_op(self, start: TokenWrapper, end: TokenWrapper):
+        """
+        Transforms a range operation (start to end) into an appropriate range object.
+
+        Parameters:
+            start: The start token of the range.
+            end: The end token of the range.
+
+        Returns:
+            A tree node wrapping a range object. If the tokens represent
+            IP addresses, the range will be transformed into an IP4Range
+            or IP6Range object, depending on the IP version; otherwise,
+            it will return a generic range operation node.
+        """
+
+        def _create_ip_node(range_class) -> Tree[TokenWrapper]:
+            """
+            Helper function to create a tree node for IP ranges.
+
+            Parameters:
+                range_class: The class (IP4Range or IP6Range) to instantiate.
+
+            Returns:
+                A tree node wrapping the created IP range object.
+            """
+            return Tree(
+                "ip",
+                [
+                    TokenWrapper(
+                        _add_tokens(_start.token, _end.token),
+                        range_class(f"{_start.token}-{_end.token}"),
+                    )
+                ],
+            )
+
+        _start, _end = start.children[0], end.children[0]
+        if isinstance(_start.real_value, IP4) and isinstance(_end.real_value, IP4):
+            return _create_ip_node(IP4Range)
+        elif isinstance(_start.real_value, IP6) and isinstance(_end.real_value, IP6):
+            return _create_ip_node(IP6Range)
+        return Tree("range_op", [start, end])
+
+
+@v_args(inline=True)
+class Filter(Interpreter):
+    """
+    A class that evaluates parsed expressions using provided data.
+
+    It provides methods to handle various operations such as arithmetic,
+    logical conditions, and data extraction.
+    """
+
+    data = None
+
+    def eval(self, tree: Tree, data: Optional[dict] = None):
+        """
+        Evaluates the given tree using the provided data.
+
+        Parameters:
+            tree: The parse tree to evaluate.
+            data: Optional dictionary containing the data being searched.
+
+        Returns:
+            The result of evaluating the tree.
+        """
+        self.data = data if data is not None else {}
+
+        res = self.visit(tree)
+
+        self.data = None
+        return res
+
+    def number(self, token: TokenWrapper) -> int | float:
+        """
+        Extracts a numeric value from a token.
+
+        Parameters:
+            token: A TokenWrapper object.
+
+        Returns:
+            The numeric value associated with the token.
+        """
+        return token.real_value
+
+    def ip(self, token: TokenWrapper) -> IP4:
+        """
+        Extracts an IP address from a token.
+
+        Parameters:
+            token: A TokenWrapper object.
+
+        Returns:
+            The IP4 address associated with the token.
+        """
+        return token.real_value
+
+    def datetime(self, token: TokenWrapper) -> datetime:
+        """
+        Extracts a datetime value from a token.
+
+        Parameters:
+            token: A TokenWrapper object.
+
+        Returns:
+            The datetime value associated with the token.
+        """
+        return token.real_value
+
+    def timedelta_(self, token: TokenWrapper) -> timedelta:
+        """
+        Extracts a timedelta value from a token.
+
+        Parameters:
+            token: A TokenWrapper object.
+
+        Returns:
+            The timedelta value associated with the token.
+        """
+        return token.real_value
+
+    def string_(self, token: TokenWrapper) -> str:
+        """
+        Extracts a string value from a token.
+
+        Parameters:
+            token: A TokenWrapper object.
+
+        Returns:
+            The string value associated with the token.
+        """
+        return token.real_value
+
+    def _binary_operation(self, op: str, l_tree: Tree, r_tree: Tree) -> Any:
+        try:
+            return binary_operation(op, self.visit(l_tree), self.visit(r_tree))
+        except Exception as e:
+            raise EvaluationError(
+                str(e),
+                line=l_tree.meta.line,
+                column=l_tree.meta.column,
+                start_pos=l_tree.meta.start_pos,
+                end_line=r_tree.meta.end_line,
+                end_column=r_tree.meta.end_column,
+                end_pos=r_tree.meta.end_pos,
+            ) from None
+
+    def add(self, l_tree: Tree, r_tree: Tree) -> Any:
+        return self._binary_operation("+", l_tree, r_tree)
+
+    def sub(self, l_tree: Tree, r_tree: Tree) -> Any:
+        return self._binary_operation("-", l_tree, r_tree)
+
+    def neg(self, tree: Tree) -> Any:
+        return -(self.visit(tree))
+
+    def mul(self, l_tree: Tree, r_tree: Tree) -> Any:
+        return self._binary_operation("*", l_tree, r_tree)
+
+    def div(self, l_tree: Tree, r_tree: Tree) -> Any:
+        return self._binary_operation("/", l_tree, r_tree)
+
+    def mod(self, l_tree: Tree, r_tree: Tree) -> Any:
+        return self._binary_operation("%", l_tree, r_tree)
+
+    def eq(self, l_tree: Tree, r_tree: Tree) -> bool:
+        return self.visit(l_tree) == self.visit(r_tree)
+
+    def gt(self, l_tree: Tree, r_tree: Tree) -> bool:
+        return self._binary_operation(">", l_tree, r_tree)
+
+    def gte(self, l_tree: Tree, r_tree: Tree) -> bool:
+        return self._binary_operation(">=", l_tree, r_tree)
+
+    def lt(self, l_tree: Tree, r_tree: Tree) -> bool:
+        return self._binary_operation("<", l_tree, r_tree)
+
+    def lte(self, l_tree: Tree, r_tree: Tree) -> bool:
+        return self._binary_operation("<=", l_tree, r_tree)
+
+    def any_eq(self, l_tree: Tree, r_tree: Tree) -> bool:
+        return self._binary_operation("=", l_tree, r_tree)
+
+    def or_op(self, l_tree: Tree, r_tree: Tree) -> bool:
+        """
+        Performs a logical OR operation.
+
+        If the left tree is evaluated to True, the right tree is not traversed.
+
+        Parameters:
+            l_tree: The left subtree.
+            r_tree: The right subtree.
+
+        Returns:
+            True if either subtree evaluates to True, otherwise False.
+        """
+        return self.visit(l_tree) or self.visit(r_tree)
+
+    def and_op(self, l_tree: Tree, r_tree: Tree) -> bool:
+        """
+        Performs a logical AND operation.
+
+        If the left tree is evaluated to False, the right tree is not traversed.
+
+        Parameters:
+            l_tree: The left subtree.
+            r_tree: The right subtree.
+
+        Returns:
+            True if both subtrees evaluate to True, otherwise False.
+        """
+        return self.visit(l_tree) and self.visit(r_tree)
+
+    def not_op(self, tree: Tree) -> bool:
+        """
+        Performs a logical NOT operation.
+
+        Parameters:
+            tree: The subtree.
+
+        Returns:
+            True if the subtree evaluates to False, otherwise False.
+        """
+        return not self.visit(tree)
+
+    def like_op(self, l_tree: Tree, r_tree: Tree) -> bool:
+        """
+        Checks if a string matches a regular expression pattern.
+
+        Parameters:
+            l_tree: Subtree representing the string to check.
+            r_tree: Subtree representing the regex pattern.
+
+        Returns:
+            True if the string matches the pattern, otherwise False.
+        """
+        return self._binary_operation("like", l_tree, r_tree)
+
+    def in_op(self, l_tree: Tree, r_tree: Tree) -> bool:
+        """
+        Checks if a value exists within a data structure.
+
+        Parameters:
+            l_tree: Subtree representing the value to look for.
+            r_tree: Subtree representing the data structure.
+
+        Returns:
+            True if the value exists in the data structure, otherwise False.
+        """
+        return self._binary_operation("in", l_tree, r_tree)
+
+    def contains_op(self, l_tree: Tree, r_tree: Tree) -> bool:
+        """
+        Checks if a string data contains string value.
+
+        Parameters:
+            l_tree: Subtree representing the string being searched.
+            r_tree: Subtree representing the value to check.
+
+        Returns:
+            True if the string contains the value, otherwise False.
+        """
+        return self._binary_operation("contains", l_tree, r_tree)
+
+    def concat_op(self, l_tree: Tree, r_tree: Tree) -> list | str:
+        """
+        Concatenates two sequences or strings.
+
+        Parameters:
+            l_tree: Subtree representing the first sequence or string.
+            r_tree: Subtree representing the second sequence or string.
+
+        Returns:
+            The concatenated result.
+        """
+        return self._binary_operation(".", l_tree, r_tree)
+
+    def var_from_context(self, var) -> Any:
+        """
+        Retrieves a variable directly from the context.
+
+        Parameters:
+            var: The variable name.
+
+        Returns:
+            The value of the variable in the context.
+        """
+        return var
+
+    def var_from_data(self, var: TokenWrapper):
+        """
+        Retrieves a variable's value from the data dictionary.
+
+        Parameters:
+            var: The variable name as a string.
+
+        Returns:
+            The value associated with the variable in the data dictionary.
+
+        Raises:
+            EvaluationError: If var is not found in the provided data.
+        """
+        res, exists = _get_data_value(var.real_value, self.data)
+        if not exists:
+            raise EvaluationError(
+                f"Variable '{var.real_value}' not found in the provided data!",
+                line=var.line,
+                column=var.column,
+                start_pos=var.start_pos,
+                end_line=var.end_line,
+                end_column=var.end_column,
+                end_pos=var.end_pos,
+            )
+        return res
+
+    @v_args(tree=True)
+    def list(self, data: Tree) -> list:
+        """
+        Extracts non-None children from a tree structure.
+
+        Parameters:
+            data: A Tree object.
+
+        Returns:
+            A list of non-None children from the tree.
+        """
+        return [self.visit(x) for x in data.children if x is not None]
+
+    def range_op(self, l_tree: Tree, r_tree: Tree) -> tuple:
+        """
+        Creates a tuple representing a range.
+
+        Parameters:
+            l_tree: Subtree representing the start of the range.
+            r_tree: Subtree representing the end of the range.
+
+        Returns:
+            A tuple containing the start and end values.
+        """
+        return (self.visit(l_tree), self.visit(r_tree))
+
+    def exists_op(self, path: Token) -> bool:
+        """
+        Tests whether a variable on a given path exists in data.
+
+        Parameters:
+            path: The variable name as a string.
+
+        Returns:
+            True if the variable exists, otherwise False.
+        """
+        _, exists = _get_data_value(path, self.data)
+        return exists
+
+    def exists_with_default(self, path: Token, default: Any) -> Any:
+        """
+        Tests whether a variable on a given path exists in data and returns its
+        value or a default if not found.
+
+        Parameters:
+            path: The variable name as a string.
+            default: The value to return if the variable does not exist.
+
+        Returns:
+            The value of the variable if it exists, otherwise the default value.
+        """
+        res, exists = _get_data_value(path, self.data)
+        if exists:
+            return res
+        return self.visit(default)
+
+    def function_(self, name: TokenWrapper, args: Tree | None):
+        """
+        Calls a predefined function with the given arguments.
+
+        Parameters:
+            name: The name of the function as a TokenWrapper.
+            args: A Tree object containing function arguments or None.
+
+        Returns:
+            The result of the function call.
+
+        Raises:
+            ValueError: If the function name is not found in predefined functions.
+        """
+        function_name = name.real_value
+        if function_name in predefined_functions:
+            try:
+                return predefined_functions[function_name](
+                    *(self.visit(x) for x in (args.children if args else []))  # type: ignore
+                )
+            except TypeError as e:
+                raise EvaluationError(
+                    str(e),
+                    line=args.meta.line if args else name.line,
+                    column=args.meta.column if args else name.column,
+                    start_pos=args.meta.start_pos if args else name.start_pos,
+                    end_line=args.meta.end_line if args else name.end_line,
+                    end_column=args.meta.end_column if args else name.end_column,
+                    end_pos=args.meta.end_pos if args else name.end_pos,
+                )
+        raise EvaluationError(
+            f"Function '{name.real_value}' was not found.",
+            line=name.line,
+            column=name.column,
+            start_pos=name.start_pos,
+            end_line=name.end_line,
+            end_column=name.end_column,
+            end_pos=name.end_pos,
+        )