termish 0.2.0__tar.gz → 0.2.2__tar.gz

{termish-0.2.0/termish.egg-info → termish-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termish
-Version: 0.2.0
+Version: 0.2.2
 Summary: Virtual terminal with shell-like commands over a pluggable filesystem.
 Author: ashenfad
 License-Expression: MIT
@@ -46,7 +46,7 @@ Parses and executes shell scripts (pipelines, redirects, semicolons) against any
 - **Variable expansion** -- `$?` (last exit code), `$VAR` / `${VAR}` from an env dict; expands in unquoted and double-quoted contexts, literal in single quotes
 - **Binary-safe pipelines** -- pipes and redirects carry bytes, so `cat bin.dat > copy.dat` is byte-identical and `cat file.gz | zcat` works; text decoding happens at each command's own boundary, and the returned transcript is decoded once for display
 - **Terminal-faithful transcript** -- stderr diagnostics appear in the returned output when execution continues past a failure (`cmd; next`, `cmd || rescue`), like a real terminal screen; a failure with nothing after it raises `TerminalError`. Stderr redirects are honored: `2>file` captures, `2>/dev/null` suppresses, `2>&1` merges into the pipe (`cmd 2>&1 | head` works)
-- **37 builtins** -- ls, cat, echo, printf, grep, find, sed, tr, sort, uniq, cut, wc, diff, tar, gzip, zcat, zip, jq, xargs, file, true, false, basename, dirname, ...
+- **39 builtins** -- ls, cat, echo, printf, grep, find, sed, tr, sort, uniq, cut, wc, diff, tar, gzip, zcat, zip, jq, xargs, file, test/[, true, false, basename, dirname, ...
 - **Custom commands** -- inject your own command handlers alongside builtins; injected commands override builtins and compose in pipelines
 - **jq engine** -- built-in jq filter parser and evaluator (field access, pipes, functions, conditionals)
 - **Pluggable filesystem** -- `FileSystem` is a `typing.Protocol`; any object with the right methods works
@@ -203,7 +203,7 @@ That is not a coincidence, and it is a promise: termish's `FileSystem` protocol
 | Meta | `xargs` |
 | JSON | `jq` |
 | Inspection | `file` |
-| Control | `true`, `false` |
+| Control | `true`, `false`, `test` / `[` |
 
 ## Development
 

{termish-0.2.0 → termish-0.2.2}/README.md

@@ -10,7 +10,7 @@ Parses and executes shell scripts (pipelines, redirects, semicolons) against any
 - **Variable expansion** -- `$?` (last exit code), `$VAR` / `${VAR}` from an env dict; expands in unquoted and double-quoted contexts, literal in single quotes
 - **Binary-safe pipelines** -- pipes and redirects carry bytes, so `cat bin.dat > copy.dat` is byte-identical and `cat file.gz | zcat` works; text decoding happens at each command's own boundary, and the returned transcript is decoded once for display
 - **Terminal-faithful transcript** -- stderr diagnostics appear in the returned output when execution continues past a failure (`cmd; next`, `cmd || rescue`), like a real terminal screen; a failure with nothing after it raises `TerminalError`. Stderr redirects are honored: `2>file` captures, `2>/dev/null` suppresses, `2>&1` merges into the pipe (`cmd 2>&1 | head` works)
-- **37 builtins** -- ls, cat, echo, printf, grep, find, sed, tr, sort, uniq, cut, wc, diff, tar, gzip, zcat, zip, jq, xargs, file, true, false, basename, dirname, ...
+- **39 builtins** -- ls, cat, echo, printf, grep, find, sed, tr, sort, uniq, cut, wc, diff, tar, gzip, zcat, zip, jq, xargs, file, test/[, true, false, basename, dirname, ...
 - **Custom commands** -- inject your own command handlers alongside builtins; injected commands override builtins and compose in pipelines
 - **jq engine** -- built-in jq filter parser and evaluator (field access, pipes, functions, conditionals)
 - **Pluggable filesystem** -- `FileSystem` is a `typing.Protocol`; any object with the right methods works
@@ -167,7 +167,7 @@ That is not a coincidence, and it is a promise: termish's `FileSystem` protocol
 | Meta | `xargs` |
 | JSON | `jq` |
 | Inspection | `file` |
-| Control | `true`, `false` |
+| Control | `true`, `false`, `test` / `[` |
 
 ## Development
 

{termish-0.2.0 → termish-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "termish"
-version = "0.2.0"
+version = "0.2.2"
 description = "Virtual terminal with shell-like commands over a pluggable filesystem."
 readme = "README.md"
 license = "MIT"

termish-0.2.2/termish/interpreter/commands/_regex.py

@@ -0,0 +1,113 @@
+r"""POSIX basic regular expressions (BRE), read into Python ``re`` syntax.
+
+``grep`` and ``sed`` without ``-E`` take BRE, the syntax agents write
+when they write GNU commands, and its escaping is roughly the reverse of
+Python's: ``\(``, ``\{``, ``\|``, ``\+`` and ``\?`` are operators while
+their bare forms are literal characters. Handed to ``re`` unchanged, the
+operators read as literals, so ``s/a\+/X/`` matched nothing and still
+exited 0, and a bare ``(`` was a syntax error rather than a parenthesis.
+
+With ``-E`` a pattern is already in the syntax ``re`` speaks and is
+passed through untouched; this module is for the other case.
+"""
+
+from __future__ import annotations
+
+#: Escaped in BRE they are operators; bare, they are literal characters.
+_SWAPPED = "(){}|+?"
+
+
+def bre_to_python(pattern: str) -> str:
+    r"""Translate a POSIX BRE ``pattern`` into a Python ``re`` pattern.
+
+    Outside a bracket expression:
+
+    - ``\( \) \{ \} \| \+ \?`` become ``( ) { } | + ?``, and their bare
+      forms become escaped literals.
+    - ``*`` is literal where nothing precedes it: at the start of the
+      pattern, of a group, or of an alternative (and after a leading
+      ``^``).
+    - ``^`` anchors only at those same starting points and ``$`` only at
+      the end of the pattern, of a group or of an alternative; anywhere
+      else each is a literal character.
+    - ``\<`` and ``\>`` (GNU word boundaries) become ``\b``.
+    - Every other escape — ``\1``-``\9``, ``\.``, ``\*``, ``\w`` — is
+      kept as it is, since it means the same to ``re``.
+
+    Inside ``[...]`` a backslash is a literal character, as in BRE, and
+    a ``]`` right after ``[`` or ``[^`` is a member rather than the end.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(pattern)
+    # True where nothing precedes this position in the current
+    # alternative: '*' is literal here and '^' anchors.
+    at_start = True
+    while i < n:
+        ch = pattern[i]
+        if ch == "[":
+            i = _bracket(pattern, i, out)
+            at_start = False
+            continue
+        if ch == "\\":
+            if i + 1 >= n:
+                out.append("\\\\")  # a trailing backslash is literal
+                i += 1
+                continue
+            nxt = pattern[i + 1]
+            i += 2
+            if nxt in _SWAPPED:
+                out.append(nxt)
+                at_start = nxt in "(|"
+            elif nxt in "<>":
+                out.append(r"\b")
+                at_start = False
+            else:
+                out.append("\\" + nxt)
+                at_start = False
+            continue
+        i += 1
+        if ch in _SWAPPED:
+            out.append("\\" + ch)
+            at_start = False
+        elif ch == "*" and at_start:
+            out.append(r"\*")
+            at_start = False
+        elif ch == "^":
+            # An anchor leaves the position a start: '^*' is a literal '*'.
+            out.append("^" if at_start else r"\^")
+        elif ch == "$":
+            rest = pattern[i:]
+            ends = not rest or rest.startswith(("\\)", "\\|"))
+            out.append("$" if ends else r"\$")
+            at_start = False
+        else:
+            out.append(ch)
+            at_start = False
+    return "".join(out)
+
+
+def _bracket(pattern: str, start: int, out: list[str]) -> int:
+    """Copy the bracket expression at ``start`` into ``out``, with its
+    backslashes made literal; return the position after it.
+
+    An unterminated bracket is copied as far as it goes, for ``re`` to
+    refuse in its own words.
+    """
+    n = len(pattern)
+    out.append("[")
+    i = start + 1
+    if i < n and pattern[i] == "^":
+        out.append("^")
+        i += 1
+    if i < n and pattern[i] == "]":
+        out.append(r"\]")
+        i += 1
+    while i < n:
+        ch = pattern[i]
+        i += 1
+        if ch == "]":
+            out.append("]")
+            return i
+        out.append("\\\\" if ch == "\\" else ch)
+    return i

termish-0.2.2/termish/interpreter/commands/conditional.py

@@ -0,0 +1,210 @@
+"""``test`` and ``[``: the conditionals agents write before ``&&`` and ``||``.
+
+``[ -f x ] && ...``, ``test -d out || mkdir out`` and ``[ -z "$VAR" ]``
+are how a script asks a question, and without them each is
+``command not found``. The subset is the POSIX one agents use:
+
+- file tests: ``-e`` ``-f`` ``-d`` ``-s`` ``-r`` ``-w`` ``-x``
+- string tests: ``-z`` ``-n``, ``=`` (and bash's ``==``) ``!=``, and a bare
+  string, true when it is not empty
+- integer tests: ``-eq`` ``-ne`` ``-lt`` ``-le`` ``-gt`` ``-ge``
+- ``!``, ``-a``, ``-o`` and parentheses
+
+True exits 0, false exits 1 with nothing written, and a malformed
+expression or a non-integer operand exits 2 with a diagnostic, as in
+bash. Nothing is ever written to stdout.
+
+The filesystem has no permission bits, so ``-r`` and ``-w`` are true
+for any path that exists (a read-only mount still answers true: the
+protocol cannot say otherwise without writing), and ``-x`` is true for
+a directory, which can be entered, and false for a file, which nothing
+here can run. Out of scope: ``[[ ]]``, ``-nt``/``-ot``, ``-L``, pattern
+matching.
+"""
+
+from __future__ import annotations
+
+import re
+
+from termish.context import CommandContext, CommandResult
+from termish.fs import FileSystem
+
+from ._util import resolve_path
+
+_UNARY = {"-e", "-f", "-d", "-s", "-r", "-w", "-x", "-z", "-n"}
+_BINARY = {"=", "==", "!=", "-eq", "-ne", "-lt", "-le", "-gt", "-ge"}
+_INTEGER = re.compile(r"^\s*[+-]?\d+\s*$")
+#: bash's integers are signed 64-bit; past either end is not an integer.
+_INT_MIN, _INT_MAX = -(2**63), 2**63 - 1
+
+
+class _Usage(Exception):
+    """A malformed expression or a bad operand: exit 2, with this text."""
+
+
+def test_cmd(ctx: CommandContext) -> CommandResult | None:
+    """``test EXPRESSION`` — exit 0 when it holds, 1 when it does not."""
+    return _run("test", list(ctx.args), ctx.fs)
+
+
+def bracket_cmd(ctx: CommandContext) -> CommandResult | None:
+    """``[ EXPRESSION ]`` — ``test``, with a closing ``]`` required."""
+    args = list(ctx.args)
+    if not args or args[-1] != "]":
+        return CommandResult(exit_code=2, stderr="[: missing `]'")
+    return _run("[", args[:-1], ctx.fs)
+
+
+def _run(name: str, args: list[str], fs: FileSystem) -> CommandResult | None:
+    try:
+        held = _evaluate(args, fs)
+    except _Usage as e:
+        return CommandResult(exit_code=2, stderr=f"{name}: {e}")
+    return None if held else CommandResult(exit_code=1, stderr="")
+
+
+def _evaluate(args: list[str], fs: FileSystem) -> bool:
+    """POSIX reads one to four arguments by their count, which is what
+    makes ``[ -n ]`` (a bare string) and ``[ ! = x ]`` mean what they do;
+    longer expressions go to the general parser."""
+    n = len(args)
+    if n == 0:
+        return False
+    if n == 1:
+        return args[0] != ""
+    if n == 2:
+        if args[0] == "!":
+            return not _evaluate(args[1:], fs)
+        if args[0] in _UNARY:
+            return _unary(args[0], args[1], fs)
+        raise _Usage(f"{args[0]}: unary operator expected")
+    if n == 3:
+        if args[1] in _BINARY:
+            return _binary(args[0], args[1], args[2])
+        if args[0] == "!":
+            return not _evaluate(args[1:], fs)
+        if args[0] == "(" and args[2] == ")":
+            return _evaluate(args[1:2], fs)
+        if args[1] in ("-a", "-o"):
+            return _Parser(args, fs).parse()
+        raise _Usage(f"{args[1]}: binary operator expected")
+    if n == 4:
+        if args[0] == "!":
+            return not _evaluate(args[1:], fs)
+        if args[0] == "(" and args[3] == ")":
+            return _evaluate(args[1:3], fs)
+    return _Parser(args, fs).parse()
+
+
+class _Parser:
+    """``-o`` binds loosest, then ``-a``, then ``!``; a primary is a
+    parenthesised expression, a unary test, a binary test or a bare
+    string."""
+
+    def __init__(self, args: list[str], fs: FileSystem) -> None:
+        self.args = args
+        self.fs = fs
+        self.i = 0
+
+    def parse(self) -> bool:
+        value = self._or()
+        if self.i < len(self.args):
+            raise _Usage(f"{self.args[self.i]}: unexpected argument")
+        return value
+
+    def _peek(self, ahead: int = 0) -> str | None:
+        j = self.i + ahead
+        return self.args[j] if j < len(self.args) else None
+
+    def _or(self) -> bool:
+        value = self._and()
+        while self._peek() == "-o":
+            self.i += 1
+            right = self._and()
+            value = value or right
+        return value
+
+    def _and(self) -> bool:
+        value = self._not()
+        while self._peek() == "-a":
+            self.i += 1
+            right = self._not()
+            value = value and right
+        return value
+
+    def _not(self) -> bool:
+        if self._peek() == "!":
+            self.i += 1
+            return not self._not()
+        return self._primary()
+
+    def _primary(self) -> bool:
+        tok = self._peek()
+        if tok is None:
+            raise _Usage("argument expected")
+        if tok == "(":
+            self.i += 1
+            value = self._or()
+            if self._peek() != ")":
+                raise _Usage("')' expected")
+            self.i += 1
+            return value
+        if tok in _UNARY and self._peek(1) is not None:
+            self.i += 2
+            return _unary(tok, self.args[self.i - 1], self.fs)
+        if self._peek(1) in _BINARY and self._peek(2) is not None:
+            left, op, right = self.args[self.i : self.i + 3]
+            self.i += 3
+            return _binary(left, op, right)
+        self.i += 1
+        return tok != ""
+
+
+def _unary(op: str, operand: str, fs: FileSystem) -> bool:
+    if op == "-z":
+        return operand == ""
+    if op == "-n":
+        return operand != ""
+    if operand == "":
+        # No path at all, not the current directory: an unset variable
+        # in `[ -d "$OUT" ]` must not test whatever the shell stands in.
+        return False
+    path = resolve_path(operand, fs)
+    if not fs.exists(path):
+        return False
+    if op in ("-e", "-r", "-w"):
+        return True
+    if op == "-f":
+        return fs.isfile(path)
+    if op == "-d":
+        return fs.isdir(path)
+    if op == "-x":
+        return fs.isdir(path)
+    # -s: exists and is not empty; a directory counts as not empty, as a
+    # real directory's own size does
+    if fs.isdir(path):
+        return True
+    return fs.stat(path).size > 0
+
+
+def _binary(left: str, op: str, right: str) -> bool:
+    if op in ("=", "=="):
+        return left == right
+    if op == "!=":
+        return left != right
+    a, b = _integer(left), _integer(right)
+    return {
+        "-eq": a == b,
+        "-ne": a != b,
+        "-lt": a < b,
+        "-le": a <= b,
+        "-gt": a > b,
+        "-ge": a >= b,
+    }[op]
+
+
+def _integer(text: str) -> int:
+    value = int(text.strip()) if _INTEGER.match(text) else None
+    if value is None or not _INT_MIN <= value <= _INT_MAX:
+        raise _Usage(f"{text}: integer expression expected")
+    return value

{termish-0.2.0 → termish-0.2.2}/termish/interpreter/commands/filesystem.py

@@ -3,6 +3,7 @@ Filesystem commands for the terminal interpreter.
 """
 
 import posixpath
+from typing import Any
 
 from termish.context import CommandContext, CommandResult
 from termish.errors import TerminalError
@@ -91,108 +92,131 @@ def ls(ctx: CommandContext) -> CommandResult | None:
     if unknown:
         raise TerminalError(f"ls: unknown option: {unknown[0]}")
 
-    for i, path in enumerate(parsed.paths):
-        if len(parsed.paths) > 1:
-            stdout.write(f"{path}:\n")
-
-        try:
-            # -d: list directories themselves, not their contents
-            if parsed.directory and fs.isdir(path):
-                if parsed.l:
-                    meta = fs.stat(path)
-                    if parsed.human_readable:
-                        size = _human_readable_size(meta.size).rjust(6)
-                    else:
-                        size = str(meta.size).rjust(8)
-                    time = (
-                        meta.modified_at[:16].replace("T", " ")
-                        if meta.modified_at
-                        else " " * 16
-                    )
-                    stdout.write(f"drw-r--r-- 1 agent agent {size} {time} {path}\n")
-                else:
-                    stdout.write(f"{path}\n")
-                continue
-
-            # Check if it is a file first
-            if fs.isfile(path):
-                if parsed.l:
-                    # List detailed for file
-                    meta = fs.stat(path)
+    def long_line(path: str, type_char: str) -> str:
+        meta = fs.stat(path)
+        if parsed.human_readable:
+            size = _human_readable_size(meta.size).rjust(6)
+        else:
+            size = str(meta.size).rjust(8)
+        time = meta.modified_at[:16].replace("T", " ") if meta.modified_at else " " * 16
+        return f"{type_char}rw-r--r-- 1 agent agent {size} {time} {path}\n"
+
+    def list_dir(path: str) -> None:
+        needs_detailed = parsed.l or parsed.t or parsed.S or parsed.classify
+        if needs_detailed:
+            items = fs.list_detailed(path, recursive=parsed.R)
+            if not parsed.a:
+                items = [i for i in items if not i.name.startswith(".")]
+            if parsed.S:
+                items = sorted(items, key=lambda x: x.size, reverse=True)
+            elif parsed.t:
+                items = sorted(items, key=lambda x: x.modified_at or "", reverse=True)
+            if parsed.r:
+                items = list(reversed(items))
+
+            if parsed.l:
+                for item in items:
+                    type_char = "d" if item.is_dir else "-"
                     if parsed.human_readable:
-                        size = _human_readable_size(meta.size).rjust(6)
+                        size = _human_readable_size(item.size).rjust(6)
                     else:
-                        size = str(meta.size).rjust(8)
+                        size = str(item.size).rjust(8)
                     time = (
-                        meta.modified_at[:16].replace("T", " ")
-                        if meta.modified_at
+                        item.modified_at[:16].replace("T", " ")
+                        if item.modified_at
                         else " " * 16
                     )
-                    stdout.write(f"-rw-r--r-- 1 agent agent {size} {time} {path}\n")
-                else:
-                    stdout.write(f"{path}\n")
-                continue
-
-            needs_detailed = parsed.l or parsed.t or parsed.S or parsed.classify
-            if needs_detailed:
-                items = fs.list_detailed(path, recursive=parsed.R)
-                if not parsed.a:
-                    items = [i for i in items if not i.name.startswith(".")]
-                if parsed.S:
-                    items = sorted(items, key=lambda x: x.size, reverse=True)
-                elif parsed.t:
-                    items = sorted(
-                        items, key=lambda x: x.modified_at or "", reverse=True
+                    suffix = "/" if parsed.classify and item.is_dir else ""
+                    stdout.write(
+                        f"{type_char}rw-r--r-- 1 agent agent {size} {time} {item.path}{suffix}\n"
                     )
-                if parsed.r:
-                    items = list(reversed(items))
-
-                if parsed.l:
-                    for item in items:
-                        type_char = "d" if item.is_dir else "-"
-                        if parsed.human_readable:
-                            size = _human_readable_size(item.size).rjust(6)
-                        else:
-                            size = str(item.size).rjust(8)
-                        time = (
-                            item.modified_at[:16].replace("T", " ")
-                            if item.modified_at
-                            else " " * 16
-                        )
-                        suffix = "/" if parsed.classify and item.is_dir else ""
-                        stdout.write(
-                            f"{type_char}rw-r--r-- 1 agent agent {size} {time} {item.path}{suffix}\n"
-                        )
-                else:
-                    filtered = [
-                        item.path + ("/" if parsed.classify and item.is_dir else "")
-                        for item in items
-                    ]
-                    if filtered:
-                        stdout.write("\n".join(filtered) + "\n")
             else:
-                items_str = fs.list(path, recursive=parsed.R)
                 filtered = [
-                    p
-                    for p in items_str
-                    if parsed.a or not p.split("/")[-1].startswith(".")
+                    item.path + ("/" if parsed.classify and item.is_dir else "")
+                    for item in items
                 ]
-                if parsed.r:
-                    filtered = list(reversed(filtered))
                 if filtered:
                     stdout.write("\n".join(filtered) + "\n")
+        else:
+            items_str = fs.list(path, recursive=parsed.R)
+            filtered = [
+                p for p in items_str if parsed.a or not p.split("/")[-1].startswith(".")
+            ]
+            if parsed.r:
+                filtered = list(reversed(filtered))
+            if filtered:
+                stdout.write("\n".join(filtered) + "\n")
+
+    # GNU's order: an operand that is missing is reported and the rest
+    # are listed; file operands (and, with -d, directories as entries)
+    # come first, by name and with no header; then each directory, by
+    # name, under a "dir:" header whenever there is more than one
+    # operand, with a blank line before every group after the first.
+    missing: list[str] = []
+    files: list[str] = []
+    dirs: list[str] = []
+    for path in parsed.paths:
+        try:
+            if fs.isdir(path):
+                (files if parsed.directory else dirs).append(path)
+            elif fs.isfile(path) or fs.exists(path):
+                files.append(path)
+            else:
+                missing.append(path)
+        except Exception:
+            missing.append(path)
+
+    def operand_order(paths: list[str]) -> list[str]:
+        """Operands in the order their entries would be: by name, or by
+        size or time (largest and newest first) under -S and -t, and
+        reversed under -r."""
+        if parsed.S or parsed.t:
+
+            def key(p: str) -> Any:
+                try:
+                    meta = fs.stat(p)
+                except Exception:
+                    return 0 if parsed.S else ""
+                return meta.size if parsed.S else (meta.modified_at or "")
+
+            paths = sorted(sorted(paths), key=key, reverse=True)
+        else:
+            paths = sorted(paths)
+        return list(reversed(paths)) if parsed.r else paths
 
-        except FileNotFoundError:
-            raise TerminalError(
-                f"ls: cannot access '{path}': No such file or directory"
-            )
-        except NotADirectoryError:
-            raise TerminalError(f"ls: cannot access '{path}': Not a directory")
-        except Exception as e:
-            raise TerminalError(f"ls: {e}")
+    files = operand_order(files)
+    dirs = operand_order(dirs)
+    errors = [f"ls: cannot access '{p}': No such file or directory" for p in missing]
+    if not files and not dirs:
+        raise TerminalError("\n".join(errors))
+
+    try:
+        for path in files:
+            if parsed.l:
+                stdout.write(long_line(path, "d" if fs.isdir(path) else "-"))
+            else:
+                stdout.write(f"{path}\n")
+        headers = len(parsed.paths) > 1
+        for k, path in enumerate(dirs):
+            if files or k:
+                stdout.write("\n")
+            if headers:
+                stdout.write(f"{path}:\n")
+            list_dir(path)
+    except FileNotFoundError as e:
+        raise TerminalError(
+            f"ls: cannot access '{e.filename or e}': No such file or directory"
+        )
+    except NotADirectoryError as e:
+        raise TerminalError(f"ls: cannot access '{e.filename or e}': Not a directory")
+    except TerminalError:
+        raise
+    except Exception as e:
+        raise TerminalError(f"ls: {e}")
 
-        if i < len(parsed.paths) - 1:
-            stdout.write("\n")
+    if errors:
+        return CommandResult(exit_code=2, stderr="\n".join(errors) + "\n")
+    return None
 
 
 def touch(ctx: CommandContext) -> CommandResult | None: