jaclang 0.7.29__py3-none-any.whl → 0.7.31__py3-none-any.whl

jaclang/__init__.py

@@ -1,12 +1,428 @@
 """The Jac Programming Language."""
 
+import inspect
+import os
+from abc import ABCMeta, abstractmethod as abstract
+from dataclasses import dataclass, field as dc_field
+from types import ModuleType
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    Generic,
+    Tuple,
+    Type,
+    TypeGuard,
+    TypeVar,
+    cast,
+    override,
+)
+
+from jaclang.plugin.builtin import dotgen, jid, jobj  # noqa: F401
 from jaclang.plugin.default import JacFeatureImpl
-from jaclang.plugin.feature import JacFeature, plugin_manager
+from jaclang.plugin.feature import JacFeature as Jac, plugin_manager
+from jaclang.plugin.spec import EdgeDir
+from jaclang.runtimelib.context import ExecutionContext
+
+__all__ = [
+    # Jac types.
+    "Obj",
+    "Walker",
+    "Node",
+    "Edge",
+    "JacList",
+    "EdgeDir",
+    "Root",
+    # Decorators.
+    "with_entry",
+    "with_exit",
+    "jac_test",
+    "abstract",
+    "override",
+    # Functions.
+    "jac_import",
+    "field",
+    # Builtin.
+    "Jac",
+    "root",
+    "static",
+    "dotgen",
+    "jid",
+    "jobj",
+]
 
-jac_import = JacFeature.jac_import
 
+# ----------------------------------------------------------------------------
+# Plugin Initialization.
+# ----------------------------------------------------------------------------
 
 plugin_manager.register(JacFeatureImpl)
 plugin_manager.load_setuptools_entrypoints("jac")
 
