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.

Table of Contents
More Builtins
push appends strings to an array
pp shows the value of a variable, for debugging
Shell Builtins Enhanced with Block
cd
Builtin Flag Syntax
I/O Builtins
More

More Builtins

push appends strings to an array

Example:

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

A more awkward way to write this:

setvar a = %( @a three four )

pp shows the value of a variable, for debugging

This is implemented, but the output format may change.

Shell Builtins Enhanced with Block

Done:

Not done:

Planned, but not implemented:

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:

Builtin Flag Syntax

(TODO: Implement this)

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:

(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:


Generated on Mon May 10 14:09:34 PDT 2021