-spec compile_path(binary() | iolist()) -> path().

Compile a jq-style path expression into a path() for use with find/2.

Supports a small subset of jq syntax:

• . - identity (returns the input term itself)
• .foo, .foo.bar - field access (map key)
• .["foo bar"] - bracketed field access, for keys with special characters
• .[] - iterate: every element of a list, or every value of a map
• .[N], .[-N] - index into a list (negative indices count from the end)

Segments can be chained freely, e.g. .a.b[].c[0].

Raises {invalid_path, Filter} if Filter doesn't match this grammar.

Example

1> glazer:compile_path(<<".a[].b">>).
[{field,<<"a">>},iterate,{field,<<"b">>}]

-spec decode_integer(binary() | iolist()) -> integer().

Decode a JSON number string to an integer. Raises invalid_number_format on invalid input.

-spec encode_integer(integer()) -> binary().

Encode an integer to its JSON string representation. Raises badarg if Int is not an integer.

-spec find(term(), path() | binary()) -> [term()].

Find value(s) in Term by walking Path.

Term is typically a decoded JSON/YAML document: nested maps and lists. Path is either a path() produced by compile_path/1, or a raw jq-style filter string (compiled on the fly via compile_path/1 — raises {invalid_path, Filter} if it doesn't parse).

As a string, Path supports a small subset of jq syntax (see compile_path/1 for the full grammar), e.g. .a.b[].c[0].

Returns the list of values found at the end of Path. An empty list means no match. .[] steps fan out over every element of a list (or every value of a map), so a path containing .[] can produce multiple results.

Examples

1> Doc = #{<<"a">> => [#{<<"b">> => 1}, #{<<"b">> => 2}, #{<<"c">> => 3}]}.
2> glazer:find(Doc, <<".a[].b">>).
[1, 2]
3> glazer:find(Doc, <<".a[2].c">>).
[3]
4> glazer:find(Doc, <<".a[-1].c">>).
[3]
5> glazer:find(Doc, <<".">>).
[Doc]
6> glazer:find(#{<<"foo bar">> => 1}, <<".[\"foo bar\"]">>).
[1]

-spec format_error(io:format(), [term()]) -> binary().

Format an error message with io_lib:format/2 and flatten to a binary.

-spec info() ->
              #{app_version => binary(),
                version => binary(),
                pgo => boolean(),
                optimization => none | 'O1' | 'O3'}.

Return build information about the loaded NIF library:

• app_version: the vsn from glazer.app.src that this build was made

              from (e.g. `<<"0.5.9">>`)

• version: git describe of the checkout the NIF was built from

              (e.g. `<<"0.5.9-3-abc123">>`, with a trailing `*` if the
              working tree was dirty at build time)

• pgo: true if built with profile-guided optimisation

              (`make optimize` / `make PGO=use`)

• optimization: none, 'O1' (debug/ASan builds), or 'O3' (release)

Example

1> glazer:info().
#{app_version => <<"0.5.9">>, version => <<"0.5.9-3-abc123">>,
  pgo => true, optimization => 'O3'}

-spec try_decode_integer(binary() | iolist()) -> {ok, integer()} | {error, invalid_number_format}.

Decode a JSON number string to an integer, returning {ok, Int} or {error, invalid_number_format} instead of raising.