@spec build(String.t()) :: {:ok, JSONPath.AST.t()} | {:error, JSONPath.Error.t()}

Builds a JSON Path query JSONPath.AST.t/0. Returns {:ok, ast} or {:error, JSONPath.Error.t()}.

Prefer this function when running the same query multiple times, since building the query each time performs potentially expensive semantic checks.

@spec build!(String.t()) :: JSONPath.AST.t()

Same as build/1 but raises in case of error

@spec evaluate(json(), String.t() | JSONPath.AST.t(), returning()) ::
  {:ok, [json()]} | {:error, JSONPath.Error.t()}

Evaluates a JSON value against the given query string or parsed AST. Returns an {:ok, results} or {:error, JSONPath.Error.t()} tuple.

The results type is controlled by the returning argument:

• :values - List of node values. This is the default behavior
• :paths - List of normalized paths
• :values_and_paths - List of tuples {value, normalized_path}

@spec evaluate!(json(), String.t() | JSONPath.AST.t(), returning()) :: [json()]

Same as evaluate/2 but raises in case of error

@spec paths(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [String.t()]} | {:error, JSONPath.Error.t()}

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of normalized paths

Examples

iex> JSONPath.paths(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, ["$[2]"]}

iex> JSONPath.paths(%{"foo" => ["a", "b", "c", "d"]}, "$.foo[::-1]")
{:ok, ["$['foo'][3]", "$['foo'][2]", "$['foo'][1]", "$['foo'][0]"]}

@spec paths!(json(), String.t() | JSONPath.AST.t()) :: [String.t()]

Same as paths/2 but returns the list of normalized paths or raises an error

Examples

iex> JSONPath.paths!(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
["$[2]"]

@spec value_paths(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [{json(), String.t()}]} | {:error, JSONPath.Error.t()}

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing two-element tuples of {node_value, normalized_path}

Examples

iex> JSONPath.value_paths(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, [{"bab", "$[2]"}]}

@spec value_paths!(json(), String.t() | JSONPath.AST.t()) :: [{json(), String.t()}]

Same as value_paths/2 but returns the list of two-element tuple {node_value, normalized_path} or raises an error

Examples

iex> JSONPath.value_paths!(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
[{"bab", "$[2]"}]

@spec values(json(), String.t() | JSONPath.AST.t()) ::
  {:ok, [json()]} | {:error, JSONPath.Error.t()}

Evaluates a JSON value against the given query string or parsed AST. Returns a result tuple containing the list of matching node values.

Examples

iex> JSONPath.values(["aba", "bbab", "bab"], "$[?match(@, 'b.b')]")
{:ok, ["bab"]}

iex> JSONPath.values(%{"foo" => ["a", "b", "c", "d"]}, "$.foo[::-1]")
{:ok, ["d", "c", "b", "a"]}

iex> JSONPath.values(%{"foo" => [1,2,3,4]}, "$.foo[?@ > 2]")
{:ok, [3, 4]}

iex> JSONPath.values(%{"foo" => %{"bar" => "baz"}}, "$[?length(@)]")
{:error, %JSONPath.Error{
  type: :invalid_expression,
  expression: "length(@)",
  message: "comparison operator expected"
  }
}

@spec values!(json(), String.t() | JSONPath.AST.t()) :: [json()]

Same as values/2 but returns the list of nodes values or raises an error

Examples

iex> JSONPath.values!(%{"foo" => [1,2,3,4]}, "$.foo[?@ > 2]")
[3, 4]