@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}

Examples

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

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

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

iex> JSONPath.evaluate(
...>  %{"foo" => [%{"a" => 1}, %{"a" => 2}]},
...>  "$.foo[?@.a < 2]",
...>  :values_and_paths
...>)
{:ok, [{%{"a" => 1}, "$['foo'][0]"}]}

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

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

Same as evaluate/2 but raises in case of error