[PATCH 2/3] doc: usage: add description for setexpr command

[Roland Gaudig]

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

 MAINTAINERS           |   6 ++
 doc/usage/index.rst   |   1 +
 doc/usage/setexpr.rst | 130 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 137 insertions(+)
 create mode 100644 doc/usage/setexpr.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 11e11d51a7..15df95567f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1048,6 +1048,12 @@ F:	arch/sandbox/
 F:	doc/arch/sandbox.rst
 F:	include/dt-bindings/*/sandbox*.h
 
+SETEXPR
+M:	Simon Glass <sjg at chromium.org>
+S:	Maintained
+F:	cmd/setexpr.c
+F:	doc/usage/setexpr.rst
+
 SH
 M:	Marek Vasut <marek.vasut+renesas at gmail.com>
 M:	Nobuhiro Iwamatsu <iwamatsu at nigauri.org>
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 843b4371f1..6e94ab0313 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -42,6 +42,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..ed2fd284fa
--- /dev/null
+++ b/doc/usage/setexpr.rst
@@ -0,0 +1,130 @@
+.. 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 like format string. In contrast to the C
+    language some simplificatinons were made. Only one argument is supported.
+    Only the following format types are supported:
+
+    d, i
+        decimal value
+    o
+        octal value
+    x, X
+        hexadecimal value
+    u
+        unsigned decimal value
+    '%'
+        no conversion, instead a % character will be written
+
+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
+
+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.
+
+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