pagedmov/shed
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implemented the 'help' builtin, and support for :h <topic> in ex mode

Browse Source 
:h is an alias for the 'help' builtin.

'help' takes a single argument and tries to find a suitable match among the files in '$SHED_HPATH'

if a match is found, this file is opened in your pager

calling the 'help' builtin using :h in ex mode will preserve your current pending line
This commit is contained in:
pagedmov
2026-03-15 18:18:53 -04:00
parent f6a3935bcb
commit 99b9440ee1
18 changed files with 1080 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
doc/arith.txt Normal file
View File

@@ -0,0 +1,76 @@
*arith* *arithmetic* *arithmetic-expansion*
#ARITHMETIC EXPANSION#
Arithmetic expansion evaluates a mathematical expression and substitutes
the result. The expression is subject to parameter expansion and command
substitution before evaluation.
`$((expression))`
Example:
`echo $((2 + 3))` # prints: 5
`x=$((width * height))`
==============================================================================
1. Operators *arith-operators*
The following operators are supported, listed from highest to lowest
precedence:
`( )` *arith-parens*
Grouping. Override default precedence.
Example:
`echo $(( (2+3) * 4 ))` # prints: 20
`*` `/` `%` *arith-muldivmod*
Multiplication, division, and modulo (remainder).
Example:
`echo $((10 / 3))` # prints: 3
`echo $((10 % 3))` # prints: 1
`+` `-` *arith-addsub*
Addition and subtraction.
Example:
`echo $((10 - 3 + 1))` # prints: 8
==============================================================================
2. Variables in Expressions *arith-variables*
Variables can be referenced by name inside arithmetic expressions.
They are expanded and converted to numbers.
`x=10`
`echo $(($x + 5))` # prints: 15
`echo $((x + 5))` # also works
If a variable is unset or not a valid number, an error is reported.
==============================================================================
3. Nesting *arith-nesting*
Arithmetic expressions can be nested with parentheses to any depth:
`echo $(( (1+2) * (3+4) ))` # prints: 21
Arithmetic expansion can also appear inside other expansions:
`echo "Total: $((price * qty))"`
==============================================================================
4. Whitespace *arith-whitespace*
Whitespace inside `$((...))` is ignored and can be used freely for
readability:
`echo $((2+3))` # prints: 5
`echo $(( 2 + 3 ))` # same result
==============================================================================
See also: |param| |redirect| |glob|

155
doc/glob.txt Normal file
View File

