source | version 0.8.0 | all versions | oilshell.org

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

Oil Documentation

The Oil project aims to transform Unix shell into a better programming language. It's our upgrade path from bash.

Preliminaries

• Why Use Oil? This document is on the home page.
• INSTALL. How do I install Oil? This text file is also in the tarball.

OSH is a Compatible Shell

• OSH User Manual. How do I use OSH as my shell?
• Known Differences is trivia for advanced users. It lists differences between OSH and other shells.
• Quirks for compatibility.
• errexit (in progress)
• OSH Help Topics (incomplete). This document underlies the help builtin.

Oil is a New Shell Language

• The Oil Language From 10,000 Feet A tour of Oil.
• Oil Language Idioms. A list of idioms you may want to use.
• Shell Language Deprecations. When you turn on Oil, there are some shell constructs you can no longer use. We try to minimize the length of this list.
• Syntactic Concepts
  • Command vs. Expression Mode.
• Oil Help Topics (incomplete). This document underlies the help builtin.

The shell command language has been enhanced:

• Procs, Funcs, and Blocks
• Oil Keywords. New keywords for assignment, etc.
• Oil Builtins (Shell builtins aren't discussed.)
  • IO Builtins

Commands are made of words:

• Word Language. Oil extends the "word language".
• Special Variables
• Simple Word Evaluation. Written for shell experts.

Oil has a new expression language:

• Oil Expressions are similar to Python and JavaScript.
• Egg Expressions. A new regex syntax, abbreviated eggex.

More:

• Options. Parsing and runtime options turn OSH into Oil.
• Oil Language Design Notes
• Future: Error Handling

Interchange Formats

• JSON: Currently supported only in the Python prototype of Oil.
• QSN: Quoted String Notation. A human- and machine-readable format for byte strings.
• QTSV: An extension of TSV, built on top of QSN.
• Unicode. Oil supports and prefers UTF-8.

Internal Details

• Interpreter State
• Process Model. Shell is a language that lets you use low-level Unix constructs.
• Notes on Oil's Architecture
  • Parser Architecture
• Error List
• Toil. Continuous Testing on Many Platforms.

For Contributors

• README.md. If you want to modify Oil, start here. We welcome contributions!
• Github Wiki for oilshell/oil