/ 
Marmoset-0.000_01
River stage zero No dependents
/ Marmoset

NAME

Marmoset - class builder for memory-efficient objects

SYNOPSIS

use v5.14;
use warnings;

package MyClass {
	use Marmoset;
	has id   => (is => 'ro', pack => 'L');
	has name => (is => 'rw', pack => 'Z32');
}

my $obj = MyClass->new(id => 42, name => "The Answer");

DESCRIPTION

Eating marmoset II

Marmoset is a slightly less featureful version of class builders like Moose, Mouse, and Moo, designed for efficient memory usage when you need to deal with many thousands of very simple objects.

Attributes are stored using a variation on the pack/unpack shown by BrowserUK on PerlMonks at http://www.perlmonks.org/?node_id=1040313.

However, inside-out attributes are also offered for data which cannot be reasonably serialized to a string.

Keywords provided by Marmoset

extends(@classes)

Set inheritance for the current class. Currently you may only inherit from other Marmoset classes.

If you don't specify a class to inherit from, your class will inherit from Marmoset::Object. (See "Methods provided by Marmoset::Object".)

has $attribute => %specification

Creates an attribute for your class, using a Moose-like specification. There is a convention that attributes named with a leading underscore are undocumented, unsupported or "private". (see Lexical::Accessor for true private attributes though.)

The following keys are supported in the specification hash:

is => "ro"|"rw"|"rwp"|"lazy"

Shortcuts for common patterns of accessors. As documented in Moo and MooseX::AttributeShortcuts.

pack => $template

The presence of this key in the specification makes your attribute be stored in the object's packed string.

Attributes suitable for packed storage include numbers and small (especially fixed-length) strings.

Templates are as defined in "pack" in perlfunc.

reader => $name|1

Specify the name for a read-only accessor method. Passing the value "1" names the accessor "get_${attribute}" (for "private" attributes, "_get${attribute}").

writer => $name|1

Specify the name for a write-only accessor method. Passing the value "1" names the accessor "set_${attribute}" (for "private" attributes, "_set${attribute}").

accessor => $name|1

Specify the name for a read/write accessor method. Passing the value "1" names the accessor "${attribute}".

predicate => $name|1

Specify the name for a predicate method. Passing the value "1" names the predicate "has_${attribute}" (for "private" attributes, "_has${attribute}").

For any attributes which are stored packed, it makes little sense to define a predicate. The predicate will always return true.

clearer => $name|1

Specify the name for a clearer method. Passing the value "1" names the predicate "clear_${attribute}" (for "private" attributes, "_clear${attribute}").

For any attributes which are stored packed, it makes little sense to define a clearer. The clearer will always throw an exception.

trigger => $coderef|$name|1

A coderef to call after the value for the attribute has been set. Alternatively, a method name may be supplied. Passing the value "1" is equivalent to the method name "_trigger_${attribute}".

builder => $coderef|$name|1

A method name to call to build a default value for the attribute. Passing the value "1" is equivalent to the method name "_build_${attribute}". If a coderef is supplied, this will be installed into the class as "_build_${attribute}".

default => $coderef|$nonref

Similar to builder, but the coderef will not be installed as a class method. Non-reference values (i.e. undef, numbers, strings), may be supplied as a simple value instead of a coderef.

isa => $constraint|$coderef|$typename

A type constraint to validate values for the attribute. Any constraint object which meets the Type::API::Constraint specification can be provided, including Type::Tiny, MooseX::Types, MouseX::Types, and Specio type constraint objects.

Alternatively a validation coderef may be provided, which must return true to indicate a valid value, and either return false or throw an exception to indicate an invalid one.

If Type::Utils is installed, this may be provided as a string, which will be expanded to a type constraint object using dwim_type. (See "dwim_type" in Type::Utils.)

does => $role

Shorthand for isa => ConsumerOf[$role].

coerce => $coercion|$coderef|0|1

Indicates whether type coercion should be attempted before validating values.

If an object meeting the Type::API::Constraint::Coercible specification has been provided for isa, then the value "1" will reuse any coercion attached to the type constraint object.

Otherwise, an type coercion object (i.e. with a coerce method) may be provided, or a coderef which accepts a value and returns the coerced value.

handles => $arrayref|$hashref

Delegates methods to the attribute value.

weak_ref => 0|1

Indicates whether the attribute value should be weakened. Only makes sense for attributes which are not stored packed.

init_arg => $name|undef

The named constructor argument that will provide an initial value for the attribute. If omitted, will default to $attribute.

required => 0|1

Indicates whether it is necessary to set the attribute when constructing objects.

Attributes which are stored packed must be required unless they provide a default/builder.

Keywords NOT provided by Marmoset

Unlike Moose, Mouse, and Moo, Marmoset does not provide native support for method modifiers or roles. Instead, it recommends the use of Class::Method::Modifiers and Role::Tiny respectively.

Note that Marmoset is sometimes forced to rebuild constructors and accessors at run-time, which may lead to your method modifiers being overwritten, if you have tried to apply any modifiers to them.

It may be useful to force Marmoset to perform its rebuilding early; after you've finished defining your class' inheritance and attributes, but before applying any roles or method modifiers. To do this, call:

Marmoset->make_immutable(__PACKAGE__);

Methods provided by Marmoset::Object

Marmoset::Object is your object's base class. It provides the following methods:

new(%attributes)

Your class' constructor.

BUILDARGS(@args)

This is the proper way to alter incoming arguments to get them into a format that Marmoset::Object's default constructor will recognize. This class method is passed the list of constructor arguments as-is, and expected to return a hashref of parameters which will be used to initialize attributes.

BUILD($parameters)

(Actually Marmoset::Object doesn't provide this, but your class may.)

This is the proper way to perform any additional initialization on your objects. It is called as an object method. If you're inheriting from another Marmoset class, you must not call $self->SUPER::BUILD(@_). Marmoset will do that for you!

DESTROY

TODO - not implemented

DEMOLISH

TODO - not implemented

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Marmoset.

SEE ALSO

Moose, Moo, Mouse, Class::Tiny.

http://www.perlmonks.org/?node_id=1040313.

http://www.flickr.com/photos/tambako/10655212644/.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2014 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.