Why Sponsor Oils? | source | all docs for version 0.27.0 | all versions | oils.pub
Oils Reference — Chapter Special Variables
This chapter describes special variables for OSH and YSH.
(in progress)
Replacement for "$@"
An Obj that's populated with environment variables. Example usage:
var x = ENV.PYTHONPATH
echo $[ENV.SSH_AUTH_SOCK]
It's initialized exactly once per process, in any of these situations:
shopt --set env_obj is on. This is true when invoking
bin/ysh.bin/osh -o ysh:upgrade or ysh:all.shopt --set ysh:upgrade or ysh:all.When launching an external command, the shell creates a Unix environ from the
ENV Obj. This means that mutating it affects all subsequent processes:
setglobal ENV.PYTHONPATH = '.'
./foo.py
./bar.py
You can also limit the change to a single process, without ENV:
PYTHONPATH=. ./foo.py
./bar.py # unaffected
YSH reads these ENV variables:
PATH - where to look for executablesPS1 - how to print the promptPS4 - how to show execution tracesYSH_HISTFILE (HISTFILE in OSH) - where to read/write command historyHOME - for tilde substitution (tilde-sub)__defaults__The shell puts some default settings in this Dict. In certain situations, it
consults __defaults__ after consulting ENV. For example:
ENV.PATH is not set, consult __defaults__.PATHENV.PS1 is not set, consult __defaults__.PS1__builtins__An object that contains names visible in every module.
If a name is not visible in the local scope, or module global scope, then it's
looked up in __builtins__.
_this_dirThe directory the current script resides in. This knows about 3 situations:
oshrc in an interactive shellosh myscript.shsource builtinIt's useful for "relative imports".
_statusDEPRECATED: Use _error.code instead.
_errorA Dict that's set by the try builtin.
The integer _error.code is always present:
try {
ls /tmp
}
echo "status is $[_error.code]"
Some errors also have a message field, like JSON/J8 encoding/decoding errors,
and user errors from the error builtin.
try {
echo $[toJson( /d+/ )] # invalid Eggex type
}
echo "failed: $[_error.message]" # => failed: Can't serialize ...
_pipeline_statusAfter a pipeline of processes is executed, this array contains the exit code of each process.
Each exit code is an Int. Compare with
PIPESTATUS.
_process_sub_statusThe exit status of all the process subs in the last command.
Builtins that read set this variable:
read --all < foo.txt
= _reply # => 'contents of file'
json read < foo.json
= _reply # => (Dict) {}
OILS_VERSIONThe version of Oils that's being run, e.g. 0.23.0.
LIB_OSHThe string ///osh, which you can use with the source builtin.
source $LIB_OSH/two.sh
LIB_YSHThe string ///ysh, which you can use with the source builtin.
source $LIB_YSH/yblocks.ysh
OILS_GC_THRESHOLDAt a GC point, if there are more than this number of live objects, collect garbage.
OILS_GC_ON_EXITSet OILS_GC_ON_EXIT=1 to explicitly collect and free() before the process
exits. By default, we let the OS clean up.
Useful for ASAN testing.
OILS_GC_STATSWhen the shell process exists, print GC stats to stderr.
OILS_GC_STATS_FDWhen the shell process exists, print GC stats to this file descriptor.
The float value for "not a number".
(The name is consistent with the C language.)
The float value for "infinity". You can negate it to get "negative infinity".
(The name is consistent with the C language.)
__provide__A module is evaluated upon use. After evaluation, the names in the
__provide__ List are put in the resulting module Obj instance.
$@ $* $# $? $- $$ $! $0 $9
Used for word splitting. And the builtin shSplit() function.
TODO: bash compat
TODO: bash compat
bash compat: serialized options for the set builtin.
bash compat: serialized options for the shopt builtin.
(Not implemented.)
The $HOME env var is read by the shell, for:
~ expansion~ abbreviation in the UI (the dirs builtin, \W in $PS1).The shell does not set $HOME. According to POSIX, the program that invokes the
login shell should set it, based on /etc/passwd.
A colon-separated string that's used to find executables to run.
In YSH, it's ENV.PATH.
Result of regex evaluation [[ $x =~ $pat ]].
After a pipeline of processes is executed, this array contains the exit code of each process.
Each exit code is a Str. Compare with
_pipeline_status.
The name of the "host" or machine that Oils is running on, determined by
gethostname().
The operating system that Oils is running on, determined by uname().
Examples: linux darwin ...
TODO
TODO
An array of words, split by : and = for compatibility with bash. New completion scripts should use COMP_ARGV instead.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
Discouraged; for compatibility with bash.
User-defined completion functions should Fill this array with candidates. It is cleared on every completion request.
An array of partial command arguments to complete. Preferred over COMP_WORDS. The compadjust builtin uses this variable.
(An OSH extension to bash.)
Override the default OSH history location.
Override the default YSH history location.
Set which completion UI to use. Defaults to minimal.
minimal - a UI that approximates the default behavior of GNU readline.nice - a UI with a fancy pager and a prompt with horizontal scrolling instead of wrapping.This variable is currently only checked once during shell initialization.
OSH read sets this:
read < myfile
bash compat
bash compat