[PATCH] doc: document test command

[Quentin Schulz]

Hi Rasmus,

On 5/12/25 11:31 AM, Rasmus Villemoes wrote:
> 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?
> 

And re-reading myself, we probably want:

.. note::
    Numbers are parsed with ``simple_strtol(,0)`` ...

here :)

[...]

>>> +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.
> 

Fair, could be also `0x` if you prefer how this renders, I don't think 
U-Boot is too picky about those.

[...]

>>> +  # 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.
> 

This is terrible :/

We now need to figure out if a command modifies environment variables to 
contain hex values, returns hex values, or simply decimal values.

Nothing that is coming from your doing in this patch though :)

[...]

>>> +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.
> 

Fair enough!

Quentin