@@ -0,0 +1,155 @@
*glob* *globbing* *pathname-expansion* *filename-expansion*
#PATHNAME EXPANSION#
After word splitting, the shell scans each word for the characters `*`,
`?`, and `[`. If any appear (and are not quoted), the word is treated as a
pattern and replaced with an alphabetically sorted list of matching file
names. If no files match, the pattern is left unchanged.
==============================================================================
1. Wildcards *glob-wildcards*
`*` *glob-star*
Matches any string of zero or more characters, except that it does
not match a leading `.` (see |glob-dotglob|) or a `/`.
Example:
`echo *.txt` # all .txt files
`ls src/*.rs` # all .rs files in src/
`?` *glob-question*
Matches exactly one character, with the same restrictions as `*`.
Example:
`ls file?.txt` # file1.txt, fileA.txt, etc.
`[...]` *glob-bracket*
Matches any one of the enclosed characters. A range can be specified
with a hyphen.
`[abc]` matches `a`, `b`, or `c`
`[a-z]` matches any lowercase letter
`[0-9]` matches any digit
`[A-Za-z]` matches any letter
`[!...]` `[^...]` *glob-bracket-negate*
Matches any character NOT in the set.
Example:
`ls [!.]*.txt` # .txt files not starting with dot
`echo file[^0-9].txt` # files without a digit
==============================================================================
2. Hidden Files *glob-dotglob*
By default, patterns do not match files whose names begin with `.`
(hidden files). A leading dot must be matched explicitly:
`echo .*` # only hidden files
`echo .* *` # hidden and non-hidden files
The `dotglob` shell option changes this behavior:
`shopt core.dotglob true`
When enabled, `*` and `?` will also match files starting with `.`.
==============================================================================
3. Brace Expansion *brace* *brace-expansion*
Brace expansion is performed before globbing and generates multiple
words from a single pattern. It is not a POSIX feature.
`{a,b,c}` *brace-list*
Comma-separated list. Each item becomes a separate word.
Example:
`echo {a,b,c}` # prints: a b c
`echo file.{txt,log}` # prints: file.txt file.log
`mkdir -p src/{bin,lib}`
`{N..M}` *brace-range*
Numeric or character range.
Example:
`echo {1..5}` # prints: 1 2 3 4 5
`echo {a..f}` # prints: a b c d e f
`echo {5..1}` # prints: 5 4 3 2 1
`{N..M..S}` *brace-range-step*
Numeric range with step {S}.
Example:
`echo {0..10..2}` # prints: 0 2 4 6 8 10
`echo {1..20..5}` # prints: 1 6 11 16
`{01..10}` *brace-range-pad*
Zero-padded ranges. If either endpoint has leading zeros, all
generated values are padded to the same width.
Example:
`echo {01..05}` # prints: 01 02 03 04 05
`echo {001..3}` # prints: 001 002 003
Brace expansion can be nested and combined with other expansions:
`echo {a,b{1..3},c}` # prints: a b1 b2 b3 c
==============================================================================
4. Quoting and Escaping *glob-quoting*
Glob characters lose their special meaning when quoted:
`echo "*"` # prints literal *
`echo '*.txt'` # prints literal *.txt
`echo \*` # prints literal *
This is important when passing patterns to commands like `find` or
`grep` where you want the command (not the shell) to interpret the
pattern.
==============================================================================
5. Tilde Expansion *tilde* *tilde-expansion*
Tilde expansion is performed before pathname expansion.
`~` *tilde-home*
Expands to the value of `$HOME`.
`~/path` *tilde-home-path*
Expands `~` to `$HOME`, then appends the path.
Example:
`cd ~/projects`
`ls ~/.config`
`~user` *tilde-user*
Expands to the home directory of {user}.
Example:
`ls ~root` # /root
`cat ~nobody/.profile`
`~uid` *tilde-uid*
Expands to the home directory of the user with numeric uid {uid}.
This is a shed-specific extension.
Example:
`echo ~0` # /root (uid 0)
`echo ~1000` # first normal user's home
==============================================================================
See also: |param| |redirect| |arith|

197
doc/param.txt Normal file
View File

