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)

## Public predicates

### `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)`

### `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)`

### `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)`

### `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)`

### `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)`

### `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)`

### `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)`

### `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)