nandi.uk
A structured-data shell in Gleam, inspired by Nushell
7.0 kB
185 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 (``) before the `❯` character (which 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+R** | Reverse-i-search through history (Enter accepts onto the line) |
72| Ctrl+A / Ctrl+E | Beginning / end of line |
73| Ctrl+W | Delete previous word |
74| Ctrl+U / Ctrl+K | Kill to start / end of line |
75| Ctrl+L | Clear screen |
76| **Ctrl+C** | Cancel current line at the prompt; while an external command runs, send SIGINT to that process (does not exit the shell) |
77| Ctrl+D | EOF (empty line) or delete under cursor |
78
79History is persisted under the user cache as `gleshell-history/lines`.
80Non-TTY input falls back to Erlang’s `edlin`/`get_until` path.
81
82## Examples
83
84```nu
85# list files as a table, filter, project columns
86ls | where type == file | select name size
87ls | find toml md
88echo [moe larry curly] | find l
89
90# ranges and list ops
91range 10 | reverse | first 3
92range 5 | length
93
94# records and JSON
95echo {name: "gleshell", cool: true}
96echo "{\"a\": 1}" | from json | get a
97open data.json | get users | first
98range 3 | to json
99
100# variables
101let n = range 3 | length
102echo $n
103
104# process environment (Nushell-style)
105$env.HOME
106$env | get PATH
107$env.MY_VAR = hello
108echo $env.MY_VAR
109
110# external programs (stdout captured as a string)
111^uname -a
112which ls
113which -a ls
114```
115
116## Language sketch
117
118| Feature | Syntax |
119|--------|--------|
120| Pipeline | `cmd \| cmd \| cmd` |
121| Strings | `"hello"` or bare words `hello` |
122| Numbers | `42`, `3.14` |
123| Bools | `true` / `false` |
124| Nothing | `null` / `nothing` |
125| Lists | `[1 2 3]` |
126| Records | `{name: alice, age: 30}` |
127| Variables | `let x = …` then `$x` (pipeline input is `$in`) |
128| Env | `$env`, `$env.HOME`, `$env.FOO = value` |
129| Flags | `--flag` / `--flag value` |
130| Force external | `^command args…` |
131| Comments | `# …` |
132
133## Built-ins
134
135Filesystem: `ls`, `cd`, `pwd`, `cat`, `open`, `save`
136
137Table/list: `where`/`filter`, `find`, `select`, `get`, `first`, `last`, `take`, `skip`, `sort-by`, `reverse`, `length`, `columns`, `table`, `flatten`, `uniq`, `wrap`, `unwrap`, `keys`, `values`
138
139Data: `echo`, `range`, `lines`, `to`/`from` (subcommand `json`), `type`, `describe`, `env`, `sys`, `which`, `help`, `about`, `exit`
140
141Pager: `less` — builtin color-aware pager for pipeline input or files (`ls | less`,
142`less README.md`). ANSI from tables and external tools is kept; short output is
143printed without an interactive session. `^less` still runs the external binary.
144
145Unknown command names fall through to external executables on `PATH`.
146
147## Layout
148
149```text
150src/
151 gleshell.gleam # entry + REPL
152 gleshell_ffi.erl # line editor (Ctrl+R), cwd, process spawn
153 gleshell/
154 value.gleam # structured Value type
155 lexer.gleam / parser.gleam
156 eval.gleam # pipeline evaluator
157 builtins.gleam # Nu-inspired commands
158 pager.gleam # color-aware builtin less
159 display.gleam # table pretty-printer
160 color.gleam # Nushell-style ANSI colors
161 highlight.gleam # live input syntax highlighting
162 env.gleam / sys.gleam
163```
164
165Input and output are colorized on a TTY (Nu-like shapes on the command line;
166headers bold green, numbers purple, bools cyan, dirs blue, errors red, …).
167External tools (`jj`, `git`, `fastfetch`, …) keep their own colors: final-stage
168commands inherit the real TTY; captured pipeline stages get `FORCE_COLOR` /
169`CLICOLOR_FORCE`, and git gets `color.ui=always` plus `log.decorate=short` via
170`GIT_CONFIG_*` (git ignores `FORCE_COLOR`, and `decorate=auto` drops
171`(HEAD, origin/main, …)` when stdout is a pipe — so bare `git log | less`
172would otherwise lose both color and ref decorations). Pre-colored text is not
173re-painted by the shell. While the raw line editor is active, the TTY is
174switched to cooked mode for those children so LF-only output does not
175staircase. The builtin `less` keeps ANSI (like `less -R`); external pagers
176still get `LESS=FRX` when unset so they pass colors through.
177Disable with `NO_COLOR=1`; force with `FORCE_COLOR=1`.
178
179## Status
180
181Early 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.
182
183## License
184
185Apache-2.0 (same as the Gleam project template unless you change it).