.. index:: single: json_pointer_protocol
.. _json_pointer_protocol/0:

.. rst-class:: right

**protocol**

``json_pointer_protocol``
=========================

JSON Pointer (RFC 6901) and Relative JSON Pointer parser, generator, and evaluator protocol.

| **Availability:** 
|    ``logtalk_load(json_pointer(loader))``

| **Author:** Paulo Moura
| **Version:** 1:1:0
| **Date:** 2026-07-04

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: parse/2
.. _json_pointer_protocol/0::parse/2:

``parse/2``
^^^^^^^^^^^

Parses a JSON Pointer from the given source (``codes(Codes)``, ``chars(Chars)``, or ``atom(Atom)``) into a list of reference tokens. Fails if the pointer cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse(Source,Pointer)``
| **Mode and number of proofs:**
|    ``parse(++compound,--list(ground))`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid source:
|        ``domain_error(json_pointer_source,Source)``


------------

.. index:: generate/2
.. _json_pointer_protocol/0::generate/2:

``generate/2``
^^^^^^^^^^^^^^

Generates a JSON Pointer using the representation specified in the first argument (``codes(Codes)``, ``chars(Chars)``, or ``atom(Atom)``) for the list of reference tokens in the second argument.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate(Sink,Pointer)``
| **Mode and number of proofs:**
|    ``generate(+compound,++list(ground))`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Pointer`` is neither a variable nor a list:
|        ``type_error(list,Pointer)``
|    ``Pointer`` contains an invalid reference token:
|        ``domain_error(json_pointer_token,Token)``
|    ``Sink`` cannot be generated:
|        ``domain_error(json_pointer_sink,Sink)``


------------

.. index:: parse_fragment/2
.. _json_pointer_protocol/0::parse_fragment/2:

``parse_fragment/2``
^^^^^^^^^^^^^^^^^^^^

Parses a URI fragment representation of a JSON Pointer from the given source (``codes(Codes)``, ``chars(Chars)``, or ``atom(Atom)``) into a list of reference tokens. Fails if the fragment cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_fragment(Source,Pointer)``
| **Mode and number of proofs:**
|    ``parse_fragment(++compound,--list(ground))`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid source:
|        ``domain_error(json_pointer_fragment_source,Source)``


------------

.. index:: generate_fragment/2
.. _json_pointer_protocol/0::generate_fragment/2:

``generate_fragment/2``
^^^^^^^^^^^^^^^^^^^^^^^

Generates the URI fragment representation of a JSON Pointer using the representation specified in the first argument (``codes(Codes)``, ``chars(Chars)``, or ``atom(Atom)``) for the list of reference tokens in the second argument.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_fragment(Sink,Pointer)``
| **Mode and number of proofs:**
|    ``generate_fragment(+compound,++list(ground))`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Pointer`` is neither a variable nor a list:
|        ``type_error(list,Pointer)``
|    ``Pointer`` contains an invalid reference token:
|        ``domain_error(json_pointer_token,Token)``
|    ``Sink`` cannot be generated:
|        ``domain_error(json_pointer_fragment_sink,Sink)``


------------

.. index:: parse_relative/2
.. _json_pointer_protocol/0::parse_relative/2:

``parse_relative/2``
^^^^^^^^^^^^^^^^^^^^

Parses a Relative JSON Pointer from the given source (``codes(Codes)``, ``chars(Chars)``, or ``atom(Atom)``) into a canonical term ``relative(Up, Shift, Suffix)`` where ``Up`` is the number of ancestor steps, ``Shift`` is the optional array index adjustment, and ``Suffix`` is either a list of reference tokens or the atom ``'#'``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse_relative(Source,RelativePointer)``
| **Mode and number of proofs:**
|    ``parse_relative(++compound,--compound)`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid source:
|        ``domain_error(json_relative_pointer_source,Source)``


------------

.. index:: generate_relative/2
.. _json_pointer_protocol/0::generate_relative/2:

``generate_relative/2``
^^^^^^^^^^^^^^^^^^^^^^^

Generates a Relative JSON Pointer using the representation specified in the first argument (``codes(Codes)``, ``chars(Chars)``, or ``atom(Atom)``) from a canonical term ``relative(Up, Shift, Suffix)`` where ``Suffix`` is either a list of reference tokens or the atom ``'#'``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate_relative(Sink,RelativePointer)``
| **Mode and number of proofs:**
|    ``generate_relative(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``RelativePointer`` is not a valid Relative JSON Pointer term:
|        ``domain_error(json_relative_pointer,RelativePointer)``
|    ``RelativePointer`` contains an invalid reference token:
|        ``domain_error(json_pointer_token,Token)``
|    ``Sink`` cannot be generated:
|        ``domain_error(json_relative_pointer_sink,Sink)``


------------

.. index:: evaluate/3
.. _json_pointer_protocol/0::evaluate/3:

``evaluate/3``
^^^^^^^^^^^^^^

Evaluates a parsed JSON Pointer against a JSON term. Fails if the pointer does not identify a value in the given JSON term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``evaluate(Pointer,JSON,Value)``
| **Mode and number of proofs:**
|    ``evaluate(++list(ground),++term,?term)`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``Pointer`` is a variable:
|        ``instantiation_error``
|    ``JSON`` is a variable:
|        ``instantiation_error``
|    ``Pointer`` is neither a variable nor a list:
|        ``type_error(list,Pointer)``
|    ``Pointer`` contains an invalid reference token:
|        ``domain_error(json_pointer_token,Token)``


------------

.. index:: evaluate_relative/4
.. _json_pointer_protocol/0::evaluate_relative/4:

``evaluate_relative/4``
^^^^^^^^^^^^^^^^^^^^^^^

Evaluates a parsed Relative JSON Pointer term against a JSON term, using the second argument as the absolute JSON Pointer to the current context value. Fails if either the context or the relative pointer does not identify a value in the given JSON term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``evaluate_relative(RelativePointer,Context,JSON,Value)``
| **Mode and number of proofs:**
|    ``evaluate_relative(++compound,++list(ground),++term,?term)`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``RelativePointer`` is a variable:
|        ``instantiation_error``
|    ``Context`` is a variable:
|        ``instantiation_error``
|    ``JSON`` is a variable:
|        ``instantiation_error``
|    ``RelativePointer`` is not a valid Relative JSON Pointer term:
|        ``domain_error(json_relative_pointer,RelativePointer)``
|    ``Context`` is neither a variable nor a list:
|        ``type_error(list,Context)``
|    ``Context`` or ``RelativePointer`` contains an invalid reference token:
|        ``domain_error(json_pointer_token,Token)``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

