Hi Roland,
On Fri, 23 Jul 2021 at 06:30, Roland Gaudig roland.gaudig-oss@weidmueller.com wrote:
From: Roland Gaudig roland.gaudig@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@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@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@weidmueller.com S: Maintained F: cmd/printf.c +F: doc/usage/setexpr.rst
SH M: Marek Vasut marek.vasut+renesas@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 evaluatedexpression 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 likeformat string <format> evaluation of <value>.+setexpr name gsub <r> <s> [<t>]
For each substring matching the regular expression <r> in thestring <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