Home

Welcome to the Oils wiki!

Note: older pages still refer to "Oil", which is now called YSH

The project is "Oils", and it contains OSH (compatible), YSH (new), and JSON-based data languages.

For Users

• Where To Send Feedback
• Oils Deployments
  • Oils Packaging Guidelines
• OSH
  • Shell Programs That Run Under OSH
  • Using OSH as a Default Shell
  • OSH Compatibility Tips
  • How To Test OSH
• OSH to YSH
  • Migration Guide / Gradually Upgrading Shell to YSH
• YSH
  • OSH versus Oil (TODO: rename to YSH)
  • Oil Language FAQ
• The Oils Repo Is Different From the Tarball Releases

More:

• Drafts
  • Why Use Oil? / Carrots
• Shell Advocacy
  • How to understand shell: Slogans, Fallacies, and Concepts (under construction)
  • How to use shell: Patterns and Anti-Patterns (under construction)
• Software Architecture
  • Perlis-Thompson Principle

For Developers

• Contributing / Spec Tests
  • Oil Dev Cheat Sheet -- useful!
  • Oil Ninja Build
  • Oil Native Quick Start
  • Where Contributors Have Problems
  • OLD: Developing Oil With Nix
• Where Contributors Have Problems
• Soil
• Git Tips -- Patterns for using Git on this project.
• Testing the Interactive Shell -- a bunch of manual test cases
• Debugging Completion Scripts -- the useful --debug-file flag!
• Collaborations
  • Using Zephyr ASDL
  • Implementing the Oil Expression Language
  • Fish Oil Brainstorming
  • Running ble.sh With Oil
• FAQ: Why Not Write Oil in X?
• Oil Windows Port

Docs and Writing:

• #oil-documentation on Zulip
• Documentation Strategy
• Technical Writing
• Oil Language Docs

Surveys / Design Comparison

Surveys and Comparisons

Implementation Details

• Signal Handling in Oil
• OSH Word Evaluation Algorithm -- shopt -s simple_word_eval (obsolete)

Protocol Designs (old)

• Coprocess Protocol Proposal
• Shellac Protocol Proposal -- for shell-independent command-line completion.
• QTT (old: TSV2 Proposal)
• QSN (old: CSTR Proposal)

Other Designs

• Language Design Principles
• Structured Data in Oil
  • Structured Data Over Pipes

• Interactive Shell -- Ideas about the interactive shell and possibly graphical shell.
  • Shell Autocompletion
  • Headless Mode - new as of 2021/04! A better, decoupled strategy for the interactive shell.
• Distributed Shell
• Config Dialect

Analysis of Previous Work and Solutions (Existing Warts to Fix)

• Shell Security Problems
• Shell WTFs
• Unix Tools -- notes on the things that a shell interacts with. The shell "standard library".
• Little Languages
• Python Gotchas
• Python Gotchas (Dataframes)
• (Broken Link: #language-design > Things Oils Shipped Without found in Language Design Principles)

Programming Language Implementation

• Parsing Case Studies -- What algorithms and tools do production-quality languages use for parsing?
• Bootstrapping Case Studies -- How are languages bootstrapped?
• Lossless Syntax Tree Pattern
• Language Subsets -- an abstract but practical way of specifying a language
• Compact AST Representation
• Architecture of Various Interpreters
• Implementing Debuggers
• Implementer Lore About Garbage Collection

Programming Language Design

• Language Data Models
• Language Design and Theory of Computation
• Metaprogramming
  • Metaprogramming Use Cases
• Partial Evaluation

Systems Design

• Recommended Reading

Programming Patterns

• Feature Detection Is Better than Version Detection
• Language Composition Bestiary
  • Ad Hoc Protocols in Unix
• Exhaustive Test Suite

Blog Themes / Post Ideas

• Oil Blog Planning
• Parsing is Difficult

Old

• OSH Parser (mostly obsolete)
• OSH Optimization Log (already blogged about stuff after this
• Project Goals
• Travis CI for Oil
• Compiler Engineer Job (2022)

Doc Languages

• Markdown Tables