@spec compile_pointers([binary()], keyword()) :: pointers()

Pre-compiles a list of JSON Pointer paths into a reusable handle.

Workloads that parse many documents and extract the same fixed set of fields re-split and unescape those pointer strings on every call — wasted work, since they never change. compile_pointers/2 does it once and returns an opaque pointers/0 handle that parse_get_many_nil/2 and get_many_nil/2 accept in place of a path list, eliminating all per-call path parsing (≈2× faster extraction on a typical field set).

Compile once at startup (e.g. into :persistent_term, application state or the process holding the documents) and reuse the handle for every document. A pointers/0 is a NIF resource reference, so it cannot be built at compile time into a module attribute.

Raises ArgumentError if any path is not a valid UTF-8 binary or JSON Pointer. A JSON Pointer is either empty or begins with /.

Options

• :unique_keys — when true, object key lookups use a forward scan that stops at the first match (faster). Defaults to false (reverse scan, last-value-wins for duplicate keys), matching parse/2. Safe to enable when keys are known to be unique.

• :validate — controls validation of regions not selected by any path. The default, true, reports malformed input anywhere in the document. When false, unselected regions are skipped without syntax validation; selected values and every byte the walk consumes are still validated, UTF-8 included. The check for content after the document is skipped too, so ~s({"a":1} junk) succeeds where decode/1 and the default reject it, and trailing bytes are not UTF-8 checked either, being bytes the walk never reached. Truncated input is still rejected, because skipping has to find the closing delimiter. Use it only with trusted input.

  Measure before enabling it. Skipping a region structurally is a bracket scan over 64-byte blocks, which beats tokenizing a large subtree and loses to it on the few-byte scalars left over when the paths select most of the document. Reading 3 paths out of a 2 KB request is ~3.6× faster unvalidated; reading 146 of its fields is ~1.2× slower.

Any other option raises ArgumentError.

Extraction results are returned in the same order as paths.

Examples

iex> ptrs = Torque.compile_pointers(["/a", "/b/0"], unique_keys: true)
iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":[2,3]}))
iex> Torque.get_many_nil(doc, ptrs)
[1, 2]

@spec get(reference(), binary()) ::
  {:ok, term()} | {:error, :no_such_field | :nesting_too_deep}

Extracts a value from a parsed document using a JSON Pointer path (RFC 6901).

Paths must start with "/". Array elements are addressed by index (e.g. "/imp/0/banner/w"). An empty path "" returns the root value.

One deviation from RFC 6901: "/" also returns the root value, where the RFC reads it as the member whose key is the empty string. Every pointer entry point in Torque agrees on that, and changing it would silently move existing callers' lookups, so it stands until a breaking release.

Examples

iex> {:ok, doc} = Torque.parse(~s({"site":{"domain":"example.com"}}))
iex> Torque.get(doc, "/site/domain")
{:ok, "example.com"}

iex> {:ok, doc} = Torque.parse(~s({"site":{"domain":"example.com"}}))
iex> Torque.get(doc, "/missing")
{:error, :no_such_field}

@spec get(reference(), binary(), term()) :: term()

Extracts a value from a parsed document, returning default when the path does not exist.

Raises ArgumentError for errors other than :no_such_field (e.g. :nesting_too_deep).

Examples

iex> {:ok, doc} = Torque.parse(~s({"a":1}))
iex> Torque.get(doc, "/a", nil)
1

iex> {:ok, doc} = Torque.parse(~s({"a":1}))
iex> Torque.get(doc, "/b", :default)
:default

@spec get_many(reference(), [binary()]) :: [
  ok: term(),
  error: :no_such_field | :nesting_too_deep
]

Extracts multiple values from a parsed document in a single NIF call.

Returns a list of results in the same order as paths, each being {:ok, value} or {:error, :no_such_field}.

More efficient than calling get/2 in a loop because it crosses the NIF boundary only once. For a request-shaped document you query once and then discard, compile_pointers/2 + parse_get_many_nil/2 is usually faster still, since it never builds the document at all, though that advantage narrows to nothing as the document grows.

Raises ArgumentError if any path is not a valid UTF-8 binary.

Examples

iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":2}))
iex> Torque.get_many(doc, ["/a", "/b", "/c"])
[{:ok, 1}, {:ok, 2}, {:error, :no_such_field}]

@spec get_many_defaults(reference(), %{required(binary()) => term()}) :: %{
  required(binary()) => term()
}

Extracts multiple values from a parsed document with per-path defaults.

