source | all docs for version 0.9.5 | all versions | oilshell.org

Warning: Work in progress! Leave feedback on Zulip or Github if you'd like this doc to be updated.

Oil Builtins

This is an overview of shell builtins that are unique to Oil. A full description of each builtin will be available in the help pages.

What are builtins? They look like external commands, but are included with the shell itself. They don't spawn an external process, and can modify the shell's memory.

New Builtins in Oil

append appends strings to an array

Example:

var a = %(1 '2 two')
append :a three four
echo @a  # prints 4 lines

Here's another way to write it:

setvar a = %( @a three four )

Note that you can append to a string like this:

var s = 'foo'
setvar s = "${s}suffix"

(Note: Oil doesn't currently support the equivalent of shell's s+=suffix.)

pp pretty prints interpreter state

• pp cell - shows the value of a variable, for debugging
• pp proc - shows doc strings

module

use

runproc

Shell Builtins Enhanced with Block

Done:

• cd
• shopt

Planned, but not implemented:

• fork for &
• forkwait for ()
• env to replace PYTHONPATH=. foo.py
• each runs processes in parallel and replaces xargs

Examples of what we have in mind:

# this replaces an awkward idiom with eval I've seen a lot
shopt -u errexit {  # TODO: --unset
   false
   echo "temporary disable an option"
} 

# generalizes the 'NAME=value command' syntax and the 'env' prefix helps parsing
env PYTHONPATH=. {
  ./foo.py
  ./bar.py
}

# replaces sleep 5 &
fork { sleep 5 }

# replaces () syntax so we can use it for something else.
forkwait { echo subshell; sleep 5 }

# Probably used for a "syntactic pun" of Python-like "import as" functionality

use lib foo.sh {
  myfunc
  myalias otherfunc
}

cd

It now takes a block:

cd /tmp {
  echo $PWD  # prints /tmp
}
echo $PWD  # prints the original directory

This subsumes the functionality of bash builtins pushd and popd.

When a block is passed:

• cd doesn't set The OLDPWD variable (which is used to implement the cd - shortcut.)
• The directory stack for pushd and popd isn't cleared, as it is with a normal cd command.

shopt

Other Builtins That Take Blocks

fork, forkwait

argparse

Builtin Flag Syntax

TODO: Implement this, or eliminate it?

Oil's builtins accept long flags like --verbose and short flags like -v.

They behave like the popular GNU utilities on Linux distros, except that -long (single hyphen) means the same thing as --long. It's not a shortcut for -l -o -n -g or -l=ong. (This rule is consistent with the Go flags package.)

In addition, all of these are equivalent:

• -sep x
• -sep=x
• --sep x
• --sep=x

(Trivia: Oil's flag syntax avoids the issue where set -oo errexit nounset is a confusing equivalent to set -o errexit -o nounset.)

I/O Builtins

See IO Builtins.

More

• Not implemented: log, die