Why Sponsor Oils? | source | all docs for version 0.22.0 | all versions | oilshell.org
Oils Reference — Chapter Global Shell Options
This chapter describes global shell options in Oils. Some options are from POSIX shell, and some are from bash. We also use options to turn OSH into YSH.
(in progress)
These options are from POSIX shell:
nounset -u
errexit -e
These are from bash:
inherit_errexit:
pipefail
These options are from POSIX shell:
noglob -f
From bash:
nullglob failglob dotglob
From Oils:
dashglob
Some details:
When nullglob
is on, a glob matching no files expands to no arguments:
shopt -s nullglob
$ echo L *.py R
L R
Without this option, the glob string itself is returned:
$ echo L *.py R # no Python files in this dir
L *.py R
(This option is from GNU bash.)
Do globs return results that start with -
? It's on by default in bin/osh
,
but off when YSH is enabled.
Turning it off prevents a command like rm *
from being confused by a file
called -rf
.
$ touch -- myfile -rf
$ echo *
-rf myfile
$ shopt -u dashglob
$ echo *
myfile
These options are from POSIX shell:
xtrace verbose
From bash:
extdebug
These options are from bash.
emacs vi
noclobber # Redirects don't overwrite files
Allow dynamically parsed a[$(echo 42)]
For bash compatibility.
To turn OSH into YSH, we use three option groups. Some of them allow new features, and some disallow old features.
Option in this group disallow problematic or confusing shell constructs. The resulting script will still run in another shell.
shopt --set strict:all # turn on all options
shopt -p strict:all # print their current state
Details on each option:
strict_argv No empty argv
strict_arith Fatal parse errors (on by default)
strict_array Arrays and strings aren't confused
strict_control_flow Disallow misplaced keyword, empty arg
strict_errexit Disallow code that ignores failure
strict_nameref trap invalid variable names
strict_word_eval Expose unicode and slicing errors
strict_tilde Tilde subst can result in error
X strict_glob Parse the sublanguage more strictly
Options in this group enable new YSH features. It doesn't break existing shell scripts when it's avoidable.
For example, parse_at
means that @myarray
is now the operation to splice
an array. This will break scripts that expect @
to be literal, but you can
simply quote it like '@literal'
to fix the problem.
shopt --set ysh:upgrade # turn on all options
shopt -p ysh:upgrade # print their current state
Details on each option:
parse_at echo @array @[arrayfunc(x, y)]
parse_brace if true { ... }; cd ~/src { ... }
parse_equals x = 'val' in Caps { } config blocks
parse_paren if (x > 0) ...
parse_proc proc p { ... }
parse_triple_quote """$x""" '''x''' (command mode)
X parse_utf8_only YSH source code must be valid UTF-8
parse_ysh_string echo r'\' u'\\' b'\\' (command mode)
command_sub_errexit Synchronous errexit check
process_sub_fail Analogous to pipefail for process subs
sigpipe_status_ok status 141 -> 0 in pipelines
simple_word_eval No splitting, static globbing
xtrace_rich Hierarchical and process tracing
xtrace_details (-u) Disable most tracing with +
dashglob (-u) Disabled to avoid files like -rf
X env_dict Copy environ into ENV dict
Enable the full YSH language. This includes everything in the ysh:upgrade
group and the strict:all
group.
shopt --set ysh:all # turn on all options
shopt -p ysh:all # print their current state
Details on options that are not in ysh:upgrade
and strict:all
:
parse_at_all @ starting any word is an operator
parse_backslash (-u) Allow bad backslashes in "" and $''
parse_backticks (-u) Allow legacy syntax `echo hi`
parse_bare_word (-u) 'case unquoted' and 'for x in unquoted'
parse_dollar (-u) Allow bare $ to mean \$ (maybe $/d+/)
parse_dbracket (-u) Is legacy [[ allowed?
parse_dparen (-u) Is (( legacy arithmetic allowed?
parse_ignored (-u) Parse, but ignore, certain redirects
parse_sh_arith (-u) Allow legacy shell arithmetic
expand_aliases (-u) Whether aliases are expanded
X no_env_vars Use $[ENV.PYTHONPATH], not $PYTHONPATH
X old_builtins (-u) local/declare/etc. pushd/popd/dirs
... source unset printf [un]alias
... getopts
X old_syntax (-u) ( ) ${x%prefix} ${a[@]} $$
simple_echo echo doesn't accept flags -e -n
simple_eval_builtin eval takes exactly 1 argument
simple_test_builtin 3 args or fewer; use test not [
X simple_trap Function name only
verbose_errexit Whether to print detailed errors
In the interactive shell, you can redefine procs and funcs.
redefine_module 'module' builtin always returns 0
redefine_proc_func (-u) Can shell func, proc and func be redefined?
X redefine_const Can consts be redefined?
These options are used by the interpreter. You generally shouldn't set them yourself.
_allow_command_sub To implement strict_errexit, eval_unsafe_arith
_allow_process_sub To implement strict_errexit
dynamic_scope To implement proc and func
_no_debug_trap Used in pipelines in job control shell
_running_trap To disable strict_errexit
_running_hay Hay evaluation
Here are some descriptions of individual options.
Disallow break
and continue
at the top level, and disallow empty args like
return $empty
.
Failed tilde expansions cause hard errors (like zsh) rather than silently
evaluating to ~
or ~bad
.
When strict_nameref
is set, undefined references produce fatal errors:
declare -n ref
echo $ref # fatal error, not empty string
ref=x # fatal error instead of decaying to non-reference
References that don't contain variables also produce hard errors:
declare -n ref='not a var'
echo $ref # fatal
ref=x # fatal
For compatibility, YSH will parse some constructs it doesn't execute, like:
return 0 2>&1 # redirect on control flow
When this option is disabled, that statement is a syntax error.
Parse the shell-style multi-line strings, which strip leading whitespace:
echo '''
one
two
'''
echo """
hello
$name
"""
(This option affects only command mode. Such strings are always parsed in expression mode.)
Allow r'\'
and u'\\'
and b'\\'
strings, as well as their multi-line
versions.
Since shell strings are already raw, this means that YSH just ignores the r prefix:
echo r'\' # a single backslash
J8 unicode strings:
echo u'mu \u{3bc}' # mu char
J8 byte strings:
echo b'byte \yff'
(This option affects only command mode. Such strings are always parsed in expression mode.)
If a process that's part of a pipeline exits with status 141 when this is option is on, it's turned into status 0, which avoids failure.
SIGPIPE errors occur in cases like 'yes | head', and generally aren't useful.