Add docs for variables resolving (#24)

Author: Viicos

README.rst

@@ -62,7 +62,10 @@ Usage
     # 2. Parse the JSON Logic expression:
     from jsonlogic import JSONLogicExpression
 
-    expr = JSONLogicExpression.from_json({">": [{"var": "my_int"}, 2]})
+    expr = JSONLogicExpression.from_json({"map": [
+        [1, 2],
+        {"*": [{"var": ""}, {"var": "/my_int@1"}]},
+    ]})
 
     # 3. Create an operator tree:
     root_op = expr.as_operator_tree(operator_registry)
@@ -80,14 +83,14 @@ Usage
         }
     )
     print(typ)
-    #> BooleanType()
+    #> ArrayType(IntegerType())
 
     # 5. Evaluate with data:
     from jsonlogic.evaluation import evaluate
     value = evaluate(
         root_op,
-        data={"my_int": 3},
+        data={"my_int": 2},
         data_schema=None,
     )
     print(value)
-    #> True
+    #> [2, 4]

docs/source/usage/index.rst

@@ -91,6 +91,7 @@ The next sections will go over typechecking and evaluating the expression.
 .. toctree::
     :maxdepth: 2
 
+    resolving_variables
     typechecking
     evaluation
     creating_operators

docs/source/usage/resolving_variables.rst

@@ -0,0 +1,117 @@
+Resolving variables
+===================
+
+In the original `JsonLogic`_ format, operators `accessing data <https://jsonlogic.com/operations.html#accessing-data>`_
+use a dot-like notation. With the following expression:
+
+.. code-block:: json
+
+    {"var": "some.var"}
+
+and the following data:
+
+.. code-block:: json
+
+    {
+        "some": {
+            "var": 1
+        }
+    }
+
+the expression will evaluate to :json:`1`. However, this dot-like notation can be ambiguous:
+
+- As the empty string :json:`""` is special cased to refer to the entire data object, it is impossible
+  to refer to :json:`1` with the following data:
+
+  .. code-block:: json
+
+      {
+          "": 1
+      }
+
+  as the reference :json:`""` would evaluate to :json:`{"": 1}`, and :json:`"."` could be parsed as a reference to :json:`{"": {"": 1}}`.
+
+- There is no way to escape dots if present in data keys. The reference :json:`"some.var"` could refer to both
+  :json:`1` and :json:`2` with the following data:
+
+  .. code-block:: json
+
+      {
+          "some": {
+              "var": 1
+          },
+          "some.var": 2
+      }
+
+For this reason, an alternative format is proposed, based on the JSON Pointer standard (:rfc:`6901`). The following expressions:
+
+with the following data:
+
+.. code-block:: json
+
+    {
+        "path": 1,
+        "": 2,
+        "": {"": 3},
+        "path.to": 4,
+        "path/": 5
+    }
+
+this is how the references will evaluate:
+
+.. code-block:: bash
+
+    {"var": "/path"} -> 1
+    {"var": ""} -> 2
+    {"var": "/"} -> whole object
+    {"var": "//"} -> 3
+    {"var": "/path.to"} -> 4
+    {"var": "/path~1"} -> 5
+
+Variables scopes
+----------------
+
+The original `JsonLogic`_ format implicitly uses the notion scope in the implementation
+of some operators such as `map <https://jsonlogic.com/operations.html#map-reduce-and-filter>`_:
+
+.. code-block:: json
+
+    {
+        "map": [
+            [1, 2],
+            {"*": [{"var": ""}, 2]}
+        ]
+    }
+
+In this case, the variable reference :json:`""` will refer to each element of the array :json:`[1, 2]`.
+This means that there is no way to access data from the top level object (say for example you wanted
+to multiply every element of the array with :json:`{"var": "some_const"}` instead of :json:`2`).
+
+The notion of *scope* is thus introduced, so that it is still possible to access data from the parent scope.
+This scope can be specified by appending ``@n`` at the end of the variable reference. The current scope starts at
+0, so using :json:`"some_var@0"` is equivalent to :json:`"some_var"`.
+
+Using our previous ``map`` example, with the following data:
+
+.. code-block:: json
+
+    {
+        "some_const": 2
+    }
+
+the operator can be written as:
+
+.. code-block:: json
+
+    {
+        "map": [
+            [1, 2],
+            {"*": [{"var": ""}, {"var": "some_const@1"}]}
+        ]
+    }
+
+and would evaluate to :json:`[2, 4]`.
+
+For more details on resolving variables, you can refer to the API documentation: :doc:`../api/evaluation`.
+
+.. _`JsonLogic`: https://jsonlogic.com/

tests/test_resolving.py

@@ -57,15 +57,22 @@ def test_reference_parser(pointer_reference: str, dot_reference: str, expected:
     assert (parsed_ref.segments, scope) == expected
 
 
-def test_pointer_reference_empty_string() -> None:
+@pytest.mark.parametrize(
+    ["pointer_reference", "expected"],
+    [
+        ("/", ([""], 0)),
+        ("//", (["", ""], 0)),
+    ],
+)
+def test_pointer_reference(pointer_reference: str, expected: tuple[list[str], int]) -> None:
     """Pointer references are unambiguous, thus we can parse `"/"` as being `[""]`.
 
     Note that this is not possible with dot references, so this is tested separately.
     (`""` is special cased to be the root document, and `"."` has to be parsed to `["", ""]`).
     """
 
-    parsed_ref, scope = pointer_ref_parser("/")
-    assert (parsed_ref.segments, scope) == ([""], 0)
+    parsed_ref, scope = pointer_ref_parser(pointer_reference)
+    assert (parsed_ref.segments, scope) == expected
 
 
 @pytest.mark.parametrize(