The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Struct-Path-0.64
River stage one • 3 direct dependents • 3 total dependents
/ Struct::Path

NAME

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

VERSION

Version 0.64

SYNOPSIS

    use Struct::Path qw(slist spath spath_delta);

    $s = [
        0,
        1,
        {
            '2a' => {
                '2aa' => '2aav',
                '2ab' => '2abv'
            }
        },
        undef
    ];

    @list = slist($s);                              # get all paths and their values
    # @list == (
    #    [[[0]],0],
    #    [[[1]],1],
    #    [[[2],{keys => ['2a']},{keys => ['2aa']}],'2aav'],
    #    [[[2],{keys => ['2a']},{keys => ['2ab']}],'2abv'],
    #    [[[3]],undef]
    # )

    @r = spath($s, [ [3,0,1] ]);                    # get refs to values by paths
    # @r == (\undef, \0, \1)

    @r = spath($s, [ [2],{keys => ['2a']},{} ]);    # same, another example
    # @r == (\'2aav', \'2abv')

    @r = spath($s, [ [2],{},{regs => [qr/^2a/]} ]); # or using regular expressions
    # @r == (\'2aav', \'2abv')

    ${$r[0]} =~ s/2a/blah-blah-/;                   # replace substructire by path
    # $s->[2]{2a}{2aa} eq "blah-blah-av"

    @d = spath_delta([[0],[4],[2]], [[0],[1],[3]]); # new steps relatively for first path
    # @d == ([1],[3])

DESCRIPTION

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

Why existed *Path* modules ("SEE ALSO") is not enough? Used scheme has no collisions for paths like '/a/0/c' ('0' may be an ARRAY index or a key for HASH, depends on passed structure). In some cases this is important, for example, when you want to define exact path in structure, but unable to validate it's schema or when structure doesn't exists yet (see "expand" 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 in structure and must contain desired indexes or be empty (means "all items"). Sequence for indexes is important and defines result sequence.

Hashref represents HASH in the structure and may contain keys keys, regs or be empty. keys may contain list of desired keys, regs must contain list of regular expressions. Empty hash or empty list for keys means all keys. Sequence in keys and regs lists defines result sequence. keys have higher priority than regs.

Sample:

    $spath = [
        [1,7],
        {regs => qr/foo/}
    ];

Since v0.50 coderefs (filters) as steps supported as well. Path as first argument and stack of references (arrayref) as second passed to it when executed. Some true (match) value or false (doesn't match) value expected as output.

See Struct::Path::PerlStyle if you're looking for human friendly path definition method.

SUBROUTINES

is_implicit_step

    $implicit = is_implicit_step($step);

Returns true value if step contains filter or specified all keys/items or key regexp match.

slist

Returns list of paths and their values from structure.

    @list = slist($struct, %opts)

Available options

depth <N>

Don't dive into structure deeper than defined level.

spath

Returns list of references from structure.

    @list = spath($struct, $path, %opts)

Available options

delete <true|false>

Delete specified by path items from structure.

deref <true|false>

Dereference result items.

expand <true|false>

Expand structure if specified in path items does't exists. All newly created items initialized by undef.

strict <true|false>

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

spath_delta

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

    @delta = spath_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,2017 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.