snail-lang 0.7.2__cp38-abi3-win_amd64.whl

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/env.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import os
+
+
+class EnvMap:
+    __slots__ = ("_env",)
+
+    def __init__(self, env=None) -> None:
+        self._env = os.environ if env is None else env
+
+    def __fallback__(self) -> str:
+        return ""
+
+    def _lookup(self, key):
+        try:
+            return self._env[key]
+        except KeyError as exc:
+            exc.__fallback__ = self.__fallback__
+            raise
+
+    def __getitem__(self, key):
+        return self._lookup(key)
+
+    def __getattr__(self, name):
+        return self._lookup(name)

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.2.dist-info/METADATA

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: snail-lang
+Version: 0.7.2
+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
+```
+
+### Built-in Variables (All Modes)
+
+| Variable | Description |
+|----------|-------------|
+| `$e` | Exception object in `expr:fallback?` |
+| `$env` | Environment map (wrapper around `os.environ`) |
+
+### 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}") }'
+
+# Environment variables
+snail 'print($env.PATH)'
+```
+
+## 📚 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
+```
+