Add documentation for the test command, including the newly added =~ operator and some gotchas wrt. the numeric comparisons.
Signed-off-by: Rasmus Villemoes <r...@prevas.dk> --- This should be considered on top of https://lore.kernel.org/u-boot/20250506141035.385756-1-r...@prevas.dk/ , but everything other than the regex-related stuff could stand on its own. My rst-fu is quite weak. doc/usage/cmd/setexpr.rst | 5 ++- doc/usage/cmd/test.rst | 95 +++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 3 files changed, 99 insertions(+), 2 deletions(-) create mode 100644 doc/usage/cmd/test.rst diff --git a/doc/usage/cmd/setexpr.rst b/doc/usage/cmd/setexpr.rst index 593a0ea91e1..5bc37ae50fc 100644 --- a/doc/usage/cmd/setexpr.rst +++ b/doc/usage/cmd/setexpr.rst @@ -144,8 +144,9 @@ Configuration * The *setexpr* command is only available if CMD_SETEXPR=y. * The *setexpr fmt* sub-command is only available if CMD_SETEXPR_FMT=y. -* The *setexpr gsub* and *setexpr sub* sub-commands are only available if - CONFIG_REGEX=y. +* The *setexpr gsub* and *setexpr sub* sub-commands are only available + if CONFIG_REGEX=y. For an overview of the supported regex syntax, + see :doc:`test`. Return value ------------ diff --git a/doc/usage/cmd/test.rst b/doc/usage/cmd/test.rst new file mode 100644 index 00000000000..74ee4173639 --- /dev/null +++ b/doc/usage/cmd/test.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +.. index:: + single: test (command) + +test command +============ + +Synopsis +-------- + +:: + + test <str-op> <s> + test <s1> <str-cmp> <s2> + test <n1> <num-cmp> <n2> + test ! <expr> + test <expr1> -o <expr2> + test <expr1> -a <expr2> + test -e <interface> <dev[:part]> <path> + test <s> =~ <re> + +Description +----------- + +The ``test`` command is similar to the ordinary shell built-in by the +same name. Unlike in ordinary shells, it cannot be spelled ``[``. + +Strings +~~~~~~~ + +The string tests ``-n`` and ``-z``, and string comparison operators +``=``, ``!=``, ``<`` and ``>``, work exactly as in ordinary shells. + +Numbers +~~~~~~~ + +The number comparison operators ``-lt``, ``-le``, ``-gt``, ``-gt``, +``-eq`` and ``-ne`` work as in ordinary shells. + +*Note*, however, that the numbers are parsed with ``simple_strtol(, +0)``, meaning that they are treated as decimal unless there is a 0x +prefix, any errors in parsing are ignored, and parsing stops as soon +as a non-digit (for the selected base) is encountered. And most U-Boot +commands that generate "numeric" environment variables store them as +hexadecimal *without* a 0x prefix. + +For example, this is not a correct way of testing whether a given file +has a size less then 4KiB:: + + # Assuming readme.txt exists, sets 'filesize' environment variable + $ size mmc 0:1 readme.txt + $ if test "$filesize" -lt 4096 ; then ... + +If the file size is actually 8000 (decimal), its hexadecimal +representation, and thus the value of ``$filesize``, is ``1f40``, so +the comparison that is done ends up being "1 < 4096". + +Logic +~~~~~ + +The ``!`` operator negates the sense of the test of the expression +``<expr>``. The ``-o`` and ``-a`` operators perform logical or and +logical and, respectively, of the two expressions. + +File existence +~~~~~~~~~~~~~~ + +Like ordinary shells, the ``-e`` operator can be used to test for +existence of a file. However, the U-Boot version takes three +arguments: The interface and device number (possibly including a +partition specification), in addition to the usual path. + +Regular expressions +~~~~~~~~~~~~~~~~~~~ + +When ``CONFIG_REGEX`` is enabled, an additional operator ``=~`` is +available. This is similar to the same operator available with bash's +extended test command ``[[ ]]``. The left operand is a string which is +matched against the regular expression described by the right operand. + +The regular expression engine supports these features: + +- Anchoring ``^`` and ``$``, matching at the beginning/end of the + string. +- Matching any single character (including whitespace) using ``.``. +- Character classes ``[ ]``, including ranges ``[0-9]`` and negation + ``[^ /.]``. +- Grouping ``( )``. +- Alternation ``|``. +- Postfix qualifiers ``*``, ``+`` and ``?`` and their non-greedy + variants ``*?``, ``+?`` and ``??`` + +For extracting the parts matching a capture group and/or performing +substitutions, including back references, see :doc:`setexpr`. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 372ef56c967..c5b45fd9290 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -123,6 +123,7 @@ Shell commands cmd/source cmd/tcpm cmd/temperature + cmd/test cmd/tftpput cmd/trace cmd/true -- 2.49.0
