Home - oilshell/oil GitHub Wiki

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
• OSH versus Oil
• How To Test OSH
• Shell Programs That Run Under OSH
• Using OSH as a Default Shell
• Oil Deployments
• Migration Guide / Gradually Upgrading Shell to Oil
• 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
• Oil Language FAQ

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
• Toil / Travis CI for Oil
• 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
• Compiler Engineer Job
  • Oil Native Quick Start
  • Where Contributors Have Problems
• FAQ: Why Not Write Oil in X?
• Oil Windows Port

Docs and Writing:

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

Other:

• Project Goals

Implementation Details

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

Surveys / Design Comparison

• Alternative Shells
  • Internal DSLs for Shell
• The Biggest Shell Programs in the World
• External Resources -- More Shell Resources

More:

• Alternative Regex Syntax
• Survey of Config Languages
• Polyglot Language Understanding

Protocol Designs

• 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