Why Sponsor Oils? | source | version 0.23.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

This page links to all docs. A dagger † means a doc isn't finished.

See Published Docs for those that are ready to read.

Good Places to Start

• A Tour of YSH
• YSH vs. Shell Idioms
• Oils Reference - underlies the help builtin
• FAQ on Docs. Look here if you can't find something.

Preliminaries

• INSTALL. How do I install Oils? This text file is also in the oils-for-unix tarball.
  • Portability
• Getting Started. How do I use the shell?

Interactive Shell

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

OSH is a Compatible Shell

• Shell Language Idioms has some advice for using any shell, not just Oils.
• OSH Standard Library †. Small but useful enhancements.

For sophisticated users:

• Known Differences Between OSH and Other Shells
• OSH Quirks for compatibility.

YSH is a New, Powerful Shell

• 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
• YSH Style Guide

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.
  • YSH Regex API. Convenient and powerful.

Features:

• Guide to YSH Error Handling
• Guide to Procs and Funcs
  • Block Literals †

Designs for "Maximalist YSH":

• Streams, Tables, and Processes - awk, R, xargs †
• Document Processing in YSH - Notation, Query, Templating †

Crosscutting design issues:

• 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.

• J8 Notation. An upgrade of JSON to bytes, strings, lines, and structured data.
  • JSON. Some usage details.
  • Framing †
• BYO Protocols - for testing and completion.

The Shared Oils Runtime

• Types in the Oils Runtime
• YSH Fixes Shell's Error Handling (errexit)
• Oils Error Catalog, With Hints
• 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
• Pretty Printing - March 2024 design notes.
• mycpp/README - How we translate typed Python to C++.

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.

Old:

• INSTALL-old for the slow oil-$VERSION tarball, based on CPython.