Data::PathSimple - Navigate and manipulate data structures using paths
use Data::PathSimple qw{ get set }; my $data = { Languages => { Perl => { CurrentVersion => '5.16.1', URLs => [ 'http://www.perl.org', 'http://www.cpan.org', ], }, PHP => { CurrentVersion => '5.4.7', URLs => [ 'http://www.php.net', 'http://pear.php.net', ], }, Python => { CurrentVersion => '2.7.3', URLs => [ 'http://www.python.org', ], }, }, }; my $current_perl = get( $data, '/Languages/Perl/CurrentVersion' ); my @perl_urls = @{ get( $data, '/Languages/Perl/URLs' ) || [] }; set( $data, '/Languages/Perl/CurrentVersion', '5.16.2' ); set( $data, '/Languages/Python/URLs/1/', 'http://pypi.python.org' );
Data::PathSimple allows you to get and set values deep within a data structure using simple paths to navigate (think XPATH without the steroids).
Why do this when we already have direct access to the data structure? The motivation is that the path will come from a user using a command line tool.
A path is specified as a string consisting of components separated by a path separator. By default the separator is the / character, but that may be changed via the path_sep option. Paths are always specified relative to the root of the structure; a leading path separator is optional.
/
path_sep
A path component is treated as an array index if it matches an integer number, as a hash key otherwise.
If an error occurs (e.g, an incorrect input, or if a path cannot be resolved) an error value is returned. By default this is undef, but it may be changed with the error option. That option can also take a code reference, so, for example,
undef
error
error => sub { require Croak; Croak::carp( "error" ) }
would cause an exception to be thrown on errors.
Functions are not exported by default.
Gets the value at the specified path:
my $current_perl = get( $data, '/Languages/Perl/CurrentVersion', ?\%options );
The following options are supported:
A string or reqular expression which will match the path separator. It defaults to the string /.
How non-existent paths or mismatched array indices or hash keys should be handled. If set to a coderef, the result of the coderef will be returned. Otherwise, whatever error is set to will be returned. It defaults to undef.
If a path does not exist, an error value is returned. For example, the following will return an error since the Ruby path does not exist:
Ruby
my $current_ruby = get( $data, '/Languages/Ruby/CurrentVersion' );
If the path is not an integer yet we are accessing an array ref, an error value is returned. For example, the following will return an error since the first path is not an integer:
first
my $perl_url = get( $data, '/Languages/Perl/URLs/first' );
Note that no autovivification occurs. In other words, your data structure will never be modified by a call to get().
get()
Sets the value at the specified path:
set( $data, '/Languages/Perl/CurrentVersion', '5.16.2', ?\%options );
How errors should be handled. If set to a coderef, the result of the coderef will be returned. Otherwise, whatever error is set to will be returned. It defaults to undef.
If a path does not exist, it will be autovivified. For example, the following will create the Ruby path:
set( $data, '/Languages/Ruby/CurrentVersion', '1.9.3' );
By default hash refs are used when autovivifying. However if the path is an integer, then an array ref will be used instead. For example, the following will create an array ref for the URLs path:
URLs
set( $data, '/Languages/Ruby/URLs/0', 'http://www.ruby-lang.org' );
If the path is not an integer yet we are accessing an array ref, an error value is returned. For example, the following will return undef since the first path is not an integer:
my $perl_url = set( $data, '/Languages/Perl/URLs/first', '5.16.2' );
The latest version can be found at:
https://github.com/alfie/Data-PathSimple
Watch the repository and keep up with the latest changes:
https://github.com/alfie/Data-PathSimple/subscription
Please report any bugs or feature requests at:
https://github.com/alfie/Data-PathSimple/issues
Feel free to fork the repository and submit pull requests :)
To install this module type the following:
perl Makefile.PL make make test make install
Alfie John <alfie@alfie.wtf>
Diab Jerius <djerius@cfa.harvard.edu>
IT COMES WITHOUT WARRANTY OF ANY KIND.
Copyright (C) 2021 by Alfie John
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.
To install Data::PathSimple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::PathSimple
CPAN shell
perl -MCPAN -e shell install Data::PathSimple
For more information on module installation, please visit the detailed CPAN module installation guide.