Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-11-10 07:04:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: Clarify command substitution section

Browse source 
Put `$()` version front-and-center and make the quoting more
prominent.

In turn mention `()` as a version that can't be quoted.
This commit is contained in:
Fabian Boehm 2024-04-01 15:40:25 +02:00
parent 3a98db46bc
commit f4a3dcca3a
1 changed files with 8 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
doc_src/language.rst
View file

@ -800,16 +800,22 @@ Command substitution
A ``command substitution`` is an expansion that uses the *output* of a command as the arguments to another. For example:: A ``command substitution`` is an expansion that uses the *output* of a command as the arguments to another. For example::
echo (pwd) echo $(pwd)
This executes the :doc:`pwd <cmds/pwd>` command, takes its output (more specifically what it wrote to the standard output "stdout" stream) and uses it as arguments to :doc:`echo <cmds/echo>`. So the inner command (the ``pwd``) is run first and has to complete before the outer command can even be started. This executes the :doc:`pwd <cmds/pwd>` command, takes its output (more specifically what it wrote to the standard output "stdout" stream) and uses it as arguments to :doc:`echo <cmds/echo>`. So the inner command (the ``pwd``) is run first and has to complete before the outer command can even be started.
If the inner command prints multiple lines, fish will use each separate line as a separate argument to the outer command. Unlike other shells, the value of ``$IFS`` is not used [#]_, fish splits on newlines. If the inner command prints multiple lines, fish will use each separate line as a separate argument to the outer command. Unlike other shells, the value of ``$IFS`` is not used [#]_, fish splits on newlines.
A command substitution can also be spelled with a dollar sign like ``outercommand $(innercommand)``. This variant is also allowed inside double quotes. When using double quotes, the command output is not split up by lines, but trailing empty lines are still removed. Command substitutions can also be double-quoted::
echo "$(pwd)"
When using double quotes, the command output is not split up by lines, but trailing empty lines are still removed.
If the output is piped to :doc:`string split or string split0 <cmds/string-split>` as the last step, those splits are used as they appear instead of splitting lines. If the output is piped to :doc:`string split or string split0 <cmds/string-split>` as the last step, those splits are used as they appear instead of splitting lines.
Fish also allows spelling command substitutions without the dollar, like ``echo (pwd)``. This variant will not be expanded in double-quotes (``echo "(pwd)"`` will print ``(pwd)``).
The exit status of the last run command substitution is available in the :ref:`status <variables-status>` variable if the substitution happens in the context of a :doc:`set <cmds/set>` command (so ``if set -l (something)`` checks if ``something`` returned true). The exit status of the last run command substitution is available in the :ref:`status <variables-status>` variable if the substitution happens in the context of a :doc:`set <cmds/set>` command (so ``if set -l (something)`` checks if ``something`` returned true).
To use only some lines of the output, refer to :ref:`slices <expand-slices>`. To use only some lines of the output, refer to :ref:`slices <expand-slices>`.