From 236d39bd10bd94545c5b0283ebc0999ddfd82344 Mon Sep 17 00:00:00 2001
From: Roland Gaudig <roland.gaudig@weidmueller.com>
Date: Fri, 23 Jul 2021 12:29:22 +0000
Subject: [PATCH] doc: usage: add description for setexpr command

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>
Reviewed-by: Simon Glass <sjg@chromium.org>
---
 MAINTAINERS           |   1 +
 doc/usage/index.rst   |   1 +
 doc/usage/setexpr.rst | 148 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 150 insertions(+)
 create mode 100644 doc/usage/setexpr.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 2a6d01cc31..776ff703b9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1054,6 +1054,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 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.
+    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)
+
+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).