= Built-in commands
:encoding: UTF-8
:lang: en
//:title: Yash manual - Built-in commands
:description: This page describes common properties of built-ins of yash.

dfn:[Built-in commands] are commands that are implemented in the shell and are
executed by the shell without starting external programs.

ifdef::basebackend-html[]
See the link:index.html#builtins[table of contents] for the list of the
built-ins.
endif::basebackend-html[]

[[types]]
== Types of built-in commands

Yash has several types of built-in commands described below.

dfn:[Special built-in commands] are the most important kinds of built-in
commands.
They are executed regardless of whether the corresponding external commands
exist or not. Results of variable assignments that occur in a
link:syntax.html#simple[simple command] that invokes a special built-in last
after the command has finished. Moreover, in the
link:posix.html[POSIXly-correct mode], a link:interact.html[non-interactive]
shell immediately exits with a non-zero exit status when an error occurs in a
simple command executing a special built-in.

dfn:[Mandatory built-in commands] and dfn:[elective built-in commands] are
similar to special built-ins in that they do not need external commands to be
executed but differ in that they may be overridden by
link:exec.html#function[functions].
While mandatory built-ins are always available, you cannot use elective
built-ins in the link:posix.html[POSIXly-correct mode] because POSIX only
reserves their names without defining their behavior.

An dfn:[extension built-in command] is a built-in that is not mentioned in
POSIX. Like an elective built-in, it can be executed without an external
command when the link:posix.html[POSIXly-correct mode] is off. However, when
the POSIXly-correct mode is on, the shell works as if the built-in does not
exist.

dfn:[Substitutive built-in commands] work on behalf of external commands
link:exec.html#search[found in PATH]. These built-ins improve execution speed
by bypassing invocation overheads for external programs.

[[argsyntax]]
== Syntax of command arguments

In this section we explain common rules about command arguments. 
The built-in commands of yash follow the rules unless otherwise stated. 

There are two types of command arguments. One is options and the other is
operands. An option is an argument that starts with a hyphen (+-+) and
changes the way the command behaves. Some options take arguments. An operand
is an argument that is not an option and specifies objects the command
operates on.

If you specify more than one option to a command, the order of the options are
normally not significant. The order of operands, however, affects the command
behavior.

An option is either a single-character option or a long option.
A single-character option is identified by one alphabetic character. A long
option is identified by multiple alphabetic characters. The POSIX standard only
prescribes single-character options, so in the link:posix.html[POSIXly-correct
mode] you cannot use long options.

A single-character option is composed of a hyphen followed by a letter. For
example, +-a+ is a single-character option. A single-character option that
takes an argument requires the argument to be just after the option name.

.The set built-in and single-character options
====
For the set built-in, +-m+ is a single-character option that does not take an
argument and +-o+ is one that takes an argument.

- +set -o errexit -m+
- +set -oerrexit -m+

In these two command lines, +errexit+ is the argument to the +-o+ option.
====

In the second example above, the +-o+ option and its argument are combined
into a single command line argument.
The POSIX standard deprecates that style and any POSIX-conforming applications
must specify options and their arguments as separate command line arguments,
although yash accepts both styles.

You can combine single-character options that do not take arguments into a
single command line argument. For example, the three options +-a+, +-b+ and
+-c+ can be combined into +-abc+.

A long option is composed of two hyphens followed by an option name.
For example, +--long-option+ is a long option.
You can omit some last characters of a long option name as long as it is not ambiguous.
For example, you can use +--long+ instead of +--long-option+
if there is no other options beginning with +--long+.
Like a single-character option, a long option that takes an argument requires
the argument to be a command line argument just after the option name or to be
specified in the same command line argument as the option name,
separated by an equal sign (+=+).

.The fc built-in and long options
====
For the fc built-in, +--quiet+ is a long option that does not take an argument
and +--editor+ is one that takes an argument.

- +fc --editor vi --quiet+
- +fc --editor=vi --quiet+

In these command lines, +vi+ is the argument to the +--editor+ option. 
====

Arguments that are not options (nor arguments to them) are interpreted as
operands. The POSIX standard requires all options should be specified before
any operands. Therefore, in the link:posix.html[POSIXly-correct mode], any
arguments that come after the first operand are interpreted as operands (even
if they look like options). If not in the POSIXly-correct mode, you can
specify options after operand.

Regardless of whether the shell is in the POSIXly-correct mode or not, an
argument that is just composed of two hyphens (+--+) can be used as a
separator between options and operands. All command line arguments after the
+--+ separator are interpreted as operands, so you can specify operands that
start with a hyphen correctly using the separator.

.Options and operands to the set built-in
====
- `set -a -b -- -c -d`

In this example, +-a+ and +-b+ are options and +-c+ and +-d+ are operands. The
+--+ separator itself is neither an option nor an operand.
====

Regardless of whether the shell is in the POSIXly-correct mode or not, an
argument that is just composed of a single hyphen (+-+) is interpreted as an
operand.

// vim: set filetype=asciidoc textwidth=78 expandtab:
