snail-lang 0.7.1__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,386 @@
+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.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("  -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 == "-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 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__))
+        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:
+        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,250 @@
+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
+
+
+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_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["js"] = _lazy_js
+    globals_dict["__SnailLazyText"] = _get_lazy_text_class()
+    globals_dict["__SnailLazyFile"] = _get_lazy_file_class()

snail/runtime/augmented.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import operator as _op
+
+_OPS = {
+    "+": _op.add,
+    "-": _op.sub,
+    "*": _op.mul,
+    "/": _op.truediv,
+    "//": _op.floordiv,
+    "%": _op.mod,
+    "**": _op.pow,
+}
+
+
+def _apply_op(left, right, op: str):
+    try:
+        func = _OPS[op]
+    except KeyError as exc:
+        raise ValueError(f"unknown augmented op: {op}") from exc
+    return func(left, right)
+
+
+def __snail_incr_attr(obj, attr: str, delta: int, pre: bool):
+    old = getattr(obj, attr)
+    new = old + delta
+    setattr(obj, attr, new)
+    return new if pre else old
+
+
+def __snail_incr_index(obj, index, delta: int, pre: bool):
+    old = obj[index]
+    new = old + delta
+    obj[index] = new
+    return new if pre else old
+
+
+def __snail_aug_attr(obj, attr: str, value, op: str):
+    old = getattr(obj, attr)
+    new = _apply_op(old, value, op)
+    setattr(obj, attr, new)
+    return new
+
+
+def __snail_aug_index(obj, index, value, op: str):
+    old = obj[index]
+    new = _apply_op(old, value, op)
+    obj[index] = new
+    return new

snail/runtime/compact_try.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+
+def compact_try(expr_fn, fallback_fn=None):
+    try:
+        return expr_fn()
+    except Exception as exc:
+        if fallback_fn is None:
+            fallback_member = getattr(exc, "__fallback__", None)
+            if callable(fallback_member):
+                return fallback_member()
+            return None
+        return fallback_fn(exc)

snail/runtime/lazy_file.py

@@ -0,0 +1,41 @@
+"""Lazy file opener for map mode."""
+
+from __future__ import annotations
+
+
+class LazyFile:
+    """Context manager that opens the file on first access."""
+
+    __slots__ = ("_path", "_mode", "_kwargs", "_fd", "_closed")
+
+    def __init__(self, path, mode="r", **kwargs):
+        self._path = path
+        self._mode = mode
+        self._kwargs = kwargs
+        self._fd = None
+        self._closed = False
+
+    def _ensure_open(self):
+        if self._closed:
+            raise ValueError("I/O operation on closed file.")
+        if self._fd is None:
+            self._fd = open(self._path, self._mode, **self._kwargs)
+        return self._fd
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self._closed = True
+        if self._fd is not None:
+            self._fd.close()
+        return False
+
+    def __getattr__(self, name):
+        return getattr(self._ensure_open(), name)
+
+    def __iter__(self):
+        return iter(self._ensure_open())
+
+    def __next__(self):
+        return next(self._ensure_open())

snail/runtime/lazy_text.py

@@ -0,0 +1,50 @@
+"""Lazy text content reader for map mode."""
+
+from __future__ import annotations
+
+
+class LazyText:
+    """Lazily reads file content on first access."""
+
+    __slots__ = ("_fd", "_text")
+
+    def __init__(self, fd):
+        self._fd = fd
+        self._text = None
+
+    def _ensure_loaded(self):
+        if self._text is None:
+            self._text = self._fd.read()
+        return self._text
+
+    def __str__(self):
+        return self._ensure_loaded()
+
+    def __repr__(self):
+        return repr(str(self))
+
+    def __eq__(self, other):
+        if isinstance(other, LazyText):
+            return str(self) == str(other)
+        return str(self) == other
+
+    def __hash__(self):
+        return hash(str(self))
+
+    def __len__(self):
+        return len(str(self))
+
+    def __iter__(self):
+        return iter(str(self))
+
+    def __contains__(self, item):
+        return item in str(self)
+
+    def __add__(self, other):
+        return str(self) + other
+
+    def __radd__(self, other):
+        return other + str(self)
+
+    def __getattr__(self, name):
+        return getattr(str(self), name)

