Description: This page describes parameters and variables supported by yash.

# Parameters and variables

Parameters are string values that are expanded in parameter expansion. There are three types of parameters: positional parameters, special parameters and variables.

## Positional parameters

Positional parameters are parameters that are identified by natural numbers. If there are three positional parameters, for example, they are identified as `1`, `2`, and `3`. You can obtain the number of positional parameters by the `#` special parameter. The `*` and `@` special parameters are expanded to all positional parameters.

Positional parameters are initialized from the shell’s command line arguments when the shell is started (see Command line arguments). In the initialization, the order of the operands are preserved as the order of the positional parameters.

When the shell executes a function call, positional parameters are changed to the arguments to the function call so that you can access the arguments while the function is being executed. Positional parameters are restored to the original values when the execution of the function is finished.

Positional parameters can be manipulated by built-in commands like set and shift.

Note that `0` is not a positional parameter but a special parameter.

## Special parameters

Special parameters are parameters each identified by a single symbol. They cannot be directly assigned to by the user.

Yash provides the following special parameters:

`0`

  The name of the shell executable file or the script file that was specified in the invocation of the shell.

`#`

  The number of current positional parameters. The value is a non-negative integer.

`$`

  The process ID of the shell. The value is a positive integer and is never changed even in subshells.

`-`

  Currently enabled shell options. The value is a concatenation of alphabet characters that are the names of currently enabled single-character options that can be specified in shell invocation. The value reflects changes of enabled options when you enable or disable options using the set built-in.

`?`

  The exit status of the last executed pipeline. The value is a non-negative integer.

`!`

  The process ID of the last started asynchronous list or the last resumed background job.

`*`

  This special parameter represents the whole positional parameters. When there is no positional parameters, the value of this special parameter is the empty string. When there is more than one positional parameter, the value is a concatenation of all the positional parameters, each of which is separated as follows:

  - If the `IFS` variable exists and its value is not empty, positional parameters are each separated by the first character of the value of the `IFS` variable.

  - If the `IFS` variable exists and has an empty value, positional parameters are just concatenated without any separator.

  - If the `IFS` variable does not exist, positional parameters are each separated by a space character.

  If field-splitting is applied to an expansion result of this parameter, the value is first split into the original positional parameters and then further split depending on the current `IFS` variable. The first splitting is performed even if the `IFS` variable is empty.

`@`

  This special parameter represents the whole positional parameters like the `*` special parameter above. The difference between the two is the results of expansion that occurs between a pair of double-quotation marks. If the `@` special parameter is expanded inside double-quotations, the result is field-split into the exact positional parameter values. If there are no positional parameters, the expansion yields no word rather than an empty word. (Even if the expansion is double-quoted, the result is not always a single word.)

  - When there are no positional parameters, the command words `echo 1 "$@" 2` are expanded to the three words `echo`, `1`, and `2`.

  - When positional parameters are the three words `1`, `2 2`, and `3`, the command words `echo "$@"` are expanded to the four words `echo`, `1`, `2 2`, and `3`, and the words `echo "a$@b"` to the four words `echo`, `a1`, `2 2`, and `3b`.

## Variables

Variables are parameters the user can assign values to. Each variable has a name that identifies it and a value that defines the results of expansion.

A variable name is composed of one or more alphanumeric characters and underscores (`_`). A name cannot start with a digit. Other characters may be used in a name depending on internationalization support of your environment.

Variables that are exported to external commands are called environment variables. They are passed to all external commands the shell invokes. Variables passed to the shell in invocation will be automatically exported.

You can assign to variables by a simple command as well as the typeset built-in. You can remove variables by using the unset built-in.

### Variables used by the shell

The following variables are used by the shell for special purposes.

`CDPATH`

  This variable is used by the cd built-in to find a destination directory.

`COLUMNS`

  This variable specifies the width (the number of character columns) of the terminal screen. The value affects the display of line-editing.

`COMMAND`

  While a post-prompt command is being executed, this variable is set to the just input command line. It will be unset after the post-prompt command finishes.

`COMMAND_NOT_FOUND_HANDLER`

  When the shell cannot find a command to be executed, the value of this variable is interpreted and executed instead. You can override the shell’s error handling behavior with this variable. See Execution of simple commands for detail.

  This feature is disabled in the POSIXly-correct mode.

