srsh 0.7.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c0910382ad05f07b93041cfbecb7d3db98f24e23df1ecd5d23243aab35a7f63
-  data.tar.gz: c39ce2184076112bb950035ea2f09939bef9f4105b2c207e6ec73ee152fc3c89
+  metadata.gz: 5b4ebcca8a9c5952dd9608cd8fe5dd311aae5445224896c4e190db2c7981a4dc
+  data.tar.gz: 17f76ba91a316ebd35dfdfaf5c260baf778348a73e4f930c8c61fb0de2222cc3
 SHA512:
-  metadata.gz: ee7bd7e5ae91582ed612171eda2f3440d16d8d07988b465fd61470e094d80b0f766cfc6f248d2980f0371a0db228593a326934fe7f6c4367fb8e9b009213e26f
-  data.tar.gz: 6195a9d026471e57b1b7b8f87970362261302d0e7f8b936a030ecc02bce7de2c56d3420d2e7cee0b7810f60acc32f5a171bd45acd1181ffc7d2469389f37ebd7
+  metadata.gz: 37f82634b0c88623c50d1aa3eee65d2b219ed317c87ea6e9abe42c904a9989aec5a0fd360715a33879a5dfc44ecf020611c5880b0a024868bb4f6627cabf95d0
+  data.tar.gz: 787a567cfed45fdd641874c8a0e9f43b919645ff5c882c5be0aac6bde2899a6cb4c89f2f5f032bfe0b1c2a274df4df66800542834937fe8d12dec0f3932db835

data/LICENSE

@@ -1,17 +1,21 @@
-Copyright (C) 2025 RobertFlexx
+MIT License
 
-  This software is provided 'as-is', without any express or implied
-  warranty.  In no event will the authors be held liable for any damages
-  arising from the use of this software.
+Copyright (c) 2026 RobertFlexx
 
-  Permission is granted to anyone to use this software for any purpose,
-  including commercial applications, and to alter it and redistribute it
-  freely, subject to the following restrictions:
+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:
 
-  1. The origin of this software must not be misrepresented; you must not
-     claim that you wrote the original software. If you use this software
-     in a product, an acknowledgment in the product documentation would be
-     appreciated but is not required.
-  2. Altered source versions must be plainly marked as such, and must not be
-     misrepresented as being the original software.
-  3. This notice may not be removed or altered from any source distribution.
+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.

data/README.md

