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 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, 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, 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, treats the remaining non-file argument as the dotted query path, accepts $d or . for the whole parsed document, and prints scalars as plain text while arrays and hashes are emitted as canonical JSON. The XML path is intentionally minimal right now: the helper stores the raw XML payload under _raw rather than pretending to offer a full tree query language.

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'
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 _raw