jaclang 0.7.34__py3-none-any.whl → 0.8.1__py3-none-any.whl

jaclang/cli/cmdreg.py

@@ -6,7 +6,8 @@ import argparse
 import cmd
 import inspect
 import pprint
-from typing import Callable, Optional
+import re
+from typing import Callable, Dict, Optional
 
 
 class Command:
@@ -25,6 +26,57 @@ class Command:
         return self.func(*args, **kwargs)
 
 
+def extract_param_descriptions(docstring: str) -> Dict[str, str]:
+    """Extract parameter descriptions from a function's docstring.
+
+    Args:
+        docstring: The function's docstring
+
+    Returns:
+        A dictionary mapping parameter names to their descriptions
+    """
+    param_descriptions: dict[str, str] = {}
+
+    # Check if the docstring has an Args section
+    args_match = re.search(r"Args:(.*?)(?:\n\n|\Z)", docstring, re.DOTALL)
+    if not args_match:
+        return param_descriptions
+
+    args_section = args_match.group(1)
+
+    # Extract parameter descriptions from the Args section
+    # Looking for patterns like "param_name: Description" or "param_name (type): Description"
+    current_param = None
+    current_desc = []
+
+    for line in args_section.strip().split("\n"):
+        line = line.strip()
+        if not line:
+            continue
+
+        # Match parameter name at the beginning of the line
+        param_match = re.match(r"\s*([a-zA-Z0-9_]+)(?:\s*\([^)]*\))?:\s*(.*)", line)
+        if param_match:
+            # Save the previous parameter if there was one
+            if current_param and current_desc:
+                param_descriptions[current_param] = " ".join(current_desc)
+                current_desc = []
+
+            # Start a new parameter
+            current_param = param_match.group(1)
+            if param_match.group(2):
+                current_desc.append(param_match.group(2))
+        elif current_param and line:
+            # Continue the description for the current parameter
+            current_desc.append(line)
+
+    # Save the last parameter
+    if current_param and current_desc:
+        param_descriptions[current_param] = " ".join(current_desc)
+
+    return param_descriptions
+
+
 class CommandRegistry:
     """Registry for managing commands in the command line interface."""
 
@@ -36,11 +88,24 @@ class CommandRegistry:
     def __init__(self) -> None:
         """Initialize a CommandRegistry instance."""
         self.registry = {}
