.. This file is part of Sympathy for Data.
.. Copyright (c) 2020 Combine Control Systems AB
..
.. Sympathy for Data is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, version 3 of the License.
..
.. Sympathy for Data is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with Sympathy for Data.  If not, see <http://www.gnu.org/licenses/>.

.. _appendix_json_queries:

Json query syntax
-----------------

Some nodes allow you to input a Json query, which is a string parameter for
selecting what parts of a Json structure to work on. For simple queries they
can usually be created by clicking on an entry in the tree view of the query
editor, but more advanced queries must be entered by hand. Such queries must
adhere to a specific syntax to give the correct results.

Let's start off with a few examples:

.. code-block::

   articles[0].author
   articles[:].comments[:]
   users.*.fullName

The query is built out of segments where each segment is either a key, an
index, a pattern, or a slice. The empty query (with no segments) matches the
root of the Json structure.

Simple keys
^^^^^^^^^^^
A key is a simple string used to select a single entry in a dictionary.
It is written: ``.key``, but for simple keys at the start of the query, the
period is omitted: ``key``.

The key ends when a period (``.``) or a left square bracket (``[``) is found.
Including an asterisk (``*``) in the key turns it into a
:ref:`pattern<json_query_pattern>`. To be able to include any of these
characters in a key you need to use a
:ref:`bracketed key<json_query_bracketed_key>`. The key can include Unicode
characters directly in the string.

.. _json_query_pattern:

Patterns
^^^^^^^^
Like a key but with one or more asterisks in it: ``.key*``. Selects the values
of all keys that match the pattern with asterisks interpreted as wildcards that
can match zero or more arbitrary characters. As an important special case, the
pattern ``.*`` selects all entries in the dictionary.

Indices
^^^^^^^
An index is used to select a single entry from a list.
It is written ``[5]``, starting at index zero for the first entry in the list.
The index can also be negative with ``[-1]`` denoting the last entry in the list,
``[-2]`` denoting the second-to-last entry, and so on.

This exactly mirrors how Python interprets indices in lists.

Slices
^^^^^^
A slice is used to select multiple entries in a list.
It can be written ``[3:8]`` for selecting entries with indices from 3 (inclusive)
to 8 (exclusive).
The slice can also contain a third part (separated by another colon) which is
interpreted as a step. As an example ``[3:8:2]`` would select indices 3, 5,
and 7. Only positive steps are supported.

If the start is omitted (``[:8]``) the slice starts from the first entry in the
list. If the end is omitted (``[3:]``) the slice includes all entries until the end of the list.
As an important special case, the full slice ``[:]`` selects all entries in the list.

This is a subset of the slice syntax in Python.

.. _json_query_bracketed_key:

Bracketed keys
^^^^^^^^^^^^^^
Bracketed keys: ``["key"]`` or ``['key']`` selects a single entry in a dictionary.

The key can include Unicode characters directly in the string.
The following escape sequences are also recognized:

===============  ===============================
Escape sequence  Meaning
===============  ===============================
``\\``           Backslash (\\)
``\'``           Single quote (')
``\"``           Double quote (")
``\n``           Line Feed (U+000A)
``\r``           Carriage Return (U+000D)
``\t``           Vertical Tab, (U+000B)
``\xhh``         Unicode character with
                 hexadecimal code point hh
``\uhhhh``       Unicode character with
                 hexadecimal code point hhhh
``\Uhhhhhhhh``   Unicode character with
                 hexadecimal code point hhhhhhhh
===============  ===============================

This is a subset of the escape sequences in Python strings:
https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals.