[PATCH] doc: document test command

[Rasmus Villemoes]

On Mon, May 12 2025, Quentin Schulz <quentin.schulz at cherry.de> wrote:

> Hi Rasmus,
>

Hi Quentin

Thanks for the review.

> On 5/6/25 10:54 PM, Rasmus Villemoes wrote:
>> +
>> +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(,
>
> Maybe use an admonition here?
>
> Something like
>
> .. note:: Numbers are parsed with ``simple_strtol(,0)`` ...
>
> so it's (hopefully) properly highlighted?

Good idea, as I said I'm not really an rst expert so I mostly just
copy-paste.

>> +0)``, meaning that they are treated as decimal unless there is a 0x
>
> ``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.
>> +
>
> ``0x`` ?
>

Hm, perhaps, I'm not sure if "code" highlighting is the best for those
0x, but I agree that some highlighting is in order.

>> +For example, this is not a correct way of testing whether a given file
>> +has a size less then 4KiB::
>> +
>
> s/then/than/

Ack.

>> +  # 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".
>> +
>
> All nicely explained! Can you provide an example on how to do this
> properly though?
>
> I assume something like:
>
> if test "0x$filesize" -lt 4096 ; then ...
>
> maybe?

Yes, I think that would be the proper way - but it's really messy,
because if you ever have some variable that happens to contain a hex
number with a 0x prefix, adding another 0x in front would end up
yielding 0 when parsed. So I don't want to give the impression that one
should always blindly prefix 0x (also, sometimes one really does have a
decimal value). So I'm actually leaning on leaving a "positive" example
out, to force a developer to think.

>> +Logic
>> +~~~~~
>> +
>> +The ``!`` operator negates the sense of the test of the expression
>> +``<expr>``. The ``-o`` and ``-a`` operators perform logical or and
>
> logical OR and logical AND (and maybe even highlight them with
> backticks like ``OR``?) to make them stand out of the sentence since
> those are typical English words it may make it harder to parse the
> sentence if left looking like all other words?

Ah yes, ack, I did think about the "logical or and ..." reading quite
oddly, but didn't think of a good way of making them stand
out. Capitalizing is probably a good fix.

>> +logical and, respectively, of the two expressions.
>> +
>
> I would have the second sentence on a newline (with a blank link
> between the first and second sentence so that they make separate
> paragraphs in rST).

Ack.

>
>> +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.
>> +
>
> This could be a list, e.g.:
>
> arguments:
>
> - the interface (e.g. `mmc`)
> - the device number (possibly including a partition specification)
> - the typical path to the file
>

Ack.

>> +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`.
>
> Question: Should we provide an example use case for each test subcommand?

I don't think so. I'd assume any U-Boot developer to be reasonably
familiar with the ordinary shell test, so I think it's better to just
emphasize the differences and gotchas than providing "shell 101"
material.

I'll fold in your suggestions, then resend the whole regex series with
this one properly included as patch 12.

Thanks,
Rasmus