-        self.parser = argparse.ArgumentParser(prog="jac")
+        self.parser = argparse.ArgumentParser(
+            prog="jac",
+            description="Jac Programming Language CLI - A tool for working with Jac programs",
+            epilog="For more information, visit: https://github.com/Jaseci-Labs/jaseci",
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
         self.parser.add_argument(
-            "-V", "--version", action="store_true", help="Show the Jac version"
+            "-V",
+            "--version",
+            action="store_true",
+            help="Show the Jac version and installation path",
+        )
+        self.sub_parsers = self.parser.add_subparsers(
+            title="commands",
+            dest="command",
+            description="The following commands are available:",
+            metavar="COMMAND",
         )
-        self.sub_parsers = self.parser.add_subparsers(title="commands", dest="command")
         self.args = argparse.Namespace()
 
     def register(self, func: Callable) -> Callable:
@@ -48,12 +113,34 @@ class CommandRegistry:
         name = func.__name__
         cmd = Command(func)
         self.registry[name] = cmd
+        # Extract the first paragraph from the docstring for brief description
+        doc = func.__doc__ or ""
+        brief_desc = doc.split("\n\n")[0].strip()
+
+        # Use the full docstring for the detailed description
         cmd_parser: argparse.ArgumentParser = self.sub_parsers.add_parser(
-            name, description=func.__doc__
+            name,
+            description=func.__doc__,
+            help=brief_desc,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
         )
         first = True
         for param_name, param in cmd.sig.parameters.items():
-            arg_msg = f"type: {param.annotation.__name__}"
+            # Get parameter type name
+            type_name = (
+                param.annotation.__name__
+                if hasattr(param.annotation, "__name__")
+                else str(param.annotation)
+            )
+
+            # Extract parameter descriptions from the docstring
+            docstring_param_descriptions = extract_param_descriptions(doc)
+
+            # Use docstring description if available, otherwise fallback to predefined or just type
+            if param_name in docstring_param_descriptions:
+                arg_msg = f"{type_name} - {docstring_param_descriptions[param_name]}"
+            else:
+                arg_msg = f"{type_name}"
             # shorthand is first character by default,
             # If already taken, use the first 2 characters
             shorthand = param_name[:1]
@@ -182,43 +269,113 @@ class CommandShell(cmd.Cmd):
                 self.stdout.write(f"{ret_str}\n")
 
     def do_help(self, arg: str) -> None:
-        """Jac CLI 'help' implementaion."""
+        """Jac CLI help implementation."""
 
         def get_info(name: str, doc: str, args: dict[str, inspect.Parameter]) -> None:
-            """Details to display."""
-            arg_details = ", ".join(
-                [
-                    f"{param.name}: {param.annotation.__name__}"
-                    for param in args.values()
-                ]
-            )
-            self.stdout.write(f"{name}: {doc}\n")
-            self.stdout.write(
-                f"\tArguments: {arg_details}\n" if arg_details else "\tNo arguments\n"
-            )
+            """Format and display detailed command information."""
+            # Format the command header
+            self.stdout.write(f"\n{'=' * 80}\n")
+            self.stdout.write(f"COMMAND: {name}\n")
+            self.stdout.write(f"{'=' * 80}\n\n")
+
+            # Format the command description
+            doc_lines = doc.strip().split("\n")
+            for line in doc_lines:
+                self.stdout.write(f"{line}\n")
+
+            # Format the command arguments
+            if args:
+                self.stdout.write("\nARGUMENTS:\n")
+                for param_name, param in args.items():
+                    # Get parameter type
+                    type_name = (
+                        param.annotation.__name__
+                        if hasattr(param.annotation, "__name__")
+                        else str(param.annotation)
+                    )
+
+                    # Format default value if present
+                    default_str = ""
+                    if param.default is not param.empty:
+                        default_str = f" (default: {param.default})"
+
+                    # Format required/optional status
+                    req_str = (
+                        " [required]"
+                        if param.default is param.empty and param_name != "args"
+                        else " [optional]"
+                    )
+
+                    self.stdout.write(
+                        f"  {param_name}: {type_name}{default_str}{req_str}\n"
+                    )
+            else:
+                self.stdout.write("\nNo arguments\n")
+
+            # Format usage examples
             command_parser = self.cmd_reg.sub_parsers.choices[name]
-            self.stdout.write(f"\tUsage: {command_parser.format_usage()[7:]}\n")
+            self.stdout.write(f"\nUSAGE:\n  {command_parser.format_usage()[7:]}\n")
+
+            # Extract and format examples from docstring if present
+            if "Examples:" in doc:
+                examples_section = doc.split("Examples:")[1].strip()
+                example_lines = examples_section.split("\n")
+                self.stdout.write("\nEXAMPLES:\n")
+                for example in example_lines:
+                    if example.strip():
+                        self.stdout.write(f"  {example.strip()}\n")
+
+            self.stdout.write("\n")
 
         if arg == "all":
-            commands = self.cmd_reg.get_all_commands()
-            for name, (doc, args) in commands.items():
+            # Display all commands with their details
+            command_details = self.cmd_reg.get_all_commands()
+            for name, (doc, args) in sorted(command_details.items()):
                 get_info(name, doc, args)
 
         elif arg:
+            # Display help for a specific command
             command = self.cmd_reg.get(arg)
             if command:
                 doc = command.func.__doc__ or "No help available."
                 args = command.sig.parameters
                 get_info(arg, doc, args)
             else:
-                self.stdout.write(f"\tUnknown command: {arg}; Type 'help'\n")
+                self.stdout.write(f"\nUnknown command: '{arg}'\n")
+                self.stdout.write("Type 'help' to see available commands.\n")
         else:
-            self.stdout.write("\tWelcome to Jaseci's help utility!\n")
-            self.stdout.write(
-                "\tType 'help all' to see all available commands with details. or,\n"
-            )
-            self.stdout.write(
-                f"\tType 'help <choose on of ({', '.join(self.cmd_reg.registry.keys())})>'"
-                " to see details of a specific command.\n"
-            )
-            self.stdout.write("\tType 'exit' to exit the Jac CLI.\n\n")
+            # Display general help information
+            self.stdout.write("\n")
+            self.stdout.write("JAC PROGRAMMING LANGUAGE COMMAND LINE INTERFACE\n")
+            self.stdout.write("=" * 50 + "\n\n")
+
+            self.stdout.write("AVAILABLE COMMANDS:\n")
+
+            # Get all command names and sort them alphabetically
+            command_names = sorted(self.cmd_reg.registry.keys())
+
+            # Get brief descriptions for each command
+            command_descriptions: dict[str, str] = {}
+            for name in command_names:
+                command = self.cmd_reg.get(name)
+                if command and command.func.__doc__:
+                    # Extract the first line of the docstring as a brief description
+                    brief = command.func.__doc__.split("\n")[0].strip()
+                    command_descriptions[name] = brief
+                else:
+                    command_descriptions[name] = "No description available"
+
+            # Display commands with their brief descriptions
+            for name in command_names:
+                self.stdout.write(
+                    f"  {name.ljust(15)} - {command_descriptions[name]}\n"
+                )
+
+            self.stdout.write("\nFor detailed information on a specific command:\n")
+            self.stdout.write("  help <command>\n")
+
+            self.stdout.write("\nTo see detailed information for all commands:\n")
+            self.stdout.write("  help all\n")
+
+            self.stdout.write("\nTo exit the Jac CLI:\n")
+            self.stdout.write("  exit\n\n")

jaclang/compiler/__init__.py

@@ -6,40 +6,35 @@ import os
 import shutil
 import sys
 
-from jaclang.utils.helpers import auto_generate_refs
 from jaclang.vendor.lark.tools import standalone
 
 
 def generate_static_parser(force: bool = False) -> None:
     """Generate static parser."""
     cur_dir = os.path.dirname(__file__)
-    if force or not os.path.exists(os.path.join(cur_dir, "generated", "jac_parser.py")):
-        if os.path.exists(os.path.join(cur_dir, "generated")):
-            shutil.rmtree(os.path.join(cur_dir, "generated"))
-        os.makedirs(os.path.join(cur_dir, "generated"), exist_ok=True)
-        with open(os.path.join(cur_dir, "generated", "__init__.py"), "w"):
+    if force or not os.path.exists(os.path.join(cur_dir, "larkparse", "jac_parser.py")):
+        if os.path.exists(os.path.join(cur_dir, "larkparse")):
+            shutil.rmtree(os.path.join(cur_dir, "larkparse"))
+        os.makedirs(os.path.join(cur_dir, "larkparse"), exist_ok=True)
+        with open(os.path.join(cur_dir, "larkparse", "__init__.py"), "w"):
             pass
         save_argv = sys.argv
         sys.argv = [
             "lark",
             os.path.join(cur_dir, "jac.lark"),
             "-o",
-            os.path.join(cur_dir, "generated", "jac_parser.py"),
+            os.path.join(cur_dir, "larkparse", "jac_parser.py"),
             "-c",
         ]
         standalone.main()
         sys.argv = save_argv
-        try:
-            auto_generate_refs()
-        except Exception as e:
-            logging.error(f"Error generating reference files: {e}")
 
 
 try:
-    from jaclang.compiler.generated import jac_parser as jac_lark
+    from jaclang.compiler.larkparse import jac_parser as jac_lark
 except ModuleNotFoundError:
     generate_static_parser(force=True)
-    from jaclang.compiler.generated import jac_parser as jac_lark
+    from jaclang.compiler.larkparse import jac_parser as jac_lark
 
 jac_lark.logger.setLevel(logging.DEBUG)
 contextlib.suppress(ModuleNotFoundError)
@@ -58,9 +53,9 @@ TOKEN_MAP.update(
         "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": "<++>",
+        "ARROW_L_P2": ":<-", "ARROW_R_P1": "->:", "CARROW_BI": "<++>",
         "CARROW_L_P1": "<+:", "RSHIFT_EQ": ">>=", "ELLIPSIS": "...",
-        "CARROW_R_P2": ":+>", "CARROW_L_P2": ":+", "CARROW_R_P1": "+:",
+        "CARROW_R_P2": ":+>", "CARROW_L_P2": ":<+", "CARROW_R_P1": "+>:",
         "PIPE_FWD": "|>", "PIPE_BKWD": "<|", "A_PIPE_FWD": ":>",
         "A_PIPE_BKWD": "<:", "DOT_FWD": ".>", "STAR_POW": "**",
         "STAR_MUL": "*", "FLOOR_DIV": "//", "DIV": "/",

jaclang/compiler/{codeloc.py → codeinfo.py}

@@ -3,31 +3,26 @@
 from __future__ import annotations
 
 import ast as ast3
-from dataclasses import dataclass, field
 from typing import Optional, TYPE_CHECKING
 
-from jaclang.vendor.mypy.nodes import Node as MypyNode
 
 if TYPE_CHECKING:
-    from jaclang.compiler.absyntree import JacSource, Token
+    from jaclang.compiler.unitree import Source, Token
 
 
-@dataclass
 class CodeGenTarget:
     """Code generation target."""
 
-    py: str = ""
-    jac: str = ""
-    py_ast: list[ast3.AST] = field(default_factory=lambda: [])
-    mypy_ast: list[MypyNode] = field(default_factory=lambda: [])
-    py_bytecode: Optional[bytes] = None
+    def __init__(self) -> None:
+        """Initialize code generation target."""
+        import jaclang.compiler.passes.tool.doc_ir as doc
 
-    def clean(self) -> None:
-        """Clean code generation target."""
-        self.py = ""
-        self.jac = ""
-        self.py_ast = []
-        self.mypy_ast = []
+        self.py: str = ""
+        self.jac: str = ""
+        self.doc_ir: doc.DocType = doc.Text("")
+        self.js: str = ""
+        self.py_ast: list[ast3.AST] = []
+        self.py_bytecode: Optional[bytes] = None
 
 
 class CodeLocInfo:
@@ -43,73 +38,59 @@ class CodeLocInfo:
         self.last_tok = last_tok
 
     @property
-    def orig_src(self) -> JacSource:
+    def orig_src(self) -> Source:
         """Get file source."""
         return self.first_tok.orig_src
 
     @property
     def mod_path(self) -> str:
-        """Get line number."""
         return self.first_tok.orig_src.file_path
 
     @property
     def first_line(self) -> int:
-        """Get line number."""
         return self.first_tok.line_no
 
     @property
     def last_line(self) -> int:
-        """Get line number."""
         return self.last_tok.end_line
 
     @property
     def col_start(self) -> int:
-        """Get column position number."""
         return self.first_tok.c_start
 
     @property
     def col_end(self) -> int:
-        """Get column position number."""
         return self.last_tok.c_end
 
     @property
     def pos_start(self) -> int:
-        """Get column position number."""
         return self.first_tok.pos_start
 
     @property
     def pos_end(self) -> int:
-        """Get column position number."""
         return self.last_tok.pos_end
 
     @property
     def tok_range(self) -> tuple[Token, Token]:
-        """Get token range."""
         return (self.first_tok, self.last_tok)
 
     @property
     def first_token(self) -> Token:
-        """Get first token."""
         return self.first_tok
 
     @property
     def last_token(self) -> Token:
-        """Get last token."""
         return self.last_tok
 
     def update_token_range(self, first_tok: Token, last_tok: Token) -> None:
-        """Update token range."""
         self.first_tok = first_tok
         self.last_tok = last_tok
 
     def update_first_token(self, first_tok: Token) -> None:
-        """Update first token."""
         self.first_tok = first_tok
 
     def update_last_token(self, last_tok: Token) -> None:
-        """Update last token."""
         self.last_tok = last_tok
 
     def __str__(self) -> str:
-        """Stringify."""
         return f"{self.first_line}:{self.col_start} - {self.last_line}:{self.col_end}"

jaclang/compiler/constant.py

@@ -31,7 +31,6 @@ class SymbolType(Enum):
     UNKNOWN = "unknown"  # LSP: Unknown
 
     def __str__(self) -> str:
-        """Stringify."""
         return self.value
 
 
@@ -63,7 +62,6 @@ class JacSemTokenType(IntEnum):
 
     @staticmethod
     def as_str_list() -> list[str]:
-        """Return the string representation of the token."""
         return [i.name.lower() for i in JacSemTokenType]
 
 
@@ -90,30 +88,12 @@ class JacSemTokenModifier(IntFlag):
 class Constants(StrEnum):
     """Token constants for Jac."""
 
-    JAC_LANG_IMP = "jac"
-    HERE = "here"  # "_jac_here_"
+    HERE = "here"
+    ROOT = "root"
+    VISITOR = "visitor"
     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"
-    CONNECT_NODE = "__jac__.connect_node"
-    DISCONNECT_NODE = "__jac__.disconnect_node"
-    WALKER_VISIT = "__jac__.visit_node"
-    WALKER_IGNORE = "__jac__.ignore_node"
-    DISENGAGE = "__jac__.disengage_now"
-    OBJECT_CLASS = "_jac_Object_"
-    NODE_CLASS = "_jac_Node_"
-    EDGE_CLASS = "_jac_Edge_"
-    WALKER_CLASS = "_jac_Walker_"
-    WITH_DIR = "__jac__.apply_dir"
-    EDGE_DIR = "_jac_Edge_Dir"
-    ON_ENTRY = "_jac_ds_.on_entry"
-    ON_EXIT = "_jac_ds_.on_exit"
-
-    PYNLINE = "::py::"
-    JAC_GEN_DIR = "__jac_gen__"
     JAC_MYPY_CACHE = ".jac_mypy_cache"
+    SUPER_ROOT_UUID = "00000000-0000-0000-0000-000000000000"
 
     def __str__(self) -> str:
         """Return the string representation of the token."""
@@ -181,9 +161,9 @@ class Tokens(str, Enum):
     KW_NODE = "KW_NODE"
     KW_IGNORE = "KW_IGNORE"
     KW_VISIT = "KW_VISIT"
-    KW_REVISIT = "KW_REVISIT"
     KW_SPAWN = "KW_SPAWN"
     KW_WITH = "KW_WITH"
+    KW_LAMBDA = "KW_LAMBDA"
     KW_ENTRY = "KW_ENTRY"
     KW_EXIT = "KW_EXIT"
     KW_IMPORT = "KW_IMPORT"
@@ -194,6 +174,8 @@ class Tokens(str, Enum):
     KW_WALKER = "KW_WALKER"
     KW_ASYNC = "KW_ASYNC"
     KW_AWAIT = "KW_AWAIT"
+    KW_FLOW = "KW_FLOW"
+    KW_WAIT = "KW_WAIT"
     KW_TEST = "KW_TEST"
     KW_ASSERT = "KW_ASSERT"
     KW_CHECK = "KW_CHECK"
@@ -262,6 +244,7 @@ class Tokens(str, Enum):
     KW_GLOBAL = "KW_GLOBAL"
     COMMA = "COMMA"
     KW_CAN = "KW_CAN"
+    KW_DEF = "KW_DEF"
     KW_STATIC = "KW_STATIC"
     KW_OVERRIDE = "KW_OVERRIDE"
     KW_MATCH = "KW_MATCH"
@@ -300,19 +283,14 @@ class Tokens(str, Enum):
     GLOBAL_OP = "GLOBAL_OP"
     NONLOCAL_OP = "NONLOCAL_OP"
     KW_HERE = "KW_HERE"
+    KW_VISITOR = "KW_VISITOR"
     KW_SELF = "KW_SELF"
     KW_INIT = "KW_INIT"
     KW_SUPER = "KW_SUPER"
     KW_ROOT = "KW_ROOT"
     KW_POST_INIT = "KW_POST_INIT"
-    WALKER_OP = "WALKER_OP"
-    NODE_OP = "NODE_OP"
-    EDGE_OP = "EDGE_OP"
-    CLASS_OP = "CLASS_OP"
-    OBJECT_OP = "OBJECT_OP"
+    KW_IMPL = "KW_IMPL"
     TYPE_OP = "TYPE_OP"
-    ENUM_OP = "ENUM_OP"
-    ABILITY_OP = "ABILITY_OP"
     A_PIPE_FWD = "A_PIPE_FWD"
     A_PIPE_BKWD = "A_PIPE_BKWD"
     RETURN_HINT = "RETURN_HINT"
@@ -329,7 +307,6 @@ class Tokens(str, Enum):
     WS = "WS"
 
     def __str__(self) -> str:
-        """Return the string representation of the token."""
         return self.value