| 1 | ---
|
| 2 | in_progress: yes
|
| 3 | body_css_class: width40 help-body
|
| 4 | default_highlighter: oils-sh
|
| 5 | preserve_anchor_case: yes
|
| 6 | ---
|
| 7 |
|
| 8 | Global Shell Options
|
| 9 | ===
|
| 10 |
|
| 11 | This chapter in the [Oils Reference](index.html) describes global shell options
|
| 12 | for OSH and YSH.
|
| 13 |
|
| 14 | <div id="toc">
|
| 15 | </div>
|
| 16 |
|
| 17 | ## Option Groups
|
| 18 |
|
| 19 | <!-- note: explicit anchor necessary because of mangling -->
|
| 20 | <h3 id="strict:all">strict:all</h3>
|
| 21 |
|
| 22 | Option in this group disallow problematic or confusing shell constructs. The
|
| 23 | resulting script will still run in another shell.
|
| 24 |
|
| 25 | shopt --set strict:all # turn on all options
|
| 26 | shopt -p strict:all # print their current state
|
| 27 |
|
| 28 | <h3 id="ysh:upgrade">ysh:upgrade</h3>
|
| 29 |
|
| 30 | Options in this group enable YSH features that are less likely to break
|
| 31 | existing shell scripts.
|
| 32 |
|
| 33 | For example, `parse_at` means that `@myarray` is now the operation to splice
|
| 34 | an array. This will break scripts that expect `@` to be literal, but you can
|
| 35 | simply quote it like `'@literal'` to fix the problem.
|
| 36 |
|
| 37 | shopt --set ysh:upgrade # turn on all options
|
| 38 | shopt -p ysh:upgrade # print their current state
|
| 39 |
|
| 40 | <h3 id="ysh:all">ysh:all</h3>
|
| 41 |
|
| 42 | Enable the full YSH language. This includes everything in the `ysh:upgrade`
|
| 43 | group.
|
| 44 |
|
| 45 | shopt --set ysh:all # turn on all options
|
| 46 | shopt -p ysh:all # print their current state
|
| 47 |
|
| 48 | ## Strictness
|
| 49 |
|
| 50 | ### strict_control_flow
|
| 51 |
|
| 52 | Disallow `break` and `continue` at the top level, and disallow empty args like
|
| 53 | `return $empty`.
|
| 54 |
|
| 55 | ### strict_tilde
|
| 56 |
|
| 57 | Failed tilde expansions cause hard errors (like zsh) rather than silently
|
| 58 | evaluating to `~` or `~bad`.
|
| 59 |
|
| 60 | ### strict_word_eval
|
| 61 |
|
| 62 | TODO
|
| 63 |
|
| 64 | ### strict_nameref
|
| 65 |
|
| 66 | When `strict_nameref` is set, undefined references produce fatal errors:
|
| 67 |
|
| 68 | declare -n ref
|
| 69 | echo $ref # fatal error, not empty string
|
| 70 | ref=x # fatal error instead of decaying to non-reference
|
| 71 |
|
| 72 | References that don't contain variables also produce hard errors:
|
| 73 |
|
| 74 | declare -n ref='not a var'
|
| 75 | echo $ref # fatal
|
| 76 | ref=x # fatal
|
| 77 |
|
| 78 | ### parse_ignored
|
| 79 |
|
| 80 | For compatibility, YSH will parse some constructs it doesn't execute, like:
|
| 81 |
|
| 82 | return 0 2>&1 # redirect on control flow
|
| 83 |
|
| 84 | When this option is disabled, that statement is a syntax error.
|
| 85 |
|
| 86 | ## ysh:upgrade
|
| 87 |
|
| 88 | ### parse_at
|
| 89 |
|
| 90 | TODO
|
| 91 |
|
| 92 | ### parse_brace
|
| 93 |
|
| 94 | TODO
|
| 95 |
|
| 96 | TODO
|
| 97 |
|
| 98 | ### parse_paren
|
| 99 |
|
| 100 | TODO
|
| 101 |
|
| 102 | ### parse_triple_quote
|
| 103 |
|
| 104 | Parse the shell-style multi-line strings, which strip leading whitespace:
|
| 105 |
|
| 106 | echo '''
|
| 107 | one
|
| 108 | two
|
| 109 | '''
|
| 110 |
|
| 111 | echo """
|
| 112 | hello
|
| 113 | $name
|
| 114 | """
|
| 115 |
|
| 116 | (This option affects only command mode. Such strings are always parsed in
|
| 117 | expression mode.)
|
| 118 |
|
| 119 | ### parse_ysh_string
|
| 120 |
|
| 121 | Allow `r'\'` and `u'\\'` and `b'\\'` strings, as well as their multi-line
|
| 122 | versions.
|
| 123 |
|
| 124 | Since shell strings are already raw, this means that YSH just ignores the r
|
| 125 | prefix:
|
| 126 |
|
| 127 | echo r'\' # a single backslash
|
| 128 |
|
| 129 | J8 unicode strings:
|
| 130 |
|
| 131 | echo u'mu \u{3bc}' # mu char
|
| 132 |
|
| 133 | J8 byte strings:
|
| 134 |
|
| 135 | echo b'byte \yff'
|
| 136 |
|
| 137 | (This option affects only command mode. Such strings are always parsed in
|
| 138 | expression mode.)
|
| 139 |
|
| 140 | ### command_sub_errexit
|
| 141 |
|
| 142 | TODO
|
| 143 |
|
| 144 | ### process_sub_fail
|
| 145 |
|
| 146 | TODO
|
| 147 |
|
| 148 | ### sigpipe_status_ok
|
| 149 |
|
| 150 | If a process that's part of a pipeline exits with status 141 when this is
|
| 151 | option is on, it's turned into status 0, which avoids failure.
|
| 152 |
|
| 153 | SIGPIPE errors occur in cases like 'yes | head', and generally aren't useful.
|
| 154 |
|
| 155 | ### simple_word_eval
|
| 156 |
|
| 157 | TODO:
|
| 158 |
|
| 159 | <!-- See doc/simple-word-eval.html -->
|
| 160 |
|
| 161 | ## YSH Breaking
|
| 162 |
|
| 163 | ### copy_env
|
| 164 |
|
| 165 | ### parse_equals
|
| 166 |
|
| 167 | ## Errors
|
| 168 |
|
| 169 | ## Globbing
|
| 170 |
|
| 171 | ### nullglob
|
| 172 |
|
| 173 | Normally, when no files match a glob, the glob itself is returned:
|
| 174 |
|
| 175 | $ echo L *.py R # no Python files in this dir
|
| 176 | L *.py R
|
| 177 |
|
| 178 | With nullglob on, the glob expands to no arguments:
|
| 179 |
|
| 180 | shopt -s nullglob
|
| 181 | $ echo L *.py R
|
| 182 | L R
|
| 183 |
|
| 184 | (This option is in GNU bash as well.)
|
| 185 |
|
| 186 | ### dashglob
|
| 187 |
|
| 188 | Do globs return results that start with `-`? It's on by default in `bin/osh`,
|
| 189 | but off when YSH is enabled.
|
| 190 |
|
| 191 | Turning it off prevents a command like `rm *` from being confused by a file
|
| 192 | called `-rf`.
|
| 193 |
|
| 194 | $ touch -- myfile -rf
|
| 195 |
|
| 196 | $ echo *
|
| 197 | -rf myfile
|
| 198 |
|
| 199 | $ shopt -u dashglob
|
| 200 | $ echo *
|
| 201 | myfile
|
| 202 |
|
| 203 | ## Debugging
|
| 204 |
|
| 205 | ## Interactive
|
| 206 |
|
| 207 | ## Other Option
|
| 208 |
|