snail/runtime/regex.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import re
+
+
+class SnailRegex:
+    def __init__(self, pattern: str) -> None:
+        self.pattern = pattern
+        self._regex = re.compile(pattern)
+
+    def search(self, value):
+        return regex_search(value, self._regex)
+
+    def __contains__(self, value):
+        return bool(self.__snail_contains__(value))
+
+    def __snail_contains__(self, value):
+        return self.search(value)
+
+    def __repr__(self) -> str:
+        return f"/{self.pattern}/"
+
+
+def regex_search(value, pattern):
+    if isinstance(pattern, SnailRegex):
+        return pattern.search(value)
+    if hasattr(pattern, "search"):
+        match = pattern.search(value)
+    else:
+        match = re.search(pattern, value)
+    if match is None:
+        return ()
+    return (match.group(0),) + match.groups()
+
+
+def regex_compile(pattern):
+    return SnailRegex(pattern)

snail/runtime/structured_accessor.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json as _json
+import os as _os
+import sys as _sys
+
+def __snail_jmespath_query(query: str):
+    """Create a callable that applies JMESPath query.
+
+    Used by the $[query] syntax which lowers to __snail_jmespath_query(query).
+    """
+
+    import jmespath as _jmespath
+
+    def apply(data):
+        return _jmespath.search(query, data)
+
+    return apply
+
+
+def _parse_jsonl(content: str):
+    lines = [line for line in content.splitlines() if line.strip()]
+    if not lines:
+        return []
+
+    items = []
+    for line in lines:
+        try:
+            items.append(_json.loads(line))
+        except _json.JSONDecodeError as exc:
+            raise _json.JSONDecodeError(
+                f"Invalid JSONL line: {exc.msg}",
+                line,
+                exc.pos,
+            ) from exc
+    return items
+
+
+def js(input_data=None):
+    """Parse JSON from various input sources.
+
+    Returns the parsed Python object (dict, list, etc.) directly.
+    If called with no arguments, reads from stdin.
+    """
+    if input_data is None:
+        input_data = _sys.stdin
+
+    if isinstance(input_data, str):
+        try:
+            return _json.loads(input_data)
+        except _json.JSONDecodeError:
+            if _os.path.exists(input_data):
+                with open(input_data, "r", encoding="utf-8") as handle:
+                    content = handle.read()
+                try:
+                    return _json.loads(content)
+                except _json.JSONDecodeError:
+                    return _parse_jsonl(content)
+            else:
+                return _parse_jsonl(input_data)
+    elif hasattr(input_data, "read"):
+        content = input_data.read()
+        if isinstance(content, bytes):
+            content = content.decode("utf-8")
+        try:
+            return _json.loads(content)
+        except _json.JSONDecodeError:
+            return _parse_jsonl(content)
+    elif isinstance(input_data, (dict, list, int, float, bool)) or input_data is None:
+        return input_data
+    else:
+        raise TypeError(
+            f"js() input must be JSON-compatible, got {type(input_data).__name__}"
+        )

snail/runtime/subprocess.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import subprocess
+
+
+class SubprocessCapture:
+    def __init__(self, cmd: str) -> None:
+        self.cmd = cmd
+
+    def __call__(self, input_data=None):
+        try:
+            if input_data is None:
+                completed = subprocess.run(
+                    self.cmd,
+                    shell=True,
+                    check=True,
+                    text=True,
+                    stdout=subprocess.PIPE,
+                )
+            else:
+                if not isinstance(input_data, (str, bytes)):
+                    input_data = str(input_data)
+                completed = subprocess.run(
+                    self.cmd,
+                    shell=True,
+                    check=True,
+                    text=True,
+                    input=input_data,
+                    stdout=subprocess.PIPE,
+                )
+            return completed.stdout.rstrip("\n")
+        except subprocess.CalledProcessError as exc:
+
+            def __fallback(exc=exc):
+                raise exc
+
+            exc.__fallback__ = __fallback
+            raise
+
+
+class SubprocessStatus:
+    def __init__(self, cmd: str) -> None:
+        self.cmd = cmd
+
+    def __call__(self, input_data=None):
+        try:
+            if input_data is None:
+                subprocess.run(self.cmd, shell=True, check=True)
+            else:
+                if not isinstance(input_data, (str, bytes)):
+                    input_data = str(input_data)
+                subprocess.run(
+                    self.cmd,
+                    shell=True,
+                    check=True,
+                    text=True,
+                    input=input_data,
+                )
+            return 0
+        except subprocess.CalledProcessError as exc:
+
+            def __fallback(exc=exc):
+                return exc.returncode
+
+            exc.__fallback__ = __fallback
+            raise

