add subshells, here-documents and redirections/pipes for control structures

- control structures can have redirections (while read l; do ...; done
  < file), which apply to all commands in them; they run in the shell
- in pipes and in the background they run in a subshell (cmd | while
  read l; do ...; done, for ...; done &, a && b &)
- ( list ) subshells; ( and ) are operators now
- here-documents <<EOF, <<-EOF, <<'EOF' and here-strings <<<word
- redirections of source apply to the commands of the file
- fix non-ASCII characters in quotes being mangled ('für')

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitignore

@@ -1,2 +1,3 @@
 gosh
 dist/
+packaging/man/gosh.1.gz

.goreleaser.yaml

@@ -12,6 +12,8 @@ before:
   hooks:
     - go mod tidy
     - go test ./...
+    # Man page with the release version, gzipped for /usr/share/man
+    - sh -c 'sed "s/@VERSION@/{{ .Version }}/" packaging/man/gosh.1 | gzip -9n > packaging/man/gosh.1.gz'
 
 builds:
   - id: gosh
@@ -50,6 +52,10 @@ archives:
       - src: README.md
         info:
           mode: 0644
+      - src: packaging/man/gosh.1.gz
+        dst: man/gosh.1.gz
+        info:
+          mode: 0644
 
 nfpms:
   - id: gosh
@@ -75,6 +81,10 @@ nfpms:
         dst: /usr/share/doc/gosh/README.md
         file_info:
           mode: 0644
+      - src: packaging/man/gosh.1.gz
+        dst: /usr/share/man/man1/gosh.1.gz
+        file_info:
+          mode: 0644
     scripts:
       postinstall: packaging/scripts/postinstall.sh
       postremove: packaging/scripts/postremove.sh

README.md

@@ -1,8 +1,8 @@
-`gosh` eine einfache Shell, geschrieben in golang.
+`gosh` eine Shell, in golang geschrieben.
 
 ```
 gosh - Go Shell
-Version: 0.2.1 (branch: main, commit: 03e791c)
+Version: 0.13.0 (branch: main, commit: f79fb0b)
 
 Built-in commands:
   cd [dir]       - Change directory (cd with no args goes to home)
@@ -11,8 +11,10 @@ Built-in commands:
   exit [code]   - Exit shell with status code (default: $?)
   quit [code]   - Quit shell with status code (default: $?)
   set VAR=val   - Set environment variable
+  set -- args   - Set the positional parameters $1, $2, ...
   export VAR=val - Export environment variable
-  source file   - Run the commands of file in this shell (also: . file)
+  unset VAR     - Remove a variable (unset -f name: a function)
+  source file [args] - Run the commands of file in this shell (also: . file)
   jobs          - List background and stopped jobs
   fg [%n]       - Continue job n (default: current job) in the foreground
   bg [%n]       - Continue stopped job n in the background
@@ -22,6 +24,12 @@ Built-in commands:
   :             - Do nothing (exit status 0)
   break [n]     - Leave the innermost (or n-th) for/while/until loop
   continue [n]  - Continue with the next iteration of a loop
+  return [n]    - Leave a function or sourced file with status n
+  local VAR[=val] - Variable that gets its old value back when the
+                  function returns
+  shift [n]     - Remove the first n positional parameters (default 1)
+  read [-r] [-p prompt] [VAR ...] - Read a line into variables (split
+                  at $IFS; the last one gets the rest; default $REPLY)
   help          - Show this help
 
 Features:
@@ -44,8 +52,14 @@ Features:
     GOSH_COLORS='user=1;33:path=36' (keys user, root, path, error; values
     are ANSI SGR codes, empty = no color); disabled with $NO_COLOR,
     TERM=dumb or when output is not a terminal
+  - Variables: name=value sets a variable (like set), name=value command
+    sets it only for that command; the value is not split or expanded as
+    a pattern
   - Environment variable expansion ($VAR, ${VAR}, ${VAR:-default});
     using an unset variable is an error, use ${VAR:-} for an empty default
+  - Positional parameters: $0, $1 ... $9, ${10}, $# (count), "$@" (one
+    word each), "$*" (one word), $$ (process ID); set by gosh script
+    args, gosh -c command name args, functions, set -- and source
   - Command substitution: $(command) is replaced by the output of command
     (run in a subshell); unquoted it is split into words, "$(command)"
     stays one word
@@ -53,9 +67,16 @@ Features:
     a || b (b only if a failed); $? is the exit status of the last command
   - Control structures: if cmd; then ...; elif cmd; then ...; else ...; fi,
     for x in words; do ...; done, while cmd; do ...; done, until ...,
-    ! cmd negates the status; they can span several lines (prompt "> ")
+    case word in pattern|pattern) ...;; esac, { cmd; cmd; } groups,
+    ( cmd; cmd ) subshells; ! cmd negates the status; they can span
+    several lines (prompt "> "), have redirections (done < file) and can
+    be used in pipes (| while read l; do ...; done) and with &
+  - Functions: name() { ...; } (or function name { ...; }); the arguments
+    are $1, $2, ...; in pipes, & and $(...) they run in a subshell
   - Pipes (a | b) and redirections: < file, > file, >> file, 2> file,
-    2>> file, 2>&1, >&2, &> file (stdout and stderr), &>> file
+    2>> file, 2>&1, >&2, &> file (stdout and stderr), &>> file,
+    <<EOF here-documents (<<-EOF strips tabs, <<'EOF' expands nothing),
+    <<<word here-strings
   - Job control: command & runs in the background, Ctrl+Z stops the
     foreground job; jobs, fg, bg and wait manage the jobs
   - Aliases replace the first word of a command in interactive shells
@@ -71,8 +92,8 @@ Features:
 ### Aufruf
 
 ```
-gosh [-l] [-i] [--norc] [--noprofile] [script]
+gosh [-l] [-i] [--norc] [--noprofile] [script [args ...]]
-gosh [-l] [--noprofile] -c command
+gosh [-l] [--noprofile] -c command [name [args ...]]
 gosh -version
 ```
 
@@ -80,7 +101,8 @@ gosh -version
 |------------------------|------------------------------------------------------------------|
 | `gosh`                 | interaktive Shell (wenn stdin ein Terminal ist)                  |
 | `gosh -c 'befehl'`     | führt den Befehl aus und beendet sich                            |
-| `gosh skript.gosh`     | führt das Skript Zeile für Zeile aus                             |
+| `gosh -c 'befehl' name a b` | wie oben, mit `$0` = `name`, `$1` = `a`, `$2` = `b`         |
+| `gosh skript.gosh a b` | führt das Skript Zeile für Zeile aus, `$1` = `a`, `$2` = `b`     |
 | `befehle \| gosh`      | liest die Befehle von stdin                                      |
 | `-i`                   | erzwingt den interaktiven Modus, auch ohne Terminal              |
 | `-l`, `--login`        | Login-Shell, liest die Profil-Dateien (siehe unten)              |
@@ -133,7 +155,7 @@ export PATH=$HOME/bin:$PATH
 
 ### Kontrollstrukturen
 
-gosh kennt `if`, `for`, `while` und `until` wie `sh`, auf einer Zeile oder über mehrere Zeilen:
+gosh kennt `if`, `for`, `while`, `until`, `case`, `{ …; }` und `( … )` wie `sh`, auf einer Zeile oder über mehrere Zeilen:
 
 ```bash
 if [ -f ~/.goshrc ]; then
@@ -150,13 +172,22 @@ done
 
 for i in {1..5}; do echo "Durchlauf $i"; done
 
-set n=3
+n=3
 while [ $n -gt 0 ]; do
   echo $n
-  set n=$(expr $n - 1)
+  n=$(expr $n - 1)
 done
 
 until ping -c1 -W1 server >/dev/null; do sleep 1; done
+
+case "$1" in
+  start|run) echo "starte" ;;
+  stop)      echo "stoppe" ;;
+  *.tar.gz)  tar xzf "$1" ;;
+  *)         echo "unbekannt: $1" ;;
+esac
+
+test -d build || { echo "kein build-Verzeichnis"; exit 1; }
 ```
 
 | Konstrukt                                   | Bedeutung                                                         |
@@ -165,17 +196,176 @@ until ping -c1 -W1 server >/dev/null; do sleep 1; done
 | `for x in wörter; do …; done`               | setzt `x` nacheinander auf jedes Wort                             |
 | `while befehl; do …; done`                  | wiederholt, solange `befehl` erfolgreich ist                      |
 | `until befehl; do …; done`                  | wiederholt, bis `befehl` erfolgreich ist                          |
+| `case wort in muster\|muster) …;; esac`     | führt den ersten Zweig aus, dessen Muster auf `wort` passt        |
+| `{ befehl; befehl; }`                       | fasst Befehle zusammen (z. B. nach `\|\|`)                         |
+| `( befehl; befehl )`                        | führt die Befehle in einer Subshell aus                           |
 | `! befehl`                                  | kehrt den Exit-Status um                                          |
 | `break [n]`, `continue [n]`                 | verlässt die (n-te) Schleife bzw. springt zum nächsten Durchlauf  |
 | `:`                                         | tut nichts, Exit-Status 0 (z. B. `while :; do …; done`)           |
 
 - Bedingungen sind normale Befehle (auch Listen mit `&&`/`||`), meist `test` bzw. `[ … ]` (z. B. `[ -f datei ]`, `[ "$a" = b ]`, `[ $n -lt 3 ]`).
-- Die Wörter nach `for … in` werden wie Argumente expandiert: `*.go`, `{1..10}`, `$VAR`, `$(befehl)`. Ohne `in` läuft die Schleife nicht (Positionsparameter gibt es nicht).
+- Die Wörter nach `for … in` werden wie Argumente expandiert: `*.go`, `{1..10}`, `$VAR`, `$(befehl)`, `"$@"`. Ohne `in` läuft die Schleife über die Positionsparameter (`for a; do …` ist `for a in "$@"; do …`).
+- `case`: Die Muster sind Wildcards wie bei Dateinamen (`*`, `?`, `[…]`), nur passen `*` und `?` hier auch auf `/`. Mehrere Muster werden mit `|` getrennt, das `(` vor dem Muster ist optional, das `;;` im letzten Zweig auch. Zeichen in Anführungszeichen passen nur wörtlich (`"*")` passt nur auf `*`). Wie überall in gosh sind Werte von Variablen keine Muster: Nach `p='*.go'` passt `$p)` nur auf den Text `*.go`. Passt kein Muster, ist der Status 0.
+- `{ …; }`: `{` und `}` sind nur am Anfang eines Befehls Schlüsselwörter, vor dem `}` muss deshalb ein `;` oder ein Zeilenumbruch stehen. Die Befehle laufen in der Shell selbst (keine Subshell).
 - Variablen, `$(...)` und Wildcards im Rumpf werden bei jedem Durchlauf neu ersetzt.
 - Ist ein Befehl noch nicht vollständig (z. B. nach `if …; then` oder `for …` + Enter, nach `&&`, `|` oder einem `\` am Zeilenende), zeigt gosh den Fortsetzungs-Prompt `> `; Ctrl+C verwirft die angefangene Eingabe. Skripte und Startdateien lesen entsprechend weiter.
 - Ctrl+C bricht die ganze Befehlszeile ab, also auch eine Schleife (`while true; do sleep 1; done`).
 - Der Exit-Status ist der des zuletzt ausgeführten Befehls; ein `if` ohne passenden Zweig und eine Schleife ohne Durchlauf haben den Status 0.
-- Nicht unterstützt: Kontrollstrukturen in Pipes (`for …; done | sort`), mit Umleitung (`done > datei`) oder im Hintergrund (`done &`), außerdem `case`, Funktionen, `read` und Zuweisungen der Form `x=1` – Variablen setzt man mit `set x=1`, Arithmetik geht z. B. mit `$(expr $n + 1)`.
+- Arithmetik geht noch nicht mit `$((…))`, sondern z. B. mit `n=$(expr $n + 1)`.
+
+### Umleitungen, Pipes und Hintergrund bei Kontrollstrukturen
+
+Kontrollstrukturen lassen sich wie einfache Befehle umleiten, in Pipes verwenden und im Hintergrund starten:
+
+```bash
+# Datei Zeile für Zeile lesen
+while read -r name rest; do
+  echo "Name: $name"
+done < /etc/passwd
+
+# Ausgabe einer Schleife sortieren bzw. umleiten
+for f in *.log; do wc -l < "$f"; done | sort -n
+if make; then echo ok; else echo kaputt; fi > build.status 2>&1
+{ date; uptime; } >> status.log
+
+# Zeilen aus einer Pipe verarbeiten
+git ls-files | while read -r f; do echo "== $f"; done
+
+# Schleife im Hintergrund
+for host in a b c; do ping -c1 $host; done > ping.log &
+```
+
+- Umleitungen nach `done`, `fi`, `esac`, `}` und `)` gelten für alle Befehle darin. Die Kontrollstruktur läuft dabei in der Shell selbst, Variablen aus `while read x; do …; done < datei` sind danach also gesetzt.
+- In einer Pipe und im Hintergrund (`&`) läuft eine Kontrollstruktur (wie in `sh`) in einer Subshell, einem eigenen gosh-Prozess, weil alle Teile einer Pipe gleichzeitig laufen. Variablen, die dort gesetzt werden, gelten danach nicht mehr: Nach `ls | while read f; do n=$f; done` ist `n` nicht gesetzt. Die Subshell kennt die Funktionen und Positionsparameter der Shell.
+- Auch Listen lassen sich in den Hintergrund schicken: `make && make install &` läuft als ein Job in einer Subshell.
+- Mit Ctrl+C wird die ganze Pipe abgebrochen, auch eine Endlosschleife wie `while true; do date; sleep 1; done | tee log`.
+
+### Subshells
+
+`( befehle )` führt Befehle in einer Subshell aus, einem eigenen gosh-Prozess. Änderungen an Verzeichnis, Variablen und Funktionen gelten nur dort:
+
+```bash
+(cd /tmp && tar xzf ~/paket.tar.gz)    # danach ist man noch im alten Verzeichnis
+(export LANG=C; sort datei)
+(exit 3); echo $?                      # 3
+(cd build && make) > build.log 2>&1
+```
+
+- `exit` beendet nur die Subshell, ihr Exit-Status ist der des letzten Befehls bzw. von `exit`.
+- Die Subshell bekommt alle Variablen (in gosh sind alle exportiert), die Funktionen und die Positionsparameter. Aliase gelten dort nicht (wie in Skripten).
+- `{ …; }` fasst dagegen Befehle zusammen, ohne eine Subshell zu starten.
+- `(` und `)` sind Operatoren: Ein Wort wie `a(b)` ist ein Syntaxfehler, Klammern als Text brauchen Anführungszeichen oder `\` (`echo "(a)"`, `find . \( -name x \)`).
+
+### Funktionen
+
+```bash
+# Definition (auch: function gruss { … })
+gruss() {
+  local name=${1:-Welt}       # local: nur in der Funktion
+  echo "Hallo $name"
+}
+
+gruss                       # Hallo Welt
+gruss Flo                   # Hallo Flo
+gruss Flo > datei           # Umleitungen gelten für alle Befehle der Funktion
+gruss Flo | tr a-z A-Z      # auch in Pipes
+x=$(gruss Flo)
+
+ist_root() {
+  [ "$(id -u)" = 0 ] && return 0
+  return 1
+}
+ist_root || echo "kein root"
+
+# Die Funktion liest von stdin
+zeilen() {
+  while read -r zeile; do echo "> $zeile"; done
+}
+zeilen < /etc/hostname
+ls | zeilen
+```
+
+- Eine Funktion wird mit `name() { …; }`, `name () { …; }` oder `function name { …; }` definiert. Der Rumpf ist ein zusammengesetzter Befehl, meist `{ …; }`, aber auch `if`, `for`, `while` oder `case` sind möglich. Die Definition darf über mehrere Zeilen gehen.
+- Die Argumente des Aufrufs sind in der Funktion `$1`, `$2`, …, `$#` und `"$@"`; danach haben die Positionsparameter wieder ihre alten Werte. `$0` bleibt der Name des Skripts.
+- `return [n]` beendet die Funktion mit dem Status `n` (ohne `n`: der Status des letzten Befehls). Ohne `return` ist der Status der des letzten Befehls.
+- Funktionen laufen in der Shell selbst: Variablen, die sie setzen, und `cd` gelten danach weiter. `local name[=wert]` macht eine Variable lokal, sie bekommt beim Verlassen der Funktion ihren alten Wert zurück (Funktionen, die von dort aufgerufen werden, sehen den lokalen Wert).
+- `name=wert funktion` setzt die Variable nur während des Aufrufs.
+- In einer Pipeline, im Hintergrund (`funktion &`) und in `$(...)` läuft eine Funktion in einer Subshell, Änderungen an Variablen gehen dort also verloren (wie in `sh`). Die Subshell kennt alle Funktionen.
+- Eine Funktion hat Vorrang vor Built-ins und Programmen gleichen Namens. Weil es noch kein `command` gibt, kann eine Funktion `ls` das Programm `ls` aber nicht aufrufen. Mit `\ls` umgeht man nur Aliase. Besser ist ein anderer Name, z. B. `ll() { ls -l "$@"; }`.
+- `unset -f name` entfernt eine Funktion. Rekursion ist erlaubt, aber nur bis zu einer Tiefe von 1000.
+- Namen dürfen aus Buchstaben, Ziffern, `_`, `-` und `.` bestehen (nicht mit einer Ziffer oder `-` beginnend). Funktionen werden auch mit Tab vervollständigt.
+
+### Positionsparameter
+
+| Parameter          | Bedeutung                                                        |
+|--------------------|------------------------------------------------------------------|
+| `$0`               | Name des Skripts (bzw. `name` bei `gosh -c befehl name`)         |
+| `$1` … `$9`, `${10}` | die Argumente                                                  |
+| `$#`               | Anzahl der Argumente                                             |
+| `"$@"`             | alle Argumente, jedes als eigenes Wort                           |
+| `"$*"`             | alle Argumente als ein Wort, durch Leerzeichen getrennt          |
+| `$$`               | Prozess-ID der Shell                                             |
+
+```bash
+#!/usr/bin/gosh
+# aufruf: skript.gosh [-v] datei ...
+if [ $# -eq 0 ]; then
+  echo "usage: $0 [-v] datei ..." >&2
+  exit 2
+fi
+verbose=no
+case $1 in
+  -v) verbose=yes; shift ;;
+esac
+for f in "$@"; do
+  test $verbose = yes && echo "verarbeite $f"
+  wc -l "$f"
+done
+```
+
+- Gesetzt werden sie von `gosh skript a b`, `gosh -c befehl name a b`, beim Aufruf einer Funktion, mit `source datei a b` (nur während die Datei läuft) und mit `set -- a b c`.
+- `shift [n]` entfernt die ersten `n` (Standard: 1) Parameter, `$2` wird zu `$1` usw.
+- Wie bei Variablen ist ein nicht gesetzter Parameter ein Fehler: `$1` ohne Argumente meldet `1: unbound variable`. Für optionale Argumente `${1:-}` bzw. `${1:-standard}` verwenden oder vorher `$#` prüfen.
+- `"$@"` ohne Argumente ergibt kein Wort (auch nicht das leere). Ohne Anführungszeichen verhalten sich `$@` und `$*` wie `"$@"`, da gosh Werte nie an Leerzeichen teilt.
+
+### read
+
+`read` liest eine Zeile von stdin und verteilt sie auf Variablen:
+
+```bash
+read -p "Name? " name                  # Eingabe vom Terminal mit Prompt
+read vorname nachname < name.txt       # erste Zeile einer Datei
+read -r zeile                          # Backslashes nicht auswerten
+while read -r zeile; do echo "$zeile"; done   # in einem Skript: alle Zeilen von stdin
+```
+
+- `read name1 name2 …` teilt die Zeile an den Zeichen von `$IFS` (Standard: Leerzeichen, Tab, Zeilenumbruch). Jede Variable bekommt ein Feld, die letzte den Rest der Zeile. Bei zu wenigen Feldern werden die übrigen Variablen leer. Leerzeichen am Anfang und Ende werden entfernt. Andere `IFS`-Zeichen trennen genau ein Feld (`IFS=:` macht aus `a::b` die Felder `a`, ``, `b`).
+- Ohne Namen landet die ganze Zeile unverändert in `$REPLY`.
+- Ohne `-r` maskiert `\` das nächste Zeichen (`a\ b` bleibt ein Feld), und ein `\` am Zeilenende setzt die Zeile fort. `-p prompt` gibt den Prompt auf stderr aus, wenn stdin ein Terminal ist.
+- Der Status ist 0, oder 1 am Ende der Eingabe (die Variablen werden trotzdem mit dem Rest gesetzt). So endet `while read …` nach der letzten Zeile.
+- `read` liest Byte für Byte und damit nie mehr als eine Zeile, den Rest bekommen die nächsten Befehle. Ctrl+C bricht `read` in der interaktiven Shell ab (Status 130).
+- `read` verändert die Shell und lässt sich deshalb nicht als einfacher Befehl in einer Pipeline verwenden (`echo a | read x`, in `sh` wirkungslos). Umleitungen funktionieren: `read x < datei`, `read x <<< "$text"`, `while read l; do …; done < datei`. In einer Schleife in einer Pipe (`… | while read l; do …; done`) geht es auch, da die ganze Schleife in einer Subshell läuft.
+
+### Variablen
+
+```bash
+name=wert                 # Variable setzen (wie set name=wert)
+a=1 b=2                   # mehrere auf einmal
+gruss="Hallo Welt"        # Leerzeichen im Wert brauchen Anführungszeichen
+heute=$(date +%F)         # Ausgabe eines Befehls
+PATH=~/bin:$PATH          # ~ wird auch nach = und : ersetzt
+LANG=C sort datei         # nur für diesen einen Befehl
+unset name                # Variable entfernen
+echo $name ${name:-standard}
+```
+
+- Eine Zuweisung ist ein Wort `name=wert` am Anfang eines Befehls, bei dem `name` und `=` ohne Anführungszeichen stehen und `name` aus Buchstaben, Ziffern und `_` besteht (nicht mit einer Ziffer beginnend). `"x=1"`, `x\=1` und `echo x=1` sind keine Zuweisungen.
+- Steht danach kein Befehl, wird die Variable in der Shell gesetzt. Wie bei `set` und `export` sind in gosh alle Variablen auch für gestartete Programme sichtbar (es gibt keine reinen Shell-Variablen).
+- Steht ein Befehl danach (`LANG=C sort datei`), gilt die Zuweisung nur für diesen Befehl, die Shell behält den alten Wert.
+- Der Wert wird nicht in Wörter geteilt und nicht als Wildcard oder `{a,b}` expandiert: `x=$(ls)` speichert die ganze Ausgabe, `x=*.go` speichert `*.go`. Variablen, `$(...)` und `~` (am Anfang, nach `=` und nach `:`) werden ersetzt.
+- `$?` ist nach einer Zuweisung der Status des letzten `$(...)` darin, sonst 0.
+- Variablen in den Argumenten werden ersetzt, bevor die Zuweisung davor gilt: `x=1 echo $x` gibt nicht `1` aus, sondern meldet `x: unbound variable` (wenn `x` vorher nicht gesetzt war).
+- In einer Pipeline (`x=1 | cat`) ändert eine Zuweisung die Shell nicht.
 
 ### Befehlsersetzung
 
@@ -190,7 +380,7 @@ $ vim $(grep -l TODO *.go)
 $ echo "Dateien: $(ls | wc -l)"
 ```
 
