Hash::Lookup Query String Syntax

The get method in Hash::Lookup provides a way to retrieve values from deeply nested data structures using a query string. The query language resembles JSON Pointer, jq, or JPath and supports accessing hashes and arrays through dot (.) notation and bracket ([]) notation.

Basic Query Syntax

The query string consists of key names separated by dots (.) or array indices specified numerically. The following conventions apply:

• Dot Notation (.): Used to navigate through nested hash keys.
• Array Indexing (N): Used to access specific elements in arrays.
• Wildcard Array Mapping ([]): Used to extract values from all array elements.
• Multiple Key Selection (,): Allows retrieving multiple values at once.

Query String Behavior

1. Dot Notation (.)

Dot notation allows accessing nested hash keys. For example:

$data->get(“level1.level2.level3”); # Retrieves $data->{level1}->{level2}->{level3}

Edge Cases

• If a key does not exist, undef is returned.
• Leading or trailing dots result in undef.

2. Array Indexing (N)

When an array is encountered, an integer index retrieves a specific element:

$data->get(“level1.array_key.1.sub_key”); # Retrieves $data->{level1}->{array_key}->[1]->{sub_key}

When an hash is encountered, an integer index is treated as a key and retrieves a specific element:

$data->get(“level1.array_key.1.sub_key”); # Retrieves $data->{level1}->{array_key}->{“1}”->{sub_key}

Edge Cases

• Non-integer indices on an array return undef.
• Out-of-bounds indices return undef.

3. Wildcard Array Mapping ([])

When an array is encountered, using [] retrieves values from all elements of the array:

$data->get(“level1.array_key.[].sub_key”); # Retrieves all sub_key values in array

When a hash is encountered, using [] retrieves all the values from the hash:

$data->get(“level1.array_key.[].sub_key”); # Retrieves all sub_key values in array

• $data->get("level1.array_key.[]") returns the entire array.
• If applied to an empty array, it returns an empty array.
• $data->get("level1.array_key.[]") returns all the values in the hash.
• If applied to an empty array, it returns an empty array.

4. Multiple Key Selection (,)

A comma-separated query retrieves multiple values at once:

$data->get(“level1.level2.level3,another_key”);

This returns an array containing both values.

5. Flat vs Recursive Lookup

• $data->get("[].key") retrieves key from all hash elements.
• $data->get("[]") returns the array of hash elements as-is.

6. Special Cases and Invalid Queries