shells: move shells into own group

1 files changed, 371 insertions, 0 deletions

diff --git a/src/shells/zsh.md b/src/shells/zsh.md
new file mode 100644
index 0000000..f702655
--- /dev/null
+++ b/src/shells/zsh.md
@@ -0,0 +1,371 @@
+# zsh(1)
+
+## Keybindings
+
+Change input mode:
+```zsh
+bindkey -v              change to vi keymap
+bindkey -e              change to emacs keymap
+```
+
+Define key-mappings:
+```zsh
+bindkey                 list mappings in current keymap
+bindkey in-str cmd      create mapping for `in-str` to `cmd`
+bindkey -r in-str       remove binding for `in-str`
+
+# C-v <key>             dump <key> code, which can be used in `in-str`
+# zle -l                list all functions for keybindings
+# man zshzle(1)         STANDARD WIDGETS: get description of functions
+```
+
+Access edit buffer in zle widget:
+```zsh
+$BUFFER       # Entire edit buffer content
+$LBUFFER      # Edit buffer content left to cursor
+$RBUFFER      # Edit buffer content right to cursor
+
+# create zle widget which adds text right of the cursor
+function add-text() {
+    RBUFFER="some text $RBUFFER"
+}
+zle -N add-text
+
+bindkey "^p" add-text
+```
+
+## Parameter
+
+Default value:
+```zsh
+# default value
+echo ${foo:-defval}   # defval
+foo=bar
+echo ${foo:-defval}   # bar
+```
+
+Alternative value:
+```zsh
+echo ${foo:+altval}   # ''
+foo=bar
+echo ${foo:+altval}   # altval
+```
+
+Check variable set, error if not set:
+```zsh
+echo ${foo:?msg}      # print `msg` and return errno `1`
+foo=bar
+echo ${foo:?msg}      # bar
+```
+
+Sub-string `${var:offset:length}`:
+```zsh
+foo=abcdef
+echo ${foo:1:3}       # bcd
+```
+
+Trim prefix `${var#prefix}`:
+```zsh
+foo=bar.baz
+echo ${foo#bar}       # .baz
+```
+
+Trim suffix `${var%suffix}`:
+```zsh
+foo=bar.baz
+echo ${foo%.baz}      # bar
+```
+
+Substitute pattern `${var/pattern/replace}`:
+```zsh
+foo=aabbccbbdd
+echo ${foo/bb/XX}    # aaXXccbbdd
+echo ${foo//bb/XX}   # aaXXccXXdd
+# replace prefix
+echo ${foo/#bb/XX}   # aabbccbbdd
+echo ${foo/#aa/XX}   # XXbbccbbdd
+# replace suffix
+echo ${foo/%bb/XX}   # aabbccbbdd
+echo ${foo/%dd/XX}   # aabbccbbXX
+```
+
+> Note: `prefix`/`suffix`/`pattern` are expanded as pathnames.
+
+## Variables
+
+```zsh
+# Variable with local scope
+local var=val
+
+# Read-only variable
+readonly var=bal
+```
+
+Indexed arrays:
+```zsh
+arr=(aa bb cc dd)
+echo $arr[1]           # aa
+echo $arr[-1]          # dd
+
+arr+=(ee)
+echo $arr[-1]          # ee
+
+echo $arr[1,3]         # aa bb cc
+```
+
+Associative arrays:
+```zsh
+typeset -A arr
+arr[x]='aa'
+arr[y]='bb'
+echo $arr[x]           # aa
+```
+
+Tied arrays:
+```zsh
+typeset -T VEC vec=(1 2 3) '|'
+
+echo $vec              # 1 2 3
+echo $VEC              # 1|2|3
+```
+
+Unique arrays (set):
+```
+typeset -U vec=(1 2 3)
+
+echo $vec             # 1 2 3
+vec+=(1 2 4)
+echo $vec             # 1 2 3 4
+```
+
+### Expansion Flags
+
+Join array to string `j:sep:`:
+```zsh
+foo=(1 2 3 4)
+echo ${(j:-:)foo}     # 1-2-3-4
+echo ${(j:\n:)foo}    # join with new lines
+```
+
+Split string to array `s:sep`:
+```zsh
+foo='1-2-3-4'
+bar=(${(s:-:)foo})    # capture as array
+echo $bar             # 1 2 3 4
+echo $bar[2]          # 2
+```
+
+Upper/Lower case string:
+```zsh
+foo=aaBB
+echo ${(L)foo}        # aabb
+echo ${(U)foo}        # AABB
+```
+
+Key/values in associative arrays:
+```zsh
+typeset -A vec; vec[a]='aa'; vec[b]='bb'
+
+echo ${(k)vec}        # a b
+echo ${(v)vec}        # aa bb
+echo ${(kv)vec}       # a aa b bb
+
+# Iterate over key value pairs.
+for k v in ${(kv)vec)}; do ...; done
+```
+
+## I/O redirections
+
+See [bash - I/O redirection](bash.md#io-redirection)
+
+## Process substitution
+
+Process substitution allows to redirect the stdout of multiple processes at
+once.
+```bash
+vim -d <(grep foo bar) <(grep foo moose)
+```
+
+## Argument parsing with `zparseopts`
+
+```zsh
+zparseopts [-D] [-E] [-A assoc] specs
+```
+Arguments are copied into the associative array `assoc` according to `specs`.
+Each spec is described by an entry as `opt[:][=array]`.
+- `opt` is the option without the `-` char. Passing `-f` is matched against `f`
+  opt, `--long` is matched against `-long`.
+- Using `:` means the option will take an argument.
+- The optional `=array` specifies an alternate storage container where this
+  option should be stored.
+> Documentation can be found in `man zshmodules`.
+
+### Example
+```zsh
+#!/bin/zsh
+function test() {
+    zparseopts -D -E -A opts f=flag o: -long:
+    echo "flag $flag"
+    echo "o    $opts[-o]"
+    echo "long $opts[--long]"
+    echo "pos  $1"
+}
+
+test -f -o OPTION --long LONG_OPT POSITIONAL
+
+# Outputs:
+#   flag -f
+#   o    OPTION
+#   long LONG_OPT
+#   pos  POSITIONAL
+```
+
+## Regular Expressions
+
+Zsh supports regular expression matching with the binary operator `=~`.
+The match results can be accessed via the `$MATCH` variable and
+`$match` indexed array:
+- `$MATCH` contains the full match
+- `$match[1]` contains match of the first capture group
+
+```zsh
+INPUT='title foo : 1234'
+REGEX='^title (.+) : ([0-9]+)$'
+if [[ $INPUT =~ $REGEX ]]; then
+    echo "$MATCH"       # title foo : 1234
+    echo "$match[1]"    # foo
+    echo "$match[2]"    # 1234
+fi
+```
+
+## Completion
+
+### Installation
+
+Completion functions are provided via files and need to be placed in a location
+covered by `$fpath`. By convention the completion files are names as `_<CMD>`.
+
+A completion skeleton for the command `foo`, stored in `_foo`
+```zsh
+#compdef _foo foo
+
+function _foo() {
+    ...
+}
+```
+
+Alternatively one can install a completion function explicitly by calling `compdef <FUNC> <CMD>`.
+
+### Completion Variables
+
+Following variables are available in Completion functions:
+```zsh
+$words              # array with command line in words
+$#words             # number words
+$CURRENT            # index into $words for cursor position
+$words[CURRENT-1]   # previous word (relative to cursor position)
+```
+
+### Completion Functions
+- `_describe`     simple completion, just words + description
+- `_arguments`    sophisticated completion, allow to specify actions
+
+#### Completion with [`_describe`][zsh-comp-fn]
+```zsh
+_describe MSG COMP
+```
+- `MSG` simple string with header message
+- `COMP` array of completions where each entry is `"opt:description"`
+
+```zsh
+function _foo() {
+    local -a opts
+    opts=('bla:desc for bla' 'blu:desc for blu')
+    _describe 'foo-msg' opts
+}
+compdef _foo foo
+
+foo <TAB><TAB>
+ -- foo-msg --
+bla  -- desc for bla
+blu  -- desc for blu
+```
+
+#### Completion with [`_arguments`][zsh-comp-fn]
+```zsh
+_arguments SPEC [SPEC...]
+```
+where `SPEC` can have one of the following forms:
+- `OPT[DESC]:MSG:ACTION` for option flags
+- `N:MSG:ACTION` for positional arguments
+
+Available actions
+```zsh
+(op1 op2)   list possible matches
+->VAL       set $state=VAL and continue, `$state` can be checked later in switch case
+FUNC        call func to generate matches
+{STR}       evaluate `STR` to generate matches
+```
+
+### Example
+Skeleton to copy/paste for writing simple completions.
+
+Assume a program `foo` with the following interface:
+```zsh
+foo -c green|red|blue -s low|high -f <file> -d <dir> -h
+```
+
+The completion handler could be implemented as follows in a file called `_foo`:
+```zsh
+#compdef _foo foo
+
+function _foo_color() {
+    local colors=()
+    colors+=('green:green color')
+    colors+=('red:red color')
+    colors+=('blue:blue color')
+    _describe "color" colors
+}
+
+function _foo() {
+    _arguments                              \
+        "-c[define color]:color:->s_color"  \
+        "-s[select sound]:sound:(low high)" \
+        "-f[select file]:file:_files"       \
+        "-d[select dir]:dir:_files -/"      \
+        "-h[help]"
+
+    case $state in
+        s_color) _foo_color;;
+    esac
+}
+```
+
+### Example with optional arguments
+For this example we assume that the command `foo` takes at least three optional
+arguments such as
+```zsh
+foo arg1 arg2 arg3 [argN..]
+```
+
+```zsh
+function _foo() {
+    _arguments              \
+        "1:opt 1:(a b c)"   \
+        ":opt next:(d e f)" \
+        "*:opt all:(u v w)"
+}
+```
+Explanation:
+- `1:MSG:ACTION` sets completion for the **first** optional argument
+- `:MSG:ACTION` sets completion for the **next** optional argument
+- `*:MSG:ACTION` sets completion for the optional argument where none of the
+  previous rules apply, so in our example for `arg3, argN..`.
+
+> `_files` is a zsh builtin utility function to complete files/dirs see
+> - [zsh completion functions][zsh-comp-fn]
+> - [zsh completion utility functions][zsh-comp-utility-fn]
+
+
+[zsh-comp-fn]: http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions
+[zsh-comp-utility-fn]: https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#utility-functions