HDF Path Query Language (HDFPGL) Specification
HDFPGL is a declarative query language designed to navigate and extract data from HDF (Human Data Form) structures into Lua tables.
1. Syntax Overview
1.1 Path Navigation
- Strict Navigation (
.): Matches exactly one level.
- platform.database: Matches database directly under platform.
- *Deep Navigation (
- platformport: Finds all port nodes anywhere under platform.
- *Wildcard (
- servers.: Matches all children of the servers node.
1.2 Projections and Bindings
Projections define what data to extract from the matched nodes and how to name the keys in the resulting Lua table.
- Shorthand Binding:
path {VAR}
- Example: servers..hostname {H}
- Returns: { {H = "vh1..."}, {H = "vh2..."} }
- Multi-Field Projection:
path ( field1 {V1}, field2 {V2} )
- Example: servers. ( customer {C}, hostname {H} )
- Returns: { {C = "imperial", H = "vh1..."}, ... }
- Nested Path in Projection:
- Example: users. ( metadata.name {N} )
2. Command Line Interface: hq
The hq tool is a CLI utility for querying and formatting HDF data, similar to jq for JSON.
Usage
hq [options] <query> [file]
Options
-r, --raw-output: Output raw values (unquoted strings).-c, --compact-output: Output HDF on a single line.-n, --null-input: Ignore standard input.
Examples
# Filter and pretty-print
hq 'servers.server ( status "active", * )' inventory.hdf
# Extract a single raw value
hq -r 'server.hostname' config.hdf
3. Command Line Interface: he
The he tool is a CLI utility for editing HDF data, similar to yq for YAML.
Usage
he [options] <command> [files...]
Commands
- Assignment:
.path.to.key = value
- Updates an existing value or creates the path if it doesn't exist.
- Supports strings (quoted), numbers, booleans, and null.
- Deletion:
del(.path.to.key)
- Removes the node at the specified path.
- Deep merges multiple HDF files.
- Heuristic: Overwrites simple values, merges nested fields.
Options
-i, --in-place: Edit the first file argument in-place.-c, --compact-output: Output HDF on a single line.
Examples
# Set a value and output to stdout
he '.server.port = 8080' config.hdf
# Delete a key in-place
he -i 'del(.debug)' app.hdf
# Merge two configurations
he merge base.hdf override.hdf > final.hdf
4. Extraction Rules
- If a projection matches a node with multiple children (a list), it returns a Lua array.
- If it matches a leaf node, it returns the primitive value (string, number, boolean).
- Missing fields return
nil.
4. Features
4.1 Literals in Projections (Filtering)
Syntax: path ( field "literal_value", field2 {BINDING} )
Example: servers. ( customer "imperex", hostname {H} )
Purpose: Only return records where customer equals "imperex".
4.2 Wildcard Projection ()
Syntax: path ( ) or path ( key "val", )
Purpose: Extracts all sub-nodes of the matched node as key-value pairs in the result table.
4.3 Deep Navigation
Syntax: pathtarget
Purpose: Finds target nodes at any depth under path.