Why Sponsor Oils? | source | all docs for version 0.32.0 | all versions | oils.pub

YSH and OSH Topics by Feature

(in progress)

This page links to topics in the Oils Reference. It's organized differently than the YSH Table of Contents or OSH Table of Contents.

Where YSH Improves on OSH

Errors

YSH:

• try
• _error
• multiple processes
  • _pipeline_status
  • _process_sub_status
• Options:
  • strict_errexit, command_sub_errexit, ...

OSH:

• $? - not idiomatic in YSH
• Options:
  • errexit, pipefail, inherit_errexit

Environment Variables

YSH:

• ENV
• ysh-prefix-binding - for NAME=val env bindings
• simple-command - external commands are started with an environ
• Options:
  • shopt --unset no_exported
  • shopt --set env_obj

OSH:

• export
• prefix-binding - for NAME=val env bindings

I/O

YSH:

• write
  • ysh-echo is a shortcut for write
• ysh-read - read --all, etc.
• redir
• The io object

OSH:

• printf

Procs

YSH:

• proc
• Invokable objects: __invoke__, Obj
• simple-command is how you invoke procs

OSH:

• sh-func

Modules

• use
• is-main
• provide (TODO)
• _this_dir
• __provide__
• An imported module is an Obj with an __invoke__ method

OSH:

• source
• source-guard

Interactive Shell

• renderPrompt()

OSH:

• complete
• Oils enhancements: compexport, compadjust

Job Control

• ampersand &
  • YSH has fork
• wait
  • YSH adds --all --verbose: ysh-wait
• fg
• bg
• $!

Tracing Execution

• set -x aka set -o xtrace
• PS4
• SHX_*

Introspecting the Call Stack

OSH Debug Stack:

• BASH_SOURCE
• FUNCNAME
• BASH_LINENO

YSH Debug Stack:

• DebugFrame
  • toString() method
• vm.getDebugStack()

These may be combined with

• trap ERR
• set -o errtrace aka set -E

Reflection

Other YSH reflection:

• The io object has eval() methods, etc.
• The vm object for inspecting interpreter structures

Unicode

• TODO: which functions respect Unicode?

Also see the Unicode doc.

YSH Only

Objects

• Obj
  • __invoke__
  • TODO: __call__
  • first() and rest()
  • ENV is an Obj
• operator . ysh-attr
• operator -> thin-arrow

Closures

A closure is a way of bundling data and code. The idea originated in Lisp, and is widely used in JavaScript.

YSH behaves much like JavaScript. Exception: YSH has flat function scope, except for the body of for loops.

• Types that are closures:
  • Command and Expr
  • Proc and Func
• ysh-for creates new frames, which may be captured by any of the 4 closure types
  • This is enabled with shopt --set for_loop_frames, part of option group ysh:all
• var and setvar determine if you're creating a new variable, or modifying one that's "closed over"

Funcs

• func
• Callable objects: __call__ and Obj (TODO)
• ysh-func-call

Namespaces

• ENV
• __builtins__

Purity

• shell-flags for --eval-pure
• func/eval and func/evalExpr
• func - functions are pure
• io and vm - impure behavior is attached to these objects

OSH Features