docs/nushell/ takes the nushell material from docs/terminal/nushell.md and following.md, each fact in one place, with links to nushell's book and command pages. In nushell 012 is a number, so examples call ^012. Tapes: a pipeline in a real nu session, a followed log read by a shell region, a notebook recipe with a chart; the notebook tape fits both regions on screen. make demos draws charts as text. The landing page links the section, the README grid is 8 tiles, and nu code blocks get a small Prism grammar.
- commit
- 8ad40141a0cd6f43ceea1ba976f9610cc2b77e78
- parent
- 9e32828d82420cddbb8491b3fa33c1ca4a5c8ce9
- author
- Dami <dami.etoile@gmail.com>
- kind
- docs risk score 0.9 of 3, Jev's estimate
@@ -105,7 +105,8 @@ oracle:
105105 # frame held). Needs vhs 0.12+ (go install106106 # github.com/charmbracelet/vhs@latest), ttyd and ffmpeg. The JEV demo107107 # talks to demos/fakejev, started here, never the real service.108-# DEMOS=jev renders just one.108+# Charts are drawn as text, as the tapes and README describe; VHS109+# records text, not images. DEMOS=jev renders just one.109110 DEMOS ?= $(basename $(notdir $(wildcard demos/*.tape)))110111 FAKEJEV_ADDR := 127.0.0.1:8799111112 @@ -115,7 +116,7 @@ demos: build
115116 mkdir -p demos/out/stills116117 bin/fakejev -addr $(FAKEJEV_ADDR) & pid=$$!; trap "kill $$pid" EXIT; \117118 export DEMOS_TTYD="$$(command -v ttyd)" PATH="$(CURDIR)/demos/lib:$$PATH"; \118- export XDG_CONFIG_HOME="$$(mktemp -d)" O12_JEV_CREDENTIAL_STORE=false O12_THEME= O12_LOCALE=en-US; \119+ export XDG_CONFIG_HOME="$$(mktemp -d)" O12_JEV_CREDENTIAL_STORE=false O12_CHART_IMAGES=false O12_THEME= O12_LOCALE=en-US; \119120 cd demos && for d in $(DEMOS); do echo "vhs $$d.tape"; vhs -q $$d.tape || exit 1; done120121 mkdir -p demos/out/media121122 for d in $(DEMOS); do ffmpeg -v error -y -i demos/out/$$d.gif -filter_complex \@@ -42,13 +42,13 @@ rest: building from a clone, importing files, `012 serve` and settings.
4242 - **Files**: a diff-friendly JSON format, import from CSV, TSV, JSON,4343 nushell's NUON, XLSX, SQLite, Parquet and Lotus 1-2-3, export to CSV,4444 TSV, JSON, NUON, XLSX and SQLite ([files](docs/files/README.md)).45-- **A stage in a pipeline**: `ls | to nuon | 012 --pipe | from nuon`45+- **A stage in a pipeline**: `ls | to nuon | ^012 --pipe | from nuon`4646 edits a table on the terminal and sends it on with its types47- ([nushell and pipelines](docs/terminal/nushell.md)).47+ ([pipelines](docs/nushell/pipelines.md)).4848 - **Nushell notebooks**: `012 nu` (or `!` in any workbook) runs nushell4949 pipelines whose tables become live, named regions of the sheet;5050 `$r1` reads one in the next command, and refreshing it runs what reads51- it ([notebooks](docs/terminal/nushell.md#notebooks)).51+ it ([notebooks](docs/nushell/notebooks.md)).5252 - **Macros**, recorded or written as Starlark scripts saved with the sheet5353 ([macros](docs/sheets/macros.md)).5454 - **Made for terminals**: the mouse, hyperlinks, the system clipboard over@@ -64,12 +64,10 @@ rest: building from a clone, importing files, `012 serve` and settings.
6464 | Menus and the command palette (Ctrl+K) | Charts that float over the grid and follow their data |6565 |  |  |6666 | Conditional formatting and data validation | Pivot tables, live |67-|  |  |68-| Arrays that spill | Wrapped text, borders and merged cells |67+|  |  |68+| Arrays that spill | Nushell notebooks |6969 |  |  |7070 | JEV functions in formulas | Macros |71-|  | |72-| Nushell notebooks | |7371 7472 Each guide shows its own recordings too. They are7573 [VHS](https://github.com/charmbracelet/vhs) tapes in [`demos/`](demos),@@ -27,7 +27,7 @@ rises in measured steps; see [Bounds of support](docs/contributing/limits.md#wha
2727 ### 4. Nushell notebook2828 2929 What's left of making 012 and nushell one tool, on top of the notebook30-([Notebooks](docs/terminal/nushell.md#notebooks)).30+([Notebooks](docs/nushell/notebooks.md)).3131 3232 | Item | Result | Size |3333 |---|---|---|@@ -105,8 +105,11 @@ stream above rather than a design of their own.
105105 - `012 serve` over SSH, with files on the ssh command line and recovery of unsaved work: [Serving over SSH](docs/terminal/ssh.md)106106 - Shift+Enter, Ctrl+I and keys held to preview, with the kitty keyboard protocol: [Keys and mouse](docs/reference/keys.md#keys-the-terminal-has-to-tell-apart)107107 - Sixel chart images on terminals without kitty graphics, drawn after the frame and redrawn as the screen moves: [Charts](docs/sheets/charts.md)108-- 012 as a stage in a pipeline: `012 -` reads a table from standard input, `012 --pipe` sends the sheet or selection on, with nushell's types kept through NUON: [Nushell and pipelines](docs/terminal/nushell.md)109-- `012 nu` and notebook sheets: nushell pipelines at a prompt on the formula bar become live, named regions that read each other and refresh in dependency order, saved as commands and never run on open: [Notebooks](docs/terminal/nushell.md#notebooks)108+109+**Nushell**110+111+- 012 as a stage in a pipeline: `012 -` reads a table from standard input, `012 --pipe` sends the sheet or selection on, with nushell's types kept through NUON: [Pipelines](docs/nushell/pipelines.md)112+- `012 nu` and notebook sheets: nushell pipelines at a prompt on the formula bar become live, named regions that read each other and refresh in dependency order, saved as commands and never run on open: [Notebooks](docs/nushell/notebooks.md)110113 111114 **Files**112115 @@ -67,7 +67,7 @@ func usage() error {
6767 " sheet, or a .csv, .tsv, .json, .nuon, .xlsx, .sqlite, .parquet or .wk1 file to import\n" +6868 " 012 [flags] -: a table from standard input (NUON, JSON, CSV or TSV)\n" +6969 " 012 [flags] --pipe [--to nuon|json|csv|tsv] [file]: on quitting, send the table to standard output\n" +70- " 012 nu [flags] [file]: a nushell notebook, at its prompt (see docs/terminal/nushell.md)\n" +70+ " 012 nu [flags] [file]: a nushell notebook, at its prompt (see docs/nushell/notebooks.md)\n" +7171 " 012 serve [flags] [dir]: serve sheets in dir over SSH (see docs/terminal/ssh.md)\n" +7272 " 012 config [path|edit|default|themes|set-key|delete-key]\n" +7373 " 012 version")@@ -12,7 +12,7 @@ import (
1212 "github.com/FelineStateMachine/012/internal/ui"1313 )1414 15-// 012 - and 012 --pipe (see docs/terminal/nushell.md): standard input15+// 012 - and 012 --pipe (see docs/nushell/pipelines.md): standard input1616 // may be a table to read, and with --pipe standard output is where the1717 // result goes when the UI quits. The UI can't use either, so it runs on1818 // the terminal itself, opened as /dev/tty (CONIN$ and CONOUT$ on@@ -76,7 +76,7 @@ func (p *pipeMode) check(files []string, stdinTTY bool) error {
7676 p.stdin = true // --pipe reads standard input unless given a file7777 }7878 if p.stdin && stdinTTY {79- return errors.New("nothing piped in: 012 - reads a table from standard input, e.g. ls | to nuon | 012 -")79+ return errors.New("nothing piped in: 012 - reads a table from standard input, e.g. 012 - < sales.csv, or ls | to nuon | ^012 - in nushell")8080 }8181 return nil8282 }@@ -0,0 +1,39 @@
1+{"time":"09:14:01","method":"GET","path":"/api/items","status":200,"ms":8}2+{"time":"09:14:03","method":"GET","path":"/api/orders","status":200,"ms":45}3+{"time":"09:14:05","method":"GET","path":"/health","status":200,"ms":82}4+{"time":"09:14:07","method":"POST","path":"/api/orders","status":201,"ms":119}5+{"time":"09:14:09","method":"GET","path":"/login","status":200,"ms":156}6+{"time":"09:14:11","method":"PUT","path":"/api/cart","status":200,"ms":13}7+{"time":"09:14:13","method":"GET","path":"/api/search","status":200,"ms":50}8+{"time":"09:14:15","method":"DELETE","path":"/api/items/7","status":204,"ms":87}9+{"time":"09:14:17","method":"GET","path":"/api/items","status":500,"ms":1024}10+{"time":"09:14:19","method":"POST","path":"/api/cart/3","status":201,"ms":161}11+{"time":"09:14:21","method":"GET","path":"/api/items","status":200,"ms":18}12+{"time":"09:14:23","method":"GET","path":"/api/orders","status":404,"ms":55}13+{"time":"09:14:25","method":"GET","path":"/health","status":200,"ms":92}14+{"time":"09:14:27","method":"POST","path":"/api/orders","status":503,"ms":1029}15+{"time":"09:14:29","method":"GET","path":"/login","status":200,"ms":166}16+{"time":"09:14:31","method":"PUT","path":"/api/cart","status":200,"ms":23}17+{"time":"09:14:33","method":"GET","path":"/api/search","status":200,"ms":60}18+{"time":"09:14:35","method":"DELETE","path":"/api/items/7","status":500,"ms":997}19+{"time":"09:14:37","method":"GET","path":"/api/items","status":200,"ms":134}20+{"time":"09:14:39","method":"POST","path":"/api/cart/3","status":201,"ms":171}21+{"time":"09:14:41","method":"GET","path":"/api/items","status":200,"ms":28}22+{"time":"09:14:43","method":"GET","path":"/api/orders","status":200,"ms":65}23+{"time":"09:14:45","method":"GET","path":"/health","status":200,"ms":102}24+{"time":"09:14:47","method":"POST","path":"/api/orders","status":201,"ms":139}25+{"time":"09:14:49","method":"GET","path":"/login","status":200,"ms":176}26+{"time":"09:14:51","method":"PUT","path":"/api/cart","status":200,"ms":33}27+{"time":"09:14:53","method":"GET","path":"/api/search","status":200,"ms":70}28+{"time":"09:14:55","method":"DELETE","path":"/api/items/7","status":204,"ms":107}29+{"time":"09:14:57","method":"GET","path":"/api/items","status":500,"ms":1044}30+{"time":"09:14:59","method":"POST","path":"/api/cart/3","status":201,"ms":181}31+{"time":"09:15:01","method":"GET","path":"/api/items","status":200,"ms":38}32+{"time":"09:15:03","method":"GET","path":"/api/orders","status":404,"ms":75}33+{"time":"09:15:05","method":"GET","path":"/health","status":200,"ms":112}34+{"time":"09:15:07","method":"POST","path":"/api/orders","status":503,"ms":1049}35+{"time":"09:15:09","method":"GET","path":"/login","status":200,"ms":186}36+{"time":"09:15:11","method":"PUT","path":"/api/cart","status":200,"ms":43}37+{"time":"09:15:13","method":"GET","path":"/api/search","status":200,"ms":80}38+{"time":"09:15:15","method":"DELETE","path":"/api/items/7","status":500,"ms":1017}39+{"time":"09:15:17","method":"GET","path":"/api/items","status":200,"ms":154}@@ -0,0 +1,40 @@
1+# Following a log: a JSON lines log grows while 012 follows it in a2+# linked region (Data > Linked file > Link a table, here from the3+# palette). A shell region reads it as $app and keeps the errors;4+# refreshing it later reads the rows the log has now. The log is5+# data/requests.jsonl written a line at a time. Needs nu on the PATH.6+Output out/follow-log.gif7+Source lib/setup.tape8+9+Hide10+Type "rm -f out/app.jsonl; head -n 6 data/requests.jsonl > out/app.jsonl" Enter11+Type `(tail -n +7 data/requests.jsonl | while IFS= read -r l; do sleep 0.8; printf '%s\n' "$l" >> out/app.jsonl; done) & clear; ../bin/012` Enter12+Sleep 2s13+Show14+15+Sleep 600ms16+Ctrl+K17+Type@100ms "link a table"18+Sleep 600ms19+Enter20+Sleep 800ms21+Type "out/app.jsonl"22+Sleep 500ms23+Enter24+Sleep 1s25+Enter26+Sleep 3.5s27+Screenshot out/stills/follow-log-linked.png28+Type "!"29+Sleep 600ms30+Type "errors = $app | where status >= 500 | select time path status ms"31+Sleep 500ms32+Enter33+Sleep 2.5s34+Screenshot out/stills/follow-log-errors.png35+Escape36+Sleep 6s37+Enter38+Sleep 2.5s39+Screenshot out/stills/follow-log-refreshed.png40+Sleep 1s@@ -0,0 +1,8 @@
1+# A nushell session for the nushell tapes: nu without your config files,2+# a fixed prompt, and 012 on the PATH, so what's typed is what you'd3+# type. Source it after setup.tape; it leaves the screen clear, hidden.4+Hide5+Type `nu --no-config-file -e '$env.PROMPT_COMMAND = {|| "demos" }; $env.PROMPT_COMMAND_RIGHT = ""; $env.PATH = ($env.PATH | prepend ("../bin" | path expand))'` Enter6+Sleep 1.5s7+Type "clear" Enter8+Sleep 500ms@@ -0,0 +1,37 @@
1+# A notebook recipe: nushell cleans a CSV's money text into numbers,2+# a second region totals it by region, and a chart of the totals3+# follows the table. Needs nu on the PATH.4+Output out/nu-recipe.gif5+Source lib/setup.tape6+7+Hide8+Type "../bin/012 nu" Enter9+Sleep 2s10+Show11+12+Sleep 800ms13+Type@35ms `sales = open data/sales.csv | update Revenue { str replace -ar '[$,]' '' | into float }`14+Sleep 500ms15+Enter16+Sleep 2s17+Type@35ms "totals = $sales | group-by Region --to-table | update items { get Revenue | math sum } | rename Region Revenue"18+Sleep 500ms19+Enter20+Sleep 2s21+Screenshot out/stills/nu-recipe-regions.png22+Escape23+Sleep 400ms24+Ctrl+G25+Type "A21:B25" Enter26+Sleep 800ms27+Ctrl+K28+Type@120ms "chart"29+Sleep 800ms30+Enter31+Sleep 1.5s32+Enter33+Sleep 800ms34+Escape35+Sleep 2.5s36+Screenshot out/stills/nu-recipe-chart.png37+Sleep 1s@@ -0,0 +1,28 @@
1+# Pipelines: in a nushell session, a table goes through 012 and on.2+# ls's table goes in as NUON, 012 shows its sizes in the Size format, a3+# selection is sent back, and nu carries on with sizes that are still4+# file sizes. Needs nu on the PATH.5+Output out/pipeline.gif6+Source lib/setup.tape7+Source lib/nu.tape8+9+Show10+Sleep 600ms11+Type "ls data | select name size"12+Sleep 400ms13+Enter14+Sleep 2.2s15+Type "ls data | select name size | to nuon | ^012 --pipe | from nuon | where size > 400b"16+Sleep 600ms17+Enter18+Sleep 2s19+Screenshot out/stills/pipeline-sheet.png20+Ctrl+G21+Type "A1:B4" Enter22+Sleep 1s23+Ctrl+Q24+Sleep 1.6s25+Enter26+Sleep 2.5s27+Screenshot out/stills/pipeline-result.png28+Sleep 1s@@ -12,6 +12,7 @@ sidebar_position: 1
1212 | [Formulas](formulas/README.md) | Entries, references, building formulas, arrays, decimal arithmetic, JEV functions |1313 | [Files](files/README.md) | Import and download, Excel files, saving, the `.012` format |1414 | [The terminal](terminal/README.md) | Terminal features, themes, serving over SSH |15+| [Nushell](nushell/README.md) | 012 in a pipeline, nushell notebooks, types, a cookbook |1516 | [Reference](reference/README.md) | Keys, functions, configuration, the macro API |1617 | [Contributing](contributing/README.md) | Architecture, extending, the UX bar, testing, limits, observability |1718 @@ -53,6 +53,9 @@ page that passes `make lint` but breaks on the site shows up here.
5353 folders, `title` and `sidebar_position` for pages5454 ([Docs](testing.md#docs) has the rules the tree follows).5555 - Images in `docs/media/` are bundled from the pages that show them.56+- Prism has no nushell grammar, so `nu` code blocks use a small one in57+ `website/src/prism/nushell.ts`, loaded by the swizzled58+ `website/src/theme/prism-include-languages.ts`.5659 - A relative link that leaves `docs/` (the roadmap, `CLAUDE.md`)5760 becomes a link to the file on GitHub5861 (`website/src/remark/repo-links.ts`).@@ -101,7 +101,11 @@ so Alt+letter reaches the app. VHS has no mouse commands, so the tapes
101101 use the keyboard, and they reach commands through the palette (Ctrl+K)102102 rather than counting menu items, so a new menu item doesn't break them.103103 Tapes that change settings set them for the run (`O12_KEYMAP=vim`)104-rather than writing the config file the other tapes share.104+rather than writing the config file the other tapes share, and charts105+are drawn as text (`O12_CHART_IMAGES=false`), since VHS records text.106+The nushell tapes need `nu`: `demos/lib/nu.tape` starts a session107+without your config files, with a fixed prompt and 012 on the PATH, and108+their data is in `demos/data`, so each recording comes out the same.105109 106110 A change to what a tape shows means rendering it again, reading its107111 stills, and copying what the docs show into `docs/media/`: GIFs from@@ -26,7 +26,7 @@ it back in its format.
2626 | Parquet | Every column, with dates and timestamps; lists joined with commas | |2727 | Lotus 1-2-3 `.wk1`, `.wks` | Numbers, labels with their alignment, formats, column widths, formulas translated (references, operators, `@SUM`, `@AVG`, `@IF`, `@ROUND`, `@PMT` and 60 more) or kept as values | |2828 | JSON `.json`, `.ndjson`, `.jsonl` | A list of records (or records one after another, as NDJSON): keys become the header row, numbers, booleans and text keep their types, nested lists and records are their text | The sheet shown as a list of records named by its first row, numbers as numbers |29-| Nushell `.nuon` | A nushell table with its types: file sizes, durations and dates become numbers in the Size, Duration and Date time formats; see [Nushell](../terminal/nushell.md#types) | The sheet shown as a nushell table, first row as column names, types kept by the cells' formats |29+| Nushell `.nuon` | A nushell table with its types: file sizes, durations and dates become numbers in the Size, Duration and Date time formats; see [Nushell types](../nushell/types.md) | The sheet shown as a nushell table, first row as column names, types kept by the cells' formats |3030 3131 CSV, TSV, JSON and NUON downloads hold the rows a filter shows, as3232 Sheets copies a filtered range; XLSX keeps every row, the hidden ones@@ -36,7 +36,7 @@ Formats other than XLSX import as one sheet named after the file (or the
3636 SQLite table). A file can also be followed instead, its table in a3737 linked region that takes in new rows as the file grows or is rewritten:3838 see [Following files](following.md). A table can also come in on standard input, and go back39-out on standard output: see [Nushell and pipelines](../terminal/nushell.md).39+out on standard output: see [Pipelines](../nushell/pipelines.md).4040 4141 File > Import asks where the data goes, as Sheets' Import location does4242 (a new, empty spreadsheet is simply replaced):@@ -49,12 +49,11 @@ file's rows, typed as an import types them. The region is the file's:
4949 the file again there; deleting its first cell's row or column unlinks5050 it.5151 52-A linked file is a region, as a [notebook's](../terminal/nushell.md#notebooks)52+A linked file is a region, as a [notebook's](../nushell/notebooks.md)5353 shell regions are, named after the file (`app` for `app.csv`, `app_2`54-for a second link to it): formulas read its table, header row included,55-as `nu.app` (`=SUM(nu.app)`, on any sheet), and shell commands read it as56-`$app`. Refreshing a shell region that reads it runs its command on the57-rows the file has now; the linked file itself has no command to run.54+for a second link to it): formulas on any sheet read its table as55+`nu.app`, and nushell pipelines as `$app`56+([Linked files](../nushell/notebooks.md#linked-files)).5857 5958 The sheet's tab carries a mark, and the context line says what the6059 region under the pointer is doing:@@ -89,8 +89,8 @@ save), so they raise no version:
8989 | `arithmetic` | the workbook | `decimal` for [decimal arithmetic](../formulas/decimal.md) |9090 | `locale` | the workbook | The [locale](../sheets/locale.md) it's typed and shown in (`"de-DE"`), when File > Settings > Locale chose one; without it, the file follows the reader's `locale` setting. Cells are stored the same way in every locale: `input` is always as typed in en-US (`1,234.5`, `9/26/2026`, `=ROUND(A1,2)`) |9191 | `macros`, `macroOrigin` | the workbook | Macros as Starlark scripts, and the computer they were made or trusted on (macros', shell regions' and [linked files'](following.md#files-from-elsewhere) alike): see [Macro scripting API](../reference/macro-api.md#in-the-file). Opening a file never runs them |92-| `notebook`, `regions` | a sheet | A [notebook sheet](../terminal/nushell.md#notebooks), and its shell regions and [linked files](following.md): see [Regions](#regions). Older builds open the sheet without them |93-| `shellHistory` | the workbook | The lines typed at its [notebook prompt](../terminal/nushell.md#the-prompt), oldest first, for Up and Down |92+| `notebook`, `regions` | a sheet | A [notebook sheet](../nushell/notebooks.md), and its shell regions and [linked files](following.md): see [Regions](#regions). Older builds open the sheet without them |93+| `shellHistory` | the workbook | The lines typed at its [notebook prompt](../nushell/notebooks.md#the-prompt), oldest first, for Up and Down |9494 9595 ## Column and row formats9696 @@ -163,7 +163,7 @@ with its data.
163163 164164 ## Regions165165 166-A sheet's regions, a [notebook's](../terminal/nushell.md#notebooks)166+A sheet's regions, a [notebook's](../nushell/notebooks.md)167167 shell regions and [linked files](following.md), are a `regions` list168168 after its cells, charts and rules, one per line, in the order they were169169 made; a notebook sheet also has `"notebook": true`. The file keeps what@@ -16,14 +16,15 @@ go install github.com/FelineStateMachine/012/cmd/012@latest
1616 012 # a new sheet1717 012 budget.012 # open a sheet, or create it when it doesn't exist1818 012 sales.xlsx # import .xlsx, .csv, .tsv, .json, .nuon, .sqlite, .parquet or Lotus .wk119-ls | to nuon | 012 - # a table from standard input19+012 - < sales.csv # a table from standard input2020 012 serve ~/sheets # serve a directory over SSH, a 012 per session2121 ```2222 2323 A file on the command line opens as File > Open would: a `.012` sheet, or2424 another format imported ([files](../files/README.md)). `012 -` and2525 `012 --pipe`, 012 as a stage in a pipeline, are in26-[Nushell and pipelines](../terminal/nushell.md). `012 serve` is26+[Pipelines](../nushell/pipelines.md), and `012 nu`, a nushell notebook,27+in [Notebooks](../nushell/notebooks.md). `012 serve` is2728 described in [Serving over SSH](../terminal/ssh.md).2829 2930 `012 config` prints the settings in effect and `012 config edit` opens theBinary file.
Binary file.
Binary file.
Binary file.
@@ -0,0 +1,69 @@
1+---2+title: "Nushell"3+sidebar_position: 14+---5+6+# Nushell7+8+[Nushell](https://www.nushell.sh/book/) is a shell whose pipelines carry9+tables: `ls`, `ps`, `open data.csv` and `http get` all hand the next10+command rows and columns, with file sizes, durations and dates as values11+of their own type. 012 is a spreadsheet for those tables. A table can go12+through 012 in the middle of a pipeline, and nushell can run inside 012,13+each pipeline's table a live part of the sheet.14+15+16+17+## Three ways to use them together18+19+| Way | Looks like | For |20+|---|---|---|21+| [A stage in a pipeline](pipelines.md) | `ls \| to nuon \| ^012 --pipe \| from nuon` | Looking at a table on the terminal, editing it, and sending it on to the next command |22+| [A notebook](notebooks.md) | `012 nu`, then `sizes = ls \| select name size` at the `nu❯` prompt | Pipelines you keep: each one's table is a named region of the sheet that formulas, charts and other pipelines read, run again when you ask |23+| [A followed file](../files/following.md) | Data > Linked file, then `$app \| where status >= 500` | A log or export that keeps growing: its rows come in as they're written, and pipelines read the rows it has now |24+25+The first needs nothing but nushell. The other two run `nu` from inside26+012, so it has to be installed ([Installing27+nushell](https://www.nushell.sh/book/installation.html)); without it the28+prompt says so, and the rest of 012 works as before.29+30+## A 30-second tour31+32+```nu33+# A table in, edited, and out again, with its types34+ls | select name size | to nuon | ^012 --pipe | from nuon | where size > 1kb35+36+# A notebook: each pipeline's table lands in the grid37+^012 nu work.01238+```39+40+At the notebook's `nu❯` prompt:41+42+```nu43+sales = open sales.csv | update Revenue { str replace -ar '[$,]' '' | into float }44+$sales | group-by Region --to-table | update items { get Revenue | math sum }45+```46+47+The second region reads the first as `$sales`; typing a new command for48+`sales` runs it and then the region that reads it. In a formula on any49+sheet, `=SUM(nu.sales)` reads the same table.50+51+In nushell, a word that starts with a digit is a number, so 012 is run52+as `^012`, the caret nushell uses to call an external command by name53+([Running external commands](https://www.nushell.sh/book/running_externals.html)).54+Other shells run it as `012`.55+56+## Pages57+58+| Page | For |59+|---|---|60+| [Pipelines](pipelines.md) | `012 -` and `012 --pipe`: tables in on standard input and out on standard output, sending back, the exit status |61+| [Notebooks](notebooks.md) | `012 nu` and the `nu❯` prompt: regions, `$r1` and `$in`, `nu.r1` in formulas, refreshing, saving and trust |62+| [Types](types.md) | How each nushell type becomes a cell and goes back, and what doesn't survive the trip |63+| [Cookbook](cookbook.md) | Worked examples: disk usage, a log followed live, a CSV cleaned and summarized, an API, processes, git history |64+65+Nushell's own [book](https://www.nushell.sh/book/) explains66+[pipelines](https://www.nushell.sh/book/pipelines.html),67+[tables](https://www.nushell.sh/book/working_with_tables.html) and68+[types](https://www.nushell.sh/book/types_of_data.html); the pages here69+link to the parts they build on.@@ -0,0 +1,117 @@
1+---2+title: "Cookbook"3+sidebar_position: 54+---5+6+# Cookbook7+8+Short worked examples. Pipelines that end in `^012` run in a nushell9+session; lines of the form `name = pipeline` are typed at a10+[notebook's](notebooks.md) `nu❯` prompt (`012 nu`, or `!` in any workbook). Nushell's own11+[cookbook](https://www.nushell.sh/cookbook/) has more pipelines to start12+from.13+14+## A CSV cleaned, then summarized15+16+Money written as text (`"$2,252.50"`) becomes numbers in nushell, and a17+second region totals it by region, with a chart that follows it.18+19+20+21+```nu22+sales = open sales.csv | update Revenue { str replace -ar '[$,]' '' | into float }23+totals = $sales | group-by Region --to-table | update items { get Revenue | math sum } | rename Region Revenue24+```25+26+To chart it, select the totals table, its header row and rows, and27+**Insert > Chart**. Change `sales`'s command (F2 on its label) to read28+another file, and `totals` runs again after it and the chart redraws.29+30+To pivot rather than total, select the `sales` table and31+**Data > Pivot table** ([Pivot tables](../sheets/pivots.md)): Region in32+rows, Quarter in columns, Revenue in values.33+34+Nushell:35+[`update`](https://www.nushell.sh/commands/docs/update.html),36+[`str replace`](https://www.nushell.sh/commands/docs/str_replace.html),37+[`into float`](https://www.nushell.sh/commands/docs/into_float.html),38+[`group-by`](https://www.nushell.sh/commands/docs/group-by.html),39+[`math sum`](https://www.nushell.sh/commands/docs/math_sum.html).40+41+## A log file followed live42+43+A JSON lines log (`app.jsonl`) linked with **Data > Linked file > Link a44+table** takes in rows as they're written ([Following45+files](../files/following.md)). A region reads it as `$app`:46+47+48+49+```nu50+errors = $app | where status >= 500 | select time path status ms51+by_path = $errors | group-by path --to-table | update items { length } | rename path errors52+```53+54+The linked region grows by itself; Enter on `errors`'s label reads the55+rows the log has now, and `by_path` follows. A log in CSV or TSV works56+the same; a plain text log needs a line of nushell to become a table,57+such as [`parse`](https://www.nushell.sh/commands/docs/parse.html) in a58+region's command:59+60+```nu61+lines = open --raw app.log | lines | parse "{time} {level} {message}"62+```63+64+## Disk usage with a chart65+66+```nu67+usage = du * | select path physical | update path { path basename } | sort-by physical --reverse68+```69+70+Sizes arrive in the Size format ([Types](types.md)), so a chart's axis71+and `=SUM(nu.usage)` read them as bytes. Select the table and72+**Insert > Chart** for a column chart; Enter on the label runs `du`73+again.74+75+Nushell: [`du`](https://www.nushell.sh/commands/docs/du.html).76+77+## An API response as a table78+79+```nu80+http get https://api.github.com/repos/nushell/nushell/issues | select number title user.login comments created_at | update created_at { into datetime } | to nuon | ^012 -81+```82+83+Sort by comments, filter by author, or make a pivot table of issues by84+author, in the sheet. In a notebook, the same pipeline without85+`| to nuon | ^012 -` is a region that fetches the list again when86+refreshed; `nu-timeout` stops a request that hangs.87+88+Nushell: [`http get`](https://www.nushell.sh/commands/docs/http_get.html),89+[`into datetime`](https://www.nushell.sh/commands/docs/into_datetime.html),90+and the cookbook's [HTTP](https://www.nushell.sh/cookbook/http.html)91+page.92+93+## Processes, sorted, filtered and sent back94+95+```nu96+ps | where cpu > 1 | sort-by cpu --reverse | select pid name cpu mem | to nuon | ^012 --pipe | from nuon | get pid | each {|pid| kill $pid }97+```98+99+In 012, sort the list and filter it down to the processes to stop100+(**Data > Create a filter**); Ctrl+Q, Enter sends the rows the filter101+shows, and nushell stops those and no others. D sends nothing, and the102+pipeline stops there ([The exit status](pipelines.md#the-exit-status)).103+104+Nushell: [`ps`](https://www.nushell.sh/commands/docs/ps.html),105+[`kill`](https://www.nushell.sh/commands/docs/kill.html).106+107+## Git history as a sheet108+109+```nu110+commits = git log --pretty=%h»¦«%an»¦«%s»¦«%aI -n 500 | lines | split column "»¦«" commit author subject date | update date { into datetime }111+authors = $commits | group-by author --to-table | update items { length } | rename author commits | sort-by commits --reverse112+```113+114+`date` is a datetime, so a filter by date or a pivot table by month115+works on it in the sheet. The pattern is the one nushell's cookbook116+explains in [Parsing git117+log](https://www.nushell.sh/cookbook/parsing_git_log.html).@@ -0,0 +1,177 @@
1+---2+title: "Notebooks"3+sidebar_position: 34+---5+6+# Notebooks7+8+A notebook is a sheet where you type nushell pipelines and each one's9+table lands in the grid, named, typed and kept live. Written like a10+REPL, kept like a spreadsheet.11+12+```nu13+sales = open sales.csv | where Region in [North South] | select Region Quarter Units14+$sales | where Units > 250 | sort-by Units --reverse15+```16+17+18+19+`012 nu` opens one, at its prompt:20+21+```sh22+012 nu # a new notebook23+012 nu work.012 # open one, or make it24+```25+26+In any workbook, `!` (or **Data > Shell**, or the palette) opens the27+same prompt, writing into the workbook's notebook sheet, or a new one28+named Shell 1 at the first command. Commands run `nu` as a separate29+process, so [nushell](https://www.nushell.sh/book/installation.html)30+must be installed; without it, the prompt says so and the rest of 01231+works as before.32+33+## The prompt34+35+The formula bar becomes `nu❯`, and the mode indicator says `NU`:36+37+| Key | Does |38+|---|---|39+| Enter | Run the line; the prompt stays open for the next |40+| Tab, Shift+Tab | Complete the word at the caret: a region (`$r1`) or one of nu's commands, from the box under the context line; again for the next |41+| Up, Down | The workbook's earlier lines, those starting with what's typed; the last 100 are saved with the file |42+| Esc | Stop the command running; otherwise, back to the grid |43+44+A name and `=` before the pipeline name the region; without one it's45+`r1`, `r2` and so on:46+47+```nu48+sizes = ls | select name size49+```50+51+A name is letters, digits and `_`, not starting with a digit, as a52+nushell [variable's](https://www.nushell.sh/book/variables.html) is;53+`in`, `env`, `nu` and `it` are nushell's own. Typing a name that exists54+gives that region a new command and runs it again, as does F2 on its55+label.56+57+## Regions58+59+Each command's table is a region: a label line with its name and60+command, dimmed and underlined as wide as the table, then the table,61+its first row the column names. Regions stack down the sheet in the62+order they ran, a row between them; when a table grows or shrinks, the63+rows below it move, as if you'd inserted or deleted rows.64+65+A region is still cells of the grid. Its values are66+[typed](types.md) (file sizes in the Size format, durations, dates),67+formulas read them, and you can format them, filter them68+(**Data > Create a filter**), sort them (the sort is kept, so the table69+stays sorted when it runs again) and chart them. Like an70+[array's spill](../formulas/arrays.md#spilled-cells), they can't be71+typed over: change the command, or freeze the region. Copies paste72+values; downloads and XLSX hold the values; undo takes back a run (the73+table it replaced comes back) or the region itself.74+75+The context line says what's under the pointer: on a label, the keys76+that refresh and edit it, and why it failed if it did; on its table,77+which region the cell is part of. A label's end says what it's doing:78+`Running…`, `waiting` for a region it reads, `failed`, `stopped`,79+`not run`, or `no rows`.80+81+**Data > Shell regions** acts on the region under the pointer:82+83+| Command | Key | Does |84+|---|---|---|85+| Refresh region | Enter on its label | Runs its command again, then every region that reads it |86+| Run all regions | F9 | Runs every region, each after the regions it reads |87+| Edit region's command | F2 on its label | Opens its command at the prompt, to change it and run it again |88+| Freeze region | | Turns its table into plain values you can edit, and stops running its command |89+| Delete region | | Removes the region, its command and its table |90+| Stop shell command | Esc | Stops the command running, and those waiting after it |91+92+## Tables between regions93+94+`$r1` in a command is region r1's table, and `$in` is the range95+selected when the prompt was opened, on a sheet that isn't the notebook,96+read again each time the region runs:97+98+```nu99+big = $r1 | where size > 1kb | sort-by size --reverse100+$in | group-by region --to-table101+```102+103+Both reach nu as NUON in a file it reads, never as text spliced into104+the command: `$r1` is a nushell variable holding a table, and `$in` is105+the pipeline's input, as nushell's own106+[`$in`](https://www.nushell.sh/book/pipelines.html#pipeline-input-and-the-special-in-variable)107+is.108+109+A region reading another depends on it. Refreshing a region runs it110+again and then every region that reads it, directly or through others,111+each after what it reads; a region it reads that hasn't run yet runs112+first. A command reading itself, directly or through others, is113+refused.114+115+### Linked files116+117+A [linked file](../files/following.md) is a region too, named after the118+file ([The region](../files/following.md#the-region)), so commands read119+`app.csv` as `$app`. A region reading it doesn't run as rows120+arrive: refreshing it runs its command on the rows the file has now.121+The linked file itself has no command to run.122+123+```nu124+errors = $app | where status >= 500 | select time path status ms125+```126+127+[A log file followed live](cookbook.md#a-log-file-followed-live) shows128+it working.129+130+### In formulas131+132+Other sheets read a region by name with `nu.` in front, as a named range133+of its table, header included: `=SUM(nu.big)`, `=VLOOKUP("go.mod",134+nu.r1, 3, FALSE)`, `=COUNTIF(nu.app, 503)`. Formulas follow the table as135+it grows, shrinks or moves, and show `#REF!` while it has none.136+137+## Running138+139+Commands run in the background, one at a time: the screen stays live,140+and Esc stops the one running and those waiting after it. Each runs as141+`nu --no-config-file -c`, so your aliases and custom commands aren't142+there unless `nu-config` is on143+([nushell's configuration](https://www.nushell.sh/book/configuration.html)).144+A command stops after `nu-timeout` (30 seconds unless set), and keeps at145+most `max-cells` cells, whole rows, saying how many it left out.146+147+What a command prints is read as a table: a record is one row, a list148+of values that aren't records one column named `value`, and a single149+value that column with one row. When a command fails, its label says150+so and the context line gives nushell's message.151+152+## Saving and trust153+154+The file keeps each region's command, name, place and what it reads,155+not its table ([format](../files/format.md#regions)), and the lines156+typed at the prompt. Opening a notebook never runs anything: its157+regions say `not run`, and F9 runs them all, each after what it reads.158+159+Like [macros](../sheets/macros.md#macros-from-other-computers), a160+file's commands run as you, with your files, so a notebook saved on161+another computer asks once before they run:162+163+```164+Run this file's shell commands? Enter Run Esc Cancel165+```166+167+What you type at the prompt runs without asking. The options, in168+[Configuration](../reference/config.md#nushell-notebooks):169+170+| Option | Default | Does |171+|---|---|---|172+| `shell` | `ask` | `ask` as above; `on` never asks; `off` runs nothing |173+| `nu-timeout` | `30s` | Stops a command that runs longer; `0` lets it run until Esc |174+| `nu-config` | `false` | Runs commands with your `config.nu` and `env.nu` |175+176+[012 serve](../terminal/ssh.md#notebooks) shows notebooks but runs no177+commands unless the server's `serve-shell` is on.@@ -0,0 +1,139 @@
1+---2+title: "Pipelines"3+sidebar_position: 24+---5+6+# Pipelines7+8+012 can be a stage in a pipeline: a table comes in on standard input,9+you look at it or edit it in the terminal, and with `--pipe` the result10+goes out on standard output for the next command.11+12+```nu13+ls | select name size | to nuon | ^012 --pipe | from nuon | where size > 1kb14+```15+16+17+18+[`to nuon`](https://www.nushell.sh/commands/docs/to_nuon.html) writes19+the table in NUON, nushell's own notation, so file sizes, durations and20+dates arrive as themselves, and21+[`from nuon`](https://www.nushell.sh/commands/docs/from_nuon.html) reads22+what 012 sends back with the same types ([Types](types.md)). In23+nushell, 012 is called as `^012`, since a word starting with a digit is24+a number there.25+26+The screen is the terminal's own (`/dev/tty`, or the console on27+Windows), not standard input or output, so the pipeline's data never28+mixes with what 012 draws, and nothing but the table reaches standard29+output.30+31+| Command | Reads | Writes |32+|---|---|---|33+| `012 -` | A table from standard input, into a new sheet | Nothing; the table stays in 012 until you save or download it |34+| `012 --pipe` | A table from standard input, or a file named after it | The sheet or the selection, to standard output, when you quit |35+36+## Reading a table: `012 -`37+38+`012 -` reads a table from standard input into a new sheet named39+`stdin`, and tells its format from the text:40+41+| Text starts with | Read as |42+|---|---|43+| `[` or `{`, and is all JSON | JSON: a list of records, a record, or records one after another (NDJSON) |44+| `[` or `{` otherwise | NUON: a table (`[[name, size]; [a, 1kb]]`), a list of records, a record |45+| anything else | delimited text: TSV when tabs separate the fields, otherwise CSV, as [imports](../files/README.md#import-and-download) read them |46+47+The first row holds the column names; a record that brings a new key48+adds a column. The sheet has no file and counts as unsaved, so quitting49+asks first, as with any unsaved sheet. `max-cells` applies as it does to50+imports: whole rows while they fit, and the context line says how many51+were left out. While a long input is still coming in, the status line52+counts its rows and Esc stops reading.53+54+## Sending it on: `012 --pipe`55+56+`012 --pipe` reads standard input as `012 -` does (or a file named on57+the command line, `012 --pipe sales.csv`), and quitting sends a table to58+standard output:59+60+- The status line says what Ctrl+Q sends and in which format61+ (`Ctrl+Q send the sheet as NUON`, or `send B2:D9 as NUON` while a62+ range is selected).63+- Quit (Ctrl+Q, File > Quit, `:q`) asks: Enter sends the selection when64+ one is made, or else the sheet; S sends the whole sheet instead; D65+ quits without sending; Esc goes back to the sheet.66+- File > Quit and send selection and File > Quit and send sheet send67+ without asking. They're in the menus and the palette only with68+ `--pipe`.69+70+The sheet is its used range from A1. A selection is sent as selected,71+and its first row names the columns. Either way, rows a filter hides72+stay behind, as Sheets copies a filtered range.73+74+The table goes out in the format it came in (NUON, JSON, CSV or TSV);75+from a file of another kind, such as `.xlsx` or `.012`, as NUON.76+`--to nuon`, `--to json`, `--to csv` or `--to tsv` picks the format77+instead:78+79+```nu80+open budget.xlsx | to nuon | ^012 --pipe --to csv | save budget.csv81+```82+83+## The exit status84+85+Quitting without sending (D at the question) writes nothing and exits86+with status 1, so the pipeline stops rather than carrying on with87+nothing. Nushell treats that88+as a failed external command and stops the pipeline with an error89+([Failing external commands](https://www.nushell.sh/book/pipelines.html#failing-external-commands-in-a-pipeline));90+[`try`](https://www.nushell.sh/commands/docs/try.html) catches it:91+92+```nu93+try { ls | to nuon | ^012 --pipe | from nuon | save -f picked.nuon } catch { print "nothing sent" }94+```95+96+## Recipes97+98+Each of these reads a table into 012; add `--pipe` and `| from nuon`99+to carry on with what you send back.100+101+```nu102+# Files, largest first: sizes in the Size format, dates as dates103+ls | sort-by size --reverse | to nuon | ^012 -104+105+# Processes: CPU as numbers, memory as file sizes106+ps | select pid name cpu mem | to nuon | ^012 -107+108+# Every CSV here, one table, with the file each row came from109+glob *.csv | each {|f| open $f | insert file ($f | path basename) } | flatten | to nuon | ^012 -110+111+# An API's JSON, its dates made datetimes on the way112+http get https://api.github.com/repos/nushell/nushell/releases | select name published_at | update published_at { into datetime } | to nuon | ^012 -113+114+# This computer: sys host is a record, which comes in as one row115+sys host | to nuon | ^012 -116+sys disks | select mount total free | to nuon | ^012 -117+```118+119+The commands are nushell's:120+[`ls`](https://www.nushell.sh/commands/docs/ls.html),121+[`ps`](https://www.nushell.sh/commands/docs/ps.html),122+[`open`](https://www.nushell.sh/commands/docs/open.html),123+[`http get`](https://www.nushell.sh/commands/docs/http_get.html),124+[`sys host`](https://www.nushell.sh/commands/docs/sys_host.html).125+The [Cookbook](cookbook.md) has longer examples.126+127+## Other shells128+129+Any command that writes CSV, TSV or JSON can feed 012, and the exit130+status works as usual:131+132+```sh133+ps -eo pid,comm,%cpu | awk '{$1=$1}1' OFS='\t' | 012 --pipe | sort -t$'\t' -k3 -rn134+curl -s https://api.example.com/items | 012 --pipe --to csv > items.csv135+sqlite3 -csv -header app.db 'select * from users' | 012 --pipe > users.csv || echo "not sent"136+```137+138+`.nuon` and `.json` files also open, import and download like any other139+[file](../files/README.md).@@ -0,0 +1,68 @@
1+---2+title: "Types"3+sidebar_position: 44+---5+6+# Types7+8+Each [nushell type](https://www.nushell.sh/book/types_of_data.html)9+becomes a cell of a kind a spreadsheet can work with, and goes back to10+the same type. A file size is a number of bytes in the Size format, so11+`=SUM` adds it and `where size > 1kb` still compares it once it's back12+in nushell:13+14+```nu15+ls | select name size | to nuon | ^012 --pipe | from nuon | describe16+# table<name: string, size: filesize>17+```18+19+This holds wherever NUON carries a table: [pipelines](pipelines.md),20+[notebook regions](notebooks.md), `.nuon` files opened, imported or21+downloaded, and linked `.nuon` files.22+23+| Nushell | Cell | Sent back as |24+|---|---|---|25+| [int, float](https://www.nushell.sh/book/types_of_data.html#integers) | A number | An int when whole, a float otherwise |26+| [string](https://www.nushell.sh/book/types_of_data.html#text-strings) | Text, kept as text even when it looks like a number (`"12"`) | A string |27+| [bool](https://www.nushell.sh/book/types_of_data.html#booleans) | TRUE or FALSE | A bool |28+| [null](https://www.nushell.sh/book/types_of_data.html#nothing-null) | A blank cell | null |29+| [filesize](https://www.nushell.sh/book/types_of_data.html#file-sizes) (`1646b`) | The number of bytes, in the [Size format](../sheets/formatting.md#number-formats): `1.6 kB` | A filesize, from any number in the Size format |30+| [duration](https://www.nushell.sh/book/types_of_data.html#durations) (`90sec`) | Elapsed time, in the Duration format: `0:01:30`, with milliseconds (`0:00:01.500`) when there are fractions of a second | A duration, from any number in the Duration format |31+| [datetime](https://www.nushell.sh/book/types_of_data.html#dates) | A date and time in the local time zone, in the Date time format | A datetime with the local offset, to the microsecond, from any number in a date or date-time format; a time of day alone is a duration since midnight |32+| [list](https://www.nushell.sh/book/types_of_data.html#lists), [record](https://www.nushell.sh/book/types_of_data.html#records) | Their NUON text: `[a, b]`, `{k: 1}` | The list or record again, when the text is still exactly NUON |33+| [binary](https://www.nushell.sh/book/types_of_data.html#binary-data) | Its NUON text, `0x[DEAD]` | Binary again, as lists and records |34+35+Since the types are the cells' formats, formatting a column in 01236+decides what goes back: numbers given the Size format go back as file37+sizes, and a date column formatted as plain numbers goes back as38+numbers.39+40+## Tables, records and single values41+42+A value that isn't in a table comes in as a table too: a43+[record](https://www.nushell.sh/book/types_of_data.html#records) is one44+row (`sys host`), and a list of values that aren't records is one45+column named `value`. Errors in cells go out as their text46+(`"#DIV/0!"`).47+48+## JSON49+50+JSON has fewer types, so a table sent as JSON (`--to json`, or a table51+that came in as JSON) carries numbers, booleans, text and null as52+themselves, file sizes as bytes, durations as nanoseconds and dates as53+RFC 3339 text, as nushell's54+[`to json`](https://www.nushell.sh/commands/docs/to_json.html) does.55+Use NUON to keep the types.56+57+## What doesn't survive the trip58+59+- An empty string comes back as null: both are a blank cell.60+- A whole float such as `2.0` comes back as the int `2`.61+- Text with line breaks comes back on one line.62+- Dates past the microsecond lose the rest: a cell's date is a count of63+ days, which holds about that much.64+- Nested values are text in the sheet, so formulas see their text, not65+ their contents. Flatten them in nushell first66+ ([`flatten`](https://www.nushell.sh/commands/docs/flatten.html),67+ [`select`](https://www.nushell.sh/commands/docs/select.html) with a68+ cell path) to work with them as columns.@@ -168,7 +168,7 @@ The most cells an import keeps, and a paste or fill writes at once. Numbers and
168168 169169 #### `shell`170170 171-Whether notebook sheets run nushell commands (docs/terminal/nushell.md). `ask` runs what you type and asks once before running the commands of a file made on another computer; `on` never asks; `off` runs none. Opening a file never runs its commands.171+Whether notebook sheets run nushell commands (docs/nushell/notebooks.md). `ask` runs what you type and asks once before running the commands of a file made on another computer; `on` never asks; `off` runs none. Opening a file never runs its commands.172172 173173 | | |174174 |---|---|@@ -130,7 +130,7 @@ range, F2 renames or repoints it and Ctrl+D deletes it.
130130 131131 | Key | Action |132132 |---|---|133-| ! | Open the nushell prompt on the formula bar (the mode indicator says NU); in any workbook, it writes to the notebook sheet ([Nushell notebooks](../terminal/nushell.md#notebooks)) |133+| ! | Open the nushell prompt on the formula bar (the mode indicator says NU); in any workbook, it writes to the notebook sheet ([Notebooks](../nushell/notebooks.md)) |134134 | Enter, Tab, Up, Down, Esc | At the prompt: run the line; complete a region or command; the workbook's earlier lines; stop a command running, or else go back to the grid |135135 | Enter, F2 | On a region's label line: run it again (and what reads it); edit its command at the prompt |136136 | F9 | Run all regions, each after those it reads |@@ -38,7 +38,7 @@ Format > Increase decimal places and Format > Decrease decimal places
3838 show one more or one less.3939 4040 Size isn't one of Sheets' formats; it's what a41-[nushell](../terminal/nushell.md) table's sizes come in as. It shows41+[nushell](../nushell/types.md) table's sizes come in as. It shows4242 whole bytes below 1000 (`512 B`), and above that the number in the4343 largest unit that keeps it under 1000 once rounded, units a thousand4444 apart: kB, MB, GB, TB, PB and EB, with one decimal place until you@@ -7,13 +7,13 @@ sidebar_position: 1
77 88 012 uses what the terminal it runs in can do, and degrades quietly where99 it can't: charts as images or text, links, the clipboard, the mouse,10-colors that follow light and dark.10+colors that follow light and dark. Pipelines and nushell notebooks11+have a section of their own: [Nushell](../nushell/README.md).1112 1213 | Page | For |1314 |---|---|1415 | [Themes](themes.md) | Your terminal's colors, a built-in scheme, or your own |1516 | [Serving over SSH](ssh.md) | `012 serve`: a 012 per session, on one directory |16-| [Nushell and pipelines](nushell.md) | `012 -` and `012 --pipe`: tables in on standard input and out on standard output, with nushell's types |1717 1818 ## Terminal features 012 uses1919 @@ -1,238 +0,0 @@
1----2-title: "Nushell and pipelines"3-sidebar_position: 44----5-6-# Nushell and pipelines7-8-012 can be a stage in a pipeline: a table comes in on standard input,9-you look at it or edit it in the terminal, and with `--pipe` the result10-goes out on standard output for the next command. With11-[nushell](https://www.nushell.sh), tables travel as NUON, nushell's own12-notation, so file sizes, durations and dates arrive as themselves and13-leave as themselves.14-15-```nu16-ls | to nuon | 012 --pipe | from nuon | where size > 1kb17-```18-19-The screen is the terminal's own (`/dev/tty`, or the console on20-Windows), not standard input or output, so the pipeline's data never21-mixes with what 012 draws, and nothing but the table reaches standard22-output.23-24-The other way round, a [notebook](#notebooks) runs nushell from inside25-012: each pipeline's table becomes a live part of the sheet.26-27-## Notebooks28-29-30-31-`012 nu` opens a notebook: a sheet where you type nushell pipelines and32-each one's table lands in the grid, named, typed and kept live. Written33-like a REPL, kept like a spreadsheet.34-35-```sh36-012 nu # a new notebook37-012 nu work.012 # open one, or make it38-```39-40-In any workbook, `!` (or **Data > Shell**, or the palette) opens the41-same prompt, writing into the workbook's notebook sheet, or a new one42-named Shell 1 at the first command. Commands run `nu` as a separate43-process, so nushell must be installed; without it, the prompt says so44-and the rest of 012 works as before.45-46-### The prompt47-48-The formula bar becomes `nu❯`, and the mode indicator says `NU`:49-50-| Key | Does |51-|---|---|52-| Enter | Run the line; the prompt stays open for the next |53-| Tab, Shift+Tab | Complete the word at the caret: a region (`$r1`) or one of nu's commands, from the box under the context line; again for the next |54-| Up, Down | The workbook's earlier lines, those starting with what's typed; they're saved with the file |55-| Esc | Stop the command running; otherwise, back to the grid |56-57-A name and `=` before the pipeline name the region; without one it's58-`r1`, `r2` and so on:59-60-```nu61-sizes = ls | select name size62-```63-64-Typing a name that exists gives that region a new command and runs it65-again, as does F2 on its label.66-67-### Regions68-69-Each command's table is a region: a label line with its name and70-command, dimmed and underlined as wide as the table, then the table,71-its first row the column names. Regions stack down the sheet in the72-order they ran, a row between them; when a table grows or shrinks, the73-rows below it move, as if you'd inserted or deleted rows.74-75-A region is still cells of the grid. Its values are76-[typed](#types) (file sizes in the Size format, durations, dates),77-formulas read them, and you can format them, filter them78-(**Data > Create a filter**), sort them (the sort is kept, so the table79-stays sorted when it runs again) and chart them. Like an80-[array's spill](../formulas/arrays.md#spilled-cells), they can't be81-typed over: change the command, or **Data > Shell regions > Freeze82-region** turns the table into plain values and stops running it. Copies83-paste values; downloads and XLSX hold the values; undo takes back a run84-(the table it replaced comes back) or the region itself.85-86-The context line says what's under the pointer: on a label, the keys87-that refresh and edit it, and why it failed if it did; on its table,88-which region the cell is part of. A label's end says what it's doing:89-`Running…`, `waiting` for a region it reads, `failed`, `stopped`,90-`not run`, or `no rows`.91-92-### Tables between regions93-94-`$r1` in a command is region r1's table, handed to nu as NUON in a file95-nu reads, never as text spliced into the command. `$in` is the range96-selected when the prompt was opened, on a sheet that isn't the97-notebook, read again each time the region runs:98-99-```nu100-big = $r1 | where size > 1kb | sort-by size --reverse101-$in | group-by region | transpose region rows102-```103-104-A [linked file](../files/following.md) is a region too, named after the105-file: `$app` reads the rows `app.csv` has now.106-107-A region reading another depends on it. Refreshing a region (Enter on108-its label, **Data > Shell regions > Refresh region**) runs it again and then every region109-that reads it, directly or through others, each after what it reads.110-F9 (**Data > Shell regions > Run all regions**) runs them all. A command111-reading itself, directly or through others, is refused.112-113-Other sheets read a region by name with `nu.` in front, as a named range114-of its table, header included: `=SUM(nu.big)`, `=VLOOKUP("go.mod",115-nu.r1, 3, FALSE)`. Formulas follow the table as it grows, shrinks or116-moves, and show `#REF!` while it has none.117-118-### Running119-120-Commands run in the background, one at a time: the screen stays live,121-and Esc stops the one running and those waiting after it. Each runs as122-`nu --no-config-file -c` (with your own config files if `nu-config` is123-on), stops after `nu-timeout` (30 seconds unless set), and keeps at124-most `max-cells` cells, whole rows, saying how many it left out. When a125-command fails, its label says so and the context line gives nushell's126-message.127-128-### Saving and trust129-130-The file keeps each region's command, name, place and what it reads,131-not its table ([format](../files/format.md#regions)). Opening a notebook132-never runs anything: its regions say `not run`, and F9 runs them all,133-each after what it reads.134-135-Like [macros](../sheets/macros.md#macros-from-other-computers), a136-file's commands run as you, with your files, so a notebook saved on137-another computer asks once before they run:138-139-```140-Run this file's shell commands? Enter Run Esc Cancel141-```142-143-What you type at the prompt runs without asking. The `shell` option144-decides: `ask` (the default) as above, `on` never asks, and `off` runs145-nothing. [012 serve](ssh.md#notebooks) runs no commands unless the146-server's `serve-shell` is on. See [Configuration](../reference/config.md#nushell-notebooks)147-for the options.148-149-## Reading standard input150-151-`012 -` reads a table from standard input into a new sheet named152-`stdin`, and tells its format from the text:153-154-| Text starts with | Read as |155-|---|---|156-| `[` or `{`, and is all JSON | JSON: a list of records, a record, or records one after another (NDJSON) |157-| `[` or `{` otherwise | NUON: a table (`[[name, size]; [a, 1kb]]`), a list of records, a record |158-| anything else | delimited text: TSV when tabs separate the fields, otherwise CSV, as [imports](../files/README.md#import-and-download) read them |159-160-The first row holds the column names; a record that brings a new key161-adds a column. The sheet has no file and counts as unsaved, so quitting162-asks first, as with any unsaved sheet. `max-cells` applies as it does to163-imports: whole rows while they fit, and the context line says how many164-were left out. While a long input is still coming in, the status line165-counts its rows and Esc stops reading.166-167-## Sending a table on168-169-`012 --pipe` reads standard input as `012 -` does (or a file named on170-the command line, `012 --pipe sales.csv`), and quitting sends a table to171-standard output:172-173-- The status line says what Ctrl+Q sends and in which format174- (`Ctrl+Q send the sheet as NUON`, or `send B2:D9 as NUON` while a175- range is selected).176-- Quit (Ctrl+Q, File > Quit, `:q`) asks: Enter sends the selection when177- one is made, or else the sheet; S sends the whole sheet instead; D178- quits without sending; Esc goes back to the sheet.179-- File > Quit and send selection and File > Quit and send sheet send180- without asking. They're in the menus and the palette only with181- `--pipe`.182-183-The sheet is its used range from A1. A selection is sent as selected,184-and its first row names the columns. Either way, rows a filter hides185-stay behind, as Sheets copies a filtered range. Quitting without sending writes nothing and exits with status186-1, so the pipeline stops rather than carrying on with nothing.187-188-The table goes out in the format it came in (NUON, JSON, CSV or TSV);189-from a file of another kind, such as `.xlsx` or `.012`, as NUON.190-`--to nuon`, `--to json`, `--to csv` or `--to tsv` picks the format191-instead:192-193-```nu194-open budget.xlsx | to nuon | 012 --pipe --to csv | save budget.csv195-```196-197-In other shells, any command that writes CSV, TSV or JSON can feed 012,198-and the exit status works as usual:199-200-```sh201-ps -eo pid,comm,%cpu | awk '{$1=$1}1' OFS='\t' | 012 --pipe | sort -t$'\t' -k3 -rn202-curl -s https://api.example.com/items | 012 --pipe --to csv > items.csv203-sqlite3 -csv -header app.db 'select * from users' | 012 --pipe > users.csv || echo "not sent"204-```205-206-`.nuon` and `.json` files also open, import and download like any other207-[file](../files/README.md).208-209-## Types210-211-Each nushell type becomes a cell of a kind a spreadsheet can work with,212-and goes back to the same type:213-214-| Nushell | Cell | Sent back as |215-|---|---|---|216-| int, float | A number | An int when whole, a float otherwise |217-| string | Text, kept as text even when it looks like a number (`"12"`) | A string |218-| bool | TRUE or FALSE | A bool |219-| null | A blank cell | null |220-| filesize (`1646b`) | The number of bytes, in the [Size format](../sheets/formatting.md#number-formats): `1.6 kB` | A filesize, from any number in the Size format |221-| duration (`90sec`) | Elapsed time, in the Duration format: `0:01:30`, with milliseconds (`0:00:01.500`) when there are fractions of a second | A duration, from any number in the Duration format |222-| datetime | A date and time in the local time zone, in the Date time format | A datetime with the local offset, to the microsecond, from any number in a date or date-time format; a time of day alone is a duration since midnight |223-| list, record | Their NUON text: `[a, b]`, `{k: 1}` | The list or record again, when the text is still exactly NUON |224-| binary | Its NUON text, `0x[DEAD]` | Binary again, as lists and records |225-226-A value that isn't in a table (a record, a list of numbers, a single227-value) comes in as a table too: a record is one row, and a list of228-values that aren't records is one column named `value`. Errors in cells229-go out as their text (`"#DIV/0!"`). JSON sends numbers, booleans, text230-and null as themselves, file sizes as bytes, durations as nanoseconds and231-dates as RFC 3339 text, as nushell's `to json` does.232-233-A few things don't survive the trip: an empty string comes back as null234-(both are a blank cell), a whole float such as `2.0` as the int `2`,235-text with line breaks on one line, and dates past the microsecond (a236-cell's date is a count of days, which holds about that much). Nested237-values are text in the sheet, so formulas see their text, not their238-contents.@@ -151,7 +151,7 @@ network or clock access in any case.
151151 152152 ## Notebooks153153 154-A session opens [notebooks](nushell.md#notebooks) and shows their154+A session opens [notebooks](../nushell/notebooks.md) and shows their155155 regions, but runs none of their commands: a command is a program on the156156 server, with the server's user and every file it can reach, well157157 beyond the served directory. `serve-shell = on` in the server's config@@ -119,7 +119,7 @@ var Options = []Option{
119119 "The grid itself is 1,048,576 rows by 16,384 columns (A to XFD) whatever this is."},120120 121121 {Name: "shell", Kind: Enum, Group: GroupShell, Default: "ask", Values: []string{"off", "ask", "on"}, Env: []string{"O12_SHELL"}, Live: true,122- Desc: "Whether notebook sheets run nushell commands (docs/terminal/nushell.md). `ask` runs what you type " +122+ Desc: "Whether notebook sheets run nushell commands (docs/nushell/notebooks.md). `ask` runs what you type " +123123 "and asks once before running the commands of a file made on another computer; `on` never asks; " +124124 "`off` runs none. Opening a file never runs its commands."},125125 {Name: "nu-timeout", Kind: Duration, Group: GroupShell, Default: "30s", Env: []string{"O12_NU_TIMEOUT"}, Live: true,@@ -15,7 +15,7 @@ import (
1515 )1616 1717 // NUON and JSON tables become cells with their types (see18-// docs/terminal/nushell.md for the mapping): the header row holds the18+// docs/nushell/types.md for the mapping): the header row holds the1919 // column names, numbers stay numbers, file sizes are bytes in the Size2020 // format, durations are elapsed time in the Duration format, dates are2121 // date-time serials in the local time zone, and nested records and@@ -46,7 +46,7 @@ type Runner interface {
4646 }4747 4848 // ErrMissing is what running a command says when nu isn't installed.49-var ErrMissing = errors.New("nu isn't installed or isn't on your PATH: see docs/terminal/nushell.md")49+var ErrMissing = errors.New("nu isn't installed or isn't on your PATH: see docs/nushell/notebooks.md")5050 5151 // Error is a command that failed: nu's message, and all it wrote to5252 // standard error.@@ -52,12 +52,28 @@ const cells: Cell[] = [
5252 },5353 {5454 addr: 'B2',55- entry: "'ls | to nuon | 012 --pipe | from nuon",56- hint: 'The terminal: themes, nushell pipelines, 012 serve over SSH',55+ entry: "'theme = light:Catppuccin Latte,dark:Catppuccin Mocha",56+ hint: 'The terminal: its features, themes, 012 serve over SSH',5757 title: 'Native to the terminal',58- body: 'Your terminal\'s own colors or any of hundreds of schemes, the mouse, hyperlinks, a stage in a nushell pipeline, and your sheets over SSH.',58+ body: 'Your terminal\'s own colors or any of hundreds of schemes, the mouse, hyperlinks, charts as images, and your sheets over SSH with 012 serve.',5959 to: '/docs/terminal/',6060 },61+ {62+ addr: 'A3',63+ entry: "'ls | to nuon | ^012 --pipe | from nuon",64+ hint: 'Nushell: pipelines, notebooks, types, a cookbook',65+ title: 'Nushell, both ways',66+ body: "A stage in a nushell pipeline with file sizes, durations and dates kept, or a notebook where each pipeline's table is a live, named region that formulas and charts read.",67+ to: '/docs/nushell/',68+ },69+ {70+ addr: 'B3',71+ entry: "'$app | where status >= 500",72+ hint: 'Following files: a linked region follows a log as it grows',73+ title: 'Files that keep growing',74+ body: 'Link a CSV, JSON lines or NUON log and its rows come in as they are written, like tail -f; formulas, charts and pipelines over it keep up.',75+ to: '/docs/files/following/',76+ },6177 ];6278 6379 const menu: {label: string; to: string}[] = [@@ -67,6 +83,7 @@ const menu: {label: string; to: string}[] = [
6783 {label: 'Sheets', to: '/docs/sheets/'},6884 {label: 'Files', to: '/docs/files/'},6985 {label: 'Terminal', to: '/docs/terminal/'},86+ {label: 'Nushell', to: '/docs/nushell/'},7087 {label: 'Reference', to: '/docs/reference/'},7188 ];7289 @@ -142,11 +159,11 @@ function Hero() {
142159 );143160 }144161 145-// The features as a sheet: column and row headers around four cells,162+// The features as a sheet: column and row headers around six cells,146163 // the one under the pointer drawn as 012 draws the active cell.147164 function Sheet({active, onPoint}: {active: string | null; onPoint: (c: Cell | null) => void}) {148165 const cols = ['A', 'B'];149- const rows = [1, 2];166+ const rows = [1, 2, 3];150167 return (151168 <section className={styles.sheet} aria-label="Features" onMouseLeave={() => onPoint(null)}>152169 <div className={styles.corner} />@@ -0,0 +1,21 @@
1+import type * as PrismNamespace from 'prismjs';2+3+// A small Prism grammar for nushell, enough for the docs' pipelines:4+// comments, strings, $variables, numbers with their units (1kb, 90sec),5+// flags, keywords and operators. Tokens take the names Prism's themes6+// already color.7+export default function nushell(Prism: typeof PrismNamespace): void {8+ Prism.languages.nu = {9+ comment: {pattern: /(^|\s)#.*/, lookbehind: true, greedy: true},10+ string: {pattern: /"(?:\\.|[^"\\\n])*"|'[^'\n]*'|`[^`\n]*`/, greedy: true},11+ variable: /\$[A-Za-z_][\w-]*(?:\.[\w-]+)*/,12+ keyword: /\b(?:let|mut|const|def|alias|if|else|for|in|while|loop|match|try|catch|return|break|continue|do|use|module|export)\b/,13+ number: /\b\d+(?:\.\d+)?(?:kib|mib|gib|kb|mb|gb|tb|b|ns|us|ms|sec|min|hr|day|wk)?\b/i,14+ boolean: /\b(?:true|false|null)\b/,15+ // --flag or -f after a space, not a minus in an expression16+ 'attr-name': {pattern: /(\s)--?[A-Za-z][\w-]*/, lookbehind: true},17+ operator: /\||==|!=|>=|<=|=~|!~|[<>=^]|\b(?:and|or|not|like)\b/,18+ punctuation: /[{}[\]();,]/,19+ };20+ Prism.languages.nushell = Prism.languages.nu;21+}@@ -0,0 +1,30 @@
1+// Docusaurus's own prism-include-languages, swizzled to add a small2+// grammar for nushell (```nu blocks), which Prism doesn't ship.3+4+import siteConfig from '@generated/docusaurus.config';5+import type * as PrismNamespace from 'prismjs';6+import type {Optional} from 'utility-types';7+import nushell from '../prism/nushell';8+9+export default function prismIncludeLanguages(PrismObject: typeof PrismNamespace): void {10+ const {11+ themeConfig: {prism},12+ } = siteConfig;13+ const {additionalLanguages} = prism as {additionalLanguages: string[]};14+15+ // Prism components enhance the Prism on the window; prism-react-renderer16+ // has its own instance, mounted there while they load, then removed.17+ const PrismBefore = globalThis.Prism;18+ globalThis.Prism = PrismObject;19+20+ additionalLanguages.forEach((lang) => {21+ // eslint-disable-next-line global-require, import/no-dynamic-require22+ require(`prismjs/components/prism-${lang}`);23+ });24+ nushell(PrismObject);25+26+ delete (globalThis as Optional<typeof globalThis, 'Prism'>).Prism;27+ if (typeof PrismBefore !== 'undefined') {28+ globalThis.Prism = PrismObject;29+ }30+}