From f4a3dcca3a631eb62a1752eb91f6432ae860fb86 Mon Sep 17 00:00:00 2001 From: Fabian Boehm Date: Mon, 1 Apr 2024 15:40:25 +0200 Subject: [PATCH] docs: Clarify command substitution section Put `$()` version front-and-center and make the quoting more prominent. In turn mention `()` as a version that can't be quoted. --- doc_src/language.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc_src/language.rst b/doc_src/language.rst index 8fa9c1676..af7d3a15e 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -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:: - echo (pwd) + echo $(pwd) 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. +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 ` 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 ` variable if the substitution happens in the context of a :doc:`set ` command (so ``if set -l (something)`` checks if ``something`` returned true). To use only some lines of the output, refer to :ref:`slices `.