snail_lang-0.7.1.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: snail-lang
+Version: 0.7.1
+Requires-Dist: astunparse>=1.6.3 ; python_full_version < '3.9'
+Requires-Dist: jmespath>=1.0.1
+Requires-Dist: maturin>=1.5 ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Snail programming language interpreter
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+<p align="center">
+  <img src="logo.png" alt="Snail logo" width="200">
+</p>
+
+<h1 align="center">Snail</h1>
+
+**Snail** is a programming language that compiles to Python, combining Python's familiarity and extensive libraries with Perl/awk-inspired syntax for quick scripts and one-liners. Its what you get when you shove a snake in a shell.
+
+## AI Slop!
+
+Snail is me learning how to devlop code using LLMs. I think its neat, and
+maybe useful. I don't think this is high quality. I am going to try and LLM my
+way into something good, but its certainly not there yet.
+
+## Installing Snail
+
+```bash
+pip install snail-lang
+-or-
+uv tool install snail-lang
+```
+
+That installs the `snail` CLI for your user; try it with `snail "print('hello')"` once the install completes.
+
+## ✨ What Makes Snail Unique
+
+### Curly Braces, Not Indentation
+
+Write Python logic without worrying about whitespace:
+
+```snail
+def process(items) {
+    for item in items {
+        if item > 0 { print(item) }
+        else { continue }
+    }
+}
+```
+
+Note, since it is jarring to write python with semicolons everywhere,
+semicolons are optional. You can separate statements with newlines.
+
+### Awk Mode
+
+Process files line-by-line with familiar awk semantics:
+
+```snail-awk("hello world\nfoo bar\n")
+BEGIN { print("start") }
+/hello/ { print("matched:", $0) }
+{ print($1, "->", $2) }
+END { print("done") }
+```
+
+**Built-in variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `$0` | Current line (with newline stripped) |
+| `$1`, `$2`, ... | Individual fields (whitespace-split) |
+| `$f` | All fields as a list |
+| `$n` | Global line number (across all files) |
+| `$fn` | Per-file line number |
+| `$p` | Current file path |
+| `$m` | Last regex match object |
+
+Begin/end blocks can live in the source file (`BEGIN { ... }` / `END { ... }`) or be supplied
+via CLI flags (`-b`/`--begin`, `-e`/`--end`) for setup and teardown. CLI BEGIN blocks run
+before in-file BEGIN blocks; CLI END blocks run after in-file END blocks.
+`BEGIN` and `END` are reserved keywords in all modes.
+BEGIN/END blocks are regular Snail blocks, so awk/map-only `$` variables are not available inside them.
+```bash
+echo -e "5\n4\n3\n2\n1" | snail --awk --begin 'total = 0' --end 'print("Sum:", total)' '/^[0-9]+/ { total = total + int($1) }'
+```
+
+### Map Mode
+
+Process files one at a time instead of line-by-line:
+
+```snail-map
+BEGIN { print("start") }
+print("File:", $src)
+print("Size:", len($text), "bytes")
+END { print("done") }
+```
+
+**Built-in variables:**
+
+| Variable | Description |
+|----------|-------------|
+| `$src` | Current file path |
+| `$fd` | Open file handle for the current file |
+| `$text` | Lazy text view of the current file contents |
+
+Begin/end blocks can live in the source file (`BEGIN { ... }` / `END { ... }`) or be supplied
+via CLI flags (`-b`/`--begin`, `-e`/`--end`) for setup and teardown. CLI BEGIN blocks run
+before in-file BEGIN blocks; CLI END blocks run after in-file END blocks.
+BEGIN/END blocks are regular Snail blocks, so awk/map-only `$` variables are not available inside them.
+`BEGIN` and `END` are reserved keywords in all modes.
+```bash
+snail --map --begin "print('start')" --end "print('done')" "print($src)" *.txt
+```
+
+### Compact Error Handling
+
+The `?` operator makes error handling terse yet expressive:
+
+```snail
+# Swallow exception, return None
+err = risky()?
+
+# Swallow exception, return exception object
+err = risky():$e?
+
+# Provide a fallback value (exception available as $e)
+value = js("malformed json"):%{"error": "invalid json"}?
+details = fetch_url("foo.com"):"default html"?
+exception_info = fetch_url("example.com"):$e.http_response_code?
+
+# Access attributes directly
+name = risky("")?.__class__.__name__
+args = risky("becomes a list"):[1,2,3]?[0]
+```
+
+### Destructuring + `if let` / `while let`
+
+Unpack tuples and lists directly, including Python-style rest bindings:
+
+```snail
+x, *xs = [1, 2, 3]
+
+if let [head, *tail] = [1, 2, 3]; head > 0 {
+    print(head, tail)
+}
+```
+
+`if let`/`while let` only enter the block when the destructuring succeeds. A guard
+after `;` lets you add a boolean check that runs after the bindings are created.
+
+Note that this syntax is more powerful than the walrus operator as that does
+not allow for destructuring.
+
+
+### Pipeline Operator
+
+The `|` operator enables data pipelining as syntactic sugar for nested
+function calls. `x | y | z` becomes `z(y(x))`. This lets you stay in a
+shell mindset.
+
+```snail
+# Pipe data to subprocess stdin
+result = "hello\nworld" | $(grep hello)
+
+# Chain multiple transformations
+output = "foo\nbar" | $(grep foo) | $(wc -l)
+
+# Custom pipeline handlers
+class Doubler {
+    def __call__(self, x) { return x * 2 }
+}
+doubled = 21 | Doubler()  # yields 42
+```
+
+Arbitrary callables make up pipelines, even if they have multiple parameters.
+Snail supports this via placeholders.
+```snail
+greeting = "World" | greet("Hello ", _)  # greet("Hello ", "World")
+excited = "World" | greet(_, "!")        # greet("World", "!")
+formal = "World" | greet("Hello ", suffix=_)  # greet("Hello ", "World")
+```
+
+When a pipeline targets a call expression, the left-hand value is passed to the
+resulting callable. If the call includes a single `_` placeholder, Snail substitutes
+the piped value at that position (including keyword arguments). Only one
+placeholder is allowed in a piped call. Outside of pipeline calls, `_` remains a
+normal identifier.
+
+### Built-in Subprocess
+
+Shell commands are first-class citizens with capturing and non-capturing
+forms.
+
+```snail
+# Capture command output with interpolation
+greeting = $(echo hello {name})
+
+# Pipe data through commands
+result = "foo\nbar\nbaz" | $(grep bar) | $(cat -n)
+
+# Check command status
+@(make build)?  # returns exit code on failure instead of raising
+```
+
+
+### Regex Literals
+
+Snail supports first class patterns. Think of them as an infinte set.
+
+```snail
+if bad_email in /^[\w.]+@[\w.]+$/ {
+    print("Valid email")
+}
+
+# Compiled regex for reuse
+pattern = /\d{3}-\d{4}/
+match = pattern.search(phone)
+match2 = "555-1212" in pattern
+```
+
+Snail regexes don't return a match object, rather they return a tuple
+containing all of the match groups, including group 0. Both `search` and `in`
+return the same tuple (or `()` when there is no match).
+
+### JSON Queries with JMESPath
+
+Parse and query JSON data with the `js()` function and structured pipeline accessor:
+
+```snail
+# Parse JSON and query with $[jmespath]
+
+# JSON query with JMESPath
+data = js($(curl -s https://api.github.com/repos/sudonym1/snail))
+counts = data | $[stargazers_count]
+
+# Inline parsing and querying
+result = js('{{"foo": 12}}') | $[foo]
+
+# JSONL parsing returns a list
+names = js('{{"name": "Ada"}}\n{{"name": "Lin"}}') | $[[*].name]
+```
+
+### Full Python Interoperability
+
+Snail compiles to Python AST—import any Python module, use any library, in any
+environment. Assuming that you are using Python 3.8 or later.
+
+## 🚀 Quick Start
+
+```bash
+# One-liner: arithmetic + interpolation
+snail 'name="Snail"; print("{name} says: {6 * 7}")'
+
+# JSON query with JMESPath
+snail 'js($(curl -s https://api.github.com/repos/sudonym1/snail)) | $[stargazers_count]'
+
+# Compact error handling with fallback
+snail 'result = int("oops"):"bad int {$e}"?; print(result)'
+
+# Regex match and capture
+snail 'if let [_, user, domain] = "user@example.com" in /^[\w.]+@([\w.]+)$/ { print(domain) }'
+
+# Awk mode: print line numbers for matches
+rg -n "TODO" README.md | snail --awk '/TODO/ { print("{$n}: {$0}") }'
+```
+
+## 📚 Documentation
+
+Documentation is WIP
+
+- **[Language Reference](docs/REFERENCE.md)** — Complete syntax and semantics
+- **[examples/all_syntax.snail](examples/all_syntax.snail)** — Every feature in one file
+- **[examples/awk.snail](examples/awk.snail)** — Awk mode examples
+- **[examples/map.snail](examples/map.snail)** — Map mode examples
+
+## 🔌 Editor Support
+
+Vim/Neovim plugin with syntax highlighting, formatting, and run commands:
+
+```vim
+Plug 'sudonym1/snail', { 'rtp': 'extras/vim' }
+```
+
+See [extras/vim/README.md](extras/vim/README.md) for details. Tree-sitter grammar available in `extras/tree-sitter-snail/`.
+
+## Performance
+
+Section is WIP
+
+Startup performance is benchmarked with `./benchmarks/startup.py`. On my
+machine snail adds 5 ms of overhead above the regular python3 interpreter.
+
+## 🛠️ Building from Source
+
+### Prerequisites
+
+**Python 3.8+** (required at runtime)
+
+Snail runs in-process via a Pyo3 extension module, so it uses the active Python environment.
+
+Installation per platform:
+- **Ubuntu/Debian**: `sudo apt install python3 python3-dev`
+- **Fedora/RHEL**: `sudo dnf install python3 python3-devel`
+- **macOS**: `brew install python@3.12` (or use the system Python 3)
+- **Windows**: Download from [python.org](https://www.python.org/downloads/)
+
+### Build, Test, and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/sudonym1/snail.git
+cd snail
+
+make test
+make install
+```
+

snail_lang-0.7.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+snail\__init__.py,sha256=ycv9SAHU4p6ndYoMuBL022C3Nv4O9gPPH16cGN_mMqM,821
+snail\_native.pyd,sha256=MaXUH30xxyYSiSt0w6qqZjuCRS72zABnqES-Dvtkt3s,2135552
+snail\cli.py,sha256=k9u3iVwZCH1KLYYBqF9geq3QNsG7CBkzelBaDr2xqBQ,12184
+snail\runtime\__init__.py,sha256=PvekYIXdfs8xT3fi_ZEunarstfgc4AF6b9SqbJfwsDE,6766
+snail\runtime\augmented.py,sha256=ZBlgJL1v-uRxPOiB2QToshx6vreousSTgT3rbUiPyQ0,1091
+snail\runtime\compact_try.py,sha256=0nxfcAOsISMo3RsVb3_9kYemXtFLfW3kHrQSjAdkJxE,393
+snail\runtime\lazy_file.py,sha256=mYMQdTv9c3_g_0OzjqczBZcmiX7DgTd1yY7YS9cmPsY,1100
+snail\runtime\lazy_text.py,sha256=xNXY0r5VjK-BLRQQOXj3EmGzzjBBnPPJZZfMUkhlqx4,1143
+snail\runtime\regex.py,sha256=Vc1LJe6OfCh0G8z_n83rGz8tqrjyESg4nbbwFrR2ARw,916
+snail\runtime\structured_accessor.py,sha256=qSXauwYFZ9Ig_ACsxKarU3O49OGxbyhvm8LhEPRyT70,2237
+snail\runtime\subprocess.py,sha256=ILDdfpqRXMFjWKYdpxQvEpie_31kItCuDO2WlsNpnks,1955
+snail_lang-0.7.1.dist-info\METADATA,sha256=tdjZgk_uEjI6gbQvdsA3Ls570bRyOFzsvmuboCkfn60,9645
+snail_lang-0.7.1.dist-info\WHEEL,sha256=gPqN4EsdiAyGvmfrYy_ONrF276O8o0hPitI2CKZrEFA,95
+snail_lang-0.7.1.dist-info\entry_points.txt,sha256=8u6pjHZtKGdaZQlr6yKbftplObC07caDZ44j5PIPU6M,39
+snail_lang-0.7.1.dist-info\licenses\LICENSE,sha256=iT_e39WExFFehp3Zh4faVe3dEv3BrhhX_v3obKdBM9M,1082
+snail_lang-0.7.1.dist-info\RECORD,,

snail_lang-0.7.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp38-abi3-win_amd64

snail_lang-0.7.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+snail=snail.cli:main

snail_lang-0.7.1.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Seamus Connor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+