[PATCH v3 5/6] doc: usage: add description for setexpr command

[Simon Glass]

Hi Roland,

On Fri, 23 Jul 2021 at 06:30, Roland Gaudig
<roland.gaudig-oss at weidmueller.com> wrote:
>
> From: Roland Gaudig <roland.gaudig at weidmueller.com>
>
> Add usage for the setexpr command. It has been added to describe
> mainly the new setexpr format string operation.
>
> Signed-off-by: Roland Gaudig <roland.gaudig at weidmueller.com>
> ---
>
> (no changes since v1)
>
>  MAINTAINERS           |   1 +
>  doc/usage/index.rst   |   1 +
>  doc/usage/setexpr.rst | 148 ++++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 150 insertions(+)
>  create mode 100644 doc/usage/setexpr.rst

Reviewed-by: Simon Glass <sjg at chromium.org>

optional nits below

>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index fe53698878..57c3349ef5 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1053,6 +1053,7 @@ SETEXPR
>  M:     Roland Gaudig <roland.gaudig at weidmueller.com>
>  S:     Maintained
>  F:     cmd/printf.c
> +F:     doc/usage/setexpr.rst
>
>  SH
>  M:     Marek Vasut <marek.vasut+renesas at gmail.com>
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index 40b796a3a9..719b2c90b9 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -43,6 +43,7 @@ Shell commands
>     reset
>     sbi
>     scp03
> +   setexpr
>     size
>     true
>     ums
> diff --git a/doc/usage/setexpr.rst b/doc/usage/setexpr.rst
> new file mode 100644
> index 0000000000..2e511b1290
> --- /dev/null
> +++ b/doc/usage/setexpr.rst
> @@ -0,0 +1,148 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +setexpr command
> +===============
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    setexpr[.b, .w, .l .s] <name> [*]<value> <op> [*]<value2>
> +    setexpr[.b, .w, .l] <name> [*]<value>
> +    setexpr <name> fmt <format> [value]...
> +    setexpr <name> gsub r s [t]
> +    setexpr <name> sub r s [t]
> +
> +Description
> +-----------
> +
> +The setexpr command is used to set an environment variable to the result
> +of an evaluation.
> +
> +setexpr[.b, .w, .l .s] <name> [*]<value> <op> [*]<value2>
> +     Set environment variable <name> to the result of the evaluated
> +     expression specified by <op>.
> +
> +setexpr[.b, .w, .l] name [*]value
> +     Load <value> into environment variable <name>
> +
> +setexpr name fmt <format> value
> +     Set environment variable <name> to the result of the C like
> +     format string <format> evaluation of <value>.
> +
> +setexpr name gsub <r> <s> [<t>]
> +     For each substring matching the regular expression <r> in the
> +     string <t>, substitute the string <s>.
> +     The result is assigned to <name>.
> +     If <t> is not supplied, use the old value of <name>.
> +
> +setexpr name sub <r> <s> [<t>]
> +     Just like gsub(), but replace only the first matching substring
> +
> +The setexpr command takes the following arguments:
> +
> +format
> +    This parameter contains a C or Bash like format string.

C- or Bash-like ?

or: C or Bash-like ?

Definitely needs at least one hyphen.

> +    The number of arguments is limited to 4.
> +    The following format types are supported:
> +
> +    c
> +        single character
> +    d, i
> +        decimal value
> +    o
> +        octal value
> +    s
> +        string
> +    u
> +        unsigned decimal value
> +    x, X
> +        hexadecimal value
> +    '%'
> +        no conversion, instead a % character will be written
> +
> +    Backslash escapes:
> +
> +    \" = double quote
> +    \\ = backslash
> +    \a = alert (bell)
> +    \b = backspace
> +    \c = produce no further output
> +    \f = form feed
> +    \n = new line
> +    \r = carriage return
> +    \t = horizontal tab
> +    \v = vertical tab
> +    \NNN = octal number (NNN is 0 to 3 digits)

For me this list comes out wrong...may need an extra \ ?

> +
> +name
> +    The name of the environment variable to be set
> +
> +op
> +    '|'
> +        name = value | value2
> +    '&'
> +        name = value & value2
> +    '+'
> +        name = value + value2
> +        (This is the only operator supported for strings.
> +       It acts as concatenation operator on strings)
> +    '^'
> +        name = value ^ value2
> +    '-'
> +        name = value - value2
> +    '*'
> +        name = value * value2
> +    '/'
> +        name = value / value2
> +    '%'
> +        name = value % value2

Those ops might look better as a table.

> +
> +r
> +    Regular expression
> +
> +s
> +    Substitution string
> +
> +t
> +    string
> +
> +value
> +    Can either be an integer value, a string.
> +    If the pointer prefix '*' is given value is treated as memory address.
> +
> +value2
> +    See value
> +
> +Example
> +-------
> +
> +::
> +
> +    => setexpr foo fmt %d 0x100
> +    => echo $foo
> +    256
> +    =>
> +
> +    => setexpr foo fmt 0x%08x 63
> +    => echo $foo
> +    0x00000063
> +    =>
> +
> +    => setexpr foo fmt %%%o 8
> +    => echo $foo
> +    %10
> +    =>
> +
> +Configuration
> +-------------
> +
> +The setexpr gsub and sub operations are only available if CONFIG_REGEX=y.

Should we use `CONFIG_REGEX=y` ?


> +
> +Return value
> +------------
> +
> +The return value $? is set to 0 (true) if the operation was successful.
> +
> +If an error occurs, the return value $? is set to 1 (false).
> --
> 2.25.1
>