add functions, positional parameters, case and read

- functions: name() { ...; }, function name { ...; }, return, local,
  unset -f; in pipes, & and $(...) they run in a subshell that gets all
  function definitions and the positional parameters
- positional parameters $0, $1 ... ${10}, $#, "$@", "$*", $$; set by
  gosh script args, gosh -c command name args, function calls,
  source file args and set --; shift; for x without "in"
- case word in pattern|pattern) ...;; esac and { list; } groups
- read [-r] [-p prompt] [name ...] with $IFS splitting and $REPLY

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

packaging/man/gosh.1

@@ -9,13 +9,16 @@ gosh \- a simple shell written in Go
 .RB [ \-i ]
 .RB [ \-\-norc ]
 .RB [ \-\-noprofile ]
-.RI [ script ]
+.RI [ script
+.RI [ args " ...]]"
 .br
 .B gosh
 .RB [ \-l ]
 .RB [ \-\-noprofile ]
 .B \-c
 .I command
+.RI [ name
+.RI [ args " ...]]"
 .br
 .B gosh
 .B \-version
@@ -23,9 +26,10 @@ gosh \- a simple shell written in Go
 .B gosh
 is a small command interpreter with a syntax close to
 .BR sh (1).
-It supports command history, tab completion, variables, command
-substitution, command lists, control structures, pipes, redirections,
-wildcards, brace expansion, aliases and job control.
+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
@@ -34,16 +38,32 @@ starts an interactive shell. With a
 argument it runs the commands of that file, with
 .B \-c
 the given command string, and otherwise it reads commands from standard
-input.
+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
+.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.
@@ -168,6 +188,37 @@ 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
@@ -278,6 +329,8 @@ and 2 are supported.
 \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 \fIcommand\fP
 .fi
 .PP
@@ -285,10 +338,52 @@ Control structures may span several lines; an incomplete command shows
 the continuation prompt
 .BR "> " .
 .B !
-negates the exit status of a command. Control structures cannot be used
-in pipes, with redirections or in the background.
+negates the exit status of a command.
+.B for
+without
+.B in
+loops over the positional parameters.
+.PP
 .B case
-and functions are not supported.
+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.
+.PP
+Control structures cannot be used in pipes, with redirections or in the
+background, and there are no
+.B ( ... )
+subshells.
+.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
@@ -318,16 +413,21 @@ Exit the shell with status
 .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
-.BI unset " VAR"
-Remove a variable.
+.BR unset " [\fB\-v\fP] \fIVAR\fP ..., " "unset \-f" " \fIname\fP ..."
+Remove variables, or functions.
 .TP
-.BI source " file\fR, \fP" ". " file
+.BR source " \fIfile\fP [\fIargs\fP ...], " . " \fIfile\fP [\fIargs\fP ...]"
 Run the commands of
 .I file
-in the current shell.
+in the current shell, with
+.I args
+as positional parameters if given.
 .TP
 .B jobs
 List background and stopped jobs.
@@ -361,6 +461,39 @@ 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
@@ -448,6 +581,10 @@ without argument.
 .TP
 .B PATH
 Directories searched for commands.
+.TP
+.B IFS
+Field separators for
+.BR read .
 .SH FILES
 .TP
 .I /etc/gosh/profile
@@ -493,6 +630,9 @@ 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}"; }
+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