The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Struct-Path-0.81
River stage one • 3 direct dependents • 3 total dependents
++
/ Struct::Path

NAME

Struct::Path - Path for nested structures where path is also a structure

Travis CI Coverage Status CPAN version

VERSION

Version 0.81

SYNOPSIS

    use Struct::Path qw(list_paths path);

    $s = [
        0,
        {
            two => {
                three => 3,
                four => 4
            }
        },
        undef
    ];

    @list = list_paths($s);                         # list paths and values
    # @list == (
    #   [[0]], \0,
    #   [[1],{K => ['two']},{K => ['four']}], \4,
    #   [[1],{K => ['two']},{K => ['three']}], \3,
    #   [[2]], \undef
    # )

    @r = path($s, [ [1],{K => ['two']} ]);         # get refs to values
    # @r == (\{four => 4,three => 3})

DESCRIPTION

Struct::Path provides functions to access/match/expand/list nested data structures.

Why existed Path modules is not enough? This module has no conflicts for paths like '/a/0/c', where 0 may be an array index or a key for hash (depends on passed structure). This is vital in some cases, for example, when one need to define exact path in structure, but unable to validate it's schema or when structure itself doesn't yet exist (see option expand for "path" for example).

EXPORT

Nothing is exported by default.

ADDRESSING SCHEME

Path is a list of 'steps', each represents nested level in structure.

Arrayref as a step stands for ARRAY and must contain desired items indexes or be empty (means "all items"). Sequence for indexes define result sequence.

Hashref represent HASH and may contain keys K, R or be empty. K may contain list of desired keys, R must contain list of regular expressions. Empty hash or empty list for K means all keys. Sequence in K and R lists define result sequence. K have higher priority than R.

Coderef step is a hook - subroutine which may filter and/or modify structure. Path as first argument and a stack (arrayref) of refs to traversed subsstructures as second passed to it when executed, $_ set to current substructure. Some true (match) value or false (doesn't match) value expected as output.

Sample:

    $path = [
        [1,7],                      # first spep
        {R => [qr/foo/,qr/bar/]}    # second step
        sub { exists $_->{bar} }    # third step
    ];

Struct::Path intentionally designed to be machine-friendly. See frontend Struct::Path::PerlStyle for human friendly path definition.

SUBROUTINES

implicit_step

    $bool = implicit_step($step);

Returns true value if step contains hooks or specified 'all' items or regexp match.

list_paths

Returns list of paths and references to their values from structure.

    @list = list_paths($structure, %opts)

Options

depth <N>

Don't dive into structure deeper than defined level.

path

Returns list of references from structure.

    @found = path($structure, $path, %opts)

Options

assign <value>

Assign provided value to substructures pointed by path.

delete <true|false>

Delete specified by path items from structure.

deref <true|false>

Dereference result items.

expand <"append"|true|false>

Expand structure if specified in path items doesn't exist. All newly created items initialized by undef. Arrays will be growed smoothly if append as value used (experimental).

paths <true|false>

Return path for each result.

stack <true|false>

Return stack of references to substructures.

strict <true|false>

Croak if at least one element, specified by path, absent in the structure.

All options are disabled (undef) by default.

path_delta

Returns delta for two passed paths. By delta means list of steps from the second path without beginning common steps for both.

    @delta = path_delta($path1, $path2)

LIMITATIONS

Struct::Path will fail on structures with loops in references.

No object oriented interface provided.

AUTHOR

Michael Samoglyadov, <mixas at cpan.org>

BUGS

Please report any bugs or feature requests to bug-struct-path at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Struct-Path. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Struct::Path

You can also look for information at:

SEE ALSO

Data::Diver Data::DPath Data::DRef Data::Focus Data::Hierarchy Data::Nested Data::PathSimple Data::Reach Data::Spath JSON::Path MarpaX::xPathLike Sereal::Path Data::Find

Struct::Diff Struct::Path::PerlStyle

LICENSE AND COPYRIGHT

Copyright 2016-2018 Michael Samoglyadov.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.