View Source JsonPointer (json_ptr v0.6.0)

Implementation of JSONPointer.

This module handles JSONPointers as an internal term representation and provides functions to manipulate the JSONPointer term and to use the representation to traverse or manipulate JSON data.

See: https://www.rfc-editor.org/rfc/rfc6901 for the specification.

Warning

Do not rely on the private internal implementation of JSONPointer, it may change in the future.

Link to this section Summary

Functions

rolls back the JsonPointer to the parent of its most distant leaf.

like backtrack/1, but raises if attempted to backtrack from the root.

converts a path to a JsonPointer

converts a URI (or a URI-string) to a JsonPointer.

appends path to the JsonPointer. This may either be a t:String.t, a list of t:String.t.

returns the last part of the pointer and the pointer without it.

given some JSON data, resolves a the content pointed to by the JsonPointer.

given some JSON data, resolves a the content pointed to by the JsonPointer

creates a JsonPointer to its path equivalent.

creates a URI.t/0 struct out of a JsonPointer.

updates nested JSON data at the location given by the JsonPointer.

Link to this section Types

@type json() ::
  nil
  | boolean()
  | String.t()
  | number()
  | [json()]
  | %{optional(String.t()) => json()}
@opaque t()

Link to this section Functions

@spec backtrack(t()) :: {:ok, t()} | :error

rolls back the JsonPointer to the parent of its most distant leaf.

iex> {:ok, ptr} = "/foo/bar" |> JsonPointer.from_path |> JsonPointer.backtrack
iex> JsonPointer.to_path(ptr)
"/foo"
@spec backtrack!(t()) :: t()

like backtrack/1, but raises if attempted to backtrack from the root.

@spec from_path(Path.t()) :: t()

converts a path to a JsonPointer

iex> JsonPointer.from_path("/") # the root-only case
[]
iex> JsonPointer.from_path("/foo/bar")
["foo", "bar"]
iex> JsonPointer.from_path("/foo~0bar/baz")
["foo~bar", "baz"]
iex> JsonPointer.from_path("/currency/%E2%82%AC")
["currency", "€"]
@spec from_uri(URI.t() | String.t()) :: t()

converts a URI (or a URI-string) to a JsonPointer.

iex> JsonPointer.from_uri("#/foo/bar")
["foo", "bar"]
iex> JsonPointer.from_uri("/foo/bar")
["foo", "bar"]
iex> JsonPointer.from_uri(%URI{path: "/foo/bar"})
["foo", "bar"]
iex> JsonPointer.from_uri(%URI{fragment: "/foo/bar", host: "elixir-lang.org"})
["foo", "bar"]
Link to this function

join(pointer, next_path)

View Source
@spec join(t(), String.t() | [String.t()]) :: t()

appends path to the JsonPointer. This may either be a t:String.t, a list of t:String.t.

iex> ptr = JsonPointer.from_path("/foo/bar")
iex> ptr |> JsonPointer.join("baz") |> JsonPointer.to_path
"/foo/bar/baz"
iex> ptr |> JsonPointer.join(["baz", "quux"]) |> JsonPointer.to_path
"/foo/bar/baz/quux"
@spec pop(t()) :: {t(), String.t()} | :error

returns the last part of the pointer and the pointer without it.

iex> {rest, last} = "/foo/bar" |> JsonPointer.from_path |> JsonPointer.pop
iex> last
"bar"
iex> JsonPointer.to_path(rest)
"/foo"
iex> "/" |> JsonPointer.from_path |> JsonPointer.pop
:error
Link to this function

resolve_json(data, pointer)

View Source
@spec resolve_json(data :: json(), t() | String.t()) ::
  {:ok, json()} | {:error, String.t()}

given some JSON data, resolves a the content pointed to by the JsonPointer.

iex> JsonPointer.resolve_json(true, "/")
{:ok, true}
iex> JsonPointer.resolve_json(%{"foo~bar" => "baz"}, "/foo~0bar")
{:ok, "baz"}
iex> JsonPointer.resolve_json(%{"€" => ["quux", "ren"]}, JsonPointer.from_path("/%E2%82%AC/1"))
{:ok, "ren"}
Link to this function

resolve_json!(data, pointer)

View Source
@spec resolve_json!(data :: json(), t() | String.t()) :: json()

given some JSON data, resolves a the content pointed to by the JsonPointer

iex> JsonPointer.resolve_json!(true, "/")
true
iex> JsonPointer.resolve_json!(%{"foo~bar" => "baz"}, "/foo~0bar")
"baz"
iex> JsonPointer.resolve_json!(%{"€" => ["quux", "ren"]}, JsonPointer.from_path("/%E2%82%AC/1"))
"ren"
@spec to_path(t()) :: Path.t()

creates a JsonPointer to its path equivalent.

iex> JsonPointer.to_path(["foo", "bar"])
"/foo/bar"
iex> JsonPointer.to_path(["foo~bar", "baz"])
"/foo~0bar/baz"
iex> JsonPointer.to_path(["currency","€"])
"/currency/%E2%82%AC"
@spec to_uri(t()) :: URI.t()

creates a URI.t/0 struct out of a JsonPointer.

The JsonPointer is placed in the :fragment field of the URI.

iex> JsonPointer.to_uri(["foo", "bar"])
%URI{fragment: "/foo/bar"}
Link to this function

update_json!(object, list, transformation)

View Source
@spec update_json!(data :: json(), t(), (json() -> json())) :: json()

updates nested JSON data at the location given by the JsonPointer.

iex> ptr = JsonPointer.from_path("/foo/0")
iex> JsonPointer.update_json!(%{"foo" => [1, 2]}, ptr, &(&1 + 1))
%{"foo" => [2, 2]}
iex> JsonPointer.update_json!(%{"foo" => %{"0" => 1}}, ptr, &(&1 + 1))
%{"foo" => %{"0" => 2}}