2025-11-25

ZSH/Documentation.md

@@ -0,0 +1,107 @@
+[source](https://zsh.sourceforge.io/Guide/zshguide02.html)
+
+### Options
+The usual way to set and unset options 
+```zsh
+setopt <string> # sets an option
+unsetopt <string> # unsets the option
+
+# Note 
+set -o 
+# is the equivelant to
+setopt
+
+# NOTE:
+set # without the `-o` does something else -- sets the positional paramters
+```
+
+both `~/.zshrc` and `~/.zshenv` run for every shell
+
+`~/.zshrc` is executed upon a shell starting for every **interactive** shell
+
+
+### Parameters
+
+Simple parameters can be assigned 
+```zsh
+foo='This is a parameter'
+```
+
+Note no spaces between the `foo` and `=`
+Single quotes, as here, are the nuclear option of quotes: everything up to another single quote is treated as a simple string --- newlines, equal signs, unprintable characters, the lot, in this example all would be assigned to the variable; for example,
+
+ ```zsh
+ foo='This is a parameter.
+  This is still the same parameter.'
+  ``` 
+  
+So they're the best thing to use until you know what you're doing with double quotes, which have extra effects. Sometimes you don't need them, for example:
+
+```
+foo=oneword
+```
+
+because there's nothing in `oneword` to confuse the shell; but you could still put quotes there anyway.
+
+
+#### Parameter Expansion
+
+```zsh
+foo='This is a parameter'
+
+print -- '$foo is "'$foo'"'
+```
+
+prints
+```zsh
+$foo is "This is a parameter"
+```
+expansion happens anywhere the parameter is not quoted; it doesn't have to be on its own, just separated from anything which might make it look like a different parameter. This is one of those things that can help make shell scripts look so barbaric.
+
+Note: why the `---` after the `print`?
+	because **print**, like many UNIX commands, can take options after it which begin with a -` `--` says that there are no more options; so if what you're trying to print begins with a ``-`', it will still print out.
+
+### Arrays
+
+There is a special type of parameter called an **array** which zsh inherited from both ksh and csh. This is a slightly shaky marriage, since some of the things those two shells do with them are not compatible, and zsh has elements of both, so you need to be careful if you've used arrays in either. The option `KSH_ARRAYS` is something you can set to make them behave more like they do in ksh, but a lot of zsh users write functions and scripts assuming it isn't set, so it can be dangerous.
+
+Unlike normal parameters (known as **scalars**), arrays have more than one word in them. In the examples above, we made the parameter `$foo` get a string with spaces in, but the spaces weren't significant. If we'd done
+
+  foo=(This is a parameter.)
+
+(note the absence of quotes), it would have created an array. Again, there must be no space between the ``=`' and the `(', though inside the parentheses spaces separate words just like they do on a command line. The difference isn't obvious if you try and print it --- it looks just the same --- but now try this:
+
+  print -- ${foo[4]}
+
+and you get ``parameter.`'. The array stores the words separately, and you can retrieve them separately by putting the number of the element of the array in square brackets. Note also the braces ``{...}`' --- zsh doesn't always require them, but they make things much clearer when things get complicated, and it's never wrong to put them in: you could have said ``${foo}`' when you wanted to print out the complete parameter, and it would be treated identically to ``$foo`'. The braces simply screen off the expansion from whatever else might be lying around to confuse the shell. It's useful too in expressions like ``${foo}s`' to keep the ``s`' from being part of the parameter name; and, finally, with `KSH_ARRAYS` set, the braces are compulsory, though unfortunately arrays are indexed from 0 in that case.
+
+You can use quotes when defining arrays; as before, this protects against the shell thinking the spaces are between different elements of the array. Try:
+
+  foo=('first element' 'second element')
+  print -- ${foo[2]}
+
+Arrays are useful when the shell needs to keep a whole series of different things together, so we'll meet some you may want to put in a startup file. Users of ksh will have noticed that things are a bit different in zsh, but for now I'll just assume you're using the normal zsh way of doing things.
+
+### Compatibility Options
+- `SH_WORD_SPLT` - Split string variables into arrays. ZSH Default: `not set`
+- `NO_BANG_HIST`
+- `BSD_ECHO` (sh only)
+- `IGNORE_BRACES`
+- `INTERACTIVE_COMMENTS`
+- `KSH_OPTION_PRINT`
+- `NO_MULTIOS` 
+- `POSIX_BUILTINS`
+- `PROMPT_BANG`
+- `SINGLE_LINE_ZLE`
+
+
+**`BG_NICE`& `NOTIFY`**
+
+All UNIX shells allow you to start a _background_ job by putting `&` at the end of the line; then the shell doesn't wait for the job to finish, so you can type something else. In zsh, such jobs are usually run at a lower priority (a `higher nice value` in UNIX-speak), so that they don't use so much of the processor's time as foreground jobs (all the others, without the &`) do. This is so that jobs like editing or using the shell don't get slowed down, which can be highly annoying. You can turn this feature off by setting `NO_BG_NICE`
+
+When a background job finishes, zsh usually tells you immediately by printing a message, which interrupts whatever you're doing. You can stop this by setting `NO_NOTIFY`. Actually, this is an option in most versions of ksh, too, but it's a little less annoying in zsh because if it happens while you're typing something else to the shell, the shell will reprint the line you were on as far as you've got. For example:
+
+
+### HUP
+ - `SIGINT` - what the shell interprets `^C` (CNTRL + C)
+ - `SIGHUP` -