Newcomen

Description A static content generator.
Newcomen > Perl Modules > Newcomen::Data
Source

Index


NAME ^

Newcomen::Data - General data storage class, Data::SimplePath wrapper.

SYNOPSIS ^

use Newcomen::Data;

my $data = Newcomen::Data -> new ();

# Set a value:
$data -> set (['some', 'data'], 'value');

# Get the value:
my $value = $data -> get (['some', 'data']);

DESCRIPTION ^

Please read (and understand) the documentation of Data::SimplePath first. Newcomen::Data extends Data::SimplePath. Newcomen::Data is a Moose class. All methods provided by Data::SimplePath are available for an Newcomen::Data instance, and most of these behave exactly like or at least similar their original counterparts.

Differences To Data::SimplePath

The constructor of Newcomen::Data does not allow the setting of initial content. Instead, the initial data will always be an empty hashref. Setting the root element to an arrayref does work, but it will break the merge() method, and any code using Newcomen::Data that expects a hashref, so only do this if you really know what you are doing (usually this means: don't do it).

The get() and data() methods will always return a scalar value, i.e. calling them in list context will not work as it does for Data::SimplePath. This allows for easier usage of Newcomen::Data instances within Template Toolkit templates.

The set() method will die() on failure.

The separator() and auto_array() methods do not allow their respective settings to be changed. They can be used to get the values, though. The value of the separator is '/' (as is the default for Data::SimplePath). The value of auto_array is 0 (disabled), this is different from the initial Data::SimplePath value. This means that for an Newcomen::Data instance you will have to create arrays explicitly. Note: Trying to change any of these settings will cause the methods to die().

The key() method works like Data::SimplePath's method, but it will always return the normalized key.

Newcomen::Data's clone() will return a new Newcomen::Data instance. It will use merge() internally, which itself uses Clone to clone the data, instead of Storable used by Data::SimplePath's clone() method. This means that coderefs or regexps inside the data should work.

The methods delete() and exists() are aliases for the remove() and does_exist() methods of Data::SimplePath (both names may be used for any of these two methods).

CLASS METHODS ^

new

my $data = Newcomen::Data -> new ();

Constructor. The initial data will be an empty hashref.

INSTANCE METHODS ^

auto_array, replace_leaf, separator

# Set new value (works only for replace_leaf):
$data -> replace_leaf (1);

# Get the current separator setting:
$separator = $data -> separator ();

These get or set the Data::SimplePath options, see there for details. Also check the differences between Newcomen::Data and Data::SimplePath mentioned above.

delete, remove

$data -> delete (['some', 'data']);

Remove an element. delete() is an alias for Data::SimplePath's remove() method. Both may be used with Newcomen::Data.

exists, does_exist

if ($data -> exists (['some', 'data'])) {
   # do something...
}

Check if an element exists. exists() is an alias for Data::SimplePath's does_exist() method. Both may be used with Newcomen::Data.

get, set

my $value = $data -> get (['some', 'data']);

$data -> set (['some', 'data'], $value);

Get or set an element. See Data::SimplePath for details.

data

my $hashref = $data -> data ();

Returns the underlying data structure, same as Data::SimplePath's data() method.

clone

my $copy = $data -> clone ();

Returns a new Newcomen::Data instance with the same contents, but independent from the source instance.

merge

Toggle source:   merge

sub merge {

   my $self = shift;
   my $data = $self -> data ();

   while (@_) {
      my $hash = is_a ($_ [0], 'Newcomen::Data') ? shift -> data () : shift;
      $data = Newcomen::Util::Hash::merge ($data, $hash);
   }
   $self -> set ('', $data);

   return $self;

}
$data -> merge ($other_data);

Expects one or more hashrefs or Newcomen::Data instances as parameters. The hashrefs (or instances) will be merged with the current data of the instance, one after another in the order specified. See Newcomen::Util::Hash's merge() function for details. For convenience, this method will return the current instance, so the following may be used to create an instance with initial data:

my $data = Newcomen::Data -> new () -> merge ($initial_data);

Also, it allows calls to merge() to be chained, but the same can be achieved by using multiple parameters.

key, path, normalize_key

my $key  = $data -> key ($path);
my $path = $data -> path ($key);
my $norm = $data -> normalize_key ($key);

See Data::SimplePath for details. Note that Newcomen::Data's key() function will always return the normalized key.

SEE ALSO ^

Data::SimplePath, Newcomen::Util::Hash

VERSION ^

This is version 2014101201.

AUTHOR ^

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE ^

Copyright 2013-2014 Stefan Goebel.

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.