summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
Diffstat (limited to 'Help')
-rw-r--r--Help/command/string.rst103
-rw-r--r--Help/release/dev/string-json-support.rst5
2 files changed, 108 insertions, 0 deletions
diff --git a/Help/command/string.rst b/Help/command/string.rst
index cfcf914..0bc2b48 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -43,6 +43,19 @@ Synopsis
string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
string(`UUID`_ <out-var> ...)
+ `JSON`_
+ string(JSON <out-var> [ERROR_VARIABLE <error-var>]
+ {`GET`_ | `TYPE`_ | :ref:`LENGTH <JSONLENGTH>` | `REMOVE`_}
+ <json-string> <member|index> [<member|index> ...])
+ string(JSON <out-var> [ERROR_VARIABLE <error-var>]
+ `MEMBER`_ <json-string>
+ [<member|index> ...] <index>)
+ string(JSON <out-var> [ERROR_VARIABLE <error-var>]
+ `SET`_ <json-string>
+ <member|index> [<member|index> ...] <value>)
+ string(JSON <out-var> [ERROR_VARIABLE <error-var>]
+ `EQUAL`_ <json-string1> <json-string2>)
+
Search and Replace
^^^^^^^^^^^^^^^^^^
@@ -470,3 +483,93 @@ A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
where each ``x`` represents a lower case hexadecimal character.
Where required, an uppercase representation can be requested
with the optional ``UPPER`` flag.
+
+JSON
+^^^^
+
+.. _JSON:
+
+Functionality for querying a JSON string
+
+.. _GET:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
+ GET <json-string> <member|index> [<member|index> ...])
+
+Get an element from ``<json-string>`` at the location given
+by the list of ``<member|index>`` arguments.
+Array and object elements will be returned as a JSON string.
+Boolean elements will be returned as ``ON`` or ``OFF``.
+Null elements will be returned as an empty string.
+Number and string types will be returned as strings.
+
+.. _TYPE:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
+ TYPE <json-string> <member|index> [<member|index> ...])
+
+Get the type of an element in ``<json-string>`` at the location
+given by the list of ``<member|index>`` arguments. The ``<out-var>``
+will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
+``ARRAY``, or ``OBJECT``.
+
+.. _MEMBER:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-var>]
+ MEMBER <json-string>
+ [<member|index> ...] <index>)
+
+Get the name of the ``<index>``:th member in ``<json-string>`` at the location
+given by the list of ``<member|index>`` arguments.
+Requires an element of object type.
+
+.. _JSONLENGTH:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
+ LENGTH <json-string> <member|index> [<member|index> ...])
+
+Get the length of an element in ``<json-string>`` at the location
+given by the list of ``<member|index>`` arguments.
+Required an element of array or object type.
+
+.. _REMOVE:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
+ REMOVE <json-string> <member|index> [<member|index> ...])
+
+Remove an element from ``<json-string>`` at the location
+given by the list of ``<member|index>`` arguments. The JSON string
+without the removed element will we written in ``<out-var>``.
+
+.. _SET:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
+ SET <json-string> <member|index> [<member|index> ...] <value>)
+
+Set an element in ``<json-string>`` at the location
+given by the list of ``<member|index>`` arguments to ``<value>``.
+The contents of ``<value>`` should be valid JSON.
+
+.. _EQUAL:
+.. code-block:: cmake
+
+ string(JSON <out-var> [ERROR_VARIABLE <error-var>]
+ EQUAL <json-string1> <json-string2>)
+
+Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>``
+for equality
+
+
+If the optional ``ERROR_VARIABLE`` argument is given errors will be
+reported in ``<error-variable>``. If no error occurs the ``<error-variable>``
+will be set to ``NOTFOUND``. If ``ERROR_VARIABLE`` is not set a CMake error
+will be issued.
+When an error occurs the ``<out-var>`` will be set to
+``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements up to
+the point where the error occurred.
diff --git a/Help/release/dev/string-json-support.rst b/Help/release/dev/string-json-support.rst
new file mode 100644
index 0000000..bd75328
--- /dev/null
+++ b/Help/release/dev/string-json-support.rst
@@ -0,0 +1,5 @@
+string-json-support
+-------------------
+
+* The :command:`string` command gained set of new ``JSON`` sub commands to provide JSON
+ parsing capabilities.