-__all__ = ["jac_import"]
+T = TypeVar("T")
+S = TypeVar("S")  # S is a subtype of T.
+
+# ----------------------------------------------------------------------------
+# Meta classes.
+# ----------------------------------------------------------------------------
+
+
+# Since the meta class of the architypes are changine the base class to it's
+# suitable archi type, If a class doesn't have a parent class (ie. by default
+# inherit from object) __bases__ will be immutable. So we need to use a dummy
+# parent class to make it mutable.
+#
+# Reference: https://stackoverflow.com/a/9639512/10846399
+#
+class _ArchiTypeBase:
+
+    def __init__(self, *args, **kwargs) -> None:  # noqa: ANN002, ANN003
+        """Initialize Jac architype base."""
+
+
+class JacMeta(ABCMeta):
+    """Common metaclass for Jac types."""
+
+    def __new__(  # noqa: D102
+        cls,
+        name: str,
+        bases: Tuple[Type, ...],
+        dct: Dict[str, Any],
+    ) -> "JacMeta":
+
+        # We have added this "__init__" to the jac base class just to make the type checkers happy.
+        # Actually the dataclass decorator will create an __init__ function and assign it here bellow.
+        if bases == (_ArchiTypeBase,) and "__init__" in dct:
+            del dct["__init__"]
+
+        on_entry, on_exit = [], []
+        for func in dct.values():
+            if hasattr(func, "__jac_entry"):
+                on_entry.append(Jac.DSFunc(func.__name__, func))
+            if hasattr(func, "__jac_exit"):
+                on_exit.append(Jac.DSFunc(func.__name__, func))
+
+        inst = super().__new__(cls, name, bases, dct)
+        inst = dataclass(eq=False)(inst)  # type: ignore [arg-type, assignment]
+        inst = inst._MAKE_FN(on_entry, on_exit)(inst)  # type: ignore [assignment, attr-defined]
+        return inst
+
+
+# ----------------------------------------------------------------------------
+# Base classes.
+# ----------------------------------------------------------------------------
+
+
+class Obj(_ArchiTypeBase, metaclass=JacMeta):
+    """Base class for all the jac object types."""
+
+    _MAKE_FN = Jac.make_obj
+
+
+class Walker(_ArchiTypeBase, metaclass=JacMeta):
+    """Base class for all the jac walker types."""
+
+    _MAKE_FN = Jac.make_walker
+
+    def spawn(self, node: "Node | Root") -> "Walker":
+        """Spawn a new node from the walker."""
+        return Jac.spawn_call(self, node)  # type: ignore [arg-type, return-value]
+
+    def ignore(
+        self,
+        expr: """(
+        Root
+        | Node
+        | Edge
+        | list[Node | Root | Edge]
+        | JacList[Node | Root | Edge]
+        )""",
+    ) -> bool:
+        """Ignore statement."""
+        return Jac.ignore(self, expr)  # type: ignore [arg-type]
+
+    def visit(
+        self,
+        expr: """(
+            Root
+            | Node
+            | Edge
+            | list[Node | Root | Edge]
+            | JacList[Node | Root | Edge]
+        )""",
+    ) -> bool:
+        """Visit statement."""
+        return Jac.visit_node(self, expr)  # type: ignore [arg-type]
+
+    def disengage(self) -> None:
+        """Disengage statement."""
+        Jac.disengage(self)  # type: ignore [arg-type]
+
+
+class Node(_ArchiTypeBase, metaclass=JacMeta):
+    """Base class for all the jac node types."""
+
+    _MAKE_FN = Jac.make_node
+
+    def spawn(self, archi: Walker) -> "Walker":
+        """Spawn a new node from the walker."""
+        return Jac.spawn_call(self, archi)  # type: ignore [arg-type, return-value]
+
+    def connect(
+        self,
+        node: "Node | Root | JacList[Node | Root]",
+        edge: "type[Edge] | Edge | None" = None,
+        unidir: bool = False,
+        conn_assign: tuple[tuple, tuple] | None = None,
+        edges_only: bool = False,
+    ) -> "JacList[Node | Root| Edge]":
+        """Connect the current node to another node."""
+        # TODO: The above edge type should be reviewed, as the bellow can also take None, Edge, type[Edge].
+        ret = Jac.connect(
+            left=self,  # type: ignore [arg-type]
+            right=node,  # type: ignore [arg-type]
+            edge_spec=Jac.build_edge(
+                is_undirected=unidir, conn_type=edge, conn_assign=conn_assign  # type: ignore [arg-type]
+            ),
+            edges_only=edges_only,
+        )
+        return JacList(ret)  # type: ignore [arg-type]
+
+    def disconnect(
+        self,
+        node: "Node | Root | JacList[Node | Root]",
+        edge: "type[Edge] | None" = None,
+        dir: EdgeDir = EdgeDir.OUT,
+    ) -> bool:
+        """Disconnect the current node from the graph."""
+        filter_func = None
+        if edge:
+            filter_func = lambda edges: [  # noqa: E731
+                ed for ed in edges if isinstance(ed, edge)
+            ]
+        return Jac.disconnect(self, node, dir=dir, filter_func=filter_func)  # type: ignore [arg-type]
+
+    def refs(
+        self,
+        edge: "type[Edge] | None" = None,
+        cond: "Callable[[Edge], bool] | None" = None,
+        target: "Node | Root | JacList[Node|Root] | None" = None,
+        dir: EdgeDir = EdgeDir.OUT,
+        edges_only: bool = False,
+    ) -> "JacList[Node | Root | Edge]":
+        """Return all the connected nodes / edges."""
+        filter_func = (
+            (
+                lambda edges: (  # noqa: E731
+                    [ed for ed in edges if isinstance(ed, edge) if not cond or cond(ed)]
+                )
+            )
+            if edge
+            else None
+        )
+        ret = plugin_manager.hook.edge_ref(
+            node_obj=self,
+            target_obj=target,
+            dir=dir,
+            filter_func=filter_func,
+            edges_only=edges_only,
+        )
+        return JacList(ret)
+
+
+class Root(_ArchiTypeBase, metaclass=JacMeta):
+    """Base class for jac root type."""
+
+    _MAKE_FN = Jac.make_root
+
+    def spawn(self, archi: Walker) -> "Walker":
+        """Spawn a new node from the walker."""
+        return Jac.spawn_call(self, archi)  # type: ignore [arg-type, return-value]
+
+    def connect(
+        self,
+        node: "Node | Root | JacList[Node | Root]",
+        edge: "type[Edge] | Edge | None" = None,
+        unidir: bool = False,
+        conn_assign: tuple[tuple, tuple] | None = None,
+        edges_only: bool = False,
+    ) -> "JacList[Node | Root| Edge]":
+        """Connect the current node to another node."""
+        # TODO: The above edge type should be reviewed, as the bellow can also take None, Edge, type[Edge].
+        ret = Jac.connect(
+            left=self,  # type: ignore [arg-type]
+            right=node,  # type: ignore [arg-type]
+            edge_spec=Jac.build_edge(
+                is_undirected=unidir, conn_type=edge, conn_assign=conn_assign  # type: ignore [arg-type]
+            ),
+            edges_only=edges_only,
+        )
+        return JacList(ret)  # type: ignore [arg-type]
+
+    def disconnect(
+        self,
+        node: "Node | Root | JacList[Node | Root]",
+        edge: "type[Edge] | None" = None,
+        dir: EdgeDir = EdgeDir.OUT,
+    ) -> bool:
+        """Disconnect the current node from the graph."""
+        filter_func = None
+        if edge:
+            filter_func = lambda edges: [  # noqa: E731
+                ed for ed in edges if isinstance(ed, edge)
+            ]
+        return Jac.disconnect(self, node, dir=dir, filter_func=filter_func)  # type: ignore [arg-type]
+
+    def refs(
+        self,
+        edge: "type[Edge] | None" = None,
+        cond: "Callable[[Edge], bool] | None" = None,
+        target: "Node | Root | JacList[Node|Root] | None" = None,
+        dir: EdgeDir = EdgeDir.OUT,
+        edges_only: bool = False,
+    ) -> "JacList[Node | Root | Edge]":
+        """Return all the connected nodes / edges."""
+        filter_func = (
+            (
+                lambda edges: (  # noqa: E731
+                    [ed for ed in edges if isinstance(ed, edge) if not cond or cond(ed)]
+                )
+            )
+            if edge
+            else None
+        )
+        ret = plugin_manager.hook.edge_ref(
+            node_obj=self,
+            target_obj=target,
+            dir=dir,
+            filter_func=filter_func,
+            edges_only=edges_only,
+        )
+        return JacList(ret)
+
+
+class Edge(_ArchiTypeBase, metaclass=JacMeta):
+    """Base class for all the jac edge types."""
+
+    _MAKE_FN = Jac.make_edge
+
+    def spawn(self, archi: Walker) -> "Walker":
+        """Spawn a new node from the walker."""
+        return Jac.spawn_call(self, archi)  # type: ignore [arg-type, return-value]
+
+
+class GenericEdge(_ArchiTypeBase, metaclass=JacMeta):
+    """Base class for jac root type."""
+
+    _MAKE_FN = Jac.make_generic_edge
+
+    def spawn(self, archi: Walker) -> "Walker":
+        """Spawn a new node from the walker."""
+        return Jac.spawn_call(self, archi)  # type: ignore [arg-type, return-value]
+
+
+class JacList(Generic[T], list[T]):
+    """List with jac methods."""
+
+    # Reuse the methods.
+    connect = Node.connect
+    disconnect = Node.disconnect
+    refs = Node.refs
+
+    def filter(
+        self,
+        ty: Type[S] | None = None,
+        fn: Callable[[T | S], TypeGuard[S]] | None = None,
+    ) -> "JacList[S]":
+        """Filter comprehension."""
+        if ty and fn:
+            return JacList([item for item in self if isinstance(item, ty) and fn(item)])
+        if ty:
+            return JacList([item for item in self if isinstance(item, ty)])
+        if fn:
+            return JacList(list(filter(fn, self)))
+        return cast(JacList[S], self)
+
+    def assign(self, attrs: tuple[str], values: tuple[Any]) -> "JacList[T]":
+        """Assign Comprehension."""
+        return JacList(Jac.assign_compr(self, (attrs, values)))
+
+
+# ----------------------------------------------------------------------------
+# Decorators.
+# ----------------------------------------------------------------------------
+
+
+def with_entry(func: Callable) -> Callable:
+    """Mark a method as jac entry with this decorator."""
+    setattr(func, "__jac_entry", True)  # noqa: B010
+    return func
+
+
+def with_exit(func: Callable) -> Callable:
+    """Mark a method as jac exit with this decorator."""
+    setattr(func, "__jac_exit", True)  # noqa: B010
+    return func
+
+
+# ----------------------------------------------------------------------------
+# Functions.
+# ----------------------------------------------------------------------------
+
+
+def jac_import(
+    target: str,
+    lng: str | None = "jac",
+    base_path: str | None = None,
+    absorb: bool = False,
+    cachable: bool = True,
+    alias: str | None = None,
+    override_name: str | None = None,
+    items: dict[str, str | None] | None = None,
+    reload_module: bool | None = False,
+) -> tuple[ModuleType, ...]:
+    """Import a module."""
+    base_path = base_path or os.path.dirname(inspect.stack()[1].filename)
+    return Jac.jac_import(
+        target=target,
+        lng=lng,
+        base_path=base_path,
+        absorb=absorb,
+        cachable=cachable,
+        mdl_alias=alias,
+        override_name=override_name,
+        items=items,
+        reload_module=reload_module,
+    )
+
+
+def field(
+    value: T = None,  # type: ignore [assignment]
+    gen: Callable[[], T] | None = None,
+    postinit: bool = False,
+) -> T:
+    """Set the default value to jac architype dataclass."""
+    if postinit:
+        return dc_field(init=False)
+    gen = gen or (lambda: value)  # noqa: E731
+    return Jac.has_instance_default(gen_func=gen)  # type: ignore
+
+
+# ----------------------------------------------------------------------------
+# Builtin.
+# ----------------------------------------------------------------------------
+
+jac_test = Jac.create_test
+static = ClassVar
+
+root = cast(Root, Jac.get_root())
+
+
+# Listen to context change and update the above global root here.
+def _update_root() -> None:
+    global root
+    root = cast(Root, ExecutionContext.get_root())
+
+
+ExecutionContext.on_ctx_change.append(lambda ctx: _update_root())

