snail-lang 0.7.2__cp38-abi3-win_amd64.whl

snail/__init__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from ._native import __build_info__, compile, compile_ast, exec, parse, parse_ast
+
+
+def _resolve_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("snail-lang")
+    except Exception:  # pragma: no cover - during development
+        return "0.0.0"
+
+
+def __getattr__(name: str):
+    if name == "__version__":
+        value = _resolve_version()
+        globals()["__version__"] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + ["__version__"])
+
+
+__all__ = [
+    "compile",
+    "compile_ast",
+    "exec",
+    "parse",
+    "parse_ast",
+    "__version__",
+    "__build_info__",
+]

snail/cli.py

@@ -0,0 +1,423 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+from . import __build_info__, compile_ast, exec
+
+_USAGE = (
+    "snail [options] -f <file> [args]...\n"
+    "       snail [options] <code> [args]..."
+)
+_DESCRIPTION = "Snail programming language interpreter"
+_BOOLEAN_FLAGS = frozenset("amPIvh")
+_VALUE_FLAGS = frozenset("fbe")
+
+
+def _display_filename(filename: str) -> str:
+    if filename.startswith("snail:"):
+        return filename
+    return f"snail:{filename}"
+
+
+def _trim_internal_prefix(stack, internal_files: set[str]) -> None:
+    if not stack:
+        return
+    trim_count = 0
+    for frame in stack:
+        filename = frame.filename
+        if filename.startswith("snail:"):
+            break
+        if filename in internal_files:
+            trim_count += 1
+            continue
+        if os.path.isabs(filename) and os.path.abspath(filename) in internal_files:
+            trim_count += 1
+            continue
+        break
+    if 0 < trim_count < len(stack):
+        del stack[:trim_count]
+
+
+def _trim_traceback_exception(tb_exc, internal_files: set[str]) -> None:
+    _trim_internal_prefix(tb_exc.stack, internal_files)
+    cause = getattr(tb_exc, "__cause__", None)
+    if cause is not None:
+        _trim_traceback_exception(cause, internal_files)
+    context = getattr(tb_exc, "__context__", None)
+    if context is not None:
+        _trim_traceback_exception(context, internal_files)
+    for group_exc in getattr(tb_exc, "exceptions", ()) or ():
+        _trim_traceback_exception(group_exc, internal_files)
+
+
+def _install_trimmed_excepthook() -> None:
+    entrypoint = os.path.abspath(sys.argv[0])
+    cli_path = os.path.abspath(__file__)
+    internal_files = {entrypoint, cli_path}
+    original_excepthook = sys.excepthook
+
+    def _snail_excepthook(
+        exc_type: type[BaseException],
+        exc: BaseException,
+        tb: object,
+    ) -> None:
+        if exc_type is KeyboardInterrupt:
+            return original_excepthook(exc_type, exc, tb)
+        import traceback
+
+        tb_exc = traceback.TracebackException(
+            exc_type,
+            exc,
+            tb,
+            capture_locals=False,
+        )
+        _trim_traceback_exception(tb_exc, internal_files)
+        try:
+            import _colorize
+
+            colorize = _colorize.can_colorize(file=sys.stderr)
+        except Exception:
+            colorize = hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+        try:
+            formatted = tb_exc.format(colorize=colorize)
+        except TypeError:
+            formatted = tb_exc.format()
+        for line in formatted:
+            sys.stderr.write(line)
+
+    sys.excepthook = _snail_excepthook
+
+
+class _Args:
+    def __init__(self) -> None:
+        self.file: Optional[str] = None
+        self.awk = False
+        self.map = False
+        self.no_print = False
+        self.no_auto_import = False
+        self.debug = False
+        self.debug_snail_ast = False
+        self.debug_python_ast = False
+        self.version = False
+        self.help = False
+        self.begin_code: list[str] = []
+        self.end_code: list[str] = []
+        self.args: list[str] = []
+
+
+def _print_help(file=None) -> None:
+    if file is None:
+        file = sys.stdout
+    print(f"usage: {_USAGE}", file=file)
+    print("", file=file)
+    print(_DESCRIPTION, file=file)
+    print("", file=file)
+    print("options:", file=file)
+    print("  -f <file>               read Snail source from file", file=file)
+    print("  -a, --awk               awk mode", file=file)
+    print("  -m, --map               map mode (process files one at a time)", file=file)
+    print(
+        "  -b, --begin <code>       begin block code (awk/map mode, repeatable)",
+        file=file,
+    )
+    print(
+        "  -e, --end <code>         end block code (awk/map mode, repeatable)",
+        file=file,
+    )
+    print(
+        "  -P, --no-print          disable auto-print of implicit return value",
+        file=file,
+    )
+    print("  -I, --no-auto-import    disable auto-imports", file=file)
+    print("  --debug                 parse and compile, then print, do not run", file=file)
+    print("  --debug-snail-ast       parse and print Snail AST, do not run", file=file)
+    print("  --debug-python-ast      parse and print Python AST, do not run", file=file)
+    print("  -v, --version           show version and exit", file=file)
+    print("  -h, --help              show this help message and exit", file=file)
+
+
+def _expand_short_options(argv: list[str]) -> list[str]:
+    expanded: list[str] = []
+    idx = 0
+    while idx < len(argv):
+        token = argv[idx]
+        if token == "--":
+            expanded.append(token)
+            expanded.extend(argv[idx + 1 :])
+            return expanded
+        if token == "-" or not token.startswith("-") or token.startswith("--"):
+            expanded.append(token)
+            idx += 1
+            continue
+        if len(token) == 2:
+            expanded.append(token)
+            idx += 1
+            continue
+
+        flags = token[1:]
+        pos = 0
+        while pos < len(flags):
+            flag = flags[pos]
+            if flag in _BOOLEAN_FLAGS:
+                expanded.append(f"-{flag}")
+                pos += 1
+                continue
+            if flag in _VALUE_FLAGS:
+                remainder = flags[pos + 1 :]
+                if not remainder:
+                    expanded.append(f"-{flag}")
+                    pos += 1
+                    continue
+                if all(
+                    ch in _BOOLEAN_FLAGS or ch in _VALUE_FLAGS for ch in remainder
+                ):
+                    raise ValueError(
+                        f"option -{flag} requires an argument and must be last in a "
+                        "combined flag group"
+                    )
+                expanded.append(f"-{flag}")
+                expanded.append(remainder)
+                pos = len(flags)
+                break
+            raise ValueError(f"unknown option: -{flag}")
+        idx += 1
+    return expanded
+
+
+def _parse_args(argv: list[str]) -> _Args:
+    argv = _expand_short_options(argv)
+    args = _Args()
+    idx = 0
+    code_found = False
+    while idx < len(argv):
+        token = argv[idx]
+        if token == "--":
+            args.args = argv[idx + 1 :]
+            return args
+        if token == "-" or not token.startswith("-"):
+            if not code_found:
+                # This is the code (or the first arg when -f is used)
+                args.args = [token]
+                code_found = True
+            else:
+                args.args.append(token)
+            idx += 1
+            continue
+        if token in ("-h", "--help"):
+            args.help = True
+            return args
+        if token in ("-v", "--version"):
+            args.version = True
+            idx += 1
+            continue
+        if token in ("-a", "--awk"):
+            args.awk = True
+            idx += 1
+            continue
+        if token in ("-m", "--map"):
+            args.map = True
+            idx += 1
+            continue
+        if token in ("-P", "--no-print"):
+            args.no_print = True
+            idx += 1
+            continue
+        if token in ("-I", "--no-auto-import"):
+            args.no_auto_import = True
+            idx += 1
+            continue
+        if token == "--debug":
+            args.debug = True
+            idx += 1
+            continue
+        if token == "--debug-snail-ast":
+            args.debug_snail_ast = True
+            idx += 1
+            continue
+        if token == "--debug-python-ast":
+            args.debug_python_ast = True
+            idx += 1
+            continue
+        if token == "-f":
+            if idx + 1 >= len(argv):
+                raise ValueError("option -f requires an argument")
+            args.file = argv[idx + 1]
+            code_found = True
+            idx += 2
+            continue
+        if token in ("-b", "--begin"):
+            if idx + 1 >= len(argv):
+                raise ValueError(f"option {token} requires an argument")
+            args.begin_code.append(argv[idx + 1])
+            idx += 2
+            continue
+        if token in ("-e", "--end"):
+            if idx + 1 >= len(argv):
+                raise ValueError(f"option {token} requires an argument")
+            args.end_code.append(argv[idx + 1])
+            idx += 2
+            continue
+        raise ValueError(f"unknown option: {token}")
+    return args
+
+
+def _format_version(version: str, build_info: Optional[dict[str, object]]) -> str:
+    display_version = version if version.startswith("v") else f"v{version}"
+    if not build_info:
+        return display_version
+    git_rev = build_info.get("git_rev")
+    if not git_rev:
+        return display_version
+
+    suffixes: list[str] = []
+    if build_info.get("dirty"):
+        suffixes.append("!dirty")
+    if build_info.get("untagged"):
+        suffixes.append("!untagged")
+
+    if suffixes:
+        return f"{display_version} ({git_rev}) {' '.join(suffixes)}"
+    return f"{display_version} ({git_rev})"
+
+
+def _get_version() -> str:
+    from . import __version__ as version
+
+    return version
+
+
+def _format_python_runtime() -> str:
+    version = (
+        f"{sys.version_info.major}."
+        f"{sys.version_info.minor}."
+        f"{sys.version_info.micro}"
+    )
+    executable = sys.executable or "<unknown>"
+    if executable != "<unknown>":
+        executable = os.path.abspath(executable)
+    return f"Python {version} ({executable})"
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    if argv is None:
+        _install_trimmed_excepthook()
+        argv = sys.argv[1:]
+
+    try:
+        namespace = _parse_args(argv)
+    except ValueError as exc:
+        _print_help(file=sys.stderr)
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if namespace.help:
+        _print_help()
+        return 0
+    if namespace.version:
+        print(_format_version(_get_version(), __build_info__))
+        print(_format_python_runtime())
+        return 0
+
+    # Validate --awk and --map are mutually exclusive
+    if namespace.awk and namespace.map:
+        print("error: --awk and --map cannot be used together", file=sys.stderr)
+        return 2
+
+    # Validate -b/--begin and -e/--end only with --awk or --map mode
+    if (namespace.begin_code or namespace.end_code) and not (namespace.awk or namespace.map):
+        print(
+            "error: -b/--begin and -e/--end options require --awk or --map mode",
+            file=sys.stderr,
+        )
+        return 2
+
+    mode = "map" if namespace.map else ("awk" if namespace.awk else "snail")
+
+    if namespace.file:
+        from pathlib import Path
+
+        path = Path(namespace.file)
+        try:
+            source = path.read_text()
+        except OSError as exc:
+            print(f"failed to read {path}: {exc}", file=sys.stderr)
+            return 1
+        filename = str(path)
+        args = [filename, *namespace.args]
+    else:
+        if not namespace.args:
+            print("no input provided", file=sys.stderr)
+            return 1
+        source = namespace.args[0]
+        filename = "<cmd>"
+        args = ["--", *namespace.args[1:]]
+
+    if namespace.debug_snail_ast:
+        from . import parse_ast
+
+        snail_ast = parse_ast(
+            source,
+            mode=mode,
+            filename=filename,
+            begin_code=namespace.begin_code,
+            end_code=namespace.end_code,
+        )
+        print(snail_ast)
+        return 0
+
+    if namespace.debug_python_ast:
+        import ast
+
+        python_ast = compile_ast(
+            source,
+            mode=mode,
+            auto_print=not namespace.no_print,
+            filename=filename,
+            begin_code=namespace.begin_code,
+            end_code=namespace.end_code,
+        )
+        try:
+            output = ast.dump(python_ast, indent=2)
+        except TypeError:
+            output = ast.dump(python_ast)
+        print(output)
+        return 0
+
+    if namespace.debug:
+        import ast
+        import builtins
+
+        python_ast = compile_ast(
+            source,
+            mode=mode,
+            auto_print=not namespace.no_print,
+            filename=filename,
+            begin_code=namespace.begin_code,
+            end_code=namespace.end_code,
+        )
+        builtins.compile(python_ast, _display_filename(filename), "exec")
+        try:
+            output = ast.unparse(python_ast)
+        except AttributeError:
+            import astunparse
+
+            output = astunparse.unparse(python_ast).rstrip("\n")
+        print(output)
+        return 0
+
+    return exec(
+        source,
+        argv=args,
+        mode=mode,
+        auto_print=not namespace.no_print,
+        auto_import=not namespace.no_auto_import,
+        filename=filename,
+        begin_code=namespace.begin_code,
+        end_code=namespace.end_code,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

snail/runtime/__init__.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import importlib
+from typing import Optional
+
+__all__ = ["install_helpers", "AutoImportDict", "AUTO_IMPORT_NAMES"]
+
+# Names that can be auto-imported when first referenced.
+# Maps name -> (module, attribute) where attribute is None for whole-module imports.
+AUTO_IMPORT_NAMES: dict[str, tuple[str, Optional[str]]] = {
+    # Whole module imports: import X
+    "sys": ("sys", None),
+    "os": ("os", None),
+    # Attribute imports: from X import Y
+    "Path": ("pathlib", "Path"),
+}
+
+
+class AutoImportDict(dict):
+    """A dict subclass that lazily imports allowed names on first access.
+
+    When a key lookup fails, if the key is in AUTO_IMPORT_NAMES,
+    the corresponding module/attribute is imported and stored in the dict.
+    Supports both whole-module imports (import sys) and attribute imports
+    (from pathlib import Path).
+    """
+
+    def __missing__(self, key: str) -> object:
+        if key in AUTO_IMPORT_NAMES:
+            module_name, attr_name = AUTO_IMPORT_NAMES[key]
+            module = importlib.import_module(module_name)
+            value = getattr(module, attr_name) if attr_name else module
+            self[key] = value
+            return value
+        raise KeyError(key)
+
+
+_compact_try = None
+_regex_search = None
+_regex_compile = None
+_subprocess_capture = None
+_subprocess_status = None
+_jmespath_query = None
+_js = None
+_lazy_text_class = None
+_lazy_file_class = None
+_incr_attr = None
+_incr_index = None
+_aug_attr = None
+_aug_index = None
+_env_map = None
+
+
+def _get_compact_try():
+    global _compact_try
+    if _compact_try is None:
+        from .compact_try import compact_try
+
+        _compact_try = compact_try
+    return _compact_try
+
+
+def _get_regex_search():
+    global _regex_search
+    if _regex_search is None:
+        from .regex import regex_search
+
+        _regex_search = regex_search
+    return _regex_search
+
+
+def _get_regex_compile():
+    global _regex_compile
+    if _regex_compile is None:
+        from .regex import regex_compile
+
+        _regex_compile = regex_compile
+    return _regex_compile
+
+
+def _get_subprocess_capture():
+    global _subprocess_capture
+    if _subprocess_capture is None:
+        from .subprocess import SubprocessCapture
+
+        _subprocess_capture = SubprocessCapture
+    return _subprocess_capture
+
+
+def _get_subprocess_status():
+    global _subprocess_status
+    if _subprocess_status is None:
+        from .subprocess import SubprocessStatus
+
+        _subprocess_status = SubprocessStatus
+    return _subprocess_status
+
+
+def _get_jmespath_query():
+    global _jmespath_query
+    if _jmespath_query is None:
+        from .structured_accessor import __snail_jmespath_query
+
+        _jmespath_query = __snail_jmespath_query
+    return _jmespath_query
+
+
+def _get_js():
+    global _js
+    if _js is None:
+        from .structured_accessor import js
+
+        _js = js
+    return _js
+
+
+def _get_lazy_text_class():
+    global _lazy_text_class
+    if _lazy_text_class is None:
+        from .lazy_text import LazyText
+
+        _lazy_text_class = LazyText
+    return _lazy_text_class
+
+
+def _get_lazy_file_class():
+    global _lazy_file_class
+    if _lazy_file_class is None:
+        from .lazy_file import LazyFile
+
+        _lazy_file_class = LazyFile
+    return _lazy_file_class
+
+
+def _get_env_map():
+    global _env_map
+    if _env_map is None:
+        from .env import EnvMap
+
+        _env_map = EnvMap()
+    return _env_map
+
+
+def _get_incr_attr():
+    global _incr_attr
+    if _incr_attr is None:
+        from .augmented import __snail_incr_attr
+
+        _incr_attr = __snail_incr_attr
+    return _incr_attr
+
+
+def _get_incr_index():
+    global _incr_index
+    if _incr_index is None:
+        from .augmented import __snail_incr_index
+
+        _incr_index = __snail_incr_index
+    return _incr_index
+
+
+def _get_aug_attr():
+    global _aug_attr
+    if _aug_attr is None:
+        from .augmented import __snail_aug_attr
+
+        _aug_attr = __snail_aug_attr
+    return _aug_attr
+
+
+def _get_aug_index():
+    global _aug_index
+    if _aug_index is None:
+        from .augmented import __snail_aug_index
+
+        _aug_index = __snail_aug_index
+    return _aug_index
+
+
+def _lazy_compact_try(expr_fn, fallback_fn=None):
+    return _get_compact_try()(expr_fn, fallback_fn)
+
+
+def _lazy_regex_search(value, pattern):
+    return _get_regex_search()(value, pattern)
+
+
+def _lazy_regex_compile(pattern):
+    return _get_regex_compile()(pattern)
+
+
+def _lazy_subprocess_capture(cmd: str):
+    return _get_subprocess_capture()(cmd)
+
+
+def _lazy_subprocess_status(cmd: str):
+    return _get_subprocess_status()(cmd)
+
+
+def _lazy_jmespath_query(query: str):
+    return _get_jmespath_query()(query)
+
+
+def _lazy_js(input_data=None):
+    return _get_js()(input_data)
+
+
+def _lazy_incr_attr(obj, attr: str, delta: int, pre: bool):
+    return _get_incr_attr()(obj, attr, delta, pre)
+
+
+def _lazy_incr_index(obj, index, delta: int, pre: bool):
+    return _get_incr_index()(obj, index, delta, pre)
+
+
+def _lazy_aug_attr(obj, attr: str, value, op: str):
+    return _get_aug_attr()(obj, attr, value, op)
+
+
+def _lazy_aug_index(obj, index, value, op: str):
+    return _get_aug_index()(obj, index, value, op)
+
+
+def __snail_partial(func, /, *args, **kwargs):
+    import functools
+
+    return functools.partial(func, *args, **kwargs)
+
+
+def __snail_contains__(left, right):
+    method = getattr(right, "__snail_contains__", None)
+    if method is not None:
+        return method(left)
+    return left in right
+
+
+def __snail_contains_not__(left, right):
+    method = getattr(right, "__snail_contains__", None)
+    if method is not None:
+        return not bool(method(left))
+    return left not in right
+
+
+def install_helpers(globals_dict: dict) -> None:
+    globals_dict["__snail_compact_try"] = _lazy_compact_try
+    globals_dict["__snail_regex_search"] = _lazy_regex_search
+    globals_dict["__snail_regex_compile"] = _lazy_regex_compile
+    globals_dict["__SnailSubprocessCapture"] = _lazy_subprocess_capture
+    globals_dict["__SnailSubprocessStatus"] = _lazy_subprocess_status
+    globals_dict["__snail_jmespath_query"] = _lazy_jmespath_query
+    globals_dict["__snail_partial"] = __snail_partial
+    globals_dict["__snail_contains__"] = __snail_contains__
+    globals_dict["__snail_contains_not__"] = __snail_contains_not__
+    globals_dict["__snail_incr_attr"] = _lazy_incr_attr
+    globals_dict["__snail_incr_index"] = _lazy_incr_index
+    globals_dict["__snail_aug_attr"] = _lazy_aug_attr
+    globals_dict["__snail_aug_index"] = _lazy_aug_index
+    globals_dict["__snail_env"] = _get_env_map()
+    globals_dict["js"] = _lazy_js
+    globals_dict["__SnailLazyText"] = _get_lazy_text_class()
+    globals_dict["__SnailLazyFile"] = _get_lazy_file_class()