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
    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 <http://www.perlmonks.org/?node_id=171588> 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.

