/ 
autobox-Lookup-0.001
/ autobox::Lookup

NAME

autobox::Lookup - easy autoboxed lookup

SYNOPSIS

    use strict;
    use warnings;
    use autobox::Lookup;

    my $data = {
	level1 => {
	    level2 => {
		level3 => "value at level 3",
	    },
	    array_key => [
		{ sub_key => "value in array 0" },
		{ sub_key => "value in array 1" },
	    ],
	},
    };

    my $result = $data->get("level1.level2.level3");

DESCRIPTION

autobox::Lookup provides a way to retrieve values from deeply nested data structures using a query string that supports accessing hashes and arrays through dot (.) notation and bracket ([]) notation.

autobox::Lookup Query String Syntax

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

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.

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.

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.

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.

Flat vs Recursive Lookup

$data->get("[].key") # retrieves key from all hash elements.

$data->get("[]") # returns the array of hash elements as-is.

Special Cases and Invalid Queries