Merge "Patch # 1: Data operation response event (NCMP → Client App) to comply with...

[cps.git] / docs / cps-path.rst

diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index f321adf..bb482c2 100644 (file)
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -1,6 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 .. Copyright (C) 2021-2022 Nordix Foundation
+.. Modifications Copyright (C) 2023 TechMahindra Ltd
 
 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
 .. _path:
@@ -182,7 +183,7 @@ General Notes
 Query Syntax
 ============
 
-``( <absolute-path> | <descendant-path> ) [ <leaf-conditions> ] [ <text()-condition> ] [ <ancestor-axis> ]``
+``( <absolute-path> | <descendant-path> ) [ <leaf-conditions> ] [ <text()-condition> ] [ <contains()-condition> ] [ <ancestor-axis> ]``
 
 Each CPS path expression need to start with an 'absolute' or 'descendant' xpath.
 
@@ -222,7 +223,7 @@ descendant-path
 leaf-conditions
 ---------------
 
-**Syntax**: ``<xpath> '[' @<leaf-name1> '=' <leaf-value1> ( ' and ' @<leaf-name> '=' <leaf-value> )* ']'``
+**Syntax**: ``<xpath> '[' @<leaf-name1> '(=|>|<|>=|<=)' <leaf-value1> ( ' <and|or> ' @<leaf-name> '(=|>|<|>=|<=)' <leaf-value> )* ']'``
   - ``xpath``: Absolute or descendant or xpath to the (list) node which elements will be queried.
   - ``leaf-name``: The name of the leaf which value needs to be compared.
   - ``leaf-value``: The required value of the leaf.
@@ -232,12 +233,18 @@ leaf-conditions
   - ``//categories[@name="Kids"]``
   - ``//categories[@name='Kids']``
   - ``//categories[@code='1']/books/book[@title='Dune' and @price=5]``
+  - ``//categories[@code='1']/books/book[@title='xyz' or @price=15]``
+  - ``//categories[@code='1']/books/book[@title='xyz' or @price>20]``
+  - ``//categories[@code='1']/books/book[@title='Dune' and @price<=5]``
   - ``//categories[@code=1]``
 **Limitations**
   - Only the last list or container can be queried leaf values. Any ancestor list will have to be referenced by its key name-value pair(s).
-  - Multiple attributes can only be combined using ``and``. ``or`` and bracketing is not supported.
+  - When mixing ``and/or`` operators, ``and`` has precedence over ``or`` . So ``and`` operators get evaluated first.
+  - Bracketing is not supported.
+  - Leaf names are not validated so ``or`` operations with invalid leaf names will silently be ignored.
   - Only leaves can be used, leaf-list are not supported.
   - Only string and integer values are supported, boolean and float values are not supported.
+  - Using comparative operators with string values will lead to an error at runtime. This error can't be validated earlier as the datatype is unknown until the execution phase.
   - The key should be supplied with correct data type for it to be queried from DB. In the last example above the attribute code is of type
     Integer so the cps query will not work if the value is passed as string.
     eg: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string.
@@ -268,6 +275,25 @@ The text()-condition  can be added to any CPS path query.
   - When querying a leaf value (instead of leaf-list) it is better, more performant to use a text value condition use @<leaf-name> as described above.
   - Having '[' token in any index in any list will have a negative impact on this function.
 
+contains()-condition
+--------------------
+
+**Syntax**: ``<cps-path> '[' 'contains' '(' '<leaf-name>','<string-value>' ')' ']'?``
+  - ``cps-path``: Any CPS path query.
+  - ``leaf-name``: The name of the leaf which value needs to be compared.
+  - ``string-value``: The required value of the leaf element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This will still match integer values.
+
+**Examples**
+  - ``//categories[contains(@name,'Sci')]``
+  - ``//books[contains(@title,'Space')]``
+
+**Limitations**
+  - Only leaves can be used, leaf-list are not supported.
+  - Leaf names are not validated so ``contains() condition`` with invalid leaf names will silently be ignored.
+
+**Notes**
+  - contains condition is case sensitive.
+
 ancestor-axis
 -------------