NAME

Data::PathSimple - Navigate and manipulate data structures using paths

SYNOPSIS

  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' );

DESCRIPTION

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.

FUNCTIONS

Functions are not exported by default.

get

Gets the value at the specified path:

  my $current_perl = get( $data, '/Languages/Perl/CurrentVersion' );

If a path does not exist, undef is returned. For example, the following will return undef since the 'Ruby' path does not exist:

  my $current_ruby = get( $data, '/Languages/Ruby/CurrentVersion' );

If the path is not an integer yet we are accessing an array ref, undef is returned. For example, the following will return undef since the 'first' path is not an integer:

  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().

set

Sets the value at the specified path:

  set( $data, '/Languages/Perl/CurrentVersion', '5.16.2' );

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:

  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, undef 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' );

SEE ALSO

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

SUPPORT

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 :)

INSTALLATION

To install this module type the following:

  perl Makefile.PL
  make
  make test
  make install

DEPENDENCIES

Perl v5.10.0

AUTHOR

Alfie John <alfiej@opera.com>

WARRANTY

IT COMES WITHOUT WARRANTY OF ANY KIND.

COPYRIGHT AND LICENSE

Copyright (C) 2012 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.

cpanm Data::PathSimple

perl -MCPAN -e shell
install Data::PathSimple