snail-lang 0.2.0__cp310-abi3-macosx_11_0_arm64.whl

snail/vendor/jmespath/visitor.py

@@ -0,0 +1,329 @@
+import operator
+
+from . import functions
+from .compat import string_type
+from numbers import Number
+
+
+def _equals(x, y):
+    if _is_special_number_case(x, y):
+        return False
+    else:
+        return x == y
+
+
+def _is_special_number_case(x, y):
+    # We need to special case comparing 0 or 1 to
+    # True/False.  While normally comparing any
+    # integer other than 0/1 to True/False will always
+    # return False.  However 0/1 have this:
+    # >>> 0 == True
+    # False
+    # >>> 0 == False
+    # True
+    # >>> 1 == True
+    # True
+    # >>> 1 == False
+    # False
+    #
+    # Also need to consider that:
+    # >>> 0 in [True, False]
+    # True
+    if _is_actual_number(x) and x in (0, 1):
+        return isinstance(y, bool)
+    elif _is_actual_number(y) and y in (0, 1):
+        return isinstance(x, bool)
+
+
+def _is_comparable(x):
+    # The spec doesn't officially support string types yet,
+    # but enough people are relying on this behavior that
+    # it's been added back.  This should eventually become
+    # part of the official spec.
+    return _is_actual_number(x) or isinstance(x, string_type)
+
+
+def _is_actual_number(x):
+    # We need to handle python's quirkiness with booleans,
+    # specifically:
+    #
+    # >>> isinstance(False, int)
+    # True
+    # >>> isinstance(True, int)
+    # True
+    if isinstance(x, bool):
+        return False
+    return isinstance(x, Number)
+
+
+class Options(object):
+    """Options to control how a JMESPath function is evaluated."""
+
+    def __init__(self, dict_cls=None, custom_functions=None):
+        #: The class to use when creating a dict.  The interpreter
+        #  may create dictionaries during the evaluation of a JMESPath
+        #  expression.  For example, a multi-select hash will
+        #  create a dictionary.  By default we use a dict() type.
+        #  You can set this value to change what dict type is used.
+        #  The most common reason you would change this is if you
+        #  want to set a collections.OrderedDict so that you can
+        #  have predictable key ordering.
+        self.dict_cls = dict_cls
+        self.custom_functions = custom_functions
+
+
+class _Expression(object):
+    def __init__(self, expression, interpreter):
+        self.expression = expression
+        self.interpreter = interpreter
+
+    def visit(self, node, *args, **kwargs):
+        return self.interpreter.visit(node, *args, **kwargs)
+
+
+class Visitor(object):
+    def __init__(self):
+        self._method_cache = {}
+
+    def visit(self, node, *args, **kwargs):
+        node_type = node["type"]
+        method = self._method_cache.get(node_type)
+        if method is None:
+            method = getattr(self, "visit_%s" % node["type"], self.default_visit)
+            self._method_cache[node_type] = method
+        return method(node, *args, **kwargs)
+
+    def default_visit(self, node, *args, **kwargs):
+        raise NotImplementedError("default_visit")
+
+
+class TreeInterpreter(Visitor):
+    COMPARATOR_FUNC = {
+        "eq": _equals,
+        "ne": lambda x, y: not _equals(x, y),
+        "lt": operator.lt,
+        "gt": operator.gt,
+        "lte": operator.le,
+        "gte": operator.ge,
+    }
+    _EQUALITY_OPS = ["eq", "ne"]
+    MAP_TYPE = dict
+
+    def __init__(self, options=None):
+        super(TreeInterpreter, self).__init__()
+        self._dict_cls = self.MAP_TYPE
+        if options is None:
+            options = Options()
+        self._options = options
+        if options.dict_cls is not None:
+            self._dict_cls = self._options.dict_cls
+        if options.custom_functions is not None:
+            self._functions = self._options.custom_functions
+        else:
+            self._functions = functions.Functions()
+
+    def default_visit(self, node, *args, **kwargs):
+        raise NotImplementedError(node["type"])
+
+    def visit_subexpression(self, node, value):
+        result = value
+        for node in node["children"]:
+            result = self.visit(node, result)
+        return result
+
+    def visit_field(self, node, value):
+        try:
+            return value.get(node["value"])
+        except AttributeError:
+            return None
+
+    def visit_comparator(self, node, value):
+        # Common case: comparator is == or !=
+        comparator_func = self.COMPARATOR_FUNC[node["value"]]
+        if node["value"] in self._EQUALITY_OPS:
+            return comparator_func(
+                self.visit(node["children"][0], value),
+                self.visit(node["children"][1], value),
+            )
+        else:
+            # Ordering operators are only valid for numbers.
+            # Evaluating any other type with a comparison operator
+            # will yield a None value.
+            left = self.visit(node["children"][0], value)
+            right = self.visit(node["children"][1], value)
+            num_types = (int, float)
+            if not (_is_comparable(left) and _is_comparable(right)):
+                return None
+            return comparator_func(left, right)
+
+    def visit_current(self, node, value):
+        return value
+
+    def visit_expref(self, node, value):
+        return _Expression(node["children"][0], self)
+
+    def visit_function_expression(self, node, value):
+        resolved_args = []
+        for child in node["children"]:
+            current = self.visit(child, value)
+            resolved_args.append(current)
+        return self._functions.call_function(node["value"], resolved_args)
+
+    def visit_filter_projection(self, node, value):
+        base = self.visit(node["children"][0], value)
+        if not isinstance(base, list):
+            return None
+        comparator_node = node["children"][2]
+        collected = []
+        for element in base:
+            if self._is_true(self.visit(comparator_node, element)):
+                current = self.visit(node["children"][1], element)
+                if current is not None:
+                    collected.append(current)
+        return collected
+
+    def visit_flatten(self, node, value):
+        base = self.visit(node["children"][0], value)
+        if not isinstance(base, list):
+            # Can't flatten the object if it's not a list.
+            return None
+        merged_list = []
+        for element in base:
+            if isinstance(element, list):
+                merged_list.extend(element)
+            else:
+                merged_list.append(element)
+        return merged_list
+
+    def visit_identity(self, node, value):
+        return value
+
+    def visit_index(self, node, value):
+        # Even though we can index strings, we don't
+        # want to support that.
+        if not isinstance(value, list):
+            return None
+        try:
+            return value[node["value"]]
+        except IndexError:
+            return None
+
+    def visit_index_expression(self, node, value):
+        result = value
+        for node in node["children"]:
+            result = self.visit(node, result)
+        return result
+
+    def visit_slice(self, node, value):
+        if not isinstance(value, list):
+            return None
+        s = slice(*node["children"])
+        return value[s]
+
+    def visit_key_val_pair(self, node, value):
+        return self.visit(node["children"][0], value)
+
+    def visit_literal(self, node, value):
+        return node["value"]
+
+    def visit_multi_select_dict(self, node, value):
+        if value is None:
+            return None
+        collected = self._dict_cls()
+        for child in node["children"]:
+            collected[child["value"]] = self.visit(child, value)
+        return collected
+
+    def visit_multi_select_list(self, node, value):
+        if value is None:
+            return None
+        collected = []
+        for child in node["children"]:
+            collected.append(self.visit(child, value))
+        return collected
+
+    def visit_or_expression(self, node, value):
+        matched = self.visit(node["children"][0], value)
+        if self._is_false(matched):
+            matched = self.visit(node["children"][1], value)
+        return matched
+
+    def visit_and_expression(self, node, value):
+        matched = self.visit(node["children"][0], value)
+        if self._is_false(matched):
+            return matched
+        return self.visit(node["children"][1], value)
+
+    def visit_not_expression(self, node, value):
+        original_result = self.visit(node["children"][0], value)
+        if _is_actual_number(original_result) and original_result == 0:
+            # Special case for 0, !0 should be false, not true.
+            # 0 is not a special cased integer in jmespath.
+            return False
+        return not original_result
+
+    def visit_pipe(self, node, value):
+        result = value
+        for node in node["children"]:
+            result = self.visit(node, result)
+        return result
+
+    def visit_projection(self, node, value):
+        base = self.visit(node["children"][0], value)
+        if not isinstance(base, list):
+            return None
+        collected = []
+        for element in base:
+            current = self.visit(node["children"][1], element)
+            if current is not None:
+                collected.append(current)
+        return collected
+
+    def visit_value_projection(self, node, value):
+        base = self.visit(node["children"][0], value)
+        try:
+            base = base.values()
+        except AttributeError:
+            return None
+        collected = []
+        for element in base:
+            current = self.visit(node["children"][1], element)
+            if current is not None:
+                collected.append(current)
+        return collected
+
+    def _is_false(self, value):
+        # This looks weird, but we're explicitly using equality checks
+        # because the truth/false values are different between
+        # python and jmespath.
+        return (
+            value == "" or value == [] or value == {} or value is None or value is False
+        )
+
+    def _is_true(self, value):
+        return not self._is_false(value)
+
+
+class GraphvizVisitor(Visitor):
+    def __init__(self):
+        super(GraphvizVisitor, self).__init__()
+        self._lines = []
+        self._count = 1
+
+    def visit(self, node, *args, **kwargs):
+        self._lines.append("digraph AST {")
+        current = "%s%s" % (node["type"], self._count)
+        self._count += 1
+        self._visit(node, current)
+        self._lines.append("}")
+        return "\n".join(self._lines)
+
+    def _visit(self, node, current):
+        self._lines.append(
+            '%s [label="%s(%s)"]' % (current, node["type"], node.get("value", ""))
+        )
+        for child in node.get("children", []):
+            child_name = "%s%s" % (child["type"], self._count)
+            self._count += 1
+            self._lines.append("  %s -> %s" % (current, child_name))
+            self._visit(child, child_name)

