/ 
MooseX-ClassCompositor-0.009
River stage zero No dependents
/ MooseX::ClassCompositor

NAME

MooseX::ClassCompositor - a factory that builds classes from roles

VERSION

version 0.009

SYNOPSIS

my $comp = MooseX::ClassCompositor->new({
  class_basename  => 'MyApp::Class',
  class_metaroles => {
    class => [ 'MooseX::StrictConstructor::Trait::Class' ],
  },
  role_prefixes   => {
    ''  => 'MyApp::Role::',
    '=' => '',
  },
});

my $class = $comp->class_for( qw( PieEater ContestWinner ) );

my $object = $class->new({
  pie_type => 'banana',
  place    => '2nd',
});

OVERVIEW

A MooseX::ClassCompositor is a class factory. If you think using a class factory will make you feel like a filthy "enterprise" programmer, maybe you should turn back now.

The compositor has a "class_for" method that builds a class by combining a list of roles with Moose::Object, applying any supplied metaclass, and producing an arbitrary-but-human-scannable name. The metaclass is then made immutable, the operation is memoized, and the class name is returned.

In the "SYNOPSIS" above, you can see all the major features used: class_metaroles to enable strict constructors, role_prefixes to use String::RewritePrefix to expand role name shorthand, and class_basename to pick a namespace under which to put constructed classes.

Not shown is the "known_classes" method, which returns a list of pairs describing all the classes that the factory has constructed. This method can be useful for debugging and other somewhat esoteric purposes like serialization.

ATTRIBUTES

class_basename

This attribute must be given, and must be a valid Perl package name. Constructed classes will all be under this namespace.

class_metaroles

This attribute, if given, must be a hashref of class metaroles that will be applied to newly-constructed classes with Moose::Util::MetaRole::apply_metaroles.

known_classes

This attribute stores a mapping of class names to the parameters used to construct them. The known_classes method returns its contents as a list of pairs.

role_prefixes

This attribute is used as the arguments to String::RewritePrefix for expanding role names passed to the compositor's class_for method.

fixed_roles

This attribute may be initialized with an arrayref of role names and/or Moose::Meta::Role objects. These roles will always be composed in the classes built by the compositor.

Role names (but not Moose::Meta::Role objects) will be rewritten by the role prefixes.

forbid_meta_role_objects

If true, an exception will be raised if a Moose::Meta::Role object is passed to "class_for". This is only rarely useful, such as if it's a strict requirement that the memoization table of the compositor be serializable and its contents reproduceable.

Probably you don't need this.

METHODS

class_for

my $class = $compositor->class_for(

  'Role::Name',          #  <-- will be expanded with role_prefixes
  Other::Role->meta,     #  <-- will not be touched

  [
    'Param::Role::Name', #  <-- will be expanded with role_prefixes
    'ApplicationName',   #  <-- will not be touched
    { ...param... },
  ],
);

This method will return a class with the roles passed to it. They can be given either as names (which will be expanded according to "role_prefixes"), as Moose::Meta::Role objects, or as arrayrefs containing a role name, application name, and hashref of parameters. In the arrayref form, the application name is just a name used to uniquely identify this application of a parameterized role, so that they can be applied multiple times with each application accounted for internally.

THANKS

Thanks to Pobox.com for sponsoring the development of this library.

AUTHORS

  • Ricardo Signes <rjbs@cpan.org>

  • Mark Jason Dominus <mjd@cpan.org>

CONTRIBUTOR

Toby Inkster <tobyink@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Ricardo Signes.

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