`DIRSTACK`

  This array variable is used by the shell to store the directory stack contents. If you modify the value of this variable, the directory stack may be corrupted.

`ECHO_STYLE`

  This variable specifies the behavior of the echo built-in.

`ENV`

  When an interactive shell is started in the POSIXly-correct mode, the value of this variable is used to find the initialization file. See Initialization of yash.

`FCEDIT`

  This variable specifies an editor program used to edit command lines during execution of the fc built-in.

`HANDLED`

  This variable can be set in the command-not-found handler to tell the shell not to produce a further error message. See Execution of simple commands for detail.

`HISTFILE`

  This variable specifies the pathname of the file to save the command history in.

`HISTRMDUP`

  This variable specifies the number of command history items to be checked for duplication. When the shell is adding a new history item to the command history, if some of the most recent n items have the same contents as the new one, then the duplicate existing items are removed from the history before the new one is added, where n is the value of this variable.

  If the value of this variable is `1`, for example, the most recent item is removed when a new item that have the same contents is added.

  Items older than the nth recent item are not removed. No items are removed if the value of this variable is `0`. All items are subject to removal if the variable value is greater than or equal to the value of the `HISTSIZE` variable.

`HISTSIZE`

  This variable specifies the maximum number of items in the command history.

`HOME`

  This variable specifies the pathname of the user’s home directory and affects results of tilde expansion and cd built-in.

`IFS`

  This variable specifies separators used in field splitting. The variable value is initialized to the three characters of a space, a tab, and a newline when the shell is started.

`LANG`
`LC_ALL`
`LC_COLLATE`
`LC_CTYPE`
`LC_MESSAGES`
`LC_MONETARY`
`LC_NUMERIC`
`LC_TIME`

  These variables specify a locale in which the shell runs. The shell chooses the file input/output encoding, the error message language, etc. according to the locale specified.

  Unless the shell is interactive and not in the POSIXly-correct mode, the value of the `LC_CTYPE` variable is considered only when the shell is started. Once the shell has been initialized, changing the value of `LC_CTYPE` will have no effect on the shell’s behavior.

`LINENO`

  The value of this variable is automatically set to the line number in which the currently executed command appears in the file.

  In the interactive shell, the line number is reset to 1 each time the shell reads and executes a command.

  If you assign to or remove this variable, it will no longer provide line numbers.

`LINES`

  This variable specifies the height (the number of character lines) of the terminal screen. The value affects the display of line-editing.

`MAIL`

  This variable specifies the pathname of a file that is checked in mail checking.

`MAILCHECK`

  This variable specifies how often the shell should do mail checking. The value has to be specified as a positive integer in seconds. The value is initialized to the default value of `600` when the shell is started.

`MAILPATH`

  This variable specifies the pathnames of files that are checked in mail checking.

`NLSPATH`

  The POSIX standard prescribes that the value of this variable specifies pathname templates of locale-dependent message data files, but yash does not use it.

`OLDPWD`

  This variable is set to the previous working directory path when you change the working directory by using the cd or other built-ins. This variable is exported by default.

`OPTARG`

  When the getopts built-in parses an option that takes an argument, the argument value is assigned to this variable.

`OPTIND`

  The value of this variable specifies the index of an option that is to be parsed by the next getopts built-in execution. This variable is initialized to `1` when the shell is started.

`PATH`

  This variable specifies paths that are searched for a command in command search.

`POST_PROMPT_COMMAND`

  The shell interprets and executes the value of this variable after reading each command if the shell is interactive and not in the POSIXly-correct mode. See Prompts for details.

`PPID`

  The value of this variable is the process ID of the shell’s parent process, which is a positive integer. This variable is initialized when the shell is started. The value is not changed when the shell makes a new subshell.

`PROMPT_COMMAND`

  The shell interprets and executes the value of this variable before printing each command prompt if the shell is interactive and not in the POSIXly-correct mode. This behavior is equivalent to executing the command `eval -i -- "${PROMPT_COMMAND-}"` before each command prompt, but its exit status does not affect the expansion of the `?` special parameter in the next command.