-- Der Befehl läuft in einer eigenen Subshell (einem neuen gosh-Prozess): `cd`, `set` oder `export` darin ändern die laufende Shell nicht. Er darf alles enthalten, was gosh kann (Pipes, `;`, `&&`, Umleitungen, verschachtelte `$(...)`), und liest von der gleichen Eingabe, Fehlermeldungen gehen auf stderr.
+- Der Befehl läuft in einer eigenen Subshell (einem neuen gosh-Prozess): `cd`, `set` oder `export` darin ändern die laufende Shell nicht. Die Subshell kennt die Funktionen und Positionsparameter der Shell. Er darf alles enthalten, was gosh kann (Pipes, `;`, `&&`, Umleitungen, verschachtelte `$(...)`), und liest von der gleichen Eingabe, Fehlermeldungen gehen auf stderr.
 - Abschließende Zeilenumbrüche der Ausgabe werden entfernt.
 - Ohne Anführungszeichen wird die Ausgabe an Leerzeichen, Tabs und Zeilenumbrüchen in mehrere Wörter geteilt, `"$(befehl)"` bleibt ein einziges Wort (mit den Zeilenumbrüchen darin).
 - Anders als in `sh` werden Wildcards in der Ausgabe nicht expandiert, und Zeichen wie `;` oder `|` darin sind normaler Text: Die Ausgabe ist immer nur Daten.