jaclang/compiler/__init__.py

@@ -55,7 +55,7 @@ TOKEN_MAP.update(
         "CARROW_L": "<++", "CARROW_R": "++>", "GLOBAL_OP": ":global:",
         "NONLOCAL_OP": ":nonlocal:", "WALKER_OP": ":walker:", "NODE_OP": ":node:",
         "EDGE_OP": ":edge:", "CLASS_OP": ":class:", "OBJECT_OP": ":obj:",
-        "TYPE_OP": "`", "ABILITY_OP": ":can:", "ELVIS_OP": "?:", "NULL_OK": "?",
+        "TYPE_OP": "`", "ABILITY_OP": ":can:", "NULL_OK": "?",
         "KW_OR": "|", "ARROW_BI": "<-->", "ARROW_L": "<--",
         "ARROW_R": "-->", "ARROW_L_P1": "<-:", "ARROW_R_P2": ":->",
         "ARROW_L_P2": ":-", "ARROW_R_P1": "-:", "CARROW_BI": "<++>",

jaclang/compiler/absyntree.py

@@ -462,7 +462,7 @@ class NameAtom(AtomExpr, EnumBlockStmt):
         self._sym: Optional[Symbol] = None
         self._sym_name: str = ""
         self._sym_category: SymbolType = SymbolType.UNKNOWN
-        self._py_ctx_func: Type[ast3.AST] = ast3.Load
+        self._py_ctx_func: Type[ast3.expr_context] = ast3.Load
         AtomExpr.__init__(self)
 
     @property
@@ -492,12 +492,12 @@ class NameAtom(AtomExpr, EnumBlockStmt):
         return ret_type
 
     @property
-    def py_ctx_func(self) -> Type[ast3.AST]:
+    def py_ctx_func(self) -> Type[ast3.expr_context]:
         """Get python context function."""
         return self._py_ctx_func
 
     @py_ctx_func.setter
-    def py_ctx_func(self, py_ctx_func: Type[ast3.AST]) -> None:
+    def py_ctx_func(self, py_ctx_func: Type[ast3.expr_context]) -> None:
         """Set python context function."""
         self._py_ctx_func = py_ctx_func
 
@@ -1013,8 +1013,9 @@ class ModulePath(AstSymbolNode):
         target = self.dot_path_str
         if target_item:
             target += f".{target_item}"
-        base_path = os.path.dirname(self.loc.mod_path)
-        base_path = base_path if base_path else os.getcwd()
+        base_path = (
+            os.getenv("JACPATH") or os.path.dirname(self.loc.mod_path) or os.getcwd()
+        )
         parts = target.split(".")
         traversal_levels = self.level - 1 if self.level > 0 else 0
         actual_parts = parts[traversal_levels:]
@@ -1026,6 +1027,15 @@ class ModulePath(AstSymbolNode):
             if os.path.exists(relative_path + ".jac")
             else relative_path
         )