@@ -0,0 +1,197 @@
*param* *parameter-expansion* *param-expansion*
#PARAMETER EXPANSION#
The shell provides several forms of parameter expansion for working with
variables. In each form, {word} is subject to tilde expansion, parameter
expansion, command substitution, and arithmetic expansion.
If {parameter} is unset or null, the behavior depends on the operator used.
"Unset" means the variable has never been assigned. "Null" means the variable
is set but its value is the empty string.
==============================================================================
1. Basic Forms *param-basic*
`$var` Value of {var}
`${var}` Same, with explicit braces (needed for `${var}foo`)
Braces are required when {var} is followed by characters that could be part
of the name, or when using any of the operators below.
==============================================================================
2. Default Values *param-default*
`${var:-word}` *param-default-val*
Use default value. If {var} is unset or null, expand to {word}.
Otherwise, expand to the value of {var}.
Example:
`name=${1:-world}`
`echo "hello $name"` # prints "hello world" if \$1 is unset
`${var-word}` *param-default-nonnull*
Like `:-` but only substitutes {word} if {var} is completely unset,
not if it is null.
==============================================================================
3. Assign Defaults *param-assign*
`${var:=word}` *param-assign-val*
Assign default value. If {var} is unset or null, assign {word} to
{var} and then expand to the new value.
Note: This cannot be used with positional parameters or special
parameters.
Example:
`echo ${cache:=/tmp/cache}` # sets and uses \$cache
`${var=word}` *param-assign-nonnull*
Like `:=` but only assigns if {var} is completely unset.
==============================================================================
4. Error on Unset *param-error*
`${var:?word}` *param-error-val*
Display error. If {var} is unset or null, print {word} to stderr
and exit (in a non-interactive shell). If {word} is omitted, a
default message is printed.
Example:
`input=${1:?usage: myscript \<filename\>}`
`${var?word}` *param-error-nonnull*
Like `:?` but only errors if {var} is completely unset.
==============================================================================
5. Alternate Value *param-alt*
`${var:+word}` *param-alt-val*
Use alternate value. If {var} is unset or null, expand to nothing.
Otherwise, expand to {word}.
Example:
`echo ${verbose:+--verbose}` # flag only if \$verbose is set
`${var+word}` *param-alt-nonnull*
Like `:+` but substitutes {word} only if {var} is set (even if null).
==============================================================================
6. String Length *param-length*
`${#var}` *param-strlen*
Expands to the length of the value of {var} in characters.
Example:
`str="hello"`
`echo ${#str}` # prints 5
==============================================================================
7. Substring Removal *param-substring*
`${var#pattern}` *param-trim-short-left*
Remove shortest matching prefix. Removes the shortest match of
{pattern} from the beginning of the value of {var}.
`${var##pattern}` *param-trim-long-left*
Remove longest matching prefix.
Example:
`path="/home/user/file.txt"`
`echo ${path##*/}` # prints "file.txt"
`${var%pattern}` *param-trim-short-right*
Remove shortest matching suffix. Removes the shortest match of
{pattern} from the end of the value of {var}.
`${var%%pattern}` *param-trim-long-right*
Remove longest matching suffix.
Example:
`file="archive.tar.gz"`
`echo ${file%%.*}` # prints "archive"
`echo ${file%.*}` # prints "archive.tar"
==============================================================================
8. Search and Replace *param-replace*
`${var/pattern/replacement}` *param-replace-first*
Replace first match. Replaces the first occurrence of {pattern}
in the value of {var} with {replacement}.
`${var//pattern/replacement}` *param-replace-all*
Replace all matches.
Example:
`str="hello world"`
`echo ${str/o/0}` # prints "hell0 world"
`echo ${str//o/0}` # prints "hell0 w0rld"
`${var/#pattern/replacement}` *param-replace-prefix*
Replace if matching at the beginning.
`${var/%pattern/replacement}` *param-replace-suffix*
Replace if matching at the end.
==============================================================================
9. Case Modification *param-case*
`${var^}` *param-upper-first*
Uppercase the first character of {var}.
`${var^^}` *param-upper-all*
Uppercase all characters.
`${var,}` *param-lower-first*
Lowercase the first character of {var}.
`${var,,}` *param-lower-all*
Lowercase all characters.
Example:
`name="john doe"`
`echo ${name^}` # prints "John doe"
`echo ${name^^}` # prints "JOHN DOE"
==============================================================================
10. Substrings *param-slice*
`${var:offset}` *param-slice-from*
Substring starting at {offset} (0-indexed).
`${var:offset:length}` *param-slice-range*
Substring of {length} characters starting at {offset}.
Negative offsets count from the end (note the space before the minus
to distinguish from `:-`):
`str="hello world"`
`echo ${str: -5}` # prints "world"
`echo ${str:0:5}` # prints "hello"
==============================================================================
See also: |redirect| |glob| |arith|

181
doc/redirect.txt Normal file
View File

