source | all docs for version 0.8.7 | all versions | oilshell.org
Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.
This is for advanced users. Casual users should can read the first two sections.
Also see Oil Keywords.
This doc is filled with details, so it will help to keep these goals in mind:
proc) is easier to read/audit than code
written in shell style.
setref keyword.TODO: Improve This Example
f() {
out1='y'
setvar out2 = 'y'
}
g() {
local out1
local out2
f
}
g # when it calls f, its variables can be modified
shopt --unset dynamic_scope
g # now they can't be modified; they will be set globally
Don't use the old style of local, readonly, x=y.
const, var, and setvar.This covers 95%+ of shell programming.
shopt --unset dynamic_scope
proc.bin/oilThis option affects how nearly every shell assignment construct behaves. There are a lot of them!
This option is unset in bin/oil, but not bin/osh.
That's it!
setref for "out params". TODO: example of out params in C, as an analogy.set and setglobal if you want to be stricter.See Oil Keywords.
Read on if you want details.
Cells are locations for variables.
Named after enums.
scope_e.DynamicWhat shell uses
setref: Dynamic with nameref (no shopt)
nameref feature: declare -n.scope_e.LocalOrGlobalIn Oil, it does one of three things:
In shell, it does these things:
scope_e.LocalOnlyThe setlocal key always does the same thing. but all these other constructs
switch between setvar and setlocal semantics, depending on shopt --unset dynamic_scope.
LocalOrGlobal For Reading Variables, and for setvarConstructs That Retrieve Cells:
The other ones deal with values. These deal with cells.
GetCell() and GetAllCells()
declare -p to print variables
${x@a} to print flags
pp .cell
weird TZ test in printf. I think this could just look in the
environment itself? Do getenv()?
Dynamic → LocalOnly (keyword setlocal)Shell:
x=y
s+=suffix, a[i]+=suffix, a+=(suffix 2).export x=yreadonly x=yThese shell constructs mutate.
${undef=default} and ${undef:=default}myprog {fd}>out.txt(( i = j )), (( i += j ))
(( a[i] = j )), (( a[i] += j ))setref)These use setref semantics.
Idea: You can write functions with out params that also compose. TODO: Example.
readgetoptsmapfile / readarrayprintf -vrun --assign-statusunset -- This takes a variable name, so it's like an "out param".scope_e.GlobalOnly and setglobalThis one is the easiest to explain, to we leave it for last.
local is always LocalOnly
declare and readonly are also local by defaultsetvarset if you want to define things ahead of time