view release on metacpan or  search on metacpan

lib/JQ/Lite.pm  view on Meta::CPAN

=head1 CONSTRUCTOR

=head2 new

  my $jq = JQ::Lite->new;

Creates a new instance. Pass C<raw =E<gt> 1> to enable raw output and
C<vars =E<gt> \%hash> to predeclare jq-style variables (for example,
C<JQ::Lite-E<gt>new(vars =E<gt> { name =E<gt> 'Alice' })>).

=head1 METHODS

=head2 run_query

  my @results = $jq->run_query($json_text, $query);

Runs a jq-like query against the given JSON string.
Returns a list of matched results. Each result is a Perl scalar
(string, number, arrayref, hashref, etc.) depending on the query.

=head1 SUPPORTED SYNTAX

=head2 Navigation

=over 4

=item * C<.key.subkey> to traverse nested hashes.

=item * C<.array[0]> for positional access and C<.array[]> to flatten arrays.

=item * C<.key?> for optional key access that yields no output when the key is missing.

=back

=head2 Filtering and projection

=over 4

=item * C<select(.key > 1 and .key2 == "foo")> for boolean filtering.

=item * C<group_by(.field)>, C<group_count(.field)>, C<sum_by(.field)>, C<avg_by(.field)>, and C<median_by(.field)> for grouped reductions.

=item * C<reduce expr as $var (init; update)> for accumulators with lexical bindings.

=item * C<foreach expr as $var (init; update [; extract])> to stream intermediate results while folding values.

=item * C<unique_by(.key)> and C<sort_by(.key)> for deduplicating and ordering complex structures.

=item * C<.key | count> or C<.[] | select(...) | count> to count items after applying filters.

=item * C<.array | map(.field) | join(", ")> to transform and format array values.

=back

=head2 Conditionals

=over 4

=item * C<if CONDITION then FILTER [elif CONDITION then FILTER ...] [else FILTER] end> for jq-style branching.

Evaluates conditions as filters against the current input. The first truthy branch emits its result; optional C<elif> clauses cascade additional tests, and the optional C<else> filter only runs when no prior branch matches. Without an C<else> clause ...

Example:

  if .score >= 90 then "A"
  elif .score >= 80 then "B"
  else "C"
  end

=back

=head2 Sorting and ranking

=over 4

=item * C<sort_desc()> to order scalars in descending order.

=item * C<sort_by(.key)> for ordering arrays of objects by computed keys.

=item * C<min_by(.field)> / C<max_by(.field)> to select items with the smallest or largest projected values.

=item * C<percentile(p)>, C<mode>, and C<nth(n)> for statistical lookups within numeric arrays.

=back

=head2 String and collection utilities

=over 4

=item * C<join(", ")>, C<split(separator)>, C<explode()>, and C<implode()> for converting between text and arrays.

=item * C<keys_unsorted()> and C<values()> for working with object metadata.

=item * C<paths()> and C<leaf_paths()> to enumerate structure paths.

=item * C<getpath(path)> and C<setpath(path; value)> to read and write by path arrays without mutating the original input.

=item * C<pick(...)> and C<merge_objects()> to reshape objects.

=item * C<to_entries()>, C<from_entries()>, and C<with_entries(filter)> for entry-wise transformations.

=item * C<map_values(filter)> to apply filters across every value in an object or array of objects.

=back

=head2 Detailed helper reference

=over 4

=item * walk(filter)

Recursively traverses arrays and objects, applying the supplied filter to each
value after its children have been transformed, matching jq's C<walk/1>
behaviour. Arrays and hashes are rebuilt so nested values can be updated in a
single pass, while scalars pass directly to the filter.

Example:

  .profile | walk(upper)

Returns: