/ 
EntityModel-Class-0.016
River stage one • 2 direct dependents • 8 total dependents
/ EntityModel::Class

NAME

EntityModel::Class - define class definition

VERSION

Version 0.016

SYNOPSIS

 package Thing;
 use EntityModel::Class {
	name => 'string',
 	items => { type => 'array', subclass => 'string' }
 };

 package main;
 my $thing = Thing->new;
 $thing->name('A thing');
 $thing->items->push('an entry');
 $thing->items->push('another entry');
 print "Have " . $thing->items->count . " items\n";

DESCRIPTION

Applies a class definition to a package. Automatically includes strict, warnings, error handling and other standard features without needing to copy and paste boilerplate code.

USAGE

NOTE: This is mainly intended for use with EntityModel only, please consider Moose or similar for other projects.

Add EntityModel::Class near the top of the target package:

package Test;
use EntityModel::Class { };

The hashref parameter contains the class definition. Each key is the name of an attribute for the class, with the exception of the following underscore-prefixed keys:

  • _vcs - version control system information, a plain string containing information about the last changed revision and author for this file.

    use EntityModel::Class { _vcs => '$Id$' };

  • _isa - set up the parents for this class, similar to use parent.

    use EntityModel::Class { _isa => 'DateTime' };

An attribute definition will typically create an accessor with the same name, and depending on type may also include some additional helper methods.

Available types include:

  • string - simple string scalar value.

    use EntityModel::Class { name => { type => 'string' } };

  • array - an array of objects, provide the object type as the subclass parameter

    use EntityModel::Class { childNodes => { type => 'array', subclass => 'Node' } };

  • hash - hash of objects of subclass type

    use EntityModel::Class { authorMap => { type => 'hash', subclass => 'Author' } };

If the type (or subclass) contains '::', or starts with a Capitalised letter, then it will be treated as a class. All internal type names are lowercase.

You can also set the scope on a variable, which defines whether it should be include when exporting or importing:

  • private - private attributes are not exported or visible in attribute lists

    use EntityModel::Class { authorMap => { type => 'hash', subclass => 'Author', scope => 'private' } };

  • public (default) - public attributes are included in export/import, and will be visible when listing attributes for the class

    use EntityModel::Class { name => { type => 'string', scope => 'public' } };

You can also specify actions to take when a variable is changed, to support internal attribute observers, by specifying the watch parameter. This takes a hashref with key corresponding to the attribute to watch, and value indicating the method on that object. For example, page = 'path'> would update whenever the path mutator is called on the page attribute. This is intended for use with hash and array containers, rather than classes or simple types.

package Compendium;
use EntityModel::Class {
	authors => { type => 'array', subclass => 'Author' },
	authorByName => { type => 'hash', subclass => 'Author', scope => 'private', watch => { authors => 'name' } }
};

package main;
my $c = Compendium->new;
$c->authors->push(Author->new("Adams"));
$c->authors->push(Author->new("Brecht"));
print $c->authorByName->{'Adams'}->id;

import

Apply supplied attributes, and load in the following modules:

use strict;
use warnings;
use feature;
use 5.010;

record_class

Add an entry for this class in the central class info hash.

apply_inheritance

Set up inheritance as required for this class.

load_dependencies

Load all modules required for classes

apply_logging

apply_version

Record the VCS revision information from _vcs attribute.

apply_attributes

add_method

vcs

Add a version control system tag to the class.

setup

Standard module setup - enable strict and warnings, and disable 'import' fallthrough.

validator

Basic validation function.

_attrib_info

Returns attribute information for a given package's attribute.

has_defaults

Returns any defaults defined for this class.

add_watcher

Add watchers as required for all package definitions.

Call this after all the class definitions have been loaded.

SEE ALSO

Or rather, "please use instead of this module":

AUTHOR

Tom Molesworth <cpan@entitymodel.com>

LICENSE

Copyright Tom Molesworth 2008-2013. Licensed under the same terms as Perl itself.