Add documentation for the test command, including the newly added =~
operator and some gotchas wrt. the numeric comparisons.
Reviewed-by: Simon Glass <s...@chromium.org>
Signed-off-by: Rasmus Villemoes <r...@prevas.dk>
---
doc/usage/cmd/setexpr.rst | 5 +-
doc/usage/cmd/test.rst | 102 ++++++++++++++++++++++++++++++++++++++
doc/usage/index.rst | 1 +
3 files changed, 106 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..d1379117fca
--- /dev/null
+++ b/doc/usage/cmd/test.rst
@@ -0,0 +1,102 @@
+.. 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::
+ 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 than 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 (e.g. ``mmc``).
+- The device number, possibly including a partition specification.
+- The usual path argument, which is interpreted relative to the root
+ of the filesystem.
+
+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