snail_lang-0.2.0.dist-info/METADATA

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: snail-lang
+Version: 0.2.0
+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.10
+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>
+<p align="center"><em>What do you get when you shove a snake in a shell?</em></p>
+
+<h1>Snail, while I hope it is useful to myself and others, is my attempt at
+improving my knowledge of AI code developement. Things are probably broken
+in interesting and horrible ways.</h1>
+
+---
+
+**Snail** is a programming language that compiles to Python, combining Python's power with Perl/awk-inspired syntax for quick scripts and one-liners. No more whitespace sensitivity—just curly braces and concise expressions.
+
+## ✨ What Makes Snail Unique
+
+### Curly Braces, Not Indentation
+
+Write Python logic without worrying about tabs vs spaces:
+
+```snail
+def process(items) {
+    for item in items {
+        if item > 0 { print(item) }
+        else { continue }
+    }
+}
+```
+
+### Built-in Subprocess Pipelines
+
+Shell commands are first-class citizens with `$()` capture and `|` piping:
+
+```snail
+# Capture command output with interpolation
+name = "world"
+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
+```
+
+### Compact Error Handling
+
+The `?` operator makes error handling terse yet expressive:
+
+```snail
+# Swallow exception, get the error object
+err = risky_operation()?
+
+# Provide a fallback value (exception available as $e)
+value = parse_json(data):{}?
+details = fetch_url(url):"Error: {$e}"?
+
+# Access attributes directly
+name = risky()?.__class__.__name__
+args = risky()?.args[0]
+```
+
+### Regex Literals
+
+Pattern matching without `import re`:
+
+```snail
+if email in /^[\w.]+@[\w.]+$/ {
+    print("Valid email")
+}
+
+# Compiled regex for reuse
+pattern = /\d{3}-\d{4}/
+match = pattern.search(phone)
+```
+
+### Awk Mode
+
+Process files line-by-line with familiar awk semantics:
+
+```snail
+#!/usr/bin/env -S snail --awk -f
+BEGIN { total = 0 }
+/^[0-9]+/ { total = total + int($f[0]) }
+END { print("Sum:", total) }
+```
+
+Built-in variables: `$l` (line), `$f` (fields), `$n` (line number), `$fn` (per-file line number), `$p` (file path), `$m` (last match).
+
+### Pipeline Operator
+
+The `|` operator enables data pipelining through objects that implement `__pipeline__`:
+
+```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 __pipeline__(self, x) { return x * 2 }
+}
+doubled = 21 | Doubler()  # yields 42
+```
+
+### JSON Queries with JMESPath
+
+Parse and query JSON data with the `json()` function and structured pipeline accessor:
+
+```snail
+# Parse JSON and query with $[jmespath]
+data = json($(curl -s api.example.com/users))
+names = data | $[users[*].name]
+first_email = data | $[users[0].email]
+
+# Inline parsing and querying
+result = json('{"foo": 12}') | $[foo]
+```
+
+### Full Python Interoperability
+
+Snail compiles to Python AST—import any Python module, use any library:
+
+```snail
+import pandas as pd
+from pathlib import Path
+
+df = pd.read_csv(Path("data.csv"))
+filtered = df[df["value"] > 100]
+```
+
+## 🚀 Quick Start
+
+```bash
+# Install from PyPI
+pip install snail
+
+# Run a one-liner
+snail "print('Hello, Snail!')"
+
+# Execute a script
+snail -f script.snail
+
+# Awk mode for text processing
+cat data.txt | snail --awk '/error/ { print($l) }'
+```
+
+## 🏗️ Architecture
+
+Snail compiles to Python through a multi-stage pipeline:
+
+```mermaid
+flowchart TB
+    subgraph Input
+        A[Snail Source Code]
+    end
+
+    subgraph Parsing["Parsing (Pest PEG Parser)"]
+        B1[crates/snail-parser/src/snail.pest<br/>Grammar Definition]
+        B2[crates/snail-parser/<br/>Parser Implementation]
+    end
+
+    subgraph AST["Abstract Syntax Tree"]
+        C1[crates/snail-ast/src/ast.rs<br/>Program AST]
+        C2[crates/snail-ast/src/awk.rs<br/>AwkProgram AST]
+    end
+
+    subgraph Lowering["Lowering & Code Generation"]
+        D1[crates/snail-lower/<br/>AST → Python AST Transform]
+        D2[python/snail/runtime/<br/>Runtime Helpers]
+        D3[crates/snail-codegen/<br/>Python AST → Source Code]
+    end
+
+    subgraph Execution
+        E1[python/snail/cli.py<br/>CLI Interface]
+        E2[pyo3 extension<br/>in-process exec]
+    end
+
+    A -->|Regular Mode| B1
+    A -->|Awk Mode| B1
+    B1 --> B2
+    B2 -->|Regular| C1
+    B2 -->|Awk| C2
+    C1 --> D1
+    C2 --> D1
+    D1 --> D2
+    D1 --> D3
+    D2 --> D3
+    D3 --> E1
+    E1 --> E2
+    E2 --> F[Python Execution]
+
+    style A fill:#e1f5ff
+    style F fill:#e1ffe1
+    style D2 fill:#fff4e1
+```
+
+**Key Components:**
+
+- **Parser**: Uses [Pest](https://pest.rs/) parser generator with PEG grammar defined in `src/snail.pest`
+- **AST**: Separate representations for regular Snail (`Program`) and awk mode (`AwkProgram`) with source spans for error reporting
+- **Lowering**: Transforms Snail AST into Python AST, emitting helper calls backed by `snail.runtime`
+  - `?` operator → `__snail_compact_try`
+  - `$(cmd)` subprocess capture → `__SnailSubprocessCapture`
+  - `@(cmd)` subprocess status → `__SnailSubprocessStatus`
+  - Regex literals → `__snail_regex_search` and `__snail_regex_compile`
+- **Code Generation**: Converts Python AST to Python source for in-process execution
+- **CLI**: Python wrapper (`python/snail/cli.py`) that executes via the extension module
+
+## 📚 Documentation
+
+- **[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
+
+## 🔌 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/`.
+
+## 🛠️ Building from Source
+
+### Prerequisites
+
+**Python 3.10+** (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/)
+
+**No Python packages required**: Snail vendors jmespath under `snail.vendor`.
+
+**Rust toolchain** (cargo and rustc)
+
+Install Rust using [rustup](https://rustup.rs):
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+This installs `cargo` (Rust's package manager) and `rustc` (the Rust compiler). After installation, restart your shell or run:
+
+```bash
+source $HOME/.cargo/env
+```
+
+Verify installation:
+
+```bash
+cargo --version  # Should show cargo 1.70+
+rustc --version  # Should show rustc 1.70+
+python3 --version  # Should show Python 3.10+
+```
+
+**maturin** (build tool)
+
+```bash
+pip install maturin
+```
+
+### Build and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/sudonym1/snail.git
+cd snail
+
+# Create and activate a venv (recommended)
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Build and install into the venv
+maturin develop
+
+# Or build wheels for distribution
+maturin build --release
+```
+
+### Running Tests
+
+```bash
+# Run all Rust tests (parser, lowering, awk mode; excludes proptests by default)
+cargo test
+
+# Run tests including property-based tests (proptests)
+cargo test --features run-proptests
+
+# Check code formatting and linting
+cargo fmt --check
+cargo clippy -- -D warnings
+
+# Build with all features enabled (required before committing)
+cargo build --features run-proptests
+
+# Run Python CLI tests
+python -m pytest python/tests
+```
+
+**Note on Proptests**: The `snail-proptest` crate contains property-based tests that are skipped by default to keep development iteration fast. Use `--features run-proptests` to run them. Before committing, verify that `cargo build --features run-proptests` compiles successfully.
+
+### Troubleshooting
+
+**Using with virtual environments:**
+
+Activate the environment before running snail so it uses the same interpreter:
+
+```bash
+# Create and activate a venv
+python3 -m venv myenv
+source myenv/bin/activate  # On Windows: myenv\Scripts\activate
+
+# Install and run
+pip install snail
+snail "import sys; print(sys.prefix)"
+```
+
+## 📋 Project Status
+
+See [docs/PLANNING.md](docs/PLANNING.md) for the development roadmap.
+

snail_lang-0.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+snail/__init__.py,sha256=x6m1eb3fFd1tq6RV9roZgCCEsf94BJUpA2g5bZpMLWI,267
+snail/_native.abi3.so,sha256=gwaydlKG9KKVT3uqd00WvssSJHimvbqyntfmYzwYig4,1368112
+snail/cli.py,sha256=7fow0B1F3oJGNCI0Q5qRPN90WjtUQm8YnS2mGj4rIoE,1858
+snail/runtime/__init__.py,sha256=LE3OTZVB3-G2mvr9E1SDTbjk6sxMpwsMiPPRnzanvLo,889
+snail/runtime/compact_try.py,sha256=gwsZONWMf35Qcoi44cph4SqR8iThC3ujG3StTCHEMAY,379
+snail/runtime/regex.py,sha256=sfh-3zoYlO182mU25ATp1tg5jgILF2AKbLzeqsHe8mw,180
+snail/runtime/structured_accessor.py,sha256=C9LTJj0vbGZyuKEhNB58vs7ZdkGQH5jYouqwmICHTkg,1982
+snail/runtime/subprocess.py,sha256=e8y928wqTMUVyFgPNtdFDKA7HomHxzFSfMkHmfpKvc4,1887
+snail/vendor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snail/vendor/jmespath/LICENSE,sha256=bu-s-k1xuC0IQIx1FHCsjZhUU42iFCyye-Aof7E9Crk,1113
+snail/vendor/jmespath/__init__.py,sha256=JACw3X0msw0dG4GRxgvPqv0H7lk7TouYoS3mOrZtrsA,266
+snail/vendor/jmespath/ast.py,sha256=SiHRM1mdQPRt12R2qkQu_Ezbd-ghk5HLy1Hl1jHAyv8,2130
+snail/vendor/jmespath/compat.py,sha256=rMHpvmG3JAxX_lQ0yPK1dhLz-yOuEybMqdrEq6RRAr4,381
+snail/vendor/jmespath/exceptions.py,sha256=XIh7bvEnLdSyJvengYInkRvjL4-cA2N-QsUAx-ezUZQ,4134
+snail/vendor/jmespath/functions.py,sha256=VIpxdqieb8-dbA4ofqRkUj3A7rf6tL2F24nIqbtxvMQ,12546
+snail/vendor/jmespath/lexer.py,sha256=jyrrtScIUUxpVwJ2mI_CCZA9nBFOoRp1_bd8Soq4PYg,9410
+snail/vendor/jmespath/parser.py,sha256=bWD6_J391IXtmrS5TM9pg6llxp8gFrpdd8pgSJlQRcU,18897
+snail/vendor/jmespath/visitor.py,sha256=dlwE8OeKdXuon9r-1Y1ZjnsGg7gkf_CXsAMZ27ThLfQ,10800
+snail_lang-0.2.0.dist-info/METADATA,sha256=Kk0VtB7NWwYfoz0SWZD19Xup6ZEps16ZXZdF_wwytSw,8945
+snail_lang-0.2.0.dist-info/WHEEL,sha256=vZ12AMAE5CVtd8oYbYGrz3omfHuIZCNO_3P50V00s00,104
+snail_lang-0.2.0.dist-info/entry_points.txt,sha256=8u6pjHZtKGdaZQlr6yKbftplObC07caDZ44j5PIPU6M,39
+snail_lang-0.2.0.dist-info/licenses/LICENSE,sha256=erKVJCZPZ4jVaEjq4ZDw2OCXmmby5r1Z6xCpn2Akktc,1062
+snail_lang-0.2.0.dist-info/RECORD,,

snail_lang-0.2.0.dist-info/WHEEL

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

snail_lang-0.2.0.dist-info/entry_points.txt

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