source | all docs for version 0.8.pre8 | all versions | oilshell.org
Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.
The Oil project has a single interpreter that supports both the OSH and Oil languages.
In other words, It's useful to think of Unix shell in historical layers:
shopt
, associative arrays)Shell has many syntaxes for the same semantics, which can be confusing. For example, in bash, these four statements do similar things:
$ foo='bar'
$ declare -g foo=bar
$ x='foo=bar'; typeset $x
$ printf -v foo bar
$ echo $foo
bar
In addition Oil, adds JavaScript-like syntax:
var foo = 'bar'
Oil's syntax can express more data types, but it may also confuse new users.
So the sections below describe the shell from a semantic perspective, which should help users reason about their programs.
Quick tip: Use the repr builtin to inspect shell variables.
POSIX shell has a fairly simple model: everything is a string, and "$@"
is a
special case.
Bash adds many features on top of POSIX, including arrays and associative arrays. Oil implements those features, and a few more.
However, it also significantly simplifies the model.
A primary difference is mentioned in Known Differences:
declare -A unset_assoc_array
.In other words, Oil "salvages" the confusing semantics of bash and produces something simpler, while still being very compatible.
TODO
"$@"
in shell, and @ARGV
in
Oil.On initialization, environment variables like PYTHONPATH=.
are copied into
the shell's memory as global variables, with the export
flag set.
Global variables are stored in the first stack frame, i.e. the one at index
0
.
There are two distinct namespaces. For example:
foo() {
echo 'function named foo'
}
foo=bar # a variable; doesn't affect the function
OSH has it, but Oil limits it.
Shell is a value-oriented language.
Example:
declare -a myarray=("${other_array[@]}") # shell
var myarray = @( @other_array ) # Oil
Reason: There's no Garbage collection.
-i
in bash?fork()
Has Copy-On-Write SemanticsSee the Process Model document.
TODO: core/runtime.asdl
cell
TODO
value
Undef, Str, Sequential/Indexed Arrays, Associative Array
cmd_value
for shell builtinsAnother important type:
assign_arg = (lvalue lval, value? rval, int spid)
cmd_value =
Argv(string* argv, int* arg_spids, command__BraceGroup? block)
| Assign(builtin builtin_id,
string* argv, int* arg_spids,
assign_arg* pairs)
Oil supports various shell and bash operations to view the interpretr state.
set
prints variables and their valuesset -o
prints optionsdeclare/typeset/readonly/export -p
prints a subset of variablestest -v
tests if a variable is defined.Pretty prints a cell.
This is cleaner!
TODO: What about functions
TODO: See Oil Keywords doc.
...
You can't unset an array in OSH? But you can in bash.
Horrible
a=('1 2' 3)
b=(1 '2 3') # two different elements
[[ $a == $b ]]
[[ ${a[0]} == ${b[0]} ]]
[[ ${a[@]} == ${b[@]} ]]
Associative arrays and being undefined
set -o nounset
(in bash 4.3). I can't recommend
in good faith.