[PATCH] doc: document test command

[Rasmus Villemoes]

Add documentation for the test command, including the newly added =~
operator and some gotchas wrt. the numeric comparisons.

Signed-off-by: Rasmus Villemoes <ravi at prevas.dk>
---

This should be considered on top of
https://lore.kernel.org/u-boot/20250506141035.385756-1-ravi@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