+        jacpath = os.getenv("JACPATH")
+        if not os.path.exists(relative_path) and jacpath:
+            name_to_find = actual_parts[-1] + ".jac"
+
+            # Walk through the single path in JACPATH
+            for root, _, files in os.walk(jacpath):
+                if name_to_find in files:
+                    relative_path = os.path.join(root, name_to_find)
+                    break
         return relative_path
 
     def normalize(self, deep: bool = False) -> bool:

jaclang/compiler/compile.py

@@ -31,7 +31,7 @@ def jac_file_to_pass(
     schedule: list[Type[Pass]] = pass_schedule,
 ) -> Pass:
     """Convert a Jac file to an AST."""
-    with open(file_path) as file:
+    with open(file_path, "r", encoding="utf-8") as file:
         return jac_str_to_pass(
             jac_str=file.read(),
             file_path=file_path,

jaclang/compiler/constant.py

@@ -91,8 +91,9 @@ class Constants(StrEnum):
     """Token constants for Jac."""
 
     JAC_LANG_IMP = "jac"
-    HERE = "_jac_here_"
-    JAC_FEATURE = "_Jac"
+    HERE = "here"  # "_jac_here_"
+    JAC_CHECK = "_check"
+    JAC_FEATURE = "Jac"  # "_Jac"
     ROOT = f"{JAC_FEATURE}.get_root()"
     EDGES_TO_NODE = "__jac__.edges_to_nodes"
     EDGE_REF = "__jac__.edge_ref"
@@ -152,7 +153,6 @@ class Tokens(str, Enum):
 
     FLOAT = "FLOAT"
     STRING = "STRING"
-    DOC_STRING = "DOC_STRING"
     PYNLINE = "PYNLINE"
     BOOL = "BOOL"
     INT = "INT"
@@ -315,7 +315,6 @@ class Tokens(str, Enum):
     ABILITY_OP = "ABILITY_OP"
     A_PIPE_FWD = "A_PIPE_FWD"
     A_PIPE_BKWD = "A_PIPE_BKWD"
-    ELVIS_OP = "ELVIS_OP"
     RETURN_HINT = "RETURN_HINT"
     NULL_OK = "NULL_OK"
     DECOR_OP = "DECOR_OP"
@@ -356,7 +355,7 @@ colors = [
     "#F0FFF0",
     "#F5E5FF",
     "#FFFFE0",
-    "#D2FEFF ",
+    "#D2FEFF",
     "#E8FFD7",
     "#FFDEAD",
     "#FFF0F5",