From 72a7111260b94b168ed852f7ba6e9458e3bdd269 Mon Sep 17 00:00:00 2001 From: Fabian Boehm Date: Mon, 16 Jan 2023 18:36:59 +0100 Subject: [PATCH] docs: Revise command substitution section --- doc_src/language.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc_src/language.rst b/doc_src/language.rst index 1e5005ae9..cf88f52ae 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -700,11 +700,15 @@ When using this feature together with list brackets, the brackets will be used f Command substitution ^^^^^^^^^^^^^^^^^^^^ -The output of a command (or an entire :ref:`pipeline `) can be used as the arguments to another command. +A ``command substitution`` is an expansion that uses the *output* of a command as the arguments to another. For example:: -When you write a command in parentheses like ``outercommand (innercommand)``, fish first runs ``innercommand``, and then uses each line of its output as a separate argument to ``outercommand``, which will then be executed. Unlike other shells, the value of ``$IFS`` is not used [#]_, fish splits on newlines. + echo (pwd) -A command substitution can have a dollar sign before the opening parenthesis 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. +This executes the :doc:`pwd ` command, takes its output (more specifically what it wrote to the standard output "stdout" stream) and uses it as arguments to :doc:`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. + +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. If the output is piped to :doc:`string split or string split0 ` as the last step, those splits are used as they appear instead of splitting lines. @@ -728,7 +732,6 @@ Examples:: # Set ``$data`` to the contents of data, splitting on NUL-bytes. set data (cat data | string split0) - Sometimes you want to pass the output of a command to another command that only accepts files. If it's just one file, you can usually just pass it via a pipe, like:: grep fish myanimallist1 | wc -l