Why Sponsor Oil? | source | version 0.15.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. It's for Python and JavaScript programmers who avoid shell.

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.
• A Tour of the Oil Project. It's a big project with several components to understand!
• Getting Started.

OSH is a Compatible Shell

These docs are for advanced users:

• Known Differences lists differences between OSH and other shells.
• Quirks for compatibility.
• Shell Language Idioms.

Reference:

• OSH Help Topics (incomplete). This document underlies the help builtin.

Oil is a New Shell Language

• A Tour of the Oil Language.
• Oil vs. Shell Idioms. Idioms that are nicer in Oil than shell.
• What Breaks When You Upgrade to Oil. When you turn on Oil, there are some shell constructs you can no longer use. We try to minimize the length of this list.
• Hay - Custom Languages for Unix Systems. Use Ruby-like blocks to declare data and interleaved code.
• Oil Language FAQ. Common questions about the language.
• Warts. Mostly for compatibility.

Reference:

• Oil Help Topics (incomplete). This document underlies the help builtin.

Language Design

• A Feel For Oil's Syntax
• Language Influences
• Syntactic Concepts
  • Command vs. Expression Mode.
• Oil Language vs. Shell. How does Oil differ from Bourne/POSIX shell?
• Oil vs. Python. How do Oil's expressions differ from Python?

The Command Language

Commands are made of words, keywords, and other operators. They're for I/O, control flow, and abstraction.

• Command Language: Simple commands, redirects, control flow, etc.
• Oil Keywords. New keywords for assignment, etc.
• Pipeline Idioms. An essential part of shell that deserves its own document.
• Procs, Blocks, and Funcs
• Modules. Separating programs into files.

The Word Language

Words are expressions for strings, and arrays of strings.

• Word Language. Substitution, splicing, globbing, brace expansion, etc.
• Strings: Quotes, Interpolation, Escaping, and Buffers
  • Unicode. Oil supports and prefers UTF-8.
• Special Variables. Registers?
• Simple Word Evaluation. Written for shell experts.

The Expression Language

Oil has typed expressions, like Python and JavaScript.

• Expression Language. Types, literals, and operators.
• Egg Expressions. A new regex syntax, abbreviated eggex.

Languages for Data (Interchange Formats)

Oil supports these languages for data, which are complementary to languages for code.

• JSON: Currently supported only in the Python prototype of Oil.
• QSN: Quoted String Notation. A human- and machine-readable format for byte strings.
  • Framing
• QTT: Quoted, Typed Tables. An extension of TSV, built on top of QSN.

The Shared Runtime

• Interpreter State. What's inside a shell interpreter?
  • Options. Parsing and runtime options turn OSH into Oil.
  • Variable Declaration, Mutation, and Scope
• Process Model. The shell language is a thin layer over the Unix kernel.
• Tracing Execution. Oil enhances shell's set -x.
• Errors
  • Oil Fixes Shell's Error Handling (errexit)
  • Error List
• Oil Builtins (Shell builtins aren't discussed.)
  • IO Builtins
• Headless Mode. For alternative UIs on top of Oil.

For Contributors

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

Internal Details

• Notes on Oil's Architecture
  • Parser Architecture