Takes a map of %{path => default} and returns a map of the same shape where each value is either the parsed value or the supplied default (if the path is missing).

More ergonomic than the two-call get_many_nil/2 + Enum.map pattern when consumers need defaults at the call site.

Equivalent to:

get_many_nil(doc, Map.keys(defaults))
|> then(&Enum.zip(Map.keys(defaults), &1))
|> Map.new(fn {p, nil} -> {p, Map.get(defaults, p)}; pv -> pv end)

Note: a parsed JSON null at the path is indistinguishable from a missing field (same as get_many_nil/2) — both substitute the default.

Examples

iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":null}))
iex> Torque.get_many_defaults(doc, %{"/a" => 0, "/b" => 0, "/c" => "missing"})
%{"/a" => 1, "/b" => 0, "/c" => "missing"}

@spec get_many_nil(reference(), [binary()] | pointers()) :: [term()]

Extracts multiple values from a parsed document, returning nil for missing fields.

Like get_many/2 but returns bare values instead of {:ok, value} tuples. Missing fields return nil (indistinguishable from JSON null).

Faster than get_many/2 when you don't need to distinguish between missing fields and null values, as it avoids allocating wrapper tuples.

Accepts either a list of JSON Pointer path strings or a pointers/0 handle built by compile_pointers/2. The compiled form skips all per-call path parsing and is the recommended option for a fixed, repeatedly-queried path set.

Raises ArgumentError if any path is not a valid UTF-8 binary.

Examples

iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":null}))
iex> Torque.get_many_nil(doc, ["/a", "/b", "/c"])
[1, nil, nil]

iex> {:ok, doc} = Torque.parse(~s({"a":1,"b":null}))
iex> ptrs = Torque.compile_pointers(["/a", "/b", "/c"])
iex> Torque.get_many_nil(doc, ptrs)
[1, nil, nil]

@spec length(reference(), binary()) :: non_neg_integer() | nil

Returns the length of an array at the given JSON Pointer path, or nil if the path does not exist or does not point to an array.

Examples

iex> {:ok, doc} = Torque.parse(~s({"a":[1,2,3]}))
iex> Torque.length(doc, "/a")
3

iex> {:ok, doc} = Torque.parse(~s({"a":[1,2,3]}))
iex> Torque.length(doc, "/missing")
nil

@spec parse(binary(), keyword()) ::
  {:ok, reference()} | {:error, binary() | :nesting_too_deep}

Parses a JSON binary into an opaque document reference.

The returned reference can be passed to get/2, get/3, get_many/2, get_many_nil/2, or length/2 for efficient repeated field extraction without re-parsing.

Options

• :unique_keys — when true, assumes object keys are unique and uses a faster lookup path. Defaults to false (last-value-wins for duplicate keys).

Any other option raises ArgumentError.

Automatically uses a dirty CPU scheduler for inputs larger than 20 KB.

Examples

iex> {:ok, doc} = Torque.parse(~s({"a":1}))
iex> is_reference(doc)
true

iex> {:ok, doc} = Torque.parse(~s({"a":1}), unique_keys: true)
iex> Torque.get(doc, "/a")
{:ok, 1}

@spec parse_get_many_nil(binary(), pointers()) ::
  {:ok, [term()]} | {:error, binary() | :nesting_too_deep}

Parses a JSON binary and extracts pre-compiled pointers in a single NIF call.

Fuses parse/2 and get_many_nil/2 for the common parse-once-extract-once case: it walks the document once, building a value only where a compiled pointer ends and skipping the rest, without materializing a document, a reusable handle, or a second NIF boundary crossing. Missing fields and JSON null both become nil. Both the lookup strategy (:unique_keys) and the validation policy (:validate) come from the pointers/0 handle.

Returns {:ok, values} (in the same order as the paths given to compile_pointers/2) or {:error, reason} if the JSON is malformed. A handle compiled with validate: false reports faults only in the regions it reads, so some malformed documents return {:ok, values} instead — see compile_pointers/2. Automatically uses a dirty CPU scheduler for inputs larger than 20 KB.

Examples

iex> ptrs = Torque.compile_pointers(["/id", "/site/domain", "/missing"])
iex> Torque.parse_get_many_nil(~s({"id":"x","site":{"domain":"e.com"}}), ptrs)
{:ok, ["x", "e.com", nil]}

iex> ptrs = Torque.compile_pointers(["/a"])
iex> match?({:error, _}, Torque.parse_get_many_nil("not json", ptrs))
true