Hi Roland, On Fri, 23 Jul 2021 at 06:30, Roland Gaudig <[email protected]> wrote: > > From: Roland Gaudig <[email protected]> > > Add usage for the setexpr command. It has been added to describe > mainly the new setexpr format string operation. > > Signed-off-by: Roland Gaudig <[email protected]> > --- > > (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 <[email protected]> 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 <[email protected]> > S: Maintained > F: cmd/printf.c > +F: doc/usage/setexpr.rst > > SH > M: Marek Vasut <[email protected]> > 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 >
