From fa928754c7bbae5e59ae15e50ac397f8217b8357 Mon Sep 17 00:00:00 2001 From: Fabian Boehm Date: Sat, 13 Apr 2024 11:45:16 +0200 Subject: [PATCH] document test-require-arg --- doc_src/cmds/test.rst | 13 ++++++++++++- doc_src/language.rst | 2 ++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/doc_src/cmds/test.rst b/doc_src/cmds/test.rst index 506f863233ed..1d4111122c16 100644 --- a/doc_src/cmds/test.rst +++ b/doc_src/cmds/test.rst @@ -26,7 +26,15 @@ The first form (``test``) is preferred. For compatibility with other shells, the When using a variable or command substitution as an argument with ``test`` you should almost always enclose it in double-quotes, as variables expanding to zero or more than one argument will most likely interact badly with ``test``. -For historical reasons, ``test`` supports the one-argument form (``test foo``), and this will also be triggered by e.g. ``test -n $foo`` if $foo is unset. We recommend you don't use the one-argument form and quote all variables or command substitutions used with ``test``. +.. warning:: + + For historical reasons, ``test`` supports the one-argument form (``test foo``), and this will also be triggered by e.g. ``test -n $foo`` if $foo is unset. We recommend you don't use the one-argument form and quote all variables or command substitutions used with ``test``. + + This confusing misfeature will be removed in future. ``test -n`` without any additional argument will be false, ``test -z`` will be true and any other invocation with exactly one or zero arguments, including ``test -d`` and ``test "foo"`` will be an error. + + The same goes for ``[``, e.g. ``[ "foo" ]`` and ``[ -d ]`` will be errors. + + This can be turned on already via the ``test-require-arg`` :ref:`feature flag `, and will eventually become the default and then only option. Operators for files and directories ----------------------------------- @@ -185,6 +193,8 @@ Be careful with unquoted variables:: echo $MANPATH end +This will change in a future release of fish, or already with the ``test-require-arg`` :ref:`feature flag ` - if $MANPATH is unset, ``if test -n $MANPATH`` will be false. + Parentheses and the ``-o`` and ``-a`` operators can be combined to produce more complicated expressions. In this example, success is printed if there is a ``/foo`` or ``/bar`` file as well as a ``/baz`` or ``/bat`` file. :: @@ -234,6 +244,7 @@ Standards Unlike many things in fish, ``test`` implements a subset of the `IEEE Std 1003.1-2008 (POSIX.1) standard `__. The following exceptions apply: - The ``<`` and ``>`` operators for comparing strings are not implemented. +- With ``test-require-arg``, the zero- and one-argument modes will behave differently. In cases such as this, one can use ``command`` ``test`` to explicitly use the system's standalone ``test`` rather than this ``builtin`` ``test``. diff --git a/doc_src/language.rst b/doc_src/language.rst index 7228a49ed8a1..3d60f71b5d78 100644 --- a/doc_src/language.rst +++ b/doc_src/language.rst @@ -2010,6 +2010,7 @@ You can see the current list of features via ``status features``:: regex-easyesc on 3.1 string replace -r needs fewer \\'s ampersand-nobg-in-token on 3.4 & only backgrounds if followed by a separating character remove-percent-self off 3.8 %self is no longer expanded (use $fish_pid) + test-require-arg off 3.8 builtin test requires an argument Here is what they mean: @@ -2018,6 +2019,7 @@ Here is what they mean: - ``regex-easyesc`` was introduced in 3.1. It makes it so the replacement expression in ``string replace -r`` does one fewer round of escaping. Before, to escape a backslash you would have to use ``string replace -ra '([ab])' '\\\\\\\\$1'``. After, just ``'\\\\$1'`` is enough. Check your ``string replace`` calls if you use this anywhere. - ``ampersand-nobg-in-token`` was introduced in fish 3.4. It makes it so a ``&`` i no longer interpreted as the backgrounding operator in the middle of a token, so dealing with URLs becomes easier. Either put spaces or a semicolon after the ``&``. This is recommended formatting anyway, and ``fish_indent`` will have done it for you already. - ``remove-percent-self`` turns off the special ``%self`` expansion. It was introduced in 3.8. To get fish's pid, you can use the :envvar:`fish_pid` variable. +- ``test-require-arg`` removes :doc:`builtin test `'s one-argument form (``test "string"``. It was introduced in 3.8. To test if a string is non-empty, use ``test -n "string"``. These changes are introduced off by default. They can be enabled on a per session basis::