`PS1`

  This variable specifies the main command prompt string printed by an interactive shell. See Prompts for the format of the variable value. The value is initialized to either `$` or `#` depending on whether the effective user ID of the shell process is zero or not.

`PS1P`

  This variable specifies the font style of predicted commands. See Prompts for the format of the variable value.

`PS1R`

  This variable specifies the auxiliary prompt string printed to the right of the cursor when you input a command line to an interactive shell. See Prompts for the format of the variable value.

`PS1S`

  This variable specifies the font style of command strings you enter to an interactive shell. See Prompts for the format of the variable value.

`PS2`

  This variable is like the `PS1` variable, but it is used for the second and following lines of a command that is longer than one line. See Prompts for the format of the variable value. The value is initialized to `>` when the shell is started.

`PS2P`

  This variable is like the `PS1P` variable, but it is used when `PS2` is used. See Prompts for the format of the variable value.

`PS2R`

  This variable is like the `PS1R` variable, but it is used when `PS2` is used. See Prompts for the format of the variable value.

`PS2S`

  This variable is like the `PS1S` variable, but it is used when `PS2` is used. See Prompts for the format of the variable value.

`PS4`

  The value of this variable is printed before each command trace output when the xtrace option is enabled. The value is subject to parameter expansion, command substitution, arithmetic expansion. You can also use backslash notations if the shell is not in the POSIXly-correct mode. The value is initialized to `+` when the shell is started.

`PS4S`

  This variable is like the `PS1S` variable, but it is used when `PS4` is used. You can use this variable to modify font style of command trace output.

`PWD`

  The value of this variable is the pathname of the current working directory. The value is set when the shell is started and reset each time the working directory is changed by the cd or other built-ins. This variable is exported by default.

`RANDOM`

  You can use this variable to get random numbers. The value of this variable is a uniformly distributed random integer between 0 and 32767 (inclusive). You will get a different number each time the variable is expanded.

  You can set the “seed” of random numbers by assigning a non-negative integer to the variable.

  If you remove this variable, it will no longer work as a random number generator. If the shell was invoked in the POSIXly-correct mode, this variable does not work as a random number generator.

`TERM`

  This variable specifies the type of the terminal in which the shell is running. The value affects the behavior of line-editing. This variable has to be exported to take effect.

`XDG_CONFIG_HOME`

  This variable can be defined to specify the location where shell initialization files are placed. If not defined, it is assumed to be `$HOME/.config`.

`YASH_AFTER_CD`

  The shell interprets and executes the value of this variable after each time the shell’s working directory is changed by the cd or other built-ins. This behavior is equivalent to executing the command `eval -i -- "${YASH_AFTER_CD-}"` after the directory was changed.

`YASH_LOADPATH`

  This variable specifies directories the dot built-in searches for a script file. More than one directory can be specified by separating them by colons like the `PATH` variable. When the shell is started, this variable is initialized to the pathname of the directory where common script files are installed.

`YASH_LE_TIMEOUT`

  This variable specifies how long the shell should wait for a next possible input from the terminal when it encountered an ambiguous control sequence while line-editing. The value must be specified in milliseconds. If you do not define this variable, the default value of 100 milliseconds is assumed.

`YASH_PS1`
`YASH_PS1P`
`YASH_PS1R`
`YASH_PS1S`
`YASH_PS2`
`YASH_PS2P`
`YASH_PS2R`
`YASH_PS2S`
`YASH_PS4`
`YASH_PS4S`

  When not in the POSIXly-correct mode, if any of these variables is defined, it takes precedence over the corresponding variable without the `YASH_` prefix in the name (e.g. `PS1`). These variables are ignored in the POSIXly-correct mode. You should define them to include yash-specific notations in the prompt, so that unhandled notations do not mangle the prompt in the POSIXly-correct mode.

`YASH_VERSION`

  The value is initialized to the version number of the shell when the shell is started.

### Arrays

An array is a variable that contains zero or more strings. The string values of an array are identified by natural numbers (like positional parameters).

You can assign values to an array by using a simple command as well as the array built-in. You can use the unset built-in to remove arrays.

Arrays cannot be exported as arrays. When an array is exported, it is treated as a normal variable whose value is a concatenation of all the array values, each separated by a colon.

Arrays are not supported in the POSIXly-correct mode.