NAME

Newcomen::Collection - Manages an ordered list of source items and meta data.

SYNOPSIS

use Newcomen::Collection;

my $collection = Newcomen::Collection -> new (
   'creator' => $creator,
   'id'      => $collection_id
);

# Add a source:
$collection -> push ($source);

# Get first source item:
my $source = $collection -> source (0);

# Iterate over the source items:
for my $source ($collection -> sources ()) {
   # do something...
}

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

# Retrieve the meta data:
my $value = $collection -> get ('some/data');

DESCRIPTION

A collection is a container for an ordered list of Newcomen::Source instances and related meta data. See the developer section in Newcomen::Manual for a description of how Newcomen works and how collections fit in.

CLASS METHODS

new

my $collection = Newcomen::Collection -> new (
   'creator' => $creator,
   'id'      => $collection_id,
   'sources' => $sources
);

Constructor. The creator parameter is used to indicate which plugin created the collection. It is usually set to the plugin basename (i.e. the plugin name without the 'Newcomen::Plugin::' prefix). The id parameter is used to identify the collection. If the collection is added to the catalog (see Newcomen::Catalog), this ID must be globally unique. It is recommended to prefix the ID with the plugin basename to avoid clashes with other plugins' collections. Both creator and id are required parameters. The sources parameter is optional. If it is specified, it must be an arrayref containing Newcomen::Source instances. These will be the initial content of the collection. If it is not specified, the collection will not contain any source items initially. The collection's meta data will always be empty initially.

INSTANCE METHODS

General

creator

my $creator = $collection -> creator ();

Returns the creator of the collection. The value can only be set during construction (see new()).

id

my $id = $collection -> id ();

Returns the ID of the collection. The value can only be set during construction (see new()).

Meta Data

Meta data is stored in an Newcomen::Data instance.

delete, exists, get, set

The methods delete(), exists(), get() and set() are mapped to the Newcomen::Data methods of the same name, see there for details.

Source Items

Newcomen::Collection uses an arrayref to store the collections as an ordered list. It uses the array methods of Newcomen::Util::Traits, with the following additions:

The Newcomen::Collection method source() is an alias for the item() method.
The Newcomen::Collection method sources() is an alias for the items() method.

Please see Newcomen::Util::Traits for a complete list of methods and more details.

VERSION

This is version 2014052501.

AUTHOR

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

COPYRIGHT AND LICENSE

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/>.

Newcomen

Index