nandi.uk
A structured-data shell in Gleam, inspired by Nushell
8.1 kB
201 lines
1# gleshell
2
3A **structured-data shell** written in [Gleam](https://gleam.run), inspired by [Nushell](https://www.nushell.sh).
4
5Instead of piping opaque text between programs, gleshell pipelines pass typed values: strings, numbers, lists, records, and tables. Built-in commands like `ls`, `where`, and `select` work on that structure.
6
7```text
8~/code/gleshell on main
9 ls | where type == file | select name size | first 5
10╭──────┬──────╮
11│ name │ size │
12├──────┼──────┤
13│ … │ … │
14╰──────┴──────╯
15```
16
17The interactive prompt is zero-config and Starship-inspired: full path with `~`,
18optional git branch (read from `.git`, no external tools), and a Nerd Font shell
19icon (``) as the prompt character (turns red after a non-zero exit).
20Install a Nerd Font so the glyphs render (flake: `nix profile install
21.#nerd-fonts`, or put `nerd-fonts.symbols-only` in your system/fonts packages;
22the devenv shell already includes it).
23
24## Quick start
25
26Requires [Gleam](https://gleam.run/getting-started/) and Erlang (or use Nix):
27
28```bash
29# install a self-contained `gle` (Erlang shipment in the Nix store — no repo checkout)
30nix profile install .
31gle -c 'ls | first 3'
32
33# one-shot without installing
34nix run . -- -c 'ls | first 3'
35
36# dev shell (source tree; gleam, erlang, rebar3)
37# Preferred: direnv auto-loads the flake shell (see .envrc). Once:
38# direnv allow
39# then cd into the repo (nushell needs a direnv pre_prompt hook; see below).
40# Manual alternative — bare `nix develop` fails under pure flake eval:
41nix develop --no-pure-eval
42gleam run # interactive REPL
43gleam run -- -c 'ls | first 3'
44gleam test
45```
46
47### direnv
48
49This repo ships a [`.envrc`](.envrc) that runs `use flake . --no-pure-eval`
50so devenv can see the real project directory (pure flake eval cannot).
51
521. Install [direnv](https://direnv.net/) and hook it into your shell
53 ([nushell](https://github.com/direnv/direnv/wiki/Nushell), bash, zsh, …).
542. From the repo root: `direnv allow`
553. Open a new shell (or `cd .`) — you should see the devenv enter message and
56 have `gleam` on `PATH` without running `nix develop`.
57
58Bare `nix develop` still needs `--no-pure-eval` for the same reason; with
59direnv you usually do not need `nix develop` at all.
60
61### REPL editing
62
63On a TTY the interactive REPL uses a **raw-mode line editor** with
64**Nushell-style syntax highlighting** as you type (commands cyan, strings
65green, numbers purple, pipes purple, flags blue, variables purple, …).
66
67| Key | Action |
68|-----|--------|
69| ↑ / ↓ | History |
70| **Tab** | Command completion (builtins + `PATH`) at the start of a pipeline stage; filename completion for arguments (common prefix; list matches if ambiguous) |
71| **→ / Ctrl+F / End / Ctrl+E** (at end of line) | Accept greyed-out history suggestion (full) |
72| **Alt+F** (at end of line) | Accept one word of the history suggestion |
73| **Ctrl+R** | Fuzzy history search (stinkpot-style list; ↑/↓ move, Enter/Tab accept onto the line, Esc cancel) |
74| Ctrl+A / Ctrl+E | Beginning / end of line (Ctrl+E at end also accepts a history hint) |
75| Ctrl+W | Delete previous word |
76| Ctrl+U / Ctrl+K | Kill to start / end of line |
77| Ctrl+L | Clear screen |
78| **Ctrl+C** | Cancel current line at the prompt; while an external command runs, send SIGINT to that process (does not exit the shell) |
79| Ctrl+D | EOF (empty line) or delete under cursor |
80
81As you type, the **newest matching history line** is shown in grey after the
82cursor (Nushell/fish-style hints). Accept with **→**, **End**, **Ctrl+E**, or
83**Ctrl+F**; accept one word with **Alt+F**.
84
85History is persisted under the user cache as `gleshell-history/lines`.
86Non-TTY input falls back to Erlang’s `edlin`/`get_until` path.
87
88## Examples
89
90```nu
91# list files as a table, filter, project columns
92ls | where type == file | select name size
93ls | find toml md
94echo [moe larry curly] | find l
95
96# ranges and list ops
97range 10 | reverse | first 3
98range 5 | length
99
100# records and JSON
101echo {name: "gleshell", cool: true}
102echo "{\"a\": 1}" | from json | get a
103open data.json | get users | first
104range 3 | to json
105
106# variables
107let n = range 3 | length
108echo $n
109
110# process environment (Nushell-style)
111$env.HOME
112$env | get PATH
113$env.MY_VAR = hello
114echo $env.MY_VAR
115
116# external programs (stdout captured as a string)
117^uname -a
118which ls
119which -a ls
120which -f sh
121```
122
123## Language sketch
124
125| Feature | Syntax |
126|--------|--------|
127| Pipeline | `cmd \| cmd \| cmd` |
128| Strings | `"hello"` or bare words `hello` |
129| Numbers | `42`, `3.14` |
130| Bools | `true` / `false` |
131| Nothing | `null` / `nothing` |
132| Lists | `[1 2 3]` |
133| Records | `{name: alice, age: 30}` |
134| Variables | `let x = …` then `$x` (pipeline input is `$in`) |
135| Env | `$env`, `$env.HOME`, `$env.FOO = value` |
136| Flags | `--flag` / `--flag value` |
137| Force external | `^command args…` |
138| Comments | `# …` (word-boundary only; mid-token `#` is fine — `nixpkgs#pkg`) |
139
140## Built-ins
141
142Filesystem: `ls`, `cd`, `pwd`, `cat` (MIME/extension detect + syntax color on TTY;
143`--raw` for plain pipelines), `open`, `save`
144
145Table/list: `where`/`filter`, `find`, `select`, `get`, `first`, `last`, `take`, `skip`, `sort-by`, `reverse`, `length`, `columns`, `table`, `flatten`, `uniq`, `wrap`, `unwrap`, `keys`, `values`
146
147Data: `echo`, `range`, `lines`, `to`/`from` (subcommand `json`), `type`, `describe`, `env`, `sys`, `which`, `help`, `about`, `exit`
148
149HTTP: `http get|post|put|delete|patch|head` — fetch/send with structured JSON bodies
150and responses (`http get https://example.com`, `http post URL {a: 1}`, `--full`,
151`-H` headers, `--raw`, `--allow-errors`)
152
153Pager: `less` — builtin color-aware pager for pipeline input or files (`ls | less`,
154`less README.md`). ANSI from tables and external tools is kept; short output is
155printed without an interactive session. Interactive keys include live `/` search
156(case-insensitive, finds as you type) and `n`/`N` next/previous match. `^less`
157still runs the external binary.
158
159Unknown command names fall through to external executables on `PATH`.
160
161## Layout
162
163```text
164src/
165 gleshell.gleam # entry + REPL
166 gleshell_ffi.erl # line editor (Ctrl+R fuzzy history), cwd, process spawn
167 gleshell/
168 value.gleam # structured Value type
169 lexer.gleam / parser.gleam
170 eval.gleam # pipeline evaluator
171 builtins.gleam # Nu-inspired commands
172 pager.gleam # color-aware builtin less
173 display.gleam # table pretty-printer
174 color.gleam # Nushell-style ANSI colors
175 highlight.gleam # live input syntax highlighting
176 syntax.gleam # file language detect + cat highlighters
177 env.gleam / sys.gleam
178```
179
180Input and output are colorized on a TTY (Nu-like shapes on the command line;
181headers bold green, numbers purple, bools cyan, dirs blue, errors red, …).
182External tools (`jj`, `git`, `fastfetch`, …) keep their own colors: final-stage
183commands inherit the real TTY; captured pipeline stages (e.g. `jj log | less`,
184`git log | less`) run under a throwaway PTY when the shell wants color so tools
185that only colorize on a terminal still emit ANSI — without per-tool env hacks.
186Nested pagers are forced to `cat` so the producer cannot hang in its own
187`less`. If `script` is unavailable, capture falls back to pipes plus
188`FORCE_COLOR` / `CLICOLOR_FORCE` and a git `GIT_CONFIG_*` overlay. Pre-colored
189text is not re-painted by the shell. While the raw line editor is active, the
190TTY is switched to cooked mode for those children so LF-only output does not
191staircase. The builtin `less` keeps ANSI (like `less -R`); external pagers
192still get `LESS=FRX` when unset so they pass colors through.
193Disable with `NO_COLOR=1`; force with `FORCE_COLOR=1`.
194
195## Status
196
197Early but usable: core pipeline model, tables, filters, JSON, and external commands work. Not a full Nushell clone (no closures/plugins yet). Contributions and experiments welcome.
198
199## License
200
201Apache-2.0 (same as the Gleam project template unless you change it).