Merge "Missing licence info added in pom file"

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

diff --git a/docs/cps-path.rst b/docs/cps-path.rst
index 451c24f..aec87cd 100644 (file)
--- a/docs/cps-path.rst
+++ b/docs/cps-path.rst
@@ -51,13 +51,13 @@ General Notes
 - String values must be wrapped in quotation marks (U+0022) or apostrophes (U+0027).
 - String comparisons are case sensitive.
 
-Supported Functions
-===================
+Supported Queries
+=================
 
 Get List Elements by Any Attribute Value
 ----------------------------------------
 
-**Syntax**: ``<xpath>/<target-node>/[@<leaf-name>=<leaf-value>]``
+**Syntax**: ``<xpath>/<target-node>[@<leaf-name>=<leaf-value>]``
   - ``xpath``: The xpath to the parent of the target node including all ancestors.
   - ``target-node``: The name of the (list) node which elements will queried.
   - ``leaf-name``: The name of the leaf which value needs to be compared.
@@ -74,7 +74,7 @@ Get List Elements by Any Attribute Value
   - Only string and integer values are supported (boolean and float values are not supported).
 
 **Notes**
-  - For performance reasons it does not make sense to query the list key leaf. If the key value is known it is beter to execute a get request with the complete xpath.
+  - For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath.
 
 Get Any Descendant
 ------------------
@@ -91,3 +91,41 @@ Get Any Descendant
 
 **Limitations**
   - List elements can only be addressed using the list key leaf.
+
+Get Any Descendant by Any Attribute Value
+-----------------------------------------
+
+**Syntax**: ``//<direct-ancestors><target-node>[@<leaf-name>=<leaf-value>]``
+  - ``direct-ancestors``: Optional path to direct ancestors of the target node. This can contain zero to many ancestor nodes separated by a /.
+  - ``target-node``: The name of the (list) node which elements will queried.
+  - ``leaf1-name .. leafN-name:``: One or more leaves whose value needs to be compared.
+  - ``leaf1-value .. leafN-value:``: One or more required leaf values (multiple condition can be combined using the 'and' keyword).
+
+**Examples**
+  - ``//categories[@name='Kids']``
+  - ``//categories[@name='Kids' and @numberOfBooks=1]``
+
+**Limitations**
+  - Only string and integer values are supported (boolean and float values are not supported).
+  - Multiple attributes can only be combined using 'and'. 'or' and bracketing is not supported.
+
+Query Extensions
+================
+
+Ancestor Axis
+-------------
+
+The ancestor axis can be added to any CPS path query.
+
+**Syntax**: ``//<cps-path>/ancestor::<ancestor-path>``
+  - ``cps-path``: Any CPS path query.
+  - ``ancestor-path``:  Partial path to ancestors of the target node. This can contain one or more ancestor nodes separated by a /.
+
+**Examples**
+  - ``//book/ancestor::categories``
+  - ``//categories[@genre="SciFi"]/book/ancestor::bookstore``
+  - ``book/ancestor::categories[@code=1]/books``
+
+**Limitations**
+  - Ancestor list elements can only be addressed using the list key leaf.
+  - List elements with compound keys are not supported.
\ No newline at end of file