@@ -1,235 +1,452 @@
-This is version 0.6.0, if things dont work, or work optimally. If you notice anything wrong, please consult me.
-(Fixed Control-C, fixed some bugs, added new features (check via help command)
-THIS IS A BETA RELEASE, IT MAY NOT WORK.
+# srsh, Simple Ruby Shell
 
-The code itself is written by RobertFlexx, but the comments are written by ChatGPT.
+`srsh` is a Unix shell written in Ruby. Its scripting language is **RSH**.
 
-## Known Issues:
+The basic idea is pretty simple: keep the parts of a normal shell that are already good, then stop making people switch languages when a script gets serious.
 
-* Flatpak chaining with 'and' doesn't work.
-* Running Shell Scripts might not always work. Sometimes it works, other times not so much.
+```rsh
+printf 'c\na\nb\n' | sort
 
-## Please Consult:
+files := glob("src/**/*.rb")
+  |> reject(::p => contains(p, "/vendor/"))
+  |> sort
 
-* if you have any issues with this SRSh version, please post an issue.
+? files |> len > 20 => = "that's a lot of Ruby"
+```
+
+`|` is still a Unix process pipe. `|>` is an RSH value pipe. They look related because they *are* related, but they move different things.
+
+This tree reports **1.0.0**. It is the unreleased 1.0 line; the older 1.1/1.2 numbers were development snapshots and were a dumb way to version something that had not shipped yet.
+
+## What SRSH is trying to be
+
+Bash is fantastic at launching programs. It gets a lot less fun when you need nested data, workers, reusable modules, objects, error handling, higher-order functions, or a pile of state that has to remain understandable next month.
 
-## How to Install:
+RSH is meant to cover that gap without turning the shell into a foreign environment:
 
-### Clone the repository
+```rsh
+branch := $(git branch --show-current)
 
-```console
-git clone https://github.com/RobertFlexx/RSH
+fn changed(path) => cmd("git", "diff", "--quiet", "--", path).result().status != 0
+
+dirty := glob("src/**/*") |> filter(changed)
+= "#{branch}: #{dirty |> len} changed files"
 ```
 
-### Change the directory to where the Ruby Script is located
+It is **not a Bash parser**. Existing Bash scripts still belong to Bash. The goal is that new automation can start as a shell one-liner and grow into a proper RSH program without a rewrite.
+
+## Build and run
 
-```console
-cd RSH
+Ruby 3.2+ is required.
+
+```sh
+make test
+./bin/srsh
 ```
 
-### And finally run it
+The shell is fully usable as Ruby-only code. There is a tiny optional C extension for hot lexer work and Linux process naming:
 
-```console
-./rsh
+```sh
+make native
+./bin/srsh
 ```
 
----
+YJIT is enabled when the running Ruby supports it. Set `SRSH_YJIT=0` if you want it off.
+
+Install somewhere else with:
 
-## Requirements
+```sh
+make PREFIX="$HOME/.local" install
+```
 
-* Ruby installed (2.7+ is recommended; newer is better).
-* A POSIX-ish terminal (Linux, *BSD, macOS Terminal, iTerm2, etc).
-* `./rsh` needs the executable bit set:
+## The syntax has a reason
 
-  ```console
-  chmod +x rsh
-  ```
+RSH has some odd-looking syntax, but the goal is not to win a weird-language contest.
 
-If `./rsh` complains or behaves oddly, **run it directly in the repo first** before messing with symlinks or PATH.
+There are a few boundaries you hit constantly in shell programming, and RSH gives each one a visible shape:
 
----
+```text
+command | command        bytes/processes move between Unix programs
+value |> function        RSH values move through functions
+$(command)               process output crosses into the value layer
+name := value            local RSH binding
+$NAME := value           exported process environment
+::x => expression        tiny callable value
+bridge ... from ...      RSH crosses into a native C ABI
+```
 
-## Basic Usage
+That makes parsing less ambiguous around arbitrary Unix command names, and it lets hot scripts stay short without turning maintained code into punctuation soup.
 
-Once you’re in the repo:
+Readable forms exist too:
 
-```console
-./rsh
+```rsh
+fn deploy(files, dry := no)
+  if dry
+    = "would deploy #{files |> len} files"
+  else
+    each files -> path
+      emit path
+    end
+  end
+end
 ```
 
-Inside `srsh` / `rsh` you can:
+The short forms lower to the same AST:
 
-* Use normal commands (`ls`, `cat`, `grep`, etc.).
-* Use built-ins:
+```rsh
+:: twice(x) => x * 2
+? ready => emit "go"
+@ jobs -> job => = job.name
+```
 
-  * `help` – show builtin help with all srsh-specific commands.
-  * `systemfetch` – prints system info with nice bars.
-  * `hist` – view shell history.
-  * `clearhist` – clear history (memory + file).
-  * `alias` / `unalias` – manage aliases.
-* Enjoy:
+Use whichever one fits the size of the job.
 
-  * **Autosuggestions** (ghost text from history).
-  * **Smart Tab completion**:
+## The REPL is actually an RSH REPL
 
-    * Completes commands, files, dirs.
-    * `cd` → only directories.
-    * `cat` → only files.
+Bindings, expressions and blocks work directly at the shell prompt:
 
----
+```text
+> x := 21
+> = x * 2
+42
 
-## Adding `rsh` / `srsh` to your PATH
+> fn triple(n)
+... return n * 3
+... end
+> = triple(10)
+30
+```
 
-So you don’t have to always `cd` into the repo and run `./rsh`, you can either:
+Multiline list/map/call expressions also continue properly:
 
-1. Add the repo directory to your `PATH`, or
-2. Symlink the script into a directory that’s already on your `PATH`.
+```text
+> jobs := [
+...   fetch("a"),
+...   fetch("b")
+... ]
+```
+
+That same completeness logic is used for manually entered continuations. For an actual terminal paste, SRSH enables bracketed-paste mode and captures the whole clipboard payload before parsing any of it. Multi-line pastes get a small preview; press Enter once to run the whole program or Ctrl-C to throw it away. Embedded newlines never become a queue of accidental commands.
+
+The editor keeps the old SRSH behavior too: prefix history prediction, Right Arrow to accept it, UTF-8 cursor movement, history navigation, and first-Tab/second-Tab completion.
+
+## Shell side
+
+Normal Unix muscle memory is supposed to work:
+
+```sh
+cat *.log | grep ERROR | sort -u
+make -j8 && put "built"
+long_job &
+jobs
+fg %1
+```
+
+Implemented shell features include:
+
+- `fork`/`exec` pipelines and process groups
+- `|`, `&&`, `||`, `;`, background `&`
+- `<`, `>`, `>>`, `2>`, `2>>`
+- `jobs`, `fg`, `bg`
+- command substitution with nested `$(...)`
+- aliases
+- `$VAR`, `${VAR}`, `$?`, `$!`, positional arguments
+- pathname globbing (`*`, `?`, `[...]`, and recursive `**` where Ruby's glob supports it)
+- `~` expansion
+- command lookup caching
+- `cd`, `pwd`, `ls`, `printf`, `export`, `read`, `source`, `which`/`type`
+- `pushd`, `popd`, `dirs`, `umask`, `kill`
+- `option pipefail`, `option nounset`, `option noclobber`
+- `option strict yes` as a shortcut for `pipefail + nounset`
+
+No-match globs stay literal, which is a much less surprising default for an interactive shell.
+
+## Values and functional scripting
+
+RSH has integers, floats, strings, booleans, `void`, lists, maps, ranges, lambdas, code values, tasks, prototypes, namespaces, native handles and structured commands.
+
+```rsh
+users := json(readfile("users.json"))
+
+enabled := users
+  |> filter(::u => u?.enabled ?? no)
+  |> sort(::u => lower(u.name))
+
+= enabled |> map(::u => u.name)
+```
 
-> ⚠️ There is a *system* command called `rsh` on some systems.
-> To avoid conflict, using the name `srsh` for the installed command is usually safer.
+The usual functional operations are built in:
 
-### Option 1 — Add the repo directory to PATH (Linux & macOS, bash/zsh)
+```text
+map filter reject fold find any all count sum
+sort uniq flat zip enumerate take drop chunk group
+each tap partial compose
+```
 
-Assuming the repo is at `~/RSH`:
+Named functions are first-class too:
 
-```console
-chmod +x ~/RSH/rsh
+```rsh
+fn square(x) => x * x
+= 1 .. 10 |> map(square) |> sum
 ```
 
-#### For `bash` (Linux, older macOS)
+## Objects without a ceremony tax
+
+RSH uses prototypes plus traits. There is no class-inheritance maze to climb through just to hold some state.
+
+```rsh
+trait Named
+  fn label() => "#{self.name}: #{self.value}"
+end
 
-Add this line to `~/.bashrc` (or `~/.bash_profile` on macOS):
+proto Counter(name, start := 0) with Named
+  slot name := name
+  slot value := start
 
-```bash
-export PATH="$HOME/RSH:$PATH"
+  fn inc(by := 1)
+    self.value += by
+    return self
+  end
+end
+
+hits := Counter("hits")
+hits.inc(3)
+= hits.label()
 ```
 
-Then reload:
+Object slot updates are synchronized, so objects can be an explicit shared-state tool between tasks.
+
+## Concurrency
 
-```console
-source ~/.bashrc
+Async RSH functions return task values immediately:
+
+```rsh
+task fetch(url)
+  return cmd("curl", "-fsS", url).check().out
+end
+
+jobs := urls |> map(fetch)
+pages := await_all(jobs)
 ```
 
-#### For `zsh` (default on modern macOS)
+You can spawn a lambda directly:
+
+```rsh
+job := &:: => expensive_io()
+= job.await(2.0)
+```
 
-Add this line to `~/.zshrc`:
+Shared mutation is explicit:
 
-```zsh
-export PATH="$HOME/RSH:$PATH"
+```rsh
+hits := atom(0)
+workers := 0 ..< 32 |> map(::i => &:: => hits.swap(::n => n + 1))
+await_all(workers)
+= hits.get()
 ```
 
-Reload:
+There are channels too:
 
-```console
-source ~/.zshrc
+```rsh
+queue := chan(8)
+queue.send("hello")
+= queue.recv(1)
+queue.close()
 ```
 
-Now you can just run:
+`parallel()` is a Ruby thread pool, which is great for I/O and subprocess waits. On CRuby the GVL still exists; SRSH does not pretend otherwise. `pmap()` uses Unix fork workers when you actually want CPU parallelism.
 
-```console
-rsh
-# or if you prefer to rename it:
-srsh
+`race()` cancels losing task handles. A failing `await_all()` cancels still-running siblings before propagating the error.
+
+## Modules, namespaces and cleanup
+
+Namespaces can live in the same file:
+
+```rsh
+space mathx
+  bias := 10
+  fn bump(x) => x + bias
+end
+
+= mathx.bump(5)
 ```
 
----
+Or load a file as a namespace:
 
-### Option 2 — Symlink into `/usr/local/bin` (Linux & macOS)
+```rsh
+use "./lib/http.rsh" as http
+= http.get("https://example.com")
+```
+
+Module paths are resolved relative to the importing script when possible, and import cycles are rejected.
 
-This keeps your PATH clean and gives you a nice command name.
+Cleanup is LIFO and tied to the current execution scope:
 
-From the repo directory:
+```rsh
+fn build()
+  tmp := "/tmp/my-build.lock"
+  writefile(tmp, "busy")
+  defer rmfile(tmp)
 
-```console
-chmod +x rsh
-sudo ln -s "$(pwd)/rsh" /usr/local/bin/srsh
+  # return, error, whatever; the cleanup still runs
+  return compile()
+end
 ```
 
-Now you can just type:
+There is a block form when cleanup takes more than one statement:
 
-```console
-srsh
+```rsh
+defer
+  close_stuff()
+  emit "cleaned up"
+end
 ```
 
-from anywhere.
+## Structured process values
 
-If you really, really want to override the system `rsh` (not recommended):
+Shell strings are convenient. They are not always what you want for untrusted filenames or arguments.
 
-```console
-sudo ln -s "$(pwd)/rsh" /usr/local/bin/rsh
+```rsh
+result := cmd("git", "rev-parse", "--verify", ref).check()
+sha := result.out.trim()
 ```
 
----
+`cmd()` keeps argv as argv. It does not feed your data back through shell parsing.
 
-### *BSD: Adding to PATH
+Available methods include `.argv()`, `.run()`, `.result()`, `.capture()`, `.check()` and `.task()`.
 
-On *BSD, the default shell might be `sh`, `ksh`, `csh`, or `tcsh`. Same idea, different config files.
+## C interop: `bridge`
 
-Assuming repo at `~/RSH`:
+This is the native boundary:
 
-```console
-chmod +x ~/RSH/rsh
+```rsh
+bridge c from "@self"
+  strlen(cstr) -> usize
+end
+
+= c.strlen("hello")
 ```
 
-#### For `sh` / `ksh` / `ash` / `dash` style shells
+Or load a specific shared library:
 
-Add to `~/.profile`:
+```rsh
+bridge math from "libm.so.6"
+  cos(f64) -> f64
+  pow(f64, f64) -> f64
+end
 
-```sh
-export PATH="$HOME/RSH:$PATH"
+= math.cos(0.0)
 ```
 
-Then either log out and back in, or:
+For output buffers/pointer APIs:
 
-```console
-. ~/.profile
+```rsh
+bridge libc from "libc.so.6"
+  gethostname(ptr, usize) -> i32
+end
+
+buf := cbuf(256)
+libc.gethostname(buf, buf.size())
+= buf.string()
+```
+
+Supported ABI names are:
+
+```text
+void bool
+ i8  u8  i16 u16  i32 u32  i64 u64
+isize usize
+f32 f64
+cstr ptr
 ```
 
-#### For `csh` / `tcsh`
+`@self` means the current process' symbol table. Bridges resolve their symbols once when declared, so calls do not repeatedly search the library.
+
+This is real FFI. A wrong C signature can crash the SRSH process, because C does not care about your feelings. See `docs/SECURITY.md` before feeding native pointers to random libraries.
+
+## Errors and strict scripts
+
+```rsh
+try
+  cfg := json(readfile("config.json"))
+catch err
+  = "config failed: #{err.message}"
+  cfg := %[]
+finally
+  audit("config attempted")
+end
+```
 
-Edit `~/.cshrc` (or `~/.tcshrc`) and add:
+For value pipelines:
 
-```csh
-set path = ( $HOME/RSH $path )
+```rsh
+result := attempt(:: => risky())
+? !result.ok => = result.error.message
 ```
 
-Reload it:
+For shell-side stricter behavior:
 
-```console
-source ~/.cshrc
+```rsh
+option strict yes
+option noclobber yes
 ```
 
-Now you should be able to run:
+`strict` currently means `nounset + pipefail`; it does **not** try to clone all of Bash's `set -e` edge cases.
 
-```console
-rsh
-# or rename / symlink it as srsh if you want:
-srsh
+## Metascripting
+
+RSH code can be a value instead of a string you hope parses later:
+
+```rsh
+code cleanup
+  @ glob("tmp/*.log") -> file
+    rm $file
+  .@
+end
+
+? dry => = sourceof(cleanup)
+? !dry => run(cleanup)
 ```
 
----
+The reflective toolbox includes `code()`, `run()`, `eval()`, `sourceof()`, `valid()`, `locals()`, `fns()`, `protos()` and `traits()`.
+
+## Ruby plugins
 
-## Tips / Notes
+Ruby is still part of the point. A Ruby plugin can register builtins, hooks and themes through the SRSH API. Plugins are trusted code and are permission-checked before auto-loading.
 
-* If the command **isn’t found** after editing PATH:
+RSH plugins are supported too if you want to stay entirely in the language.
 
-  * Check which shell you’re actually using:
+## Process identity
 
-    ```console
-    echo $SHELL
-    ```
-  * Make sure you edited the correct rc file for that shell.
-  * Print your PATH to confirm:
+SRSH sets `$SHELL`, argv0, and the Linux process name to `srsh`. That keeps process-oriented tools from calling your active shell `ruby` just because Ruby is the engine.
+
+The executable behind the process is still Ruby. That is intentional, not something SRSH tries to disguise.
+
+## Repo layout
+
+```text
+bin/srsh
+lib/srsh/
+  app.rb
+  editor.rb
+  builtins.rb
+  history.rb
+  plugins.rb
+  process_identity.rb
+  state.rb
+  theme.rb
+  language/
+  shell/
+ext/srsh_native/       optional accelerator
+examples/
+docs/
+test/
+```
 
-    ```console
-    echo "$PATH"
-    ```
-* If things feel off, run it directly from the repo with:
+The code is split by job, not by architectural cosplay. If a file gets big because the job is big, it gets split when that actually makes it easier to work on.
 
-  ```console
-  ./rsh
-  ```
+## Current status
 
-  to see if the issue is PATH-related or shell-related.
+The project is still unreleased. `1.0.0` means “the 1.0 tree,” not “independently audited and incapable of bugs.” A shell has too much surface area for that kind of claim.
 
-And as i say : if anything looks cursed, **consult me and/or open an issue** :D
+Run the tests, beat on it, and report the ugly cases. Those are usually more useful than another feature bullet.