/ 
Developer-Dashboard-2.25
/ Developer::Dashboard::CLI::Query

NAME

Developer::Dashboard::CLI::Query - standalone structured-data query command support

SYNOPSIS

use Developer::Dashboard::CLI::Query qw(run_query_command);
run_query_command( command => 'jq', args => \@ARGV );

DESCRIPTION

Provides the lightweight shared implementation behind the private runtime helper scripts for jq, yq, tomq, propq, iniq, csvq, and xmlq plus the proxied dashboard ... command paths. Earlier names such as pjq, pyq, ptomq, and pjp still normalize through dashboard for compatibility.

PURPOSE

This module is the shared parser and dispatcher behind the lightweight query commands for JSON, YAML, TOML, Java properties, INI, CSV, and XML. It owns the common contract for every query helper: accept an optional dotted path or $d-based Perl expression plus an optional file path in either order, read from STDIN when no file is given, parse the requested format, and print either a scalar value or canonical JSON for structured data.

WHY IT EXISTS

It exists because the dashboard ships a family of query commands that should feel consistent across file formats. Keeping parser selection, source selection, dotted-path traversal, $d expression handling, and scalar-vs-structure output rules in one module prevents the helper wrappers from drifting apart and keeps release tests focused on one implementation.

WHEN TO USE

Use this file when changing dotted-path semantics, $d expression semantics, format-specific parsing behavior, file-vs-STDIN selection, scalar-vs-JSON output, or the exact error surface for malformed input and missing path segments.

HOW TO USE

Call run_query_command from a staged helper such as jq or tomq, passing the helper name and the raw argv list. The module treats the first existing file argument as the input source, rejoins the remaining non-file arguments into one query string, accepts $d or . for the whole parsed document, uses dotted traversal for plain path strings, and evaluates real $d-based Perl expressions such as sort keys %$d against the decoded data. Scalars print as plain text while arrays and hashes are emitted as canonical JSON. The XML path now decodes XML into nested hashes and arrays so dotted paths and $d expressions work there too.

WHAT USES IT

It is used by the private query helper scripts under share/private-cli/, by install and release smoke runs that verify format-specific helpers, and by coverage tests that exercise parser choice, order-independent argv handling, root-document queries, and format-specific edge cases.

EXAMPLES

printf '{"alpha":{"beta":2}}' | dashboard jq alpha.beta
dashboard jq response.json '$d'
dashboard jq response.json 'sort keys %$d'
printf 'alpha:\n  beta: 3\n' | dashboard yq alpha.beta
printf 'alpha.beta=5\nname=demo\n' | dashboard propq '$d'
printf 'alpha,beta\n7,8\n' | dashboard csvq 1.1
printf '<root><value>demo</value></root>' | dashboard xmlq root.value
printf '<root><item id="1">x</item><item id="2">y</item></root>' | dashboard xmlq 'join q(,), map { $_->{_attributes}{id} } @{ $d->{root}{item} }'