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

NAME

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

VERSION

version 0.010

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.

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

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 "apply_metaroles" in Moose::Util::MetaRole.

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 <cpan@semiotic.systems>

  • Mark Jason Dominus <mjd@cpan.org>

CONTRIBUTORS

  • Mohammad S Anwar <mohammad.anwar@yahoo.com>

  • Ricardo Signes <rjbs@semiotic.systems>

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