Why Sponsor Oils? | source | version 0.19.0 | all versions | oilshell.org

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

All Docs

Oils is our upgrade path from bash to a better language and runtime. This page links to all the documentation.

† means a doc is not ready to read yet.

Preliminaries

• INSTALL. How do I install Oils? This text file is also in the tarball.
• Getting Started. How do I use the shell?
• FAQ on Documentation. Look here if you can't find something.

Reference

Like many other docs, the reference is still in progress:

• Oils Reference † - These docs underlie help builtin, and are also published online.
• Links to topics within each chapter:
  • OSH Table of Contents †
  • YSH Table of Contents †
  • Data Notation Table of Contents †
• Style Guide gives coding recommendations.

Interactive Shell

• Headless Mode. For alternative UIs on top of YSH.
• Completion †. We emulate bash completion.

OSH is a Compatible Shell

These docs are for advanced users:

• Known Differences Between OSH and Other Shells
• OSH Quirks for compatibility.
• Shell Language Idioms has some advice for using any shell, not just Oils.

YSH is a Shell with Structured Data

• A Tour of YSH. Explains YSH from scratch, without referring to shell's legacy.
• What Breaks When You Upgrade to YSH. When you turn on YSH, there are some shell constructs you can no longer use. We try to minimize the length of this list.
• YSH Language FAQ. Common questions about the language.

Comparisons

• YSH vs. Shell Idioms. A list of code snippets.
• YSH vs. Shell. High-level descriptions: how does YSH differ from Bourne/POSIX shell?
• YSH Expressions vs. Python. The expression language is borrowed from Python, with a few tweaks.
• Novelties in OSH and YSH. May be helpful for experienced programmers.

Design Concepts

• YSH Language Influences - Shell, Python, JavaScript, Lisp, ...
• Syntax
  • A Feel For YSH Syntax
  • Syntactic Concepts may help you remember the language.
  • Command vs. Expression Mode.
• Warts. Mostly for compatibility.

YSH has 3 main sublanguages:

• Command language, which now consistently uses { } for blocks.
  • Hay - Custom Languages for Unix Systems. Use Ruby-like blocks to declare data and interleaved code.
• Word language.
  • Simple Word Evaluation. Written for shell experts.
• Expression language on typed data.
  • Egg Expressions. A new regex syntax, abbreviated eggex.

Crosscutting design issues:

• Guide to Procs and Funcs
  • Block Literals †
• Variable Declaration, Mutation, and Scope
• Strings: Quotes, Interpolation, Escaping, and Buffers †
  • Unicode †. Oils supports and prefers UTF-8.
• YSH I/O Builtins †

Data Languages Avoid Ad-Hoc Parsing

YSH programs "talk about" these data languages, also called interchange formats or protocols. In-memory data structures are in service of data languages on the wire, not the other way around.

• JSON: Currently supported only in the Python prototype of YSH.
• QSN: Quoted String Notation. A human- and machine-readable format for byte strings.
  • Framing

TODO:

• J8 Notation †
• Packle †

The Shared Oils Runtime

• YSH Fixes Shell's Error Handling (errexit)
• Tracing Execution. YSH enhances shell's set -x.
• Options †. Parsing and runtime options turn OSH into YSH.

Internal details:

• Interpreter State †. What's inside a shell interpreter?
• Process Model †. The shell language is a thin layer over the Unix kernel.

For Contributors

• README.md. If you want to modify Oils, start here. We welcome contributions!
• Doc Toolchain and Doc Plugins.
• Github Wiki for oilshell/oil
• Old Docs. Drafts that may be deleted.

Internal Architecture:

• Notes on Oils Architecture
  • Parser Architecture

More

• Github Wiki for oilshell/oil.
• The blog has useful background information, although older posts are more likely to have incorrect information.
• The home page has links to docs for new users.