@@ -0,0 +1,181 @@
*redirect* *redirection* *redir*
#REDIRECTION#
Redirections allow you to control where a command reads its input from and
where it sends its output. A redirection applies to a specific file
descriptor; if no descriptor number is given, output redirections default
to stdout (fd 1) and input redirections default to stdin (fd 0).
==============================================================================
1. Output Redirection *redir-output*
`command > file` *redir-out*
Redirect stdout to {file}, creating it if it does not exist or
truncating it if it does.
Example:
`echo hello > out.txt`
`ls 2> errors.txt` # redirect stderr
`command >| file` *redir-out-force*
Like `>` but overrides the {noclobber} option. If {noclobber} is set,
`>` will refuse to overwrite an existing file; `>|` forces the
overwrite.
`command >> file` *redir-append*
Append stdout to {file}, creating it if it does not exist.
Example:
`echo line >> log.txt`
==============================================================================
2. Input Redirection *redir-input*
`command < file` *redir-in*
Redirect {file} to stdin.
Example:
`sort < unsorted.txt`
==============================================================================
3. Read-Write Redirection *redir-readwrite*
`command <> file` *redir-rw*
Open {file} for both reading and writing on the specified file
descriptor (default fd 0). The file is created if it does not exist
but is not truncated.
Useful with the `seek` builtin for random-access file operations.
Example:
`exec 3<> data.bin`
`seek 3 0 set` # seek to beginning
==============================================================================
4. File Descriptor Duplication *redir-dup*
`command N>&M` *redir-dup-out*
Duplicate output file descriptor {M} onto {N}. After this, writing
to fd {N} goes to the same place as fd {M}.
Example:
`command > out.txt 2>&1` # stderr goes where stdout goes
`command N<&M` *redir-dup-in*
Duplicate input file descriptor {M} onto {N}.
`command N>&-` *redir-close-out*
`command N<&-` *redir-close-in*
Close file descriptor {N}.
Example:
`exec 3>&-` # close fd 3
==============================================================================
5. Pipelines *redir-pipe*
`command1 | command2` *pipe*
Connect stdout of {command1} to stdin of {command2}. Both commands
run concurrently.
Example:
`cat file.txt | grep pattern | sort`
`command1 |& command2` *pipe-and*
Connect both stdout and stderr of {command1} to stdin of {command2}.
Equivalent to `command1 2>&1 | command2`.
==============================================================================
6. Here Documents *heredoc*
`command << DELIM` *redir-heredoc*
Read input from the script body until a line containing only {DELIM}
is found. The text between is fed to stdin of {command}.
Parameter expansion, command substitution, and arithmetic expansion
are performed in the body unless the delimiter is quoted.
Example:
`cat << EOF`
`Hello $USER`
`EOF`
`command << 'DELIM'` *redir-heredoc-literal*
Quoting the delimiter (single or double quotes) suppresses all
expansion in the heredoc body. The text is passed literally.
Example:
`cat << 'EOF'`
`This $variable is not expanded`
`EOF`
`command <<- DELIM` *redir-heredoc-indent*
Like `<<` but strips leading tab characters from each line of the
body and from the closing delimiter. This allows heredocs to be
indented for readability without affecting the content.
Example:
`if true; then`
` cat <<- EOF`
` indented content`
` EOF`
`fi`
==============================================================================
7. Here Strings *herestring*
`command <<< word` *redir-herestring*
Feed {word} as a single string to stdin of {command}, with a
trailing newline appended. {word} is subject to the usual expansions.
Example:
`read first rest <<< "hello world"`
`bc <<< "2 + 2"`
==============================================================================
8. File Descriptor Numbers *redir-fd*
Any redirection operator can be prefixed with a file descriptor number:
`2> file` redirect stderr to file
`3< file` open file on fd 3
`4>> file` append to file on fd 4
`5<> file` open file read-write on fd 5
Standard file descriptors:
0 stdin
1 stdout
2 stderr
File descriptors 3 and above are available for general use with `exec`.
==============================================================================
9. Combining Redirections *redir-combine*
Multiple redirections can appear on a single command, processed left
to right:
`command > out.txt 2>&1` # stdout to file, stderr to same file
`command 2>&1 > out.txt` # different! stderr to terminal,
# stdout to file
Order matters: each redirection is applied in sequence.
==============================================================================
See also: |param| |glob| |arith|