@@ -273,7 +463,7 @@ $ ls -d */            # nur Verzeichnisse
 - Versteckte Dateien (mit `.` am Anfang) werden nur gefunden, wenn das Muster selbst mit `.` beginnt: `*` findet `.bashrc` nicht, `.*rc` schon.
 - Passt keine Datei, bleibt das Wort unverändert stehen (wie in `sh`), `ls *.xyz` meldet dann also `ls` den Fehler.
 - In Anführungszeichen oder mit `\` davor sind die Zeichen normale Zeichen: `echo "*"`, `echo '*.go'`, `echo \*`.
-- Werte von Variablen werden nicht als Muster behandelt (anders als in `sh`): Nach `set P=*.go` gibt `echo $P` wörtlich `*.go` aus. So kann ein Variablenwert nie unbemerkt auf viele Dateien passen. `echo $DIR/*.go` funktioniert dagegen, weil das `*` direkt in der Zeile steht.
+- Werte von Variablen werden nicht als Muster behandelt (anders als in `sh`): Nach `P='*.go'` gibt `echo $P` wörtlich `*.go` aus. So kann ein Variablenwert nie unbemerkt auf viele Dateien passen. `echo $DIR/*.go` funktioniert dagegen, weil das `*` direkt in der Zeile steht.
 - Bei einer Umleitung muss das Muster genau eine Datei treffen (`> *.log`), sonst meldet gosh `ambiguous redirect`.
 
 ### Pipes und Umleitungen
@@ -294,13 +484,47 @@ $ grep -c error < build.log
 | `2>&1`          | stderr dorthin, wohin stdout gerade geht                   |
 | `>&2`           | stdout dorthin, wohin stderr gerade geht                   |
 | `&> datei`      | stdout und stderr in `datei` (`&>>` hängt an)              |
+| `<<EOF`         | Here-Doc: die folgenden Zeilen bis `EOF` sind stdin         |
+| `<<< wort`      | Here-String: `wort` (und ein Zeilenumbruch) ist stdin      |
 | `> datei`       | ohne Befehl: legt `datei` an bzw. leert sie                |
 
 - Umleitungen werden von links nach rechts ausgewertet: `befehl > log 2>&1` schreibt beides in `log`, `befehl 2>&1 > log` schickt stderr dorthin, wo stdout vorher hinging (z. B. in eine Pipe).
 - Unterstützt werden die Dateideskriptoren 0, 1 und 2. Vor `>` und `<` zählt nur eine Zahl ohne Anführungszeichen als Deskriptor (`2>f`, aber nicht `x2>f` oder `"2">f`).
 - Operatoren in Anführungszeichen oder mit `\` davor sind normale Zeichen: `echo "a|b" 'c>d' e\>f`.
 - Der Exit-Status einer Pipeline ist der des letzten Befehls. Beendet sich ein Befehl am Ende (z. B. `head`), bekommt der schreibende Befehl davor `SIGPIPE`, `yes | head -1` endet also sofort.
-- Die Built-ins `pwd` und `help` lassen sich umleiten und in Pipes verwenden (`help | less`). `cd`, `set`, `export`, `exit` und `quit` verändern die Shell selbst und sind in einer Pipeline nicht erlaubt.
+- Die Built-ins `pwd` und `help` lassen sich umleiten und in Pipes verwenden (`help | less`). `cd`, `set`, `export`, `exit` und `quit` verändern die Shell selbst und sind in einer Pipeline nicht erlaubt. Umleitungen von `source datei > log` gelten für alle Befehle der Datei.
+- Zu Kontrollstrukturen mit Umleitungen und in Pipes siehe oben.
+
+### Here-Docs und Here-Strings
+
+```bash
+cat <<EOF > config.ini
+[server]
+host = $HOSTNAME
+started = $(date +%F)
+EOF
+
+cat <<'EOF' > script.sh       # 'EOF': nichts wird ersetzt
+echo "$HOME bleibt wörtlich stehen"
+EOF
+
+if true; then
+	cat <<-EOF                # <<-: Tabs am Zeilenanfang werden entfernt
+	eingerückt
+	EOF
+fi
+
+grep -c x <<< "$text"         # Here-String
+read a b <<< "1 2"
+```
+
+- Nach `<<WORT` folgen ab der nächsten Zeile die Eingabezeilen, bis zu einer Zeile, die genau `WORT` ist. In der interaktiven Shell zeigt gosh dafür den Fortsetzungs-Prompt `> `.
+- Ohne Anführungszeichen am Wort werden `$VAR`, `${VAR}`, `$(…)` und `\` vor `$`, `` ` ``, `\` und dem Zeilenende ersetzt (wie in `"…"`, nur dass `"` ein normales Zeichen ist). Wildcards, `~` und `{a,b}` werden nicht ersetzt. Ist das Wort ganz oder teilweise in Anführungszeichen (`'EOF'`, `"EOF"`, `\EOF`), wird nichts ersetzt.
+- `<<-WORT` entfernt Tabs (keine Leerzeichen) am Anfang jeder Zeile und der Endzeile, damit sich Here-Docs in Skripten einrücken lassen.
+- Mehrere Here-Docs in einer Zeile (`cat <<A; cat <<B`) folgen nacheinander. Here-Docs gehen auch an Funktionen, Schleifen (`done <<EOF`) und in Pipes.
+- `<<< wort` übergibt `wort` mit einem Zeilenumbruch als Eingabe. Das Wort wird wie ein Argument expandiert (Variablen, `$(…)`), aber nicht als Wildcard.
+- Die Eingabe steht in einer temporären Datei, die sofort wieder gelöscht wird, deshalb sind auch große Here-Docs kein Problem.
+- Ein Here-Doc in einer Befehlsersetzung (`x=$(cat <<EOF … EOF)`) funktioniert, solange der Text darin keine unpaarigen Anführungszeichen wie `it's` enthält.
 
 ### Aliase
 
@@ -482,4 +706,4 @@ git push origin v0.1.0
 goreleaser release --clean
 ```
 
-Das Paket installiert `/usr/bin/gosh` und trägt die Shell in `/etc/shells` ein, sodass sie mit `chsh -s /usr/bin/gosh` gesetzt werden kann.
+Das Paket installiert `/usr/bin/gosh` und die Man-Page `gosh(1)` (`man gosh`, Quelle: `packaging/man/gosh.1`, lokal ansehen mit `man ./packaging/man/gosh.1`) und trägt die Shell in `/etc/shells` ein, sodass sie mit `chsh -s /usr/bin/gosh` gesetzt werden kann.

assign_test.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+func TestTokenize_Assignments(t *testing.T) {
+	t.Setenv("HOME", "/home/u")
+	tests := []struct {
+		input  string
+		word   string
+		assign bool
+	}{
+		{"x=1", "x=1", true},
+		{"_a1=", "_a1=", true},
+		{`x="a b"`, "x=a b", true},
+		{"x=a=b", "x=a=b", true},
+		{"P=~/bin:~/go/bin", "P=/home/u/bin:/home/u/go/bin", true},
+		{"x=a~b", "x=a~b", true},
+		{"x=~", "x=/home/u", true},
+		// Not an assignment: quoted or escaped name or =, invalid name
+		{`"x=1"`, "x=1", false},
+		{`x"=1"`, "x=1", false},
+		{`x\=1`, "x=1", false},
+		{"1x=2", "1x=2", false},
+		{"=x", "=x", false},
+		{"a-b=1", "a-b=1", false},
+	}
+	for _, tc := range tests {
+		tokens, err := tokenize(tc.input)
+		if err != nil || len(tokens) != 1 {
+			t.Errorf("tokenize(%q) = %+v, %v", tc.input, tokens, err)
+			continue
+		}
+		if tokens[0].word != tc.word || tokens[0].assign != tc.assign {
+			t.Errorf("tokenize(%q) = %q (assign %v), want %q (assign %v)",
+				tc.input, tokens[0].word, tokens[0].assign, tc.word, tc.assign)
+		}
+	}
+
+	// The output of $(...) is not split in an assignment
+	tokens, _ := tokenize("x=$(echo a b) y")
+	if len(tokens) != 2 || tokens[0].word != "x=a b" || !tokens[0].assign {
+		t.Errorf("x=$(echo a b): %+v", tokens)
+	}
+}
+
+func TestExec_Assignments(t *testing.T) {
+	for _, name := range []string{"GOSH_A", "GOSH_B", "GOSH_C"} {
+		os.Unsetenv(name)
+		defer os.Unsetenv(name)
+	}
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"GOSH_A=1; echo $GOSH_A > out", "1\n"},
+		{"GOSH_A=1 GOSH_B=2; echo $GOSH_A$GOSH_B > out", "12\n"},
+		{`GOSH_A="a  b"; echo "$GOSH_A" > out`, "a  b\n"},
+		{"GOSH_A=$(printf 'a b\\nc'); echo \"$GOSH_A\" > out", "a b\nc\n"},
+		// No wildcard or brace expansion in the value
+		{"touch x.go; GOSH_A=*.go; echo \"$GOSH_A\" > out", "*.go\n"},
+		{"GOSH_A={a,b}; echo $GOSH_A > out", "{a,b}\n"},
+		// ... but as an argument, assignment-like words are normal words
+		{"echo GOSH_A={a,b} > out", "GOSH_A=a GOSH_A=b\n"},
+		// Before a command, only in its environment
+		{"GOSH_C=temp sh -c 'echo $GOSH_C' > out; echo ${GOSH_C:-unset} >> out", "temp\nunset\n"},
+		{"GOSH_A=old; GOSH_A=new sh -c 'echo $GOSH_A' > out; echo $GOSH_A >> out", "new\nold\n"},
+		// ... and before a builtin only while it runs
+		{"GOSH_C=temp pwd > /dev/null; echo ${GOSH_C:-unset} > out", "unset\n"},
+		// In a pipeline or with a command they do not change the shell
+		{"GOSH_C=x | cat; echo ${GOSH_C:-unset} > out", "unset\n"},
+		// Redirections are applied
+		{"GOSH_A=r > out", ""},
+		// In loops
+		{"for i in 1 2 3; do GOSH_A=$i; done; echo $GOSH_A > out", "3\n"},
+		{"GOSH_B=0; while [ $GOSH_B -lt 3 ]; do echo $GOSH_B >> out; GOSH_B=$(expr $GOSH_B + 1); done", "0\n1\n2\n"},
+		// Not assignments
+		{`echo "GOSH_A=1" GOSH_B=2 > out`, "GOSH_A=1 GOSH_B=2\n"},
+		// unset
+		{"GOSH_A=1; unset GOSH_A; echo ${GOSH_A:-gone} > out", "gone\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+
+	// The status of an assignment is the one of its last $(...)
+	for input, want := range map[string]int{
+		"GOSH_A=1":                       0,
+		"GOSH_A=$(false)":                1,
+		"GOSH_A=$(sh -c 'exit 3')":       3,
+		"GOSH_A=$(false) GOSH_B=$(true)": 0,
+	} {
+		runIn(t, input)
+		if lastStatus != want {
+			t.Errorf("%q: $? = %d, want %d", input, lastStatus, want)
+		}
+	}
+
+	if err := execInput("unset 1x"); err == nil || err.Error() != "unset: `1x': not a valid identifier" {
+		t.Errorf("unset 1x: %v", err)
+	}
+	if err := execInput(`"GOSH_A=1"`); err == nil || exitStatus(err) != 127 {
+		t.Errorf(`"GOSH_A=1" must be a command: %v`, err)
+	}
+}

brace.go

@@ -22,6 +22,7 @@ func expandBraceWords(input string) (string, error) {
 	var (
 		out           strings.Builder
 		afterRedirect bool // the next word is the target of a redirection
+		commandStart  = true
 	)
 
 	for i := 0; i < len(input); {
@@ -33,6 +34,8 @@ func expandBraceWords(input string) (string, error) {
 		case strings.IndexByte(";&|<>", ch) >= 0:
 			if ch == '<' || ch == '>' {
 				afterRedirect = true
+			} else {
+				commandStart = true
 			}
 			out.WriteByte(ch)
 			i++
@@ -42,6 +45,16 @@ func expandBraceWords(input string) (string, error) {
 			return out.String(), nil
 		default:
 			end := wordEnd(input, i)
+			if commandStart && !afterRedirect && isAssignment(input[i:end]) {
+				// name=value before the command: no brace expansion, like
+				// in bash
+				out.WriteString(input[i:end])
+				i = end
+				continue
+			}
+			if !afterRedirect {
+				commandStart = false
+			}
 			words, err := expandBraces(input[i:end])
 			if err != nil {
 				return "", err
@@ -57,6 +70,12 @@ func expandBraceWords(input string) (string, error) {
 	return out.String(), nil
 }
 
+// isAssignment reports whether a word starts with name= (unquoted).
+func isAssignment(word string) bool {
+	name, _, ok := strings.Cut(word, "=")
+	return ok && isVarName(name)
+}
+
 // wordEnd returns the end of the word starting at i: the next unquoted blank
 // or operator character.
 func wordEnd(s string, i int) int {

compound_test.go

@@ -0,0 +1,274 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestExec_CompoundRedirections(t *testing.T) {
+	resetShell(t)
+	for _, name := range []string{"GOSH_A", "GOSH_N"} {
+		os.Unsetenv(name)
+		defer os.Unsetenv(name)
+	}
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"if true; then echo yes; fi > out", "yes\n"},
+		{"for x in a b; do echo $x; done > out", "a\nb\n"},
+		{"for x in a b; do echo $x; done >> out; echo c >> out", "a\nb\nc\n"},
+		{"{ echo out; echo err >&2; } > out 2>&1", "out\nerr\n"},
+		{"{ echo err >&2; } 2> out", "err\n"},
+		{"case x in x) echo case;; esac > out", "case\n"},
+		// The redirections apply to all commands, also nested ones
+		{"{ echo a; { echo b; }; } > out", "a\nb\n"},
+		{"{ echo a; echo b > other; echo c; } > out", "a\nc\n"},
+		{"f() { echo from-f; }; { f; } > out", "from-f\n"},
+		// Reading a file line by line in the shell itself
+		{"printf 'l1\\nl2 x\\n' > in; while read -r l; do echo \"<$l>\" >> out; done < in", "<l1>\n<l2 x>\n"},
+		{"printf 'a b\\nc d\\n' > in; while read x y; do echo $y$x >> out; done < in", "ba\ndc\n"},
+		{"printf '1\\n2\\n3\\n' > in; GOSH_N=0; while read l; do GOSH_N=$(expr $GOSH_N + $l); done < in; echo $GOSH_N > out", "6\n"},
+		// ... with the loop's variables changed in the shell
+		{"printf 'v\\n' > in; while read GOSH_A; do :; done < in; echo ${GOSH_A:-empty} > out", "empty\n"},
+		{"printf 'v\\n' > in; { read GOSH_A; } < in; echo $GOSH_A > out", "v\n"},
+		// Redirections are expanded
+		{"GOSH_A=out; { echo var; } > $GOSH_A", "var\n"},
+		// Files are closed and stdout is restored afterwards
+		{"{ echo a; } > out; echo b >> out", "a\nb\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+		if ioOverride != [3]*os.File{} {
+			t.Fatalf("%q: ioOverride not restored", tc.input)
+		}
+	}
+
+	for input, want := range map[string]string{
+		"{ :; } < gosh-no-such-file": "gosh-no-such-file: no such file or directory",
+		"{ :; } > {a,b}":             "{a,b}: ambiguous redirect",
+	} {
+		if err := runInErr(t, input); err == nil || err.Error() != want {
+			t.Errorf("%q: err = %v, want %q", input, err, want)
+		}
+	}
+}
+
+// runInErr runs input in a temporary directory and returns its error.
+func runInErr(t *testing.T, input string) error {
+	t.Helper()
+	origDir, _ := os.Getwd()
+	defer os.Chdir(origDir)
+	os.Chdir(t.TempDir())
+	return execInput(input)
+}
+
+func TestExec_CompoundPipelines(t *testing.T) {
+	resetShell(t)
+	os.Unsetenv("GOSH_A")
+	defer os.Unsetenv("GOSH_A")
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"for x in 3 1 2; do echo $x; done | sort > out", "1\n2\n3\n"},
+		{"printf 'a b\\nc d\\n' | while read x y; do echo $y$x; done > out", "ba\ndc\n"},
+		{"echo hi | { read l; echo got $l; } > out", "got hi\n"},
+		{"if true; then echo yes; fi | tr a-z A-Z > out", "YES\n"},
+		{"echo x | case y in y) cat;; esac | tr x X > out", "X\n"},
+		{"for x in a b; do echo $x; done > /dev/null | cat > out", ""},
+		{"{ echo b; echo a; } | sort | head -1 > out", "a\n"},
+		// The parts of a pipeline run in subshells: the shell is not changed
+		{"echo v | while read GOSH_A; do :; done; echo ${GOSH_A:-unset} > out", "unset\n"},
+		// Functions and positional parameters are known in the subshell
+		{"f() { echo f-$1; }; set -- p; for x in 1; do f $1; done | cat > out", "f-p\n"},
+		// The status is the one of the last command
+		{"echo | while read l; do false; done; echo $? > out", "1\n"},
+		{"true | if false; then :; else sh -c 'exit 3'; fi; echo $? > out", "3\n"},
+		{"for x in 1; do sh -c 'exit 4'; done | true; echo $? > out", "0\n"},
+		{"! echo | while read l; do false; done; echo $? > out", "0\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+}
+
+func TestExec_Subshells(t *testing.T) {
+	resetShell(t)
+	os.Unsetenv("GOSH_A")
+	defer os.Unsetenv("GOSH_A")
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"(echo a; echo b) > out", "a\nb\n"},
+		{"(echo sub) | tr a-z A-Z > out", "SUB\n"},
+		// Changes stay in the subshell
+		{"mkdir d; (cd d; pwd > ../in); cd d 2>/dev/null && echo still-outside > out", "still-outside\n"},
+		{"GOSH_A=1; (GOSH_A=2; echo $GOSH_A > out); echo $GOSH_A >> out", "2\n1\n"},
+		{"(exit 3); echo $? > out", "3\n"},
+		{"(exit 3) || echo failed > out", "failed\n"},
+		{"(f() { echo in-sub; }; f) > out; f 2>> out || echo no-f >> out", "in-sub\nno-f\n"},
+		{"(echo a; (echo b)) > out", "a\nb\n"},
+		{"( echo spaced ) > out", "spaced\n"},
+		{"(\n  echo multi\n  echo line\n) > out", "multi\nline\n"},
+		// The subshell knows the functions and positional parameters
+		{"f() { echo f-$1; }; set -- p; (f $1) > out", "f-p\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+}
+
+func TestExec_CompoundBackground(t *testing.T) {
+	resetShell(t)
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"for x in a b; do echo $x; done > out & wait", "a\nb\n"},
+		{"true && echo and > out & wait", "and\n"},
+		{"false || echo or > out & wait", "or\n"},
+		{"(echo sub > out) & wait", "sub\n"},
+		{"{ echo group; } > out & wait", "group\n"},
+		{"! false && echo negated > out & wait", "negated\n"},
+		{"for x in 3 1; do echo $x; done | sort > out & wait", "1\n3\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+	// The shell does not wait for a background loop
+	start := time.Now()
+	runIn(t, "for x in 1; do sleep 1; done & echo $? > out")
+	if lastStatus != 0 || time.Since(start) > 500*time.Millisecond {
+		t.Errorf("background loop: $? = %d after %v", lastStatus, time.Since(start))
+	}
+	execInput("wait")
+}
+
+func TestExtractHeredocs(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"cat <<EOF\nhello\nEOF\n", "cat <<<\"hello\"\n"},
+		{"cat <<EOF\nhello\nEOF", "cat <<<\"hello\"\n"},
+		{"cat << EOF\na\nb\nEOF\necho x\n", "cat <<<\"a\nb\"\necho x\n"},
+		{"cat <<'EOF'\n$x \"q\" it's\nEOF\n", "cat <<<'$x \"q\" it'\\''s'\n"},
+		{"cat <<\"EOF\"\n$x\nEOF\n", "cat <<<'$x'\n"},
+		{"cat <<\\EOF\n$x\nEOF\n", "cat <<<'$x'\n"},
+		{"cat <<E\"O\"F\n$x\nEOF\n", "cat <<<'$x'\n"},
+		{"cat <<EOF\n\"q\" \\\" \\$x \\a\nEOF\n", "cat <<<\"\\\"q\\\" \\\\\\\" \\$x \\\\a\"\n"},
+		{"cat <<EOF\n$(echo \"a\")\nEOF\n", "cat <<<\"$(echo \"a\")\"\n"},
+		{"cat <<-EOF\n\t\ttabs\n\tEOF\n", "cat <<<\"tabs\"\n"},
+		{"cat <<EOF\nEOF\n", "cat </dev/null\n"},
+		{"cat <<A; cat <<B\na\nA\nb\nB\n", "cat <<<\"a\"; cat <<<\"b\"\n"},
+		{"cat <<EOF | sort\nb\nEOF\n", "cat <<<\"b\" | sort\n"},
+		// The delimiter must be the whole line
+		{"cat <<EOF\n EOF\nEOFX\nEOF\n", "cat <<<\" EOF\nEOFX\"\n"},
+		// Not here-documents
+		{"echo '<<EOF'\n", "echo '<<EOF'\n"},
+		{"echo \"<<EOF\"\n", "echo \"<<EOF\"\n"},
+		{"echo \\<<x\n", "echo \\<<x\n"},
+		{"echo # <<EOF\n", "echo # <<EOF\n"},
+		{"cat <<<word\n", "cat <<<word\n"},
+		{"echo $(echo a <<<b)\n", "echo $(echo a <<<b)\n"},
+	}
+	for _, tc := range tests {
+		got, err := extractHeredocs(tc.input)
+		if err != nil {
+			t.Errorf("%q: %v", tc.input, err)
+			continue
+		}
+		if got != tc.want {
+			t.Errorf("%q:\n got %q\nwant %q", tc.input, got, tc.want)
+		}
+	}
+
+	for _, input := range []string{"cat <<EOF", "cat <<EOF\n", "cat <<EOF\nbody\n", "cat <<'EOF\n"} {
+		if _, err := extractHeredocs(input); !errors.Is(err, errIncomplete) {
+			t.Errorf("%q: err = %v, want incomplete", input, err)
+		}
+	}
+	for _, input := range []string{"cat <<\n", "cat << ;\n"} {
+		if _, err := extractHeredocs(input); err == nil || errors.Is(err, errIncomplete) {
+			t.Errorf("%q: err = %v, want syntax error", input, err)
+		}
+	}
+}
+
+func TestExec_Heredocs(t *testing.T) {
+	resetShell(t)
+	t.Setenv("GOSH_A", "value")
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"cat <<EOF > out\nhello\nworld\nEOF", "hello\nworld\n"},
+		{"cat <<EOF > out\n$GOSH_A ${GOSH_A} $(echo sub) \\$GOSH_A\nEOF", "value value sub $GOSH_A\n"},
+		{"cat <<'EOF' > out\n$GOSH_A $(echo sub)\nEOF", "$GOSH_A $(echo sub)\n"},
+		{"cat <<EOF > out\n\"quotes\" 'single' back\\slash\nEOF", "\"quotes\" 'single' back\\slash\n"},
+		{"cat <<EOF > out\nline \\\ncontinued\nEOF", "line continued\n"},
+		{"cat <<'EOF' > out\nline \\\nkept\nEOF", "line \\\nkept\n"},
+		{"cat <<-EOF > out\n\tindented\n\t\tmore\n\tEOF", "indented\nmore\n"},
+		{"cat <<EOF > out\n  *.go {a,b} ~\nEOF", "  *.go {a,b} ~\n"},
+		{"cat <<EOF > out\nEOF", ""},
+		{"cat <<EOF | tr a-z A-Z > out\npiped\nEOF", "PIPED\n"},
+		{"cat > out <<EOF\nredirect first\nEOF", "redirect first\n"},
+		{"cat <<A > out; cat <<B >> out\na\nA\nb\nB", "a\nb\n"},
+		{"while read l; do echo \"<$l>\" >> out; done <<EOF\none\ntwo\nEOF", "<one>\n<two>\n"},
+		{"f() { cat; }; f <<EOF > out\nto f\nEOF", "to f\n"},
+		{"set -- a 'b c'; cat <<EOF > out\n$# $1 $@\nEOF", "2 a a b c\n"},
+		{"for x in 1 2; do\n  cat <<EOF >> out\nx=$x\nEOF\ndone", "x=1\nx=2\n"},
+		{"echo \"$(cat <<EOF\nin subst\nEOF\n)\" > out", "in subst\n"},
+		// Here-strings
+		{"cat <<<word > out", "word\n"},
+		{"cat <<< \"two words $GOSH_A\" > out", "two words value\n"},
+		{"cat <<<'*.go' > out", "*.go\n"},
+		{"read x y <<<'a b c'; echo $y > out", "b c\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+}
+
+// TestRunScript_Heredoc checks that a script reads a here-document and
+// continues after it, with correct line numbers in error messages.
+func TestRunScript_Heredoc(t *testing.T) {
+	resetShell(t)
+	got := runIn(t, `printf 'cat <<EOF > out\nbody\nEOF\necho after >> out\n' > s; . ./s`)
+	if got != "body\nafter\n" {
+		t.Errorf("script with here-document: out = %q", got)
+	}
+	got = runIn(t, `printf 'cat <<EOF\nbody\n' > s; . ./s 2> out`)
+	if !strings.Contains(got, "s:1: syntax error: unexpected end of file") {
+		t.Errorf("unterminated here-document: %q", got)
+	}
+}
+
+// TestTokenize_UTF8 checks that non-ASCII characters survive quoting and
+// escaping (each byte used to be converted to a rune of its own).
+func TestTokenize_UTF8(t *testing.T) {
+	got, err := splitWords(`echo 'wörtlich' "für" über \ä 'a'"ö"`)
+	want := []string{"echo", "wörtlich", "für", "über", "ä", "aö"}
+	if err != nil || !reflect.DeepEqual(got, want) {
+		t.Errorf("got %q, %v, want %q", got, err, want)
+	}
+	if got := runIn(t, "cat <<'EOF' > out\nGrüße\nEOF"); got != "Grüße\n" {
+		t.Errorf("here-document: %q", got)
+	}
+}

funcs.go

@@ -0,0 +1,231 @@
+package main
+
+// Functions and positional parameters. A function runs in the shell itself
+// (it can change variables and the directory), with its arguments as the
+// positional parameters $1, $2, ... In a pipeline, in the background and in
+// $(...) it runs in a subshell, which gets the definitions of all functions.
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"slices"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// funcDef is a function defined with name() { ...; }.
+type funcDef struct {
+	name string
+	body node
+	text string // the source of the definition, passed to subshells
+}
+
+var (
+	functions = map[string]*funcDef{}
+
+	// scriptName is $0: the script, the name given after gosh -c command,
+	// or the name gosh was started with.
+	scriptName = "gosh"
+	// positional are the positional parameters $1, $2, ...
+	positional []string
+
+	// funcDepth is the number of functions that are currently running.
+	funcDepth int
+	// localFrames holds, for every running function, the previous values
+	// of the variables it declared with local.
+	localFrames []map[string]savedVar
+
+	// ioOverride replaces stdin, stdout and stderr of the shell while a
+	// function with redirections runs (f > file), so that the commands in
+	// it use the redirected files.
+	ioOverride [3]*os.File
+)
+
+// maxFuncDepth limits the nesting of function calls, so that endless
+// recursion ends with an error.
+const maxFuncDepth = 1000
+
+type savedVar struct {
+	value string
+	ok    bool
+}
+
+// returnSignal is returned by the return builtin and ends the running
+// function or sourced file with the given status.
+type returnSignal struct {
+	status int
+}
+
+func (r returnSignal) Error() string { return "return" }
+
+// stdio returns stdin (0), stdout (1) or stderr (2) of the shell, which are
+// redirected while a function with redirections runs.
+func stdio(fd int) *os.File {
+	if f := ioOverride[fd]; f != nil {
+		return f
+	}
+	return [3]*os.File{os.Stdin, os.Stdout, os.Stderr}[fd]
+}
+
+// isFuncName reports whether name can be the name of a function: letters,
+// digits, _, - and ., not starting with a digit or -.
+func isFuncName(name string) bool {
+	if name == "" || name[0] == '-' || name[0] >= '0' && name[0] <= '9' || terminators[name] || compoundStarts[name] {
+		return false
+	}
+	for i := 0; i < len(name); i++ {
+		if c := name[i]; !isVarNameByte(c, false) && c != '-' && c != '.' {
+			return false
+		}
+	}
+	return true
+}
+
+func defineFunction(def *funcDef) {
+	functions[def.name] = def
+}
+
+// functionNames returns the names of all functions, sorted.
+func functionNames() []string {
+	names := make([]string, 0, len(functions))
+	for name := range functions {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// functionDefs returns the definitions of all functions as source text, to
+// run them in a subshell.
+func functionDefs() string {
+	var b strings.Builder
+	for _, name := range functionNames() {
+		b.WriteString(functions[name].text)
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
+
+// callFunction runs a function in the shell with args[1:] as positional
+// parameters, the files fds as stdin, stdout and stderr and the assignments
+// that came before the call set while it runs.
+func callFunction(fn *funcDef, args []string, fds [3]*os.File, assigns []string) error {
+	if funcDepth >= maxFuncDepth {
+		return fmt.Errorf("%s: maximum function nesting level exceeded (%d)", sanitize(fn.name), maxFuncDepth)
+	}
+	defer setTemporarily(assigns)()
+
+	savedIO, savedPositional, savedLoopDepth := ioOverride, positional, loopDepth
+	ioOverride, positional, loopDepth = fds, slices.Clone(args[1:]), 0
+	funcDepth++
+	localFrames = append(localFrames, map[string]savedVar{})
+	defer func() {
+		// Restore the variables declared with local
+		for name, v := range localFrames[len(localFrames)-1] {
+			if v.ok {
+				os.Setenv(name, v.value)
+			} else {
+				os.Unsetenv(name)
+			}
+		}
+		localFrames = localFrames[:len(localFrames)-1]
+		funcDepth--
+		ioOverride, positional, loopDepth = savedIO, savedPositional, savedLoopDepth
+	}()
+
+	err := fn.body.exec()
+	var ret returnSignal
+	if errors.As(err, &ret) {
+		if ret.status == 0 {
+			return nil
+		}
+		return statusError(ret.status)
+	}
+	return err
+}
+
+// lookupParam returns the value of a special or positional parameter ($?,
+// $#, $$, $0, $1, ..., $@ and $* joined with blanks) or of a variable.
+func lookupParam(name string) (string, bool) {
+	switch {
+	case name == "?":
+		return strconv.Itoa(lastStatus), true
+	case name == "#":
+		return strconv.Itoa(len(positional)), true
+	case name == "$":
+		return strconv.Itoa(os.Getpid()), true
+	case name == "@" || name == "*":
+		return strings.Join(positional, " "), true
+	case name == "0":
+		return scriptName, true
+	case isDigits(name):
+		n, err := strconv.Atoi(name)
+		if err != nil || n > len(positional) {
+			return "", false
+		}
+		return positional[n-1], true
+	}
+	return os.LookupEnv(name)
+}
+
+// builtinReturn implements return [n].
+func builtinReturn(args []string) error {
+	if funcDepth == 0 && sourceDepth == 0 {
+		return errors.New("return: can only `return' from a function or sourced script")
+	}
+	status := lastStatus
+	if len(args) > 1 {
+		n, err := strconv.Atoi(args[1])
+		if err != nil {
+			return fmt.Errorf("return: %s: numeric argument required", sanitize(args[1]))
+		}
+		status = n & 0xff
+	}
+	return returnSignal{status}
+}
+
+// builtinLocal implements local name[=value] ...: the variables get their
+// previous values back when the function returns. Without a value the
+// variable is unset in the function.
+func builtinLocal(args []string) error {
+	if funcDepth == 0 {
+		return errors.New("local: can only be used in a function")
+	}
+	frame := localFrames[len(localFrames)-1]
+	var err error
+	for _, arg := range args[1:] {
+		name, value, hasValue := strings.Cut(arg, "=")
+		if !isVarName(name) {
+			err = fmt.Errorf("local: `%s': not a valid identifier", sanitize(arg))
+			continue
+		}
+		if _, saved := frame[name]; !saved {
+			old, ok := os.LookupEnv(name)
+			frame[name] = savedVar{old, ok}
+		}
+		if hasValue {
+			os.Setenv(name, value)
+		} else {
+			os.Unsetenv(name)
+		}
+	}
+	return err
+}
+
+// builtinShift implements shift [n].
+func builtinShift(args []string) error {
+	n := 1
+	if len(args) > 1 {
+		var err error
+		if n, err = strconv.Atoi(args[1]); err != nil || n < 0 {
+			return fmt.Errorf("shift: %s: numeric argument required", sanitize(args[1]))
+		}
+	}
+	if n > len(positional) {
+		return fmt.Errorf("shift: %d: shift count out of range", n)
+	}
+	positional = positional[n:]
+	return nil
+}

funcs_test.go

@@ -0,0 +1,363 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// resetShell removes functions and positional parameters after a test.
+func resetShell(t *testing.T) {
+	t.Helper()
+	t.Cleanup(func() {
+		functions = map[string]*funcDef{}
+		positional, scriptName = nil, "gosh"
+	})
+}
+
+func TestTokenize_PositionalParameters(t *testing.T) {
+	resetShell(t)
+	scriptName, positional = "prog", []string{"a", "b c", ""}
+
+	tests := []struct {
+		input string
+		want  []string
+	}{
+		{"echo $0 $1 $2", []string{"echo", "prog", "a", "b c"}},
+		{"echo $# ${#}", []string{"echo", "3", "3"}},
+		{`echo "$@"`, []string{"echo", "a", "b c", ""}},
+		{`echo x"$@"y`, []string{"echo", "xa", "b c", "y"}},
+		{`echo $@`, []string{"echo", "a", "b c", ""}},
+		{`echo "$*"`, []string{"echo", "a b c "}},
+		{`echo ${2}x $10`, []string{"echo", "b cx", "a0"}},
+		{`echo ${4:-four}`, []string{"echo", "four"}},
+		{`echo '$1' \$1`, []string{"echo", "$1", "$1"}},
+	}
+	for _, tc := range tests {
+		got, err := splitWords(tc.input)
+		if err != nil {
+			t.Errorf("%q: %v", tc.input, err)
+			continue
+		}
+		if !reflect.DeepEqual(got, tc.want) {
+			t.Errorf("%q: got %q, want %q", tc.input, got, tc.want)
+		}
+	}
+
+	// An unset positional parameter is an error, like an unset variable
+	if _, err := splitWords("echo $4"); err == nil || !strings.Contains(err.Error(), "4: unbound variable") {
+		t.Errorf("$4: err = %v", err)
+	}
+
+	// "$@" without parameters is no word at all
+	positional = nil
+	for input, want := range map[string][]string{
+		`echo "$@"`:   {"echo"},
+		`echo "$@" x`: {"echo", "x"},
+		`echo "x$@"`:  {"echo", "x"},
+		`echo "$*"`:   {"echo", ""},
+		`echo $#`:     {"echo", "0"},
+	} {
+		if got, _ := splitWords(input); !reflect.DeepEqual(got, want) {
+			t.Errorf("%q without parameters: got %q, want %q", input, got, want)
+		}
+	}
+}
+
+func TestExec_Functions(t *testing.T) {
+	resetShell(t)
+	for _, name := range []string{"GOSH_A", "GOSH_L"} {
+		os.Unsetenv(name)
+		defer os.Unsetenv(name)
+	}
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"f() { echo hi > out; }; f", "hi\n"},
+		{"f () { echo $1-$2-$# >> out; }; f a b", "a-b-2\n"},
+		{"f(){ echo braces >> out; }; f", "braces\n"},
+		{"function f { echo keyword >> out; }; f", "keyword\n"},
+		{"function f() { echo both >> out; }; f", "both\n"},
+		{"f() {\n  echo multi >> out\n  echo line >> out\n}\nf", "multi\nline\n"},
+		{"f()\n{\n  echo next-line >> out\n}\nf", "next-line\n"},
+		{"f() if true; then echo if-body >> out; fi; f", "if-body\n"},
+		{`f() { for a in "$@"; do echo "<$a>" >> out; done; }; f x "y z"`, "<x>\n<y z>\n"},
+		// The positional parameters are restored after the call
+		{`set -- outer; f() { echo $1 >> out; }; f inner; echo $1 >> out`, "inner\nouter\n"},
+		// Functions change the shell (variables, directory)
+		{"f() { GOSH_A=set; }; f; echo $GOSH_A > out", "set\n"},
+		// return
+		{"f() { echo a >> out; return; echo b >> out; }; f", "a\n"},
+		{"f() { return 3; }; f; echo $? > out", "3\n"},
+		{"f() { false; return; }; f; echo $? > out", "1\n"},
+		{"f() { for x in 1 2 3; do if [ $x = 2 ]; then return 7; fi; echo $x >> out; done; }; f; echo $? >> out", "1\n7\n"},
+		{"f() { sh -c 'exit 4'; }; f; echo $? > out", "4\n"},
+		// local
+		{"GOSH_L=global; f() { local GOSH_L=local; echo $GOSH_L >> out; }; f; echo $GOSH_L >> out", "local\nglobal\n"},
+		{"f() { local GOSH_L; GOSH_L=x; }; f; echo ${GOSH_L:-unset} > out", "unset\n"},
+		{"f() { local GOSH_L=1; g; echo $GOSH_L >> out; }; g() { GOSH_L=2; }; f", "2\n"},
+		// Assignments before a call apply only while it runs
+		{"f() { echo $GOSH_A >> out; }; GOSH_A=temp f; echo ${GOSH_A:-unset} >> out", "temp\nunset\n"},
+		// Redirections of a call apply to all commands in the function
+		{"f() { echo one; echo two; }; f > out", "one\ntwo\n"},
+		{"f() { echo err >&2; }; f 2> out", "err\n"},
+		{"echo input > in; f() { cat; }; f < in > out", "input\n"},
+		{"f() { echo nested > out; }; g() { f; }; g", "nested\n"},
+		// Functions run before builtins and commands of the same name
+		{"echo() { printf 'own\\n' > out; }; echo x; unset -f echo", "own\n"},
+		{"f() { echo x > out; }; unset -f f; f", ""},
+		// In pipelines, in the background and in $(...) they run in a subshell
+		{"f() { echo piped; }; f | tr a-z A-Z > out", "PIPED\n"},
+		{"f() { tr a-z A-Z; }; echo lower | f > out", "LOWER\n"},
+		{"f() { echo bg > out; }; f & wait", "bg\n"},
+		{`f() { echo "sub $1"; }; echo "$(f arg)" > out`, "sub arg\n"},
+		{`f() { g; }; g() { echo g-in-sub; }; echo $(f) > out`, "g-in-sub\n"},
+		{`set -- p1; echo "$(echo $1)" > out`, "p1\n"},
+		{"f() { GOSH_A=changed; }; f | cat; echo ${GOSH_A:-unchanged} > out", "unchanged\n"},
+	}
+	for _, tc := range tests {
+		os.Unsetenv("GOSH_A")
+		os.Unsetenv("GOSH_L")
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+		if funcDepth != 0 || len(localFrames) != 0 || ioOverride != [3]*os.File{} {
+			t.Fatalf("%q: function state not restored", tc.input)
+		}
+	}
+
+	for input, want := range map[string]string{
+		"return":               "return: can only `return' from a function or sourced script",
+		"local x":              "local: can only be used in a function",
+		"f() { f; }; f":        "f: maximum function nesting level exceeded (1000)",
+		"f() echo x":           "f: the body of a function must be a compound command like { ...; }",
+		"f() { return x; }; f": "return: x: numeric argument required",
+	} {
+		if err := execInput(input); err == nil || err.Error() != want {
+			t.Errorf("%q: err = %v, want %q", input, err, want)
+		}
+	}
+}
+
+func TestExec_Case(t *testing.T) {
+	resetShell(t)
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"case abc in a*) echo a > out;; b*) echo b > out;; esac", "a\n"},
+		{"case bcd in a*) echo a > out;; b*) echo b > out;; esac", "b\n"},
+		{"case xyz in a*) echo a > out;; esac", ""},
+		{"case stop in start|run) echo s > out;; stop|halt) echo h > out;; esac", "h\n"},
+		{"case x in (x) echo paren > out;; esac", "paren\n"},
+		{"case x in x)echo tight > out;;esac", "tight\n"},
+		{"case x in x ) echo blank > out ;; esac", "blank\n"},
+		{"case x in\n  y) echo y > out ;;\n  x)\n    echo x1 >> out\n    echo x2 >> out\n    ;;\nesac", "x1\nx2\n"},
+		// The last clause needs no ;;
+		{"case x in x) echo last > out; esac", "last\n"},
+		{"case x in x) ;; esac; echo empty > out", "empty\n"},
+		{"case x in esac; echo none > out", "none\n"},
+		// Patterns: wildcards, also across /, quoted characters are literal
+		{"case a/b/c in *) echo star > out;; esac", "star\n"},
+		{"case a/b in a?b) echo q > out;; esac", "q\n"},
+		{"case b in [abc]) echo class > out;; esac", "class\n"},
+		{"case d in [!abc]) echo neg > out;; esac", "neg\n"},
+		{`case '*' in "*") echo quoted > out;; *) echo glob > out;; esac`, "quoted\n"},
+		{`case abc in "*") echo quoted > out;; *) echo glob > out;; esac`, "glob\n"},
+		{`case 'a b' in "a b") echo space > out;; esac`, "space\n"},
+		{`case 'x)' in 'x)') echo paren-in-quotes > out;; esac`, "paren-in-quotes\n"},
+		// Variables in the word and in patterns
+		{`set -- --help; case $1 in -h|--help) echo help > out;; esac`, "help\n"},
+		// Values of variables are no patterns (like everywhere in gosh)
+		{`P='b*'; case bar in $P) echo pattern > out;; *) echo literal > out;; esac`, "literal\n"},
+		{`P='b*'; case 'b*' in $P) echo same > out;; esac`, "same\n"},
+		{`case $(echo hi) in hi) echo subst > out;; esac`, "subst\n"},
+		{`case "" in "") echo empty-word > out;; esac`, "empty-word\n"},
+		// Only the first matching clause runs
+		{"case a in a) echo 1 >> out;; *) echo 2 >> out;; esac", "1\n"},
+		// Nested in other structures
+		{"for x in a b; do case $x in a) echo A >> out;; *) echo other >> out;; esac; done", "A\nother\n"},
+		{"f() { case $1 in y) return 0;; *) return 1;; esac; }; f y && echo yes > out", "yes\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+
+	for input, status := range map[string]int{
+		"case x in y) false;; esac": 0,
+		"case x in x) false;; esac": 1,
+		"case x in x) true;; esac":  0,
+		"case x in x) echo;":        2,
+		"case x y in x) ;; esac":    2,
+		"echo a;; echo b":           2,
+	} {
+		runIn(t, input)
+		if lastStatus != status {
+			t.Errorf("%q: $? = %d, want %d", input, lastStatus, status)
+		}
+	}
+}
+
+func TestExec_Group(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"{ echo a >> out; echo b >> out; }", "a\nb\n"},
+		{"{\n  echo multi >> out\n}", "multi\n"},
+		{"false || { echo fallback >> out; }", "fallback\n"},
+		{"echo { } > out", "{ }\n"},
+	}
+	for _, tc := range tests {
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+}
+
+func TestExec_PositionalBuiltins(t *testing.T) {
+	resetShell(t)
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"set -- a b c; echo $# $1 $3 > out", "3 a c\n"},
+		{"set -- a b c; shift; echo $# $1 > out", "2 b\n"},
+		{"set -- a b c; shift 2; echo $# $1 > out", "1 c\n"},
+		{"set -- a b; shift 3; echo $# $? > out", "2 1\n"},
+		{"set --; echo $# > out", "0\n"},
+		{"set -- a b; for x; do echo $x >> out; done", "a\nb\n"},
+		{"set -- 1 2 3; while [ $# -gt 0 ]; do echo $1 >> out; shift; done", "1\n2\n3\n"},
+		// source with arguments
+		{"echo 'echo $# $1 > out' > lib; set -- x; . ./lib a b", "2 a\n"},
+		{"echo 'echo $1 > out' > lib; set -- x; . ./lib a b; echo $1 >> out", "a\nx\n"},
+		// return ends a sourced file
+		{"printf 'echo one >> out\\nreturn 3\\necho two >> out\\n' > lib; . ./lib; echo $? >> out", "one\n3\n"},
+	}
+	for _, tc := range tests {
+		positional = nil
+		if got := runIn(t, tc.input); got != tc.want {
+			t.Errorf("%q: out = %q, want %q", tc.input, got, tc.want)
+		}
+	}
+}
+
+func TestRead(t *testing.T) {
+	for _, name := range []string{"GOSH_A", "GOSH_B", "GOSH_C", "REPLY", "IFS"} {
+		os.Unsetenv(name)
+		defer os.Unsetenv(name)
+	}
+	tests := []struct {
+		input string
+		data  string
+		want  string
+	}{
+		{"read GOSH_A", "hello world\n", "[hello world]"},
+		{"read GOSH_A GOSH_B", "  one   two  three  \n", "[one][two  three]"},
+		{"read GOSH_A GOSH_B GOSH_C", "one\n", "[one][][]"},
+		{"read GOSH_A", "no newline", "[no newline]"},
+		{"read GOSH_A GOSH_B", `a\ b c` + "\n", "[a b][c]"},
+		{"read -r GOSH_A GOSH_B", `a\ b c` + "\n", `[a\][b c]`},
+		{"read GOSH_A", "con\\\ntinued\n", "[continued]"},
+		{"read", "  reply  \n", "[  reply  ]"},
+		{"IFS=:; read GOSH_A GOSH_B GOSH_C", "a::b:c\n", "[a][][b:c]"},
+		{"IFS=:; read GOSH_A GOSH_B", "a b:c d\n", "[a b][c d]"},
+		{"IFS=; read GOSH_A", "  keep  \n", "[  keep  ]"},
+		{"read GOSH_A; read GOSH_B", "first\nsecond\n", "[first][second]"},
+	}
+	for _, tc := range tests {
+		for _, name := range []string{"GOSH_A", "GOSH_B", "GOSH_C", "REPLY", "IFS"} {
+			os.Unsetenv(name)
+		}
+		dir := t.TempDir()
+		in := filepath.Join(dir, "in")
+		os.WriteFile(in, []byte(tc.data), 0644)
+		f, _ := os.Open(in)
+		saved := os.Stdin
+		os.Stdin = f
+		execInput(tc.input)
+		os.Stdin = saved
+		f.Close()
+
+		var got strings.Builder
+		names := []string{"GOSH_A", "GOSH_B", "GOSH_C"}
+		if !strings.Contains(tc.input, "GOSH_") {
+			names = []string{"REPLY"}
+		}
+		for _, name := range names {
+			if v, ok := os.LookupEnv(name); ok {
+				got.WriteString("[" + v + "]")
+			}
+		}
+		if got.String() != tc.want {
+			t.Errorf("%q with %q: got %s, want %s", tc.input, tc.data, got.String(), tc.want)
+		}
+	}
+
+	// Status 1 at the end of the input, also after a last line without newline
+	for data, want := range map[string]int{"line\n": 0, "partial": 1, "": 1} {
+		dir := t.TempDir()
+		os.WriteFile(filepath.Join(dir, "in"), []byte(data), 0644)
+		runIn(t, "read GOSH_A < "+filepath.Join(dir, "in"))
+		if lastStatus != want {
+			t.Errorf("read from %q: $? = %d, want %d", data, lastStatus, want)
+		}
+	}
+
+	if err := execInput("read 1x"); err == nil || err.Error() != "read: `1x': not a valid identifier" {
+		t.Errorf("read 1x: %v", err)
+	}
+	if err := execInput("echo a | read GOSH_A"); err == nil || !strings.Contains(err.Error(), "cannot be used in a pipeline") {
+		t.Errorf("read in a pipeline: %v", err)
+	}
+}
+
+// TestShell_Arguments checks $0 and the positional parameters of scripts and
+// gosh -c, and that a script reads lines from stdin with read.
+func TestShell_Arguments(t *testing.T) {
+	dir := t.TempDir()
+	script := filepath.Join(dir, "script.gosh")
+	os.WriteFile(script, []byte(`echo "$# [$1] [$2]"
+usage() {
+  echo "usage: $1" >&2
+  return 2
+}
+case ${1:-} in
+  -h) usage x; exit $? ;;
+esac
+while read -r line; do
+  echo "line: $line"
+done
+`), 0644)
+
+	tests := []struct {
+		args  []string
+		stdin string
+		want  string
+	}{
+		{[]string{"-c", `echo $0 $# "$@"`}, "", subshellPath + " 0\n"},
+		{[]string{"-c", `echo $0 $# "$@"`, "name", "a", "b c"}, "", "name 2 a b c\n"},
+		{[]string{"-c", `for a; do echo "<$a>"; done`, "n", "x y", "z"}, "", "<x y>\n<z>\n"},
+		{[]string{script, "one", "two words"}, "l1\nl2\n", "2 [one] [two words]\nline: l1\nline: l2\n"},
+	}
+	for _, tc := range tests {
+		cmd := exec.Command(subshellPath, tc.args...)
+		cmd.Stdin = strings.NewReader(tc.stdin)
+		out, _ := cmd.Output()
+		if string(out) != tc.want {
+			t.Errorf("gosh %q: got %q, want %q", tc.args, out, tc.want)
+		}
+	}
+
+	cmd := exec.Command(subshellPath, script, "-h")
+	out, err := cmd.CombinedOutput()
+	if exitStatus(err) != 2 || !strings.Contains(string(out), "usage: x") {
+		t.Errorf("script -h: status %d, output %q", exitStatus(err), out)
+	}
+}

heredoc.go

@@ -0,0 +1,268 @@
+package main
+
+// Here-documents: cmd <<WORD, followed by lines up to a line WORD, is the
+// same as a here-string cmd <<<"lines" (without the last newline, which the
+// here-string adds). extractHeredocs rewrites the source that way before it
+// is parsed, so that the rest of gosh (and subshells, which get the source
+// text) only has to know here-strings.
+
+import (
+	"strings"
+)
+
+// hereDoc is a here-document whose body has not been read yet.
+type hereDoc struct {
+	seg       int // the index of its placeholder in the output segments
+	delim     string
+	quoted    bool // the delimiter was quoted: the body is not expanded
+	stripTabs bool // <<-: leading tabs are removed from the lines
+}
+
+// extractHeredocs replaces every here-document operator in src by a
+// here-string with its body and removes the body and delimiter lines. The
+// body starts after the end of the line with the operator. If the input
+// ends before the delimiter line, it returns errIncomplete (an interactive
+// shell then reads more lines).
+//
+// The body is expanded like "..." if the delimiter is unquoted ($VAR, $(...),
+// \ before $ ` \ and newline), and taken literally if any part of the
+// delimiter is quoted ('EOF', "EOF", \EOF).
+func extractHeredocs(src string) (string, error) {
+	if !strings.Contains(src, "<<") {
+		return src, nil
+	}
+	var (
+		segs      []string
+		cur       strings.Builder
+		pending   []hereDoc
+		wordStart = true
+	)
+	copyTo := func(i, end int) int {
+		if end < 0 || end > len(src) {
+			end = len(src)
+		}
+		cur.WriteString(src[i:end])
+		return end
+	}
+
+	for i := 0; i < len(src); {
+		ch := src[i]
+		switch {
+		case ch == '\\':
+			i = copyTo(i, i+2)
+			wordStart = false
+		case ch == '\'':
+			end := strings.IndexByte(src[i+1:], '\'')
+			if end >= 0 {
+				end += i + 2
+			}
+			i = copyTo(i, end)
+			wordStart = false
+		case ch == '"':
+			end := dquoteEnd(src, i)
+			if end >= 0 {
+				end++
+			}
+			i = copyTo(i, end)
+			wordStart = false
+		case isSubstStart(src, i):
+			end := substEnd(src, i)
+			if end >= 0 {
+				end++
+			}
+			i = copyTo(i, end)
+			wordStart = false
+		case ch == '#' && wordStart:
+			// A comment, until the end of the line
+			end := strings.IndexByte(src[i:], '\n')
+			if end >= 0 {
+				end += i
+			}
+			i = copyTo(i, end)
+		case strings.HasPrefix(src[i:], "<<<"):
+			i = copyTo(i, i+3)
+			wordStart = false
+		case strings.HasPrefix(src[i:], "<<"):
+			h, n, err := parseHereOp(src[i:])
+			if err != nil {
+				return "", err
+			}
+			segs = append(segs, cur.String())
+			cur.Reset()
+			h.seg = len(segs)
+			segs = append(segs, "") // filled in when the body has been read
+			pending = append(pending, h)
+			i += n
+			wordStart = false
+		case ch == '\n':
+			cur.WriteByte(ch)
+			i++
+			wordStart = true
+			// The bodies of the here-documents of this line follow
+			for _, h := range pending {
+				body, n, ok := readHereBody(src[i:], h)
+				if !ok {
+					return "", errIncomplete
+				}
+				segs[h.seg] = hereString(body, h.quoted)
+				i += n
+			}
+			pending = nil
+		default:
+			cur.WriteByte(ch)
+			i++
+			wordStart = strings.IndexByte(" \t;&|()<>", ch) >= 0
+		}
+	}
+	if len(pending) > 0 {
+		return "", errIncomplete
+	}
+	segs = append(segs, cur.String())
+	return strings.Join(segs, ""), nil
+}
+
+// dquoteEnd returns the index of the " that ends the double-quoted string
+// starting at s[i], or -1.
+func dquoteEnd(s string, i int) int {
+	for j := i + 1; j < len(s); j++ {
+		switch {
+		case s[j] == '\\':
+			j++
+		case isSubstStart(s, j):
+			end := substEnd(s, j)
+			if end < 0 {
+				return -1
+			}
+			j = end
+		case s[j] == '"':
+			return j
+		}
+	}
+	return -1
+}
+
+// parseHereOp parses a here-document operator <<WORD or <<-WORD at the
+// start of s and returns it and its length.
+func parseHereOp(s string) (hereDoc, int, error) {
+	h := hereDoc{}
+	i := 2
+	if i < len(s) && s[i] == '-' {
+		h.stripTabs = true
+		i++
+	}
+	for i < len(s) && (s[i] == ' ' || s[i] == '\t') {
+		i++
+	}
+	var delim strings.Builder
+	start := i
+	for i < len(s) && strings.IndexByte(" \t\n;&|()<>", s[i]) < 0 {
+		switch c := s[i]; c {
+		case '\'', '"':
+			end := strings.IndexByte(s[i+1:], c)
+			if end < 0 {
+				return h, 0, errIncomplete
+			}
+			delim.WriteString(s[i+1 : i+1+end])
+			i += end + 2
+			h.quoted = true
+		case '\\':
+			if i+1 < len(s) {
+				delim.WriteByte(s[i+1])
+			}
+			i += 2
+			h.quoted = true
+		default:
+			delim.WriteByte(c)
+			i++
+		}
+	}
+	if i == start {
+		if i == len(s) || s[i] == '\n' {
+			return h, 0, syntaxError("newline")
+		}
+		return h, 0, syntaxError(s[i : i+1])
+	}
+	h.delim = delim.String()
+	return h, min(i, len(s)), nil
+}
+
+// readHereBody reads the lines of a here-document from s up to the
+// delimiter line. It returns the body (each line with its newline) and the
+// number of bytes consumed, or ok == false if there is no delimiter line yet.
+func readHereBody(s string, h hereDoc) (body string, n int, ok bool) {
+	var b strings.Builder
+	for pos := 0; ; {
+		end := strings.IndexByte(s[pos:], '\n')
+		last := end < 0
+		if last {
+			end = len(s) - pos
+		}
+		line := s[pos : pos+end]
+		if h.stripTabs {
+			line = strings.TrimLeft(line, "\t")
+		}
+		next := min(pos+end+1, len(s))
+		if line == h.delim {
+			return b.String(), next, true
+		}
+		if last {
+			return "", 0, false
+		}
+		b.WriteString(line)
+		b.WriteByte('\n')
+		pos = next
+	}
+}
+
+// hereString returns the here-string (or redirection) that has the effect of
+// a here-document with the given body.
+func hereString(body string, quoted bool) string {
+	if body == "" {
+		return "</dev/null"
+	}
+	body = strings.TrimSuffix(body, "\n")
+	if quoted {
+		return "<<<'" + strings.ReplaceAll(body, "'", `'\''`) + "'"
+	}
+	return `<<<"` + escapeHereBody(body) + `"`
+}
+
+// escapeHereBody quotes the body of an unquoted here-document for "...":
+// " becomes \", a backslash that only escapes $ ` \ and newline in a
+// here-document stays one, others become \\. $(...) and ${...} are kept as
+// they are, "$@" becomes "$*" (one word, as in a here-document).
+func escapeHereBody(body string) string {
+	var b strings.Builder
+	for i := 0; i < len(body); i++ {
+		c := body[i]
+		switch {
+		case isSubstStart(body, i):
+			end := substEnd(body, i)
+			if end < 0 {
+				end = len(body) - 1
+			}
+			b.WriteString(body[i : end+1])
+			i = end
+		case strings.HasPrefix(body[i:], "$@"):
+			b.WriteString("$*")
+			i++
+		case strings.HasPrefix(body[i:], "${"):
+			end := strings.IndexByte(body[i:], '}')
+			if end < 0 {
+				end = len(body) - i - 1
+			}
+			b.WriteString(strings.Replace(body[i:i+end+1], "${@", "${*", 1))
+			i += end
+		case c == '\\' && i+1 < len(body) && strings.IndexByte("$`\\\n", body[i+1]) >= 0:
+			b.WriteString(body[i : i+2])
+			i++
+		case c == '\\':
+			b.WriteString(`\\`)
+		case c == '"':
+			b.WriteString(`\"`)
+		default:
+			b.WriteByte(c)
+		}
+	}
+	return b.String()
+}

main.go

@@ -12,6 +12,7 @@ import (
 	"os/user"
 	"path/filepath"
 	"runtime/debug"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
@@ -121,6 +122,7 @@ type token struct {
 	word    string // the word, if op == ""
 	pattern string // the word as glob pattern (quoted characters escaped)
 	glob    bool   // the word contains unquoted * ? or [ and is expanded
+	assign  bool   // the word is an assignment name=value (unquoted name and =)
 	fd      int    // the redirected file descriptor (for redirections)
 	dup     int    // the target file descriptor of >& and <&
 }
@@ -136,7 +138,8 @@ type token struct {
 //   - $VAR, ${VAR} and ${VAR:-default} are expanded outside single quotes;
 //     an unset variable is an error, so that e.g. "rm -rf $DIR/x" never runs
 //     with an empty $DIR
-//   - ~ and ~/... are expanded at the start of an unquoted word
+//   - ~ and ~/... are expanded at the start of an unquoted word, and after
+//     the = and : of an assignment (PATH=~/bin:~/go/bin)
 //   - unquoted |, <, >, >>, N<, N>, N>>, N>&M, N<&M, &> and &>> are operators
 //
 // Expanded values are never split into several words.
@@ -147,23 +150,29 @@ func tokenize(input string) ([]token, error) {
 		pat      strings.Builder // the word as glob pattern, quoted parts escaped
 		glob     bool            // the word contains unquoted * ? or [
 		inWord   bool            // a word has been started (even if it is still empty)
+		plain    = true          // the word so far has no quotes, escapes or expansions
+		assign   bool            // the word is an assignment name=value
+		tildeOK  bool            // ~ may be expanded here (after = or : of an assignment)
+		noParams bool            // the word contains "$@" without positional parameters
 		quote    byte
 		escaped  bool
 		rawStart = -1 // start of the current word in input
 	)
 
 	endWord := func() {
-		if inWord {
+		// "$@" without parameters is no word at all, unlike ""
-			tokens = append(tokens, token{word: b.String(), pattern: pat.String(), glob: glob})
+		if inWord && !(noParams && b.Len() == 0) {
+			tokens = append(tokens, token{word: b.String(), pattern: pat.String(), glob: glob, assign: assign})
 		}
 		b.Reset()
 		pat.Reset()
-		glob = false
+		glob, assign, plain, noParams = false, false, true, false
 		inWord = false
 		rawStart = -1
 	}
 	// literal adds quoted, escaped or expanded text: it is never a pattern
 	literal := func(s string) {
+		plain = false
 		b.WriteString(s)
 		pat.WriteString(escapeGlob(s))
 	}
@@ -175,19 +184,21 @@ func tokenize(input string) ([]token, error) {
 
 	for i := 0; i < len(input); i++ {
 		ch := input[i]
+		afterAssignSep := tildeOK
+		tildeOK = false
 		switch {
 		case escaped:
 			if quote == '"' && !strings.ContainsRune("$\"\\`", rune(ch)) {
 				literal("\\")
 			}
-			literal(string(ch))
+			literal(input[i : i+1])
 			inWord = true
 			escaped = false
 		case quote == '\'':
 			if ch == '\'' {
 				quote = 0
 			} else {
-				literal(string(ch))
+				literal(input[i : i+1])
 			}
 		case ch == '\\':
 			startRaw(i)
@@ -202,7 +213,8 @@ func tokenize(input string) ([]token, error) {
 			if err != nil {
 				return nil, err
 			}
-			if quote == '"' {
+			if quote == '"' || assign {
+				// Quoted or in an assignment, the output is one word
 				literal(out)
 				inWord = true
 			} else {
@@ -218,6 +230,20 @@ func tokenize(input string) ([]token, error) {
 				}
 			}
 			i = end
+		case ch == '$' && !assign && positionalWords(input[i:], quote == '"') > 0:
+			// $@ and "$@": one word per positional parameter
+			startRaw(i)
+			if len(positional) == 0 && quote == '"' {
+				noParams = true
+			}
+			for k, param := range positional {
+				if k > 0 {
+					endWord()
+				}
+				literal(param)
+				inWord = true
+			}
+			i += positionalWords(input[i:], quote == '"') - 1
 		case ch == '$':
 			startRaw(i)
 			value, n, err := expandVar(input[i:])
@@ -237,10 +263,11 @@ func tokenize(input string) ([]token, error) {
 			if ch == '"' {
 				quote = 0
 			} else {
-				literal(string(ch))
+				literal(input[i : i+1])
 			}
 		case ch == '"' || ch == '\'':
 			startRaw(i)
+			plain = false
 			quote = ch
 			inWord = true
 		case ch == ' ' || ch == '\t' || ch == '\n':
@@ -279,6 +306,10 @@ func tokenize(input string) ([]token, error) {
 			}
 			t := token{op: string(ch), fd: fd}
 			switch {
+			case strings.HasPrefix(input[i:], "<<<"):
+				// <<<word: the word (and a newline) is the input
+				t.op = "<<<"
+				i += 2
 			case ch == '>' && i+1 < len(input) && input[i+1] == '>':
 				t.op = ">>"
 				i++
@@ -296,8 +327,8 @@ func tokenize(input string) ([]token, error) {
 				i = j - 1
 			}
 			tokens = append(tokens, t)
-		case ch == '~' && !inWord && b.Len() == 0 &&
+		case ch == '~' && (!inWord && b.Len() == 0 || afterAssignSep) &&
-			(i+1 == len(input) || strings.IndexByte("/ \t\n|<>", input[i+1]) >= 0):
+			(i+1 == len(input) || strings.IndexByte("/ \t\n|<>:", input[i+1]) >= 0):
 			startRaw(i)
 			home := getHomeDir()
 			if home == "" {
@@ -307,6 +338,14 @@ func tokenize(input string) ([]token, error) {
 			inWord = true
 		default:
 			startRaw(i)
+			switch {
+			case ch == '=' && plain && !assign && isVarName(b.String()):
+				// name=value; ~ may follow
+				assign, tildeOK = true, true
+			case ch == ':' && assign:
+				// PATH=~/bin:~/go/bin
+				tildeOK = true
+			}
 			b.WriteByte(ch)
 			switch {
 			case ch == '*' || ch == '?' || ch == '[':
@@ -488,13 +527,10 @@ func expandVar(s string) (string, int, error) {
 			return "", 0, errors.New("missing } in variable reference")
 		}
 		name, def, hasDef := strings.Cut(s[2:end], ":-")
-		if name == "?" {
+		if !isVarName(name) && !isDigits(name) && !isSpecialParam(name) {
-			return strconv.Itoa(lastStatus), end + 1, nil
-		}
-		if !isVarName(name) {
 			return "", 0, fmt.Errorf("bad substitution: %s", s[:end+1])
 		}
-		value, ok := os.LookupEnv(name)
+		value, ok := lookupParam(name)
 		if hasDef && value == "" {
 			return def, end + 1, nil
 		}
@@ -504,8 +540,13 @@ func expandVar(s string) (string, int, error) {
 		return value, end + 1, nil
 	}
 
-	if len(s) > 1 && s[1] == '?' {
+	// $?, $#, $$, $@, $*, $0 and $1 to $9 ($10 is $1 followed by 0)
-		return strconv.Itoa(lastStatus), 2, nil
+	if len(s) > 1 && (isSpecialParam(s[1:2]) || isDigits(s[1:2])) {
+		value, ok := lookupParam(s[1:2])
+		if !ok {
+			return "", 0, fmt.Errorf("%s: unbound variable", s[1:2])
+		}
+		return value, 2, nil
 	}
 
 	n := 1
@@ -522,6 +563,25 @@ func expandVar(s string) (string, int, error) {
 	return value, n, nil
 }
 
+// isSpecialParam reports whether name is one of the special parameters ?,
+// #, $, @ and *.
+func isSpecialParam(name string) bool {
+	return len(name) == 1 && strings.Contains("?#$@*", name)
+}
+
+// positionalWords returns the number of bytes of $@ or ${@} at the start of
+// s, which expands to one word per positional parameter (also in double
+// quotes). Unquoted, $* and ${*} do the same (gosh never splits values).
+// It returns 0 for anything else.
+func positionalWords(s string, quoted bool) int {
+	for _, p := range []string{"$@", "${@}", "$*", "${*}"} {
+		if strings.HasPrefix(s, p) && (strings.Contains(p, "@") || !quoted) {
+			return len(p)
+		}
+	}
+	return 0
+}
+
 func isVarName(name string) bool {
 	if name == "" {
 		return false
@@ -742,7 +802,7 @@ type shellCompleter struct {
 
 func newShellCompleter() *shellCompleter {
 	return &shellCompleter{
-		commands: []string{"cd", "pwd", "echo", "exit", "quit", "set", "export", "source", "jobs", "fg", "bg", "wait", "alias", "unalias", "break", "continue", "help"},
+		commands: []string{"cd", "pwd", "echo", "exit", "quit", "set", "export", "source", "jobs", "fg", "bg", "wait", "alias", "unalias", "break", "continue", "unset", "help", "return", "local", "shift", "read"},
 	}
 }
 
@@ -759,7 +819,7 @@ func (c *shellCompleter) Do(line []rune, pos int) ([][]rune, int) {
 	// ... and after if, then, do etc.
 	if fields := strings.Fields(before); len(fields) > 0 {
 		switch fields[len(fields)-1] {
-		case "if", "then", "elif", "else", "do", "while", "until", "!":
+		case "if", "then", "elif", "else", "do", "while", "until", "!", "{", ";;":
 			isFirstWord = true
 		}
 	}
@@ -773,7 +833,7 @@ func (c *shellCompleter) Do(line []rune, pos int) ([][]rune, int) {
 		// Complete commands
 		var candidates [][]rune
 		seen := make(map[string]bool)
-		names := append(append(append([]string(nil), c.commands...), aliasNames()...), pathExecutables(word)...)
+		names := append(append(append(append([]string(nil), c.commands...), aliasNames()...), functionNames()...), pathExecutables(word)...)
 		for _, cmd := range names {
 			if strings.HasPrefix(cmd, word) && !seen[cmd] {
 				seen[cmd] = true
@@ -917,8 +977,8 @@ func completeFilePath(line, prefix string) []string {
 	return matches
 }
 
-const usage = `usage: gosh [-l] [-i] [--norc] [--noprofile] [script]
+const usage = `usage: gosh [-l] [-i] [--norc] [--noprofile] [script [args ...]]
-       gosh [-l] [--noprofile] -c command
+       gosh [-l] [--noprofile] -c command [name [args ...]]
        gosh -version`
 
 // sysConfDir holds the system-wide startup files.
@@ -931,6 +991,7 @@ func main() {
 	if strings.HasPrefix(os.Args[0], "-") {
 		args = append([]string{"-l"}, args...)
 	}
+	scriptName = os.Args[0]
 	os.Exit(run(args))
 }
 
@@ -968,21 +1029,26 @@ flags:
 			fmt.Println(usage)
 			return 0
 		case arg == "-c":
-			// Like sh, further arguments are allowed (they would become $0,
+			// gosh -c command [name [args ...]]: name is $0, args are $1, ...
-			// $1, ...), but gosh has no positional parameters yet.
 			if len(args) < 2 {
 				fmt.Fprintln(os.Stderr, "gosh: -c: option requires an argument")
 				fmt.Fprintln(os.Stderr, usage)
 				return 2
 			}
+			if len(args) > 2 {
+				scriptName, positional = args[2], args[3:]
+			}
 			script = func() int { return runScript(strings.NewReader(args[1]), "") }
 		case strings.HasPrefix(arg, "-") && arg != "-":
 			fmt.Fprintf(os.Stderr, "gosh: %s: invalid option\n", arg)
 			fmt.Fprintln(os.Stderr, usage)
 			return 2
 		case arg == "-":
+			positional = args[1:]
 			script = func() int { return runScript(os.Stdin, "") }
 		default:
+			// gosh script [args ...]
+			scriptName, positional = arg, args[1:]
 			f, err := os.Open(arg)
 			if err != nil {
 				fmt.Fprintln(os.Stderr, "gosh:", err)
@@ -1046,6 +1112,8 @@ func sourceStartupFile(path string) {
 		return
 	}
 	defer f.Close()
+	sourceDepth++
+	defer func() { sourceDepth-- }()
 	runScript(bufio.NewReader(f), path)
 }
 
@@ -1109,12 +1177,18 @@ func runScript(r io.Reader, name string) int {
 				goto next // read the rest of the command
 			}
 			buf.Reset()
-			if err != nil {
+			if err == nil {
-				lastStatus = exitStatus(err)
+				err = tree.exec()
-				report(err, startLine)
+				var ret returnSignal
-			} else {
+				if errors.As(err, &ret) {
-				report(tree.exec(), startLine)
+					// return in a sourced file
+					lastStatus = ret.status
+					return lastStatus
 				}
+			} else {
+				lastStatus = exitStatus(err)
+			}
+			report(err, startLine)
 		}
 	next:
 		if readErr != nil {
@@ -1174,6 +1248,10 @@ func exitStatus(err error) int {
 	if errors.As(err, &lc) {
 		return 0
 	}
+	var ret returnSignal
+	if errors.As(err, &ret) {
+		return ret.status
+	}
 	var exitErr *exec.ExitError
 	if errors.As(err, &exitErr) {
 		if ws, ok := exitErr.Sys().(syscall.WaitStatus); ok && ws.Signaled() {
@@ -1321,11 +1399,12 @@ func printError(err error) {
 		exitErr   *exec.ExitError
 		statusErr statusError
 		lc        loopControl
+		ret       returnSignal
 	)
-	if err == nil || errors.As(err, &exitErr) || errors.As(err, &statusErr) || errors.As(err, &lc) {
+	if err == nil || errors.As(err, &exitErr) || errors.As(err, &statusErr) || errors.As(err, &lc) || errors.As(err, &ret) {
 		return
 	}
-	fmt.Fprintln(os.Stderr, "gosh:", err)
+	fmt.Fprintln(stdio(2), "gosh:", err)
 }
 
 // execInput parses and executes input: a command line or a whole script.
@@ -1343,27 +1422,8 @@ func execInput(input string) error {
 // execCommand executes a pipeline of simple commands with redirections, in
 // the background if background is set.
 func execCommand(input string, background bool) error {
-	// Brace expansion comes first, so that its results are expanded further
 	substStatus = 0
-	input, err := expandBraceWords(input)
+	stages, err := expandStages(input)
-	if err != nil {
-		return err
-	}
-
-	// Split the input into words and operators, expanding variables and ~ on
-	// the way.
-	tokens, err := tokenize(input)
-	var (
-		synErr    syntaxError
-		statusErr statusError
-	)
-	if errors.As(err, &synErr) || errors.As(err, &statusErr) {
-		return err
-	}
-	if err != nil {
-		return fmt.Errorf("invalid input: %w", err)
-	}
-	stages, err := parsePipeline(tokens)
 	if err != nil {
 		return err
 	}
@@ -1381,18 +1441,62 @@ func execCommand(input string, background bool) error {
 	return runPipeline(stages, strings.TrimSpace(input), background)
 }
 
-// redirect is a redirection of a simple command, e.g. 2>>file or 2>&1.
+// expandStages expands the text of a pipeline of simple commands and splits
-type redirect struct {
+// it into its stages.
-	op   string // <, >, >>, &>, &>>, >& or <&
+func expandStages(input string) ([]stage, error) {
-	fd   int    // the redirected file descriptor
+	// Brace expansion comes first, so that its results are expanded further
-	dup  int    // the target file descriptor of >& and <&
+	input, err := expandBraceWords(input)
-	file string // the file name for all other operators
+	if err != nil {
+		return nil, err
+	}
+
+	// Split the input into words and operators, expanding variables and ~ on
+	// the way.
+	tokens, err := tokenize(input)
+	var (
+		synErr    syntaxError
+		statusErr statusError
+	)
+	if errors.As(err, &synErr) || errors.As(err, &statusErr) {
+		return nil, err
+	}
+	if err != nil {
+		return nil, fmt.Errorf("invalid input: %w", err)
+	}
+	return parsePipeline(tokens)
 }
 
-// stage is a simple command of a pipeline.
+// openRedirections expands and opens the redirections of a compound command
+// and returns the resulting stdin, stdout and stderr, and the files to close
+// afterwards.
+func openRedirections(text string) ([3]*os.File, []*os.File, error) {
+	fds := [3]*os.File{stdio(0), stdio(1), stdio(2)}
+	stages, err := expandStages(text)
+	if err != nil {
+		return fds, nil, err
+	}
+	if len(stages) != 1 || len(stages[0].args) > 0 || len(stages[0].assigns) > 0 {
+		return fds, nil, syntaxError(text)
+	}
+	opened, err := applyRedirects(&fds, stages[0].redirects)
+	return fds, opened, err
+}
+
+// redirect is a redirection of a simple command, e.g. 2>>file or 2>&1.
+type redirect struct {
+	op   string // <, >, >>, &>, &>>, >&, <& or <<<
+	fd   int    // the redirected file descriptor
+	dup  int    // the target file descriptor of >& and <&
+	file string // the file name for all other operators (the text for <<<)
+}
+
+// stage is a simple command of a pipeline, or a script that runs in a
+// subshell (a compound command in a pipeline or in the background).
 type stage struct {
+	assigns   []string // name=value before the command name
 	args      []string
 	redirects []redirect
+	script    string
 }
 
 // parsePipeline groups tokens into the stages of a pipeline.
@@ -1401,13 +1505,18 @@ func parsePipeline(tokens []token) ([]stage, error) {
 		stages []stage
 		cur    stage
 	)
-	isEmpty := func(s stage) bool { return len(s.args) == 0 && len(s.redirects) == 0 }
+	isEmpty := func(s stage) bool { return len(s.assigns) == 0 && len(s.args) == 0 && len(s.redirects) == 0 }
 
 	for i := 0; i < len(tokens); i++ {
 		t := tokens[i]
 		switch t.op {
 		case "":
+			if t.assign && len(cur.args) == 0 {
+				// The value is not split and not expanded as a pattern
+				cur.assigns = append(cur.assigns, t.word)
+			} else {
 				cur.args = append(cur.args, expandWord(t)...)
+			}
 		case "|":
 			if isEmpty(cur) {
 				return nil, syntaxError("|")
@@ -1424,6 +1533,11 @@ func parsePipeline(tokens []token) ([]stage, error) {
 				return nil, syntaxError(next.op)
 			}
 			i++
+			if t.op == "<<<" {
+				// A here-string is not expanded as a pattern
+				cur.redirects = append(cur.redirects, redirect{op: t.op, fd: t.fd, file: tokens[i].word})
+				continue
+			}
 			files := expandWord(tokens[i])
 			if len(files) > 1 {
 				return nil, fmt.Errorf("%s: ambiguous redirect", sanitize(tokens[i].word))
@@ -1452,7 +1566,7 @@ func runPipeline(stages []stage, text string, background bool) error {
 		shellTTY, _ = readline.GetState(ttyFd)
 	}
 
-	stdin := os.Stdin
+	stdin := stdio(0)
 	if background && !jobControl {
 		// Without job control background jobs must not read from the
 		// terminal, like in sh
@@ -1462,12 +1576,12 @@ func runPipeline(stages []stage, text string, background bool) error {
 	}
 	var startErr error
 	for i, st := range stages {
-		stdout := os.Stdout
+		stdout := stdio(1)
 		var next *os.File
 		if i < len(stages)-1 {
 			r, w, err := os.Pipe()
 			if err != nil {
-				if stdin != os.Stdin {
+				if stdin != stdio(0) {
 					stdin.Close()
 				}
 				startErr = err
@@ -1507,10 +1621,10 @@ func runPipeline(stages []stage, text string, background bool) error {
 // longer needs them, so that the neighbors see EOF or get SIGPIPE.
 func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background bool) *proc {
 	var owned []*os.File
-	if stdin != os.Stdin {
+	if stdin != stdio(0) {
 		owned = append(owned, stdin)
 	}
-	if stdout != os.Stdout {
+	if stdout != stdio(1) {
 		owned = append(owned, stdout)
 	}
 	closeOwned := func() {
@@ -1523,16 +1637,39 @@ func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background
 	// the command would read from /dev/null, so interactive programs (su,
 	// vim, ssh, ...) would get EOF right away. readline only reads from stdin
 	// while a line is being edited, so it does not steal input.
-	fds := [3]*os.File{stdin, stdout, os.Stderr}
+	fds := [3]*os.File{stdin, stdout, stdio(2)}
 	opened, err := applyRedirects(&fds, st.redirects)
 	owned = append(owned, opened...)
-	if err != nil || len(st.args) == 0 {
+	if err == nil && len(st.args) == 0 && len(st.assigns) > 0 {
+		// Assignments without a command set variables of the shell (not in
+		// a pipeline or in the background, where sh runs them in a
+		// subshell). The status is the one of the last $(...) in them.
+		if !inPipeline && !background {
+			for _, a := range st.assigns {
+				name, value, _ := strings.Cut(a, "=")
+				os.Setenv(name, value)
+			}
+		}
+		if substStatus != 0 {
+			err = statusError(substStatus)
+		}
+	}
+	if err != nil || len(st.args) == 0 && st.script == "" {
 		// A command without arguments only creates or truncates the files
 		closeOwned()
 		return finishedProc(err)
 	}
 
-	if builtin, ok := builtins[st.args[0]]; ok {
+	var fn *funcDef
+	isFunc := false
+	if st.script == "" {
+		fn, isFunc = functions[st.args[0]]
+	}
+	if isFunc && !inPipeline && !background {
+		defer closeOwned()
+		return finishedProc(callFunction(fn, st.args, fds, st.assigns))
+	}
+	if builtin, ok := builtins[firstArg(st.args)]; !isFunc && st.script == "" && ok {
 		switch {
 		case inPipeline && builtin.changesState:
 			closeOwned()
@@ -1541,10 +1678,11 @@ func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background
 			closeOwned()
 			return finishedProc(fmt.Errorf("%s: cannot be run in the background", st.args[0]))
 		}
+		shellStderr := stdio(2)
 		run := func() error {
 			defer closeOwned()
-			err := runBuiltin(st.args, fds[1])
+			err := runBuiltin(st.args, fds[0], fds[1])
-			if err != nil && fds[2] != os.Stderr {
+			if err != nil && fds[2] != shellStderr {
 				// Report the error where stderr is redirected to
 				fmt.Fprintln(fds[2], "gosh:", err)
 				return statusError(1)
@@ -1552,6 +1690,12 @@ func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background
 			return err
 		}
 		if !inPipeline && !background {
+			// name=value before a builtin applies only while it runs, its
+			// redirections also to the commands it runs (source file > out)
+			defer setTemporarily(st.assigns)()
+			saved := ioOverride
+			ioOverride = fds
+			defer func() { ioOverride = saved }()
 			return finishedProc(run())
 		}
 		p := &proc{done: make(chan error, 1)}
@@ -1559,8 +1703,29 @@ func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background
 		return p
 	}
 
-	cmd := exec.Command(st.args[0], st.args[1:]...)
+	var cmd *exec.Cmd
+	if st.script != "" {
+		cmd, err = subshellCommand(st.script, positional)
+		if err != nil {
+			closeOwned()
+			return finishedProc(err)
+		}
+	} else if isFunc {
+		// A function in a pipeline or in the background runs in a subshell
+		cmd, err = subshellCommand(`"$@"`, st.args)
+		if err != nil {
+			closeOwned()
+			return finishedProc(err)
+		}
+	} else {
+		cmd = exec.Command(st.args[0], st.args[1:]...)
+	}
 	cmd.Stdin, cmd.Stdout, cmd.Stderr = fds[0], fds[1], fds[2]
+	if len(st.assigns) > 0 {
+		// name=value before a command is only in its environment (the
+		// last value of a name wins)
+		cmd.Env = append(os.Environ(), st.assigns...)
+	}
 	if jobControl {
 		// All processes of the job share a process group: the one of the
 		// first process. In the foreground, the first process makes its
@@ -1578,7 +1743,7 @@ func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background
 	// The child has its own copies of the files now
 	closeOwned()
 	if errors.Is(err, exec.ErrNotFound) {
-		err = fmt.Errorf("%s: %w", sanitize(st.args[0]), errCommandNotFound)
+		err = fmt.Errorf("%s: %w", sanitize(firstArg(st.args)), errCommandNotFound)
 	}
 	if err != nil {
 		return finishedProc(err)
@@ -1593,6 +1758,38 @@ func startStage(st stage, stdin, stdout *os.File, j *job, inPipeline, background
 	return &proc{cmd: cmd}
 }
 
+func firstArg(args []string) string {
+	if len(args) == 0 {
+		return ""
+	}
+	return args[0]
+}
+
+// setTemporarily sets the variables of the assignments and returns a
+// function that restores the previous values.
+func setTemporarily(assigns []string) func() {
+	type saved struct {
+		name, value string
+		ok          bool
+	}
+	var restore []saved
+	for _, a := range assigns {
+		name, value, _ := strings.Cut(a, "=")
+		old, ok := os.LookupEnv(name)
+		restore = append(restore, saved{name, old, ok})
+		os.Setenv(name, value)
+	}
+	return func() {
+		for i := len(restore) - 1; i >= 0; i-- {
+			if r := restore[i]; r.ok {
+				os.Setenv(r.name, r.value)
+			} else {
+				os.Unsetenv(r.name)
+			}
+		}
+	}
+}
+
 // applyRedirects applies the redirections in order to fds (stdin, stdout,
 // stderr) and returns the files it opened.
 func applyRedirects(fds *[3]*os.File, redirects []redirect) ([]*os.File, error) {
@@ -1616,6 +1813,16 @@ func applyRedirects(fds *[3]*os.File, redirects []redirect) ([]*os.File, error)
 			continue
 		}
 
+		if r.op == "<<<" {
+			f, err := hereFile(r.file + "\n")
+			if err != nil {
+				return fail(err)
+			}
+			opened = append(opened, f)
+			fds[r.fd] = f
+			continue
+		}
+
 		flags := os.O_WRONLY | os.O_CREATE | os.O_TRUNC
 		switch r.op {
 		case "<":
@@ -1641,6 +1848,26 @@ func applyRedirects(fds *[3]*os.File, redirects []redirect) ([]*os.File, error)
 	return opened, nil
 }
 
+// hereFile returns a file to read content from: a temporary file that is
+// already removed (like bash does for here-documents), so that large inputs
+// work and nothing is left behind.
+func hereFile(content string) (*os.File, error) {
+	f, err := os.CreateTemp("", "gosh-here-*")
+	if err != nil {
+		return nil, err
+	}
+	os.Remove(f.Name())
+	if _, err := f.WriteString(content); err != nil {
+		f.Close()
+		return nil, err
+	}
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		f.Close()
+		return nil, err
+	}
+	return f, nil
+}
+
 // builtins lists the built-in commands. Commands that change the state of
 // the shell cannot be used in a pipeline, since there they would run
 // concurrently (sh runs them in a subshell where they have no effect).
@@ -1661,12 +1888,18 @@ var builtins = map[string]struct{ changesState bool }{
 	"alias":    {},
 	"unalias":  {changesState: true},
 	":":        {},
+	"unset":    {changesState: true},
 	"break":    {changesState: true},
 	"continue": {changesState: true},
+	"return":   {changesState: true},
+	"local":    {changesState: true},
+	"shift":    {changesState: true},
+	"read":     {changesState: true},
 }
 
-// runBuiltin executes a built-in command, writing its output to stdout.
+// runBuiltin executes a built-in command, reading from stdin and writing its
-func runBuiltin(args []string, stdout io.Writer) error {
+// output to stdout.
+func runBuiltin(args []string, stdin *os.File, stdout io.Writer) error {
 	switch args[0] {
 	case "cd":
 		// Save current directory before changing (for 'cd -')
@@ -1719,6 +1952,11 @@ func runBuiltin(args []string, stdout io.Writer) error {
 		}
 		return exitShell(lastStatus)
 	case "set":
+		// set -- args: set the positional parameters
+		if len(args) > 1 && args[1] == "--" {
+			positional = slices.Clone(args[2:])
+			return nil
+		}
 		// set VAR=value - set environment variable
 		if len(args) < 2 {
 			return fmt.Errorf("usage: set VAR=value")
@@ -1745,8 +1983,39 @@ func runBuiltin(args []string, stdout io.Writer) error {
 	case ":":
 		// Does nothing, successfully (e.g. while :; do ...)
 		return nil
+	case "unset":
+		// unset [-v] NAME ... - remove variables, unset -f NAME ... - functions
+		names := args[1:]
+		funcs := len(names) > 0 && names[0] == "-f"
+		if len(names) > 0 && (names[0] == "-f" || names[0] == "-v") {
+			names = names[1:]
+		}
+		if len(names) == 0 {
+			return fmt.Errorf("usage: unset [-f|-v] NAME ...")
+		}
+		var err error
+		for _, name := range names {
+			if funcs {
+				delete(functions, name)
+				continue
+			}
+			if !isVarName(name) {
+				err = fmt.Errorf("unset: `%s': not a valid identifier", sanitize(name))
+				continue
+			}
+			os.Unsetenv(name)
+		}
+		return err
 	case "break", "continue":
 		return builtinLoopControl(args)
+	case "return":
+		return builtinReturn(args)
+	case "local":
+		return builtinLocal(args)
+	case "shift":
+		return builtinShift(args)
+	case "read":
+		return builtinRead(args, stdin)
 	case "alias":
 		return builtinAlias(args, stdout)
 	case "unalias":
@@ -1760,9 +2029,15 @@ func runBuiltin(args []string, stdout io.Writer) error {
 	case "wait":
 		return builtinWait(args)
 	case "source", ".":
-		// source file - run the commands of file in the current shell
+		// source file [args] - run the commands of file in the current shell
 		if len(args) < 2 {
-			return fmt.Errorf("usage: %s file", args[0])
+			return fmt.Errorf("usage: %s file [args ...]", args[0])
+		}
+		if len(args) > 2 {
+			// The arguments are the positional parameters while it runs
+			saved := positional
+			positional = slices.Clone(args[2:])
+			defer func() { positional = saved }()
 		}
 		return sourceFile(args[0], args[1])
 	case "help":
@@ -1775,8 +2050,10 @@ Built-in commands:
   exit [code]   - Exit shell with status code (default: $?)
   quit [code]   - Quit shell with status code (default: $?)
   set VAR=val   - Set environment variable
+  set -- args   - Set the positional parameters $1, $2, ...
   export VAR=val - Export environment variable
-  source file   - Run the commands of file in this shell (also: . file)
+  unset VAR     - Remove a variable (unset -f name: a function)
+  source file [args] - Run the commands of file in this shell (also: . file)
   jobs          - List background and stopped jobs
   fg [%n]       - Continue job n (default: current job) in the foreground
   bg [%n]       - Continue stopped job n in the background
@@ -1786,6 +2063,12 @@ Built-in commands:
   :             - Do nothing (exit status 0)
   break [n]     - Leave the innermost (or n-th) for/while/until loop
   continue [n]  - Continue with the next iteration of a loop
+  return [n]    - Leave a function or sourced file with status n
+  local VAR[=val] - Variable that gets its old value back when the
+                  function returns
+  shift [n]     - Remove the first n positional parameters (default 1)
+  read [-r] [-p prompt] [VAR ...] - Read a line into variables (split
+                  at $IFS; the last one gets the rest; default $REPLY)
   help          - Show this help
 
 Features:
@@ -1808,8 +2091,14 @@ Features:
     GOSH_COLORS='user=1;33:path=36' (keys user, root, path, error; values
     are ANSI SGR codes, empty = no color); disabled with $NO_COLOR,
     TERM=dumb or when output is not a terminal
+  - Variables: name=value sets a variable (like set), name=value command
+    sets it only for that command; the value is not split or expanded as
+    a pattern
   - Environment variable expansion ($VAR, ${VAR}, ${VAR:-default});
     using an unset variable is an error, use ${VAR:-} for an empty default
+  - Positional parameters: $0, $1 ... $9, ${10}, $# (count), "$@" (one
+    word each), "$*" (one word), $$ (process ID); set by gosh script
+    args, gosh -c command name args, functions, set -- and source
   - Command substitution: $(command) is replaced by the output of command
     (run in a subshell); unquoted it is split into words, "$(command)"
     stays one word
@@ -1817,9 +2106,16 @@ Features:
     a || b (b only if a failed); $? is the exit status of the last command
   - Control structures: if cmd; then ...; elif cmd; then ...; else ...; fi,
     for x in words; do ...; done, while cmd; do ...; done, until ...,
-    ! cmd negates the status; they can span several lines (prompt "> ")
+    case word in pattern|pattern) ...;; esac, { cmd; cmd; } groups,
+    ( cmd; cmd ) subshells; ! cmd negates the status; they can span
+    several lines (prompt "> "), have redirections (done < file) and can
+    be used in pipes (| while read l; do ...; done) and with &
+  - Functions: name() { ...; } (or function name { ...; }); the arguments
+    are $1, $2, ...; in pipes, & and $(...) they run in a subshell
   - Pipes (a | b) and redirections: < file, > file, >> file, 2> file,
-    2>> file, 2>&1, >&2, &> file (stdout and stderr), &>> file
+    2>> file, 2>&1, >&2, &> file (stdout and stderr), &>> file,
+    <<EOF here-documents (<<-EOF strips tabs, <<'EOF' expands nothing),
+    <<<word here-strings
   - Job control: command & runs in the background, Ctrl+Z stops the
     foreground job; jobs, fg, bg and wait manage the jobs
   - Aliases replace the first word of a command in interactive shells

main_test.go

@@ -941,7 +941,7 @@ func TestSplitWords(t *testing.T) {
 		{`echo x${GOSH_A}y`, []string{"echo", "xa by"}},
 		// Escaped and lone dollar signs stay literal
 		{`echo \$GOSH_A "\$GOSH_A"`, []string{"echo", "$GOSH_A", "$GOSH_A"}},
-		{`echo $ 5$ $1`, []string{"echo", "$", "5$", "$1"}},
+		{`echo $ 5$ $%`, []string{"echo", "$", "5$", "$%"}},
 		// Backslash in double quotes only escapes $ " \ and `
 		{`echo "a\nb\\c"`, []string{"echo", `a\nb\c`}},
 		// Defaults
@@ -1437,6 +1437,26 @@ func pipelineString(pl *pipelineNode) string {
 			s += "while "
 		}
 		s += treeString(n.cond) + " do " + treeString(n.body) + " done"
+	case *caseNode:
+		s += "case " + n.word + " in"
+		for _, c := range n.clauses {
+			s += " (" + strings.Join(c.patterns, "|") + ") " + treeString(c.body) + " ;;"
+		}
+		s += " esac"
+	case *groupNode:
+		s += "{ " + treeString(n.body) + " }"
+	case *subshellNode:
+		s += "(" + n.text + ")"
+	case *redirNode:
+		s += pipelineString(&pipelineNode{cmd: n.cmd}) + " <" + n.redirs + ">"
+	case *pipeNode:
+		var elems []string
+		for _, e := range n.elems {
+			elems = append(elems, "<"+e.text+">")
+		}
+		s += strings.Join(elems, " | ")
+	case *funcDefNode:
+		s += n.def.name + "() " + pipelineString(&pipelineNode{cmd: n.def.body})
 	}
 	return s
 }
@@ -1504,6 +1524,27 @@ func TestParse_ControlStructures(t *testing.T) {
 		{"while a; do if b; then break; fi; done", "while [a] do if [b] then [break] fi done"},
 		{"for i in 1 2; do for j in 3 4; do echo $i$j; done; done", "for i in (1 2) do for j in (3 4) do [echo $i$j] done done"},
 		{"if a; then if b; then c; fi fi", "if [a] then if [b] then [c] fi fi"},
+		// Compound commands in pipelines, with redirections, in the background
+		{"for x in a; do b; done | cat", "<for x in a; do b; done> | <cat>"},
+		{"a | while b; do c; done | d", "<a> | <while b; do c; done> | <d>"},
+		{"if a; then b; fi > out 2>&1", "if [a] then [b] fi <> out 2>&1>"},
+		{"while read l; do b; done < in", "while [read l] do [b] done << in>"},
+		{"{ a; b; } 2> err", "{ [a]; [b] } <2> err>"},
+		{"for x in a; do b; done &", "for x in (a) do [b] done &"},
+		{"a && b &", "[a] && [b] &"},
+		// Subshells
+		{"(a; b)", "(a; b)"},
+		{"( a ) | b", "<( a )> | <b>"},
+		{"(a) > f", "(a) <> f>"},
+		{"(a; (b)) && c", "(a; (b)) && [c]"},
+		// case, groups and functions
+		{"case $x in a|b) c;; (d) e; f;; esac", "case $x in (a|b) [c] ;; (d) [e]; [f] ;; esac"},
+		{"case x in\n  a)\n    b\n    ;;\nesac", "case x in (a) [b] ;; esac"},
+		{"{ a; }", "{ [a] }"},
+		{"f() { a; }", "f() { [a] }"},
+		{"f ( ) { a; }", "f() { [a] }"},
+		{"function f { a; }", "f() { [a] }"},
+		{"f() (a)", "f() (a)"},
 	}
 	for _, tc := range tests {
 		tree, err := parse(tc.input)
@@ -1522,6 +1563,8 @@ func TestParse_Incomplete(t *testing.T) {
 		"if a", "if a; then", "if a; then b", "if a; then b; else", "if a; then b; elif c",
 		"for x", "for x in a b", "for x in a; do", "for x in a; do b",
 		"while a", "while a; do b", "until a; do",
+		"(a", "(a; b", "{ a;", "case x in", "case x in a) b;;", "f() {", "f()",
+		"cat <<EOF", "cat <<EOF\nbody", "cat <<'EOF'\nbody\nEO",
 		"a &&", "a ||", "a |", "echo 'open", `echo "open`, "echo $(a", "echo a \\",
 	} {
 		if _, err := parse(input); !errors.Is(err, errIncomplete) {
@@ -1536,6 +1579,9 @@ func TestParse_SyntaxErrors(t *testing.T) {
 		"fi", "then", "done", "if a; then fi", "if ; then a; fi", "while a; do done",
 		"if a; then b; done", "for 1x in a; do b; done", "for x in a do b; done; x",
 		"a | | b", "| a",
+		"()", "a (", "a )", "echo (a)", ")", "(a) b", "if a; then b; fi c", "{ a; } b",
+		"case x in a b) c;; esac", "case x in ) a;; esac", "cat <<", "cat << ;",
+		"f() { a; } | b",
 	} {
 		_, err := parse(input)
 		if err == nil || errors.Is(err, errIncomplete) {
@@ -1543,11 +1589,9 @@ func TestParse_SyntaxErrors(t *testing.T) {
 		}
 	}
 	for input, want := range map[string]string{
-		"for x in a; do b; done | cat": "control structures in pipelines are not supported",
+		"f() { a; } | b":     "function definitions in pipelines are not supported",
-		"echo | while a; do b; done":   "control structures in pipelines are not supported",
+		"f() { a; } > out":   "redirections of function definitions are not supported",
-		"if a; then b; fi > out":       "redirections of control structures are not supported (near `>')",
+		"if a; then b; fi c": "syntax error near unexpected token `c'",
-		"for x in a; do b; done &":     "only simple commands and pipelines can run in the background",
-		"a && b &":                     "only simple commands and pipelines can run in the background",
 	} {
 		if _, err := parse(input); err == nil || err.Error() != want {
 			t.Errorf("parse(%q) = %v, want %q", input, err, want)
@@ -1674,7 +1718,7 @@ func TestTokenize_Operators(t *testing.T) {
 		}
 		// Patterns are tested in TestTokenize_Patterns
 		for i := range got {
-			got[i].pattern, got[i].glob = "", false
+			got[i].pattern, got[i].glob, got[i].assign = "", false, false
 		}
 		if !reflect.DeepEqual(got, tc.want) {
 			t.Errorf("tokenize(%q) = %+v, want %+v", tc.input, got, tc.want)

packaging/man/gosh.1

@@ -0,0 +1,678 @@
+.\" Man page for gosh. View with: man ./packaging/man/gosh.1
+.\" @VERSION@ is replaced by the release version when building packages.
+.TH GOSH 1 "October 2026" "gosh @VERSION@" "User Commands"
+.SH NAME
+gosh \- a simple shell written in Go
+.SH SYNOPSIS
+.B gosh
+.RB [ \-l ]
+.RB [ \-i ]
+.RB [ \-\-norc ]
+.RB [ \-\-noprofile ]
+.RI [ script
+.RI [ args " ...]]"
+.br
+.B gosh
+.RB [ \-l ]
+.RB [ \-\-noprofile ]
+.B \-c
+.I command
+.RI [ name
+.RI [ args " ...]]"
+.br
+.B gosh
+.B \-version
+.SH DESCRIPTION
+.B gosh
+is a small command interpreter with a syntax close to
+.BR sh (1).
+It supports command history, tab completion, variables, positional
+parameters, command substitution, command lists, control structures,
+functions, pipes, redirections, wildcards, brace expansion, aliases and job
+control.
+.PP
+Without arguments and with a terminal on standard input,
+.B gosh
+starts an interactive shell. With a
+.I script
+argument it runs the commands of that file, with
+.B \-c
+the given command string, and otherwise it reads commands from standard
+input. The
+.I args
+after the script, or after the
+.I name
+of
+.BR \-c ,
+become the positional parameters
+.BR $1 ,
+.BR $2 ", ..."
+.PP
+.B gosh
+is a proof of concept and not meant for production use.
+.SH OPTIONS
+.TP
+.B \-c \fIcommand\fP [\fIname\fP [\fIargs\fP ...]]
+Run
+.I command
+and exit.
+.I name
+becomes
+.BR $0 ,
+the
+.I args
+become
+.BR $1 ,
+.BR $2 ", ..."
+.TP
+.B \-i
+Force interactive mode, even if standard input is not a terminal.
+.TP
+.BR \-l ", " \-\-login
+Act as a login shell and read the profile files (see
+.BR "STARTUP FILES" ).
+A shell whose
+.I argv[0]
+starts with
+.B \-
+(as started by
+.BR login (1),
+.BR sshd (8)
+or
+.BR "su \-" )
+is a login shell as well.
+.TP
+.B \-\-norc
+Do not read the goshrc files.
+.TP
+.B \-\-noprofile
+Do not read the profile files.
+.TP
+.BR \-version ", " \-\-version ", " \-V
+Print the version, branch and commit and exit.
+.TP
+.BR \-h ", " \-\-help
+Print a usage summary and exit.
+.TP
+.B \-
+Read commands from standard input.
+.SH NON-INTERACTIVE USE
+Scripts, command strings and commands read from a pipe are executed line
+by line. Empty lines and lines starting with
+.B #
+are skipped, so a script may start with
+.BR "#!/usr/bin/gosh" .
+A failing command does not abort the script; the exit status of
+.B gosh
+is the one of the last command.
+.PP
+Because
+.B gosh
+supports
+.BR \-c ,
+.BR ssh (1),
+.BR scp (1)
+and
+.BR rsync (1)
+work when it is used as login shell.
+.SH STARTUP FILES
+Startup files are executed in the running shell, so variables and
+aliases defined there stay in effect.
+.TP
+Login shells
+read
+.I /etc/gosh/profile
+and
+.IR ~/.gosh_profile .
+.TP
+Interactive shells
+read
+.I /etc/gosh/goshrc
+and
+.IR ~/.goshrc .
+.PP
+An interactive login shell reads the profile files first, then the goshrc
+files. Scripts and
+.B \-c
+read no startup files unless
+.B gosh
+is a login shell. Missing files are skipped; errors are reported with file
+name and line number and the remaining lines still run. Files of other
+shells such as
+.I /etc/profile
+or
+.I ~/.bashrc
+are not read.
+.SH SYNTAX
+.SS Quoting
+.TP
+.B \(aq...\(aq
+Everything is literal.
+.TP
+.B \(dq...\(dq
+Variables and command substitutions are expanded, the result stays one
+word.
+.TP
+.B \e
+Escapes the next character.
+.SS Variables
+.TP
+.I name\fB=\fPvalue
+Set a variable. All variables are exported to the environment of started
+programs. The value is not split into words and not expanded as a pattern;
+variables, command substitutions and
+.B ~
+(at the start, after
+.B =
+and after
+.BR : )
+are expanded.
+.TP
+.I name\fB=\fPvalue command
+Set the variable only for
+.IR command .
+.TP
+.BR $VAR ", " ${VAR}
+The value of
+.BR VAR .
+Using an unset variable is an error and aborts the command.
+.TP
+.B ${VAR:\-default}
+The value of
+.BR VAR ,
+or
+.I default
+if it is unset or empty. Use
+.B ${VAR:\-}
+for an empty default.
+.TP
+.B $?
+The exit status of the last command.
+.SS Positional parameters
+.TP
+.B $0
+The name of the script, or the
+.I name
+given after
+.BR "gosh \-c" .
+.TP
+.BR $1 " ... " $9 ", " ${10}
+The arguments of the script, of
+.BR "gosh \-c" ,
+of a function call or of
+.BR source ,
+or the words set with
+.BR "set \-\-" .
+An unset parameter is an error like an unset variable; use
+.B ${1:\-}
+for an optional argument.
+.TP
+.B $#
+The number of positional parameters.
+.TP
+.B \(dq$@\(dq
+All positional parameters, each as a separate word. Without parameters it
+expands to no word at all.
+.TP
+.B \(dq$*\(dq
+All positional parameters as one word, separated by blanks.
+.TP
+.B $$
+The process ID of the shell.
+.SS Command substitution
+.B $(\fIcommand\fP)
+is replaced by the output of
+.IR command ,
+which runs in a subshell. Trailing newlines are removed. Unquoted, the
+output is split into words at blanks and newlines; inside double quotes it
+stays one word. Wildcards and operators in the output are not interpreted.
+Backticks and arithmetic expansion are not supported.
+.SS Tilde and brace expansion
+.B ~
+and
+.B ~/path
+at the start of an unquoted word are replaced by the home directory.
+.PP
+Brace expansion generates several words from one:
+.B a{b,c}d
+becomes
+.BR "abd acd" ,
+.B {1..5}
+becomes
+.BR "1 2 3 4 5" ,
+.B {01..10..4}
+becomes
+.B 01 05 09
+and
+.B {a..e}
+becomes
+.BR "a b c d e" .
+Brace expansion happens before all other expansions.
+.SS Wildcards
+.B *
+matches any string,
+.B ?
+any single character,
+.B [abc]
+and
+.B [a\-z]
+one of the given characters and
+.B [!abc]
+(or
+.BR [^abc] )
+any character except those. Matches are sorted. Hidden files are only
+matched if the pattern starts with a dot. A pattern without match is kept
+unchanged. Quoted wildcards and values of variables are never expanded.
+.SS Command lists
+.TP
+.IB a " ; " b
+Run
+.IR a ,
+then
+.IR b .
+.TP
+.IB a " && " b
+Run
+.I b
+only if
+.I a
+succeeded.
+.TP
+.IB a " || " b
+Run
+.I b
+only if
+.I a
+failed.
+.TP
+.IB command " &"
+Run
+.I command
+in the background.
+.SS Pipes and redirections
+.TP
+.IB a " | " b
+Connect standard output of
+.I a
+to standard input of
+.IR b .
+The exit status is the one of
+.IR b .
+.TP
+.BI < " file"
+Read standard input from
+.IR file .
+.TP
+.BR > " \fIfile\fP, " >> " \fIfile\fP"
+Write (or append) standard output to
+.IR file .
+.TP
+.BR 2> " \fIfile\fP, " 2>> " \fIfile\fP"
+Write (or append) standard error to
+.IR file .
+.TP
+.B 2>&1
+Redirect standard error to where standard output goes.
+.TP
+.B >&2
+Redirect standard output to where standard error goes.
+.TP
+.BR &> " \fIfile\fP, " &>> " \fIfile\fP"
+Write (or append) standard output and standard error to
+.IR file .
+.TP
+.BI << word
+Here-document: the lines after the command, up to a line that is exactly
+.IR word ,
+are standard input. If no part of
+.I word
+is quoted, variables, command substitutions and backslashes before
+.BR $ ,
+.BR \(ga ,
+.B \e
+and newline are expanded in the lines.
+.BI <<\- word
+also removes leading tabs from the lines and the delimiter line.
+.TP
+.BI <<< " word"
+Here-string:
+.I word
+and a newline are standard input.
+.PP
+Redirections are evaluated from left to right. Only file descriptors 0, 1
+and 2 are supported.
+.SS Control structures
+.nf
+\fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; [\fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP;] [\fBelse\fP \fIlist\fP;] \fBfi\fP
+\fBfor\fP \fIname\fP \fBin\fP \fIwords\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
+\fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
+\fBuntil\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
+\fBcase\fP \fIword\fP \fBin\fP [\fB(\fP]\fIpattern\fP[\fB|\fP\fIpattern\fP]...\fB)\fP \fIlist\fP \fB;;\fP ... \fBesac\fP
+\fB{\fP \fIlist\fP; \fB}\fP
+\fB(\fP \fIlist\fP \fB)\fP
+\fB!\fP \fIcommand\fP
+.fi
+.PP
+Control structures may span several lines; an incomplete command shows
+the continuation prompt
+.BR "> " .
+.B !
+negates the exit status of a command.
+.B for
+without
+.B in
+loops over the positional parameters.
+.PP
+.B case
+runs the list of the first clause with a pattern that matches
+.IR word .
+Patterns are wildcards as for file names, but
+.B *
+and
+.B ?
+also match a
+.BR / ;
+quoted characters match literally, and values of variables are not
+patterns. The
+.B ;;
+of the last clause may be omitted.
+.PP
+.B {
+.IR list ;
+.B }
+groups commands; they run in the current shell.
+.B (
+.I list
+.B )
+runs the commands in a subshell, a new
+.B gosh
+process, so that changes of the directory, variables and functions only
+apply there.
+.PP
+Redirections after a control structure
+.RB ( "done < file" ,
+.BR "fi > log 2>&1" )
+apply to all commands in it, which still run in the current shell. In a
+pipe and in the background
+.RB ( & ),
+a control structure runs in a subshell, like in
+.BR sh (1).
+The subshell knows the functions and positional parameters of the shell.
+.SS Functions
+.nf
+\fIname\fP\fB() {\fP \fIlist\fP; \fB}\fP
+\fBfunction\fP \fIname\fP \fB{\fP \fIlist\fP; \fB}\fP
+.fi
+.PP
+defines a function; the body can be any compound command. When the
+function is called, its arguments are the positional parameters, which get
+their old values back afterwards. Functions run in the current shell, so
+variables they set stay set; use
+.B local
+for variables that belong to the function. Redirections of a call apply to
+all commands of the function. In pipes, in the background and in
+.B $(...)
+a function runs in a subshell that knows all functions. Functions take
+precedence over builtins and programs of the same name. Calls can be nested
+up to a depth of 1000.
+.SS Aliases
+In interactive shells, the first word of a command is replaced by its
+alias. If the alias value ends with a blank, the next word is checked for
+an alias as well.
+.B \e\fIname\fP
+or
+.B \(aq\fIname\fP\(aq
+skips the alias. Aliases are not used in scripts and with
+.BR \-c .
+.SH BUILTIN COMMANDS
+.TP
+.BR cd " [\fIdir\fP]"
+Change the directory; without argument to the home directory.
+.TP
+.B pwd
+Print the working directory.
+.TP
+.BR echo " [\fIargs\fP]"
+Print the arguments.
+.TP
+.BR exit " [\fIcode\fP], " quit " [\fIcode\fP]"
+Exit the shell with status
+.I code
+(default:
+.BR $? ).
+.TP
+.BI set " VAR" = value
+Set a variable.
+.TP
+.BR "set \-\-" " [\fIargs\fP ...]"
+Set the positional parameters.
+.TP
+.BI export " VAR" = value
+Export a variable.
+.TP
+.BR unset " [\fB\-v\fP] \fIVAR\fP ..., " "unset \-f" " \fIname\fP ..."
+Remove variables, or functions.
+.TP
+.BR source " \fIfile\fP [\fIargs\fP ...], " . " \fIfile\fP [\fIargs\fP ...]"
+Run the commands of
+.I file
+in the current shell, with
+.I args
+as positional parameters if given.
+.TP
+.B jobs
+List background and stopped jobs.
+.TP
+.BR fg " [\fB%\fP\fIn\fP]"
+Continue job
+.I n
+(default: the current job) in the foreground.
+.TP
+.BR bg " [\fB%\fP\fIn\fP]"
+Continue stopped job
+.I n
+in the background.
+.TP
+.BR wait " [\fB%\fP\fIn\fP]"
+Wait for job
+.I n
+or for all background jobs.
+.TP
+.BR alias " [\fIname\fP[\fB=\fP\fIvalue\fP] ...]"
+Define or show aliases.
+.TP
+.BR unalias " \fIname\fP, " "unalias \-a"
+Remove an alias, or all aliases.
+.TP
+.B :
+Do nothing, exit status 0.
+.TP
+.BR break " [\fIn\fP], " continue " [\fIn\fP]"
+Leave the innermost (or
+.IR n -th)
+loop, or continue with its next iteration.
+.TP
+.BR return " [\fIn\fP]"
+Leave a function or sourced file with status
+.I n
+(default:
+.BR $? ).
+.TP
+.BR local " \fIVAR\fP[\fB=\fP\fIvalue\fP] ..."
+In a function: the variable gets its previous value back when the function
+returns. Without a value it is unset.
+.TP
+.BR shift " [\fIn\fP]"
+Remove the first
+.I n
+(default 1) positional parameters.
+.TP
+.BR read " [\fB\-r\fP] [\fB\-p\fP \fIprompt\fP] [\fIVAR\fP ...]"
+Read a line from standard input and split it into fields at the
+characters of
+.B IFS
+(default blank, tab and newline). Each
+.I VAR
+gets one field, the last one the rest of the line; without
+.I VAR
+the whole line is stored in
+.BR REPLY .
+Without
+.BR \-r ,
+a backslash escapes the next character and continues the line at its end.
+.B \-p
+prints
+.I prompt
+if the input is a terminal. The exit status is 1 at the end of the input.
+.TP
+.B help
+Show a summary of builtins and features.
+.SH JOB CONTROL
+In interactive shells, each command line runs as a job in its own process
+group.
+.B Ctrl+Z
+stops the foreground job,
+.B Ctrl+C
+interrupts it.
+.BR jobs ,
+.BR fg ,
+.B bg
+and
+.B wait
+manage the jobs;
+.B %n
+or
+.I n
+refers to job
+.IR n ,
+.B %\-
+to the previous job. Finished background jobs are reported before the
+next prompt. Exiting with stopped jobs warns once.
+.SH INTERACTIVE USE
+.TP
+.B Up/Down
+Browse the command history.
+.TP
+.B Tab
+Complete commands, aliases and file names.
+.TP
+.B Ctrl+C
+Cancel the current line or command.
+.TP
+.B Ctrl+D
+Exit the shell.
+.PP
+Lines starting with a space are not saved in the history.
+.PP
+The prompt shows
+.IR user @ host : dir
+followed by
+.BR $ .
+If the last command failed, its exit status is shown as
+.BI [ N ]
+before the
+.BR $ .
+.SH ENVIRONMENT
+.TP
+.B GOSH_HISTFILE
+Path of the history file. If set to an empty value, no history is saved.
+.TP
+.B XDG_STATE_HOME
+Base directory of the default history file
+.IR $XDG_STATE_HOME/gosh/history .
+.TP
+.B GOSH_COLORS
+Prompt colors as colon-separated
+.IB key = code
+entries. Keys are
+.B user
+(default
+.BR 1;32 ),
+.B root
+.RB ( 1;31 ),
+.B path
+.RB ( 1;34 )
+and
+.B error
+.RB ( 1;31 );
+values are ANSI SGR codes, an empty value disables the color. Example:
+.B GOSH_COLORS=\(aquser=1;33:path=36\(aq
+.TP
+.B NO_COLOR
+If set, the prompt is not colored. Colors are also disabled with
+.B TERM=dumb
+or when the output is not a terminal.
+.TP
+.B HOME
+Used for
+.B ~
+and
+.B cd
+without argument.
+.TP
+.B PATH
+Directories searched for commands.
+.TP
+.B IFS
+Field separators for
+.BR read .
+.SH FILES
+.TP
+.I /etc/gosh/profile
+System-wide profile for login shells.
+.TP
+.I ~/.gosh_profile
+Personal profile for login shells.
+.TP
+.I /etc/gosh/goshrc
+System-wide startup file for interactive shells.
+.TP
+.I ~/.goshrc
+Personal startup file for interactive shells.
+.TP
+.I ~/.local/state/gosh/history
+Default history file (mode 0600).
+.SH EXIT STATUS
+The exit status of the last command, or the argument of
+.BR exit .
+Typical values:
+.TP
+.B 1
+General error.
+.TP
+.B 2
+Syntax error or invalid option.
+.TP
+.B 126
+Command not executable.
+.TP
+.B 127
+Command not found.
+.TP
+.BI 128+ n
+Command terminated by signal
+.I n
+(130 for Ctrl+C).
+.SH EXAMPLES
+.nf
+gosh \-c \(aqcd /srv && git log | head\(aq
+for f in *.log; do gzip "$f"; done
+cp config.yaml{,.bak}
+make > build.log 2>&1 || echo "failed: $?"
+LANG=C sort file
+alias ll=\(aqls \-l\(aq
+greet() { echo "Hello ${1:\-World}"; }
+git ls\-files | while read \-r f; do wc \-l "$f"; done
+while read \-r user rest; do echo "$user"; done < /etc/passwd
+(cd build && make) > build.log 2>&1
+case "$1" in start|stop) echo "$1ing" ;; *) echo "usage: $0 start|stop" ;; esac
+read \-r \-p \(aqName? \(aq name
+chsh \-s /usr/bin/gosh
+.fi
+.SH SEE ALSO
+.BR sh (1),
+.BR bash (1),
+.BR chsh (1),
+.BR shells (5)
+.SH AUTHOR
+Florian Walther <florian.walther@certainity.com>

parser.go

@@ -1,8 +1,8 @@
 package main
 
 // Parser and executor for command lines and scripts: lists (; & && || and
-// newlines), pipelines, ! and the control structures if, for, while and
+// newlines), pipelines, ! and the compound commands if, for, while, until,
-// until. Simple commands (with their pipes and redirections) are kept as
+// case, { ...; } and ( ... ), and function definitions. Simple commands (with their pipes and redirections) are kept as
 // text; they are expanded and run by execCommand only when they are
 // executed, so that e.g. the variable of a for loop is expanded anew in
 // every iteration.
@@ -11,6 +11,8 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"path"
+	"slices"
 	"strconv"
 	"strings"
 	"syscall"
@@ -48,7 +50,13 @@ var aliasExpansion = true
 
 // reserved words that end a list; they are only recognized as the first word
 // of a command.
-var terminators = map[string]bool{"then": true, "elif": true, "else": true, "fi": true, "do": true, "done": true}
+var terminators = map[string]bool{
+	"then": true, "elif": true, "else": true, "fi": true, "do": true, "done": true,
+	"esac": true, "}": true,
+}
+
+// compoundStarts are the reserved words that start a compound command.
+var compoundStarts = map[string]bool{"if": true, "for": true, "while": true, "until": true, "case": true, "{": true}
 
 // ---------------------------------------------------------------------------
 // Lexer
@@ -57,7 +65,7 @@ type tokenKind int
 
 const (
 	tWord tokenKind = iota
-	tOp             // ; & && || | or newline
+	tOp             // ; ;; & && || | ( ) or newline
 )
 
 type rawToken struct {
@@ -126,6 +134,9 @@ func lex(src string) ([]rawToken, error) {
 		switch {
 		case ch == ' ' || ch == '\t':
 			i++
+		case ch == ';' && next == ';':
+			op(";;", i)
+			i += 2
 		case ch == '\n' || ch == ';':
 			op(string(ch), i)
 			i++
@@ -137,7 +148,7 @@ func lex(src string) ([]rawToken, error) {
 		case ch == '|' && next == '|', ch == '&' && next == '&':
 			op(src[i:i+2], i)
 			i += 2
-		case ch == '|', ch == '&' && next != '>':
+		case ch == '|', ch == '&' && next != '>', ch == '(', ch == ')':
 			op(string(ch), i)
 			i++
 		default:
@@ -167,6 +178,12 @@ func lexWord(src string, i int) (int, error) {
 				return 0, errIncomplete
 			}
 			j++
+			if isSubstStart(src, j) {
+				// \$(...) is literal text, but its ( and ) belong to the word
+				if end := substEnd(src, j); end >= 0 {
+					j = end
+				}
+			}
 		case isSubstStart(src, j):
 			end := substEnd(src, j)
 			if end < 0 {
@@ -183,7 +200,7 @@ func lexWord(src string, i int) (int, error) {
 			}
 		case ch == '"' || ch == '\'':
 			quote = ch
-		case ch == ' ' || ch == '\t' || ch == '\n' || ch == ';' || ch == '|':
+		case ch == ' ' || ch == '\t' || ch == '\n' || ch == ';' || ch == '|' || ch == '(' || ch == ')':
 			return j, nil
 		case ch == '&':
 			// &>, >& and <& are redirections, not the & operator
@@ -221,6 +238,7 @@ type listEntry struct {
 type andOrNode struct {
 	first *pipelineNode
 	rest  []andOrPart
+	text  string // the source, to run it in a subshell in the background
 }
 
 type andOrPart struct {
@@ -228,8 +246,8 @@ type andOrPart struct {
 	pipeline *pipelineNode
 }
 
-// pipelineNode is a simple command (whose text may contain a pipeline) or a
+// pipelineNode is a pipeline (a simpleNode or pipeNode) or a single
-// control structure, optionally negated with !.
+// compound command, optionally negated with !.
 type pipelineNode struct {
 	negate bool
 	cmd    node
@@ -240,6 +258,33 @@ type simpleNode struct {
 	text string
 }
 
+// pipeNode is a pipeline that contains compound commands. Like all commands
+// of a pipeline in sh, they run in subshells (new gosh processes), since
+// the commands of a pipeline run concurrently.
+type pipeNode struct {
+	elems []pipeElem
+	text  string
+}
+
+type pipeElem struct {
+	text     string // the source of the command, with its redirections
+	compound bool
+	subshell string // for ( list ): the list, which runs in the subshell directly
+}
+
+// redirNode is a compound command with redirections; they apply to all
+// commands in it.
+type redirNode struct {
+	cmd    node
+	redirs string // the source text of the redirections
+}
+
+// subshellNode is ( list ): the list runs in a new gosh process, so that it
+// cannot change the shell.
+type subshellNode struct {
+	text string // the source of the list
+}
+
 type ifNode struct {
 	conds    []*listNode
 	bodies   []*listNode
@@ -259,6 +304,27 @@ type whileNode struct {
 	body  *listNode
 }
 
+// caseNode is case word in pattern|pattern) list ;; ... esac.
+type caseNode struct {
+	word    string // expanded when the case command runs
+	clauses []caseClause
+}
+
+type caseClause struct {
+	patterns []string // expanded when they are tried
+	body     *listNode
+}
+
+// groupNode is { list; }.
+type groupNode struct {
+	body *listNode
+}
+
+// funcDefNode is a function definition name() compound-command.
+type funcDefNode struct {
+	def *funcDef
+}
+
 // singleSimple returns the simple command if the list is just that.
 func (l *listNode) singleSimple() *simpleNode {
 	if len(l.items) != 1 || l.items[0].background {
@@ -284,6 +350,10 @@ type parser struct {
 // parse parses a command line or script. It returns errIncomplete if the
 // input ends inside a construct.
 func parse(src string) (*listNode, error) {
+	src, err := extractHeredocs(src)
+	if err != nil {
+		return nil, err
+	}
 	src, continued := joinContinuationLines(src)
 	if continued {
 		return nil, errIncomplete
@@ -356,7 +426,7 @@ func (p *parser) parseList(terms map[string]bool) (*listNode, error) {
 	for {
 		p.skipNewlines()
 		t := p.peek()
-		if t == nil || t.kind == tWord && terms[t.text] {
+		if t == nil || terms[t.text] {
 			return list, nil
 		}
 		ao, err := p.parseAndOr()
@@ -371,16 +441,12 @@ func (p *parser) parseList(terms map[string]bool) (*listNode, error) {
 		case t.kind == tOp && (t.text == ";" || t.text == "&" || t.text == "\n"):
 			p.pos++
 			entry.background = t.text == "&"
-		case t.kind == tWord && terms[t.text]:
+		case terms[t.text]:
-			// e.g. "fi" right after the end of a nested control structure
+			// e.g. "fi" right after the end of a nested control structure,
+			// or ;; after a command in a case clause
 		default:
 			return nil, p.unexpected(t)
 		}
-		if entry.background {
-			if _, ok := ao.first.cmd.(*simpleNode); !ok || len(ao.rest) > 0 || ao.first.negate {
-				return nil, errors.New("only simple commands and pipelines can run in the background")
-			}
-		}
 		list.items = append(list.items, entry)
 	}
 }
@@ -397,6 +463,7 @@ func (p *parser) nonEmpty(list *listNode) error {
 }
 
 func (p *parser) parseAndOr() (*andOrNode, error) {
+	start := p.peek().start
 	first, err := p.parsePipeline()
 	if err != nil {
 		return nil, err
@@ -405,6 +472,7 @@ func (p *parser) parseAndOr() (*andOrNode, error) {
 	for {
 		t := p.peek()
 		if t == nil || t.kind != tOp || (t.text != "&&" && t.text != "||") {
+			ao.text = p.src[start:p.toks[p.pos-1].end]
 			return ao, nil
 		}
 		p.pos++
@@ -420,79 +488,188 @@ func (p *parser) parseAndOr() (*andOrNode, error) {
 	}
 }
 
+// parsePipeline parses [!] command [| command]... A pipeline of simple
+// commands stays one simpleNode (its text is split into the commands when it
+// runs); a pipeline with compound commands becomes a pipeNode.
 func (p *parser) parsePipeline() (*pipelineNode, error) {
 	pl := &pipelineNode{}
 	if p.peekWord("!") {
 		pl.negate = true
 		p.pos++
 	}
+	var (
+		elems []pipeElem
+		cmds  []node
+		start = -1
+	)
+	for {
 		t := p.peek()
 		if t == nil {
 			return nil, errIncomplete
 		}
-	if t.kind == tOp || terminators[t.text] {
+		if t.kind == tOp && t.text != "(" || t.kind == tWord && terminators[t.text] {
 			return nil, p.unexpected(t)
 		}
-
+		if start < 0 {
-	var err error
+			start = t.start
-	compound := true
-	switch t.text {
-	case "if":
-		pl.cmd, err = p.parseIf()
-	case "for":
-		pl.cmd, err = p.parseFor()
-	case "while", "until":
-		pl.cmd, err = p.parseWhile()
-	default:
-		compound = false
-		pl.cmd, err = p.parseSimple()
 		}
+		cmd, compound, err := p.parseCommand()
 		if err != nil {
 			return nil, err
 		}
+		elem := pipeElem{text: p.src[t.start:p.toks[p.pos-1].end], compound: compound}
+		if sub, ok := cmd.(*subshellNode); ok {
+			elem.subshell = sub.text
+		}
+		elems = append(elems, elem)
+		cmds = append(cmds, cmd)
 
-	if compound {
+		if t := p.peek(); t == nil || t.kind != tOp || t.text != "|" {
-		if t := p.peek(); t != nil {
+			break
+		}
+		p.pos++
+		p.skipNewlines()
+		if p.peek() == nil {
+			return nil, errIncomplete
+		}
+	}
+
+	text := p.src[start:p.toks[p.pos-1].end]
+	compound := false
+	for i, e := range elems {
+		if _, ok := cmds[i].(*funcDefNode); ok && len(elems) > 1 {
+			return nil, errors.New("function definitions in pipelines are not supported")
+		}
+		compound = compound || e.compound
+	}
 	switch {
-			case t.kind == tOp && t.text == "|":
+	case len(elems) == 1:
-				return nil, errors.New("control structures in pipelines are not supported")
+		pl.cmd = cmds[0]
-			case t.kind == tWord && !terminators[t.text]:
+	case !compound:
-				return nil, fmt.Errorf("redirections of control structures are not supported (near `%s')", t.text)
+		pl.cmd = &simpleNode{text: text}
-			}
+	default:
-		}
+		pl.cmd = &pipeNode{elems: elems, text: text}
 	}
 	return pl, nil
 }
 
-// parseSimple parses a pipeline of simple commands and returns its text.
+// parseCommand parses a simple command, a compound command with its
+// redirections or a function definition, and reports whether it is not a
+// simple command.
+func (p *parser) parseCommand() (node, bool, error) {
+	t := p.peek()
+	start := t.start
+	if name, ok := p.funcDefName(); ok {
+		def, err := p.parseFuncDef(name, start)
+		if err != nil {
+			return nil, true, err
+		}
+		if t := p.peek(); t != nil && t.kind == tWord && !terminators[t.text] {
+			return nil, true, errors.New("redirections of function definitions are not supported")
+		}
+		return def, true, nil
+	}
+	if !isCompoundStart(t) {
+		cmd, err := p.parseSimple()
+		return cmd, false, err
+	}
+	cmd, err := p.parseCompound()
+	if err != nil {
+		return nil, true, err
+	}
+	redirs, err := p.parseRedirections()
+	if err != nil {
+		return nil, true, err
+	}
+	if redirs != "" {
+		cmd = &redirNode{cmd: cmd, redirs: redirs}
+	}
+	return cmd, true, nil
+}
+
+// isCompoundStart reports whether a compound command starts at t.
+func isCompoundStart(t *rawToken) bool {
+	return t.kind == tWord && compoundStarts[t.text] || t.kind == tOp && t.text == "("
+}
+
+// parseRedirections parses the redirections after a compound command and
+// returns their source text (expanded when the command runs).
+func (p *parser) parseRedirections() (string, error) {
+	start, end := -1, -1
+	for t := p.peek(); t != nil && t.kind == tWord && !terminators[t.text]; t = p.peek() {
+		needsTarget, ok := redirectionWord(t.text)
+		if !ok {
+			return "", syntaxError(t.text)
+		}
+		if start < 0 {
+			start = t.start
+		}
+		end = t.end
+		p.pos++
+		if needsTarget {
+			t = p.peek()
+			if t == nil || t.kind != tWord {
+				if t == nil {
+					return "", syntaxError("newline")
+				}
+				return "", p.unexpected(t)
+			}
+			end = t.end
+			p.pos++
+		}
+	}
+	if start < 0 {
+		return "", nil
+	}
+	return p.src[start:end], nil
+}
+
+// redirectionWord reports whether word starts with a redirection operator
+// (optionally after a file descriptor), and whether the target is the next
+// word (2> file instead of 2>file).
+func redirectionWord(word string) (needsTarget, ok bool) {
+	w := strings.TrimLeft(word, "0123456789")
+	for _, op := range []string{"&>>", "&>", "<<<", ">>", ">&", "<&", ">", "<"} {
+		if strings.HasPrefix(w, op) {
+			if op[0] == '&' && len(w) != len(word) {
+				return false, false
+			}
+			return w == op, true
+		}
+	}
+	return false, false
+}
+
+// parseSimple parses a simple command (without pipes) and returns its text.
 func (p *parser) parseSimple() (*simpleNode, error) {
 	start := p.toks[p.pos].start
 	end := start
-	for t := p.peek(); t != nil; t = p.peek() {
+	for t := p.peek(); t != nil && t.kind == tWord; t = p.peek() {
-		if t.kind == tWord {
 		end = t.end
 		p.pos++
-			continue
-		}
-		if t.text != "|" {
-			break
-		}
-		p.pos++
-		end = t.end
-		p.skipNewlines()
-		next := p.peek()
-		switch {
-		case next == nil:
-			return nil, errIncomplete
-		case next.kind == tOp || terminators[next.text]:
-			return nil, p.unexpected(next)
-		case next.text == "if" || next.text == "for" || next.text == "while" || next.text == "until":
-			return nil, errors.New("control structures in pipelines are not supported")
-		}
 	}
 	return &simpleNode{text: p.src[start:end]}, nil
 }
 
+// parseCompound parses the compound command that starts at the current
+// token.
+func (p *parser) parseCompound() (node, error) {
+	switch p.peek().text {
+	case "if":
+		return p.parseIf()
+	case "for":
+		return p.parseFor()
+	case "while", "until":
+		return p.parseWhile()
+	case "case":
+		return p.parseCase()
+	case "(":
+		return p.parseSubshell()
+	default: // {
+		return p.parseGroup()
+	}
+}
+
 func (p *parser) parseIf() (*ifNode, error) {
 	p.pos++ // if
 	n := &ifNode{}
@@ -604,6 +781,167 @@ func (p *parser) parseWhile() (*whileNode, error) {
 	return n, nil
 }
 
+// parseGroup parses { list; }.
+func (p *parser) parseGroup() (*groupNode, error) {
+	p.pos++ // {
+	body, err := p.parseList(map[string]bool{"}": true})
+	if err == nil {
+		err = p.nonEmpty(body)
+	}
+	if err == nil {
+		err = p.expect("}")
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &groupNode{body: body}, nil
+}
+
+// parseSubshell parses ( list ).
+func (p *parser) parseSubshell() (*subshellNode, error) {
+	p.pos++ // (
+	start := p.toks[p.pos-1].end
+	body, err := p.parseList(map[string]bool{")": true})
+	if err == nil {
+		err = p.nonEmpty(body)
+	}
+	if err != nil {
+		return nil, err
+	}
+	t := p.peek()
+	if t == nil {
+		return nil, errIncomplete
+	}
+	if t.kind != tOp || t.text != ")" {
+		return nil, p.unexpected(t)
+	}
+	p.pos++
+	return &subshellNode{text: p.src[start:t.start]}, nil
+}
+
+// parseCase parses case word in [(]pattern[|pattern]...) list ;; ... esac.
+// The last clause may omit the ;;.
+func (p *parser) parseCase() (*caseNode, error) {
+	p.pos++ // case
+	t := p.peek()
+	if t == nil {
+		return nil, errIncomplete
+	}
+	if t.kind != tWord {
+		return nil, p.unexpected(t)
+	}
+	n := &caseNode{word: t.text}
+	p.pos++
+	p.skipNewlines()
+	if err := p.expect("in"); err != nil {
+		return nil, err
+	}
+	for {
+		p.skipNewlines()
+		t := p.peek()
+		if t == nil {
+			return nil, errIncomplete
+		}
+		if t.kind == tWord && t.text == "esac" {
+			p.pos++
+			return n, nil
+		}
+		patterns, err := p.parsePatterns()
+		if err != nil {
+			return nil, err
+		}
+		body, err := p.parseList(map[string]bool{";;": true, "esac": true})
+		if err != nil {
+			return nil, err
+		}
+		n.clauses = append(n.clauses, caseClause{patterns: patterns, body: body})
+		if t := p.peek(); t == nil {
+			return nil, errIncomplete
+		} else if t.text == ";;" {
+			p.pos++
+		}
+	}
+}
+
+// parsePatterns parses the patterns of a case clause up to and including the
+// ).
+func (p *parser) parsePatterns() ([]string, error) {
+	if t := p.peek(); t.kind == tOp && t.text == "(" {
+		p.pos++ // the optional ( before the first pattern
+	}
+	var patterns []string
+	for {
+		t := p.peek()
+		if t == nil {
+			return nil, errIncomplete
+		}
+		if t.kind != tWord {
+			return nil, p.unexpected(t)
+		}
+		patterns = append(patterns, t.text)
+		p.pos++
+		t = p.peek()
+		switch {
+		case t == nil:
+			return nil, errIncomplete
+		case t.kind == tOp && t.text == "|":
+			p.pos++
+		case t.kind == tOp && t.text == ")":
+			p.pos++
+			return patterns, nil
+		default:
+			return nil, p.unexpected(t)
+		}
+	}
+}
+
+// funcDefName reports whether a function definition starts at the current
+// token: name(), or function name [()]. It consumes the tokens up to the
+// body.
+func (p *parser) funcDefName() (string, bool) {
+	start := p.pos
+	if t := p.peek(); t.kind != tWord {
+		return "", false
+	} else if t.text == "function" {
+		p.pos++
+		if t := p.peek(); t == nil || t.kind != tWord || !isFuncName(t.text) {
+			p.pos = start
+			return "", false
+		}
+	}
+	name := p.peek().text
+	isOp := func(i int, text string) bool {
+		return i < len(p.toks) && p.toks[i].kind == tOp && p.toks[i].text == text
+	}
+	switch {
+	case isOp(p.pos+1, "(") && isOp(p.pos+2, ")") && isFuncName(name):
+		p.pos += 3
+	case p.pos > start:
+		p.pos++ // function name
+	default:
+		return "", false
+	}
+	return name, true
+}
+
+// parseFuncDef parses the body of a function definition that started at
+// src[start]: a compound command.
+func (p *parser) parseFuncDef(name string, start int) (*funcDefNode, error) {
+	p.skipNewlines()
+	t := p.peek()
+	if t == nil {
+		return nil, errIncomplete
+	}
+	if !isCompoundStart(t) {
+		return nil, fmt.Errorf("%s: the body of a function must be a compound command like { ...; }", sanitize(name))
+	}
+	body, err := p.parseCompound()
+	if err != nil {
+		return nil, err
+	}
+	return &funcDefNode{def: &funcDef{name: name, body: body, text: p.src[start:p.toks[p.pos-1].end]}}, nil
+}
+
 // parseLoopBody parses "do list done".
 func (p *parser) parseLoopBody() (*listNode, error) {
 	if err := p.expect("do"); err != nil {
@@ -623,11 +961,14 @@ func (p *parser) parseLoopBody() (*listNode, error) {
 // Execution
 
 // isAbort reports whether err stops the execution of the enclosing lists:
-// break, continue, or a command that was interrupted with Ctrl+C (like in
+// break, continue, return, or a command that was interrupted with Ctrl+C
-// bash, Ctrl+C aborts the whole command line, e.g. a loop).
+// (like in bash, Ctrl+C aborts the whole command line, e.g. a loop).
 func isAbort(err error) bool {
-	var lc loopControl
+	var (
-	return errors.As(err, &lc) || exitStatus(err) == 128+int(syscall.SIGINT)
+		lc  loopControl
+		ret returnSignal
+	)
+	return errors.As(err, &lc) || errors.As(err, &ret) || exitStatus(err) == 128+int(syscall.SIGINT)
 }
 
 // silent returns an error with only the exit status of err, for errors that
@@ -644,7 +985,7 @@ func (l *listNode) exec() error {
 	for _, entry := range l.items {
 		printError(err)
 		if entry.background {
-			err = entry.andOr.first.cmd.(*simpleNode).run(true)
+			err = entry.andOr.runBackground()
 		} else {
 			err = entry.andOr.exec()
 		}
@@ -672,6 +1013,22 @@ func (a *andOrNode) exec() error {
 	return err
 }
 
+// runBackground starts the and-or list as a background job. Pipelines run
+// like in the foreground, everything else in a subshell.
+func (a *andOrNode) runBackground() error {
+	if len(a.rest) == 0 && !a.first.negate {
+		switch cmd := a.first.cmd.(type) {
+		case *simpleNode:
+			return cmd.run(true)
+		case *pipeNode:
+			return cmd.run(true)
+		case *subshellNode:
+			return runPipeline([]stage{{script: cmd.text}}, a.text, true)
+		}
+	}
+	return runPipeline([]stage{{script: a.text}}, a.text, true)
+}
+
 func (pl *pipelineNode) exec() error {
 	err := pl.cmd.exec()
 	if !pl.negate || isAbort(err) {
@@ -779,7 +1136,8 @@ func (n *whileNode) exec() error {
 }
 
 func (n *forNode) exec() error {
-	var words []string
+	// Without "in", the loop runs over the positional parameters
+	words := slices.Clone(positional)
 	if n.hasIn {
 		var err error
 		if words, err = expandWordList(n.words); err != nil {
@@ -804,6 +1162,144 @@ func (n *forNode) exec() error {
 	return result
 }
 
+func (n *groupNode) exec() error {
+	return n.body.exec()
+}
+
+func (n *subshellNode) exec() error {
+	return runPipeline([]stage{{script: n.text}}, "("+strings.TrimSpace(n.text)+")", false)
+}
+
+// exec runs the compound command with stdin, stdout and stderr of the shell
+// redirected.
+func (n *redirNode) exec() error {
+	fds, opened, err := openRedirections(n.redirs)
+	if err != nil {
+		return err
+	}
+	saved := ioOverride
+	ioOverride = fds
+	defer func() {
+		ioOverride = saved
+		for _, f := range opened {
+			f.Close()
+		}
+	}()
+	return n.cmd.exec()
+}
+
+func (n *pipeNode) exec() error {
+	return n.run(false)
+}
+
+// run builds the stages of the pipeline: simple commands are expanded,
+// compound commands run in subshells.
+func (n *pipeNode) run(background bool) error {
+	substStatus = 0
+	var stages []stage
+	for _, e := range n.elems {
+		switch {
+		case e.subshell != "":
+			stages = append(stages, stage{script: e.subshell})
+		case e.compound:
+			stages = append(stages, stage{script: e.text})
+		default:
+			text := e.text
+			if interactiveShell && aliasExpansion {
+				if tree, err := parse(expandAliases(text)); err == nil {
+					if simple := tree.singleSimple(); simple != nil {
+						text = simple.text
+					}
+				}
+			}
+			st, err := expandStages(text)
+			if err != nil {
+				return err
+			}
+			if len(st) == 0 {
+				st = []stage{{}}
+			}
+			stages = append(stages, st...)
+		}
+	}
+	return runPipeline(stages, n.text, background)
+}
+
+func (n *funcDefNode) exec() error {
+	defineFunction(n.def)
+	return nil
+}
+
+// exec runs the body of the first clause with a pattern that matches the
+// word. The status is 0 if no pattern matches.
+func (n *caseNode) exec() error {
+	word, err := expandCaseWord(n.word)
+	if err != nil {
+		return err
+	}
+	for _, clause := range n.clauses {
+		for _, pattern := range clause.patterns {
+			ok, err := caseMatch(pattern, word)
+			if err != nil {
+				return err
+			}
+			if ok {
+				return clause.body.exec()
+			}
+		}
+	}
+	lastStatus = 0
+	return nil
+}
+
+// expandCaseWord expands the word of a case command: like an argument, but
+// without brace expansion, wildcards and splitting.
+func expandCaseWord(text string) (string, error) {
+	tokens, err := tokenize(text)
+	if err != nil {
+		return "", fmt.Errorf("invalid input: %w", err)
+	}
+	var words []string
+	for _, t := range tokens {
+		if t.op != "" {
+			return "", syntaxError(t.op)
+		}
+		words = append(words, t.word)
+	}
+	return strings.Join(words, " "), nil
+}
+
+// caseMatch reports whether word matches the pattern of a case clause. The
+// pattern is expanded first; quoted characters in it match literally. Unlike
+// for file names, * and ? also match a /.
+func caseMatch(pattern, word string) (bool, error) {
+	tokens, err := tokenize(pattern)
+	if err != nil {
+		return false, fmt.Errorf("invalid input: %w", err)
+	}
+	var literal, glob []string
+	isGlob := false
+	for _, t := range tokens {
+		if t.op != "" {
+			return false, syntaxError(t.op)
+		}
+		literal = append(literal, t.word)
+		glob = append(glob, t.pattern)
+		isGlob = isGlob || t.glob
+	}
+	if !isGlob {
+		return word == strings.Join(literal, " "), nil
+	}
+	// path.Match does not let * match a /; NUL can be in neither string
+	toNUL := strings.NewReplacer("/", "\x00")
+	ok, err := path.Match(toNUL.Replace(strings.Join(glob, " ")), toNUL.Replace(word))
+	if err != nil {
+		// An invalid pattern only matches itself
+		return word == strings.Join(literal, " "), nil
+	}
+	return ok, nil
+}
+
 // expandWordList expands the words of a for loop like the arguments of a
 // command (braces, ~, variables, $(...), wildcards).
 func expandWordList(text string) ([]string, error) {

read.go

@@ -0,0 +1,215 @@
+package main
+
+// The read builtin: read [-r] [-p prompt] [name ...] reads a line and splits
+// it into fields at the characters of $IFS (default: blank, tab, newline).
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	"github.com/chzyer/readline"
+	"golang.org/x/sys/unix"
+)
+
+// builtinRead implements read. Each name gets one field, the last one the
+// rest of the line; without names the whole line is stored in $REPLY. The
+// status is 1 at the end of the input.
+func builtinRead(args []string, stdin *os.File) error {
+	raw := false
+	prompt := ""
+	args = args[1:]
+	for len(args) > 0 && strings.HasPrefix(args[0], "-") && args[0] != "-" {
+		opt := args[0]
+		args = args[1:]
+		if opt == "--" {
+			break
+		}
+		for k := 1; k < len(opt); k++ {
+			switch opt[k] {
+			case 'r':
+				raw = true
+			case 'p':
+				switch {
+				case k+1 < len(opt):
+					prompt = opt[k+1:]
+				case len(args) > 0:
+					prompt, args = args[0], args[1:]
+				default:
+					return errors.New("read: -p: option requires an argument")
+				}
+				k = len(opt)
+			default:
+				return fmt.Errorf("read: -%c: invalid option\nusage: read [-r] [-p prompt] [name ...]", opt[k])
+			}
+		}
+	}
+	for _, name := range args {
+		if !isVarName(name) {
+			return fmt.Errorf("read: `%s': not a valid identifier", sanitize(name))
+		}
+	}
+
+	terminal := readline.IsTerminal(int(stdin.Fd()))
+	if prompt != "" && terminal {
+		fmt.Fprint(stdio(2), prompt)
+	}
+	line, literal, eof, err := readInputLine(stdin, raw, interactiveShell && terminal)
+	if err != nil {
+		return err
+	}
+
+	if len(args) == 0 {
+		os.Setenv("REPLY", line)
+	} else {
+		ifs, ok := os.LookupEnv("IFS")
+		if !ok {
+			ifs = " \t\n"
+		}
+		fields := splitFields(line, literal, ifs, len(args))
+		for i, name := range args {
+			value := ""
+			if i < len(fields) {
+				value = fields[i]
+			}
+			os.Setenv(name, value)
+		}
+	}
+	if eof {
+		return statusError(1)
+	}
+	return nil
+}
+
+// readInputLine reads a line from f, byte by byte so that nothing after the
+// line is consumed. Unless raw is set, a backslash escapes the next
+// character (literal marks the escaped characters, which never split
+// fields) and backslash-newline continues the line. eof reports that the
+// input ended before a newline. If interruptible is set, Ctrl+C aborts the
+// read with status 130.
+func readInputLine(f *os.File, raw, interruptible bool) (line string, literal []bool, eof bool, err error) {
+	readByte := plainByteReader(f)
+	if interruptible {
+		intr := make(chan os.Signal, 1)
+		signal.Notify(intr, os.Interrupt)
+		defer signal.Stop(intr)
+		readByte = interruptibleByteReader(f, intr)
+	}
+
+	var b []byte
+	for {
+		c, err := readByte()
+		if err == io.EOF {
+			return string(b), literal, true, nil
+		}
+		if err != nil {
+			return "", nil, false, err
+		}
+		if c == '\n' {
+			return string(b), literal, false, nil
+		}
+		if c == '\\' && !raw {
+			c, err = readByte()
+			if err == io.EOF {
+				return string(b), literal, true, nil
+			}
+			if err != nil {
+				return "", nil, false, err
+			}
+			if c == '\n' {
+				continue // the line goes on
+			}
+			b = append(b, c)
+			literal = append(literal, true)
+			continue
+		}
+		b = append(b, c)
+		literal = append(literal, false)
+	}
+}
+
+func plainByteReader(f *os.File) func() (byte, error) {
+	buf := make([]byte, 1)
+	return func() (byte, error) {
+		for {
+			n, err := f.Read(buf)
+			if n == 1 {
+				return buf[0], nil
+			}
+			if err != nil {
+				return 0, err
+			}
+		}
+	}
+}
+
+// interruptibleByteReader reads from the terminal f only when input is
+// available, so that a SIGINT on intr can end the read in between.
+func interruptibleByteReader(f *os.File, intr chan os.Signal) func() (byte, error) {
+	next := plainByteReader(f)
+	fds := []unix.PollFd{{Fd: int32(f.Fd()), Events: unix.POLLIN}}
+	return func() (byte, error) {
+		for {
+			select {
+			case <-intr:
+				fmt.Fprintln(stdio(2))
+				return 0, statusError(128 + int(syscall.SIGINT))
+			default:
+			}
+			n, err := unix.Poll(fds, 100)
+			if err != nil && !errors.Is(err, unix.EINTR) {
+				return 0, err
+			}
+			if n > 0 {
+				return next()
+			}
+		}
+	}
+}
+
+// splitFields splits line into at most n fields like read does: IFS
+// whitespace (blank, tab, newline in ifs) around fields is removed, other IFS
+// characters separate fields (also empty ones). The last field is the rest of
+// the line. Characters marked in literal are never separators.
+func splitFields(line string, literal []bool, ifs string, n int) []string {
+	isSep := func(i int) bool { return !literal[i] && strings.IndexByte(ifs, line[i]) >= 0 }
+	isSpace := func(i int) bool { return isSep(i) && strings.IndexByte(" \t\n", line[i]) >= 0 }
+
+	start, end := 0, len(line)
+	for start < end && isSpace(start) {
+		start++
+	}
+	for end > start && isSpace(end-1) {
+		end--
+	}
+
+	var fields []string
+	i := start
+	for i < end && len(fields) < n-1 {
+		j := i
+		for j < end && !isSep(j) {
+			j++
+		}
+		fields = append(fields, line[i:j])
+		// The separator: whitespace, at most one other IFS character,
+		// whitespace
+		for j < end && isSpace(j) {
+			j++
+		}
+		if j < end && isSep(j) && !isSpace(j) {
+			j++
+			for j < end && isSpace(j) {
+				j++
+			}
+		}
+		i = j
+	}
+	if i < end {
+		fields = append(fields, line[i:end])
+	}
+	return fields
+}

subst.go

@@ -2,7 +2,8 @@ package main
 
 // Command substitution: $(command) is replaced by the output of command,
 // which runs in a subshell (a new gosh process), so that cd, set etc. in it
-// do not change the shell.
+// do not change the shell. Functions also run in a subshell in pipelines and
+// in the background.
 
 import (
 	"bytes"
@@ -67,24 +68,34 @@ func substEnd(s string, i int) int {
 	return -1
 }
 
+// subshellCommand returns a command that runs script in a new gosh process
+// with the same $0, the given positional parameters and the functions of the
+// shell. (Variables need not be passed: they are all in the environment.)
+func subshellCommand(script string, params []string) (*exec.Cmd, error) {
+	path := subshellPath
+	if path == "" {
+		var err error
+		if path, err = os.Executable(); err != nil {
+			return nil, err
+		}
+	}
+	args := append([]string{"-c", functionDefs() + script, scriptName}, params...)
+	return exec.Command(path, args...), nil
+}
+
 // commandSubst runs command in a subshell and returns its output without
 // trailing newlines. stdin and stderr are those of the shell.
 func commandSubst(command string) (string, error) {
 	if strings.HasPrefix(command, "(") {
 		return "", errors.New("arithmetic expansion $((...)) is not supported")
 	}
-	path := subshellPath
+	var out bytes.Buffer
-	if path == "" {
+	cmd, err := subshellCommand(command, positional)
-		var err error
+	if err != nil {
-		if path, err = os.Executable(); err != nil {
 		return "", err
 	}
-	}
+	cmd.Stdin, cmd.Stdout, cmd.Stderr = stdio(0), &out, stdio(2)
-
+	err = cmd.Run()
-	var out bytes.Buffer
-	cmd := exec.Command(path, "-c", command)
-	cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, &out, os.Stderr
-	err := cmd.Run()
 	substStatus = exitStatus(err)
 	if substStatus == 128+int(syscall.SIGINT) {
 		// Ctrl+C aborts the whole command, like in bash