Provided by: libclass-container-perl_0.13-1_all bug

NAME

       Class::Container - Glues object frameworks together transparently

VERSION

       version 0.13

SYNOPSIS

        package Car;
        use Class::Container;
        @ISA = qw(Class::Container);

        __PACKAGE__->valid_params
          (
           paint  => {default => 'burgundy'},
           style  => {default => 'coupe'},
           windshield => {isa => 'Glass'},
           radio  => {isa => 'Audio::Device'},
          );

        __PACKAGE__->contained_objects
          (
           windshield => 'Glass::Shatterproof',
           wheel      => { class => 'Vehicle::Wheel',
                           delayed => 1 },
           radio      => 'Audio::MP3',
          );

        sub new {
          my $package = shift;

          # 'windshield' and 'radio' objects are created automatically by
          # SUPER::new()
          my $self = $package->SUPER::new(@_);

          $self->{right_wheel} = $self->create_delayed_object('wheel');
          ... do any more initialization here ...
          return $self;
        }

DESCRIPTION

       This class facilitates building frameworks of several classes that inter-operate.  It was
       first designed and built for "HTML::Mason", in which the Compiler, Lexer, Interpreter,
       Resolver, Component, Buffer, and several other objects must create each other
       transparently, passing the appropriate parameters to the right class, possibly
       substituting other subclasses for any of these objects.

       The main features of "Class::Container" are:

       ·   Explicit declaration of containment relationships (aggregation, factory creation,
           etc.)

       ·   Declaration of constructor parameters accepted by each member in a class framework

       ·   Transparent passing of constructor parameters to the class that needs them

       ·   Ability to create one (automatic) or many (manual) contained objects automatically and
           transparently

   Scenario
       Suppose you've got a class called "Parent", which contains an object of the class "Child",
       which in turn contains an object of the class "GrandChild".  Each class creates the object
       that it contains.  Each class also accepts a set of named parameters in its "new()"
       method.  Without using "Class::Container", "Parent" will have to know all the parameters
       that "Child" takes, and "Child" will have to know all the parameters that "GrandChild"
       takes.  And some of the parameters accepted by "Parent" will really control aspects of
       "Child" or "GrandChild".  Likewise, some of the parameters accepted by "Child" will really
       control aspects of "GrandChild".  So, what happens when you decide you want to use a
       "GrandDaughter" class instead of the generic "GrandChild"?  "Parent" and "Child" must be
       modified accordingly, so that any additional parameters taken by "GrandDaughter" can be
       accommodated.  This is a pain - the kind of pain that object-oriented programming was
       supposed to shield us from.

       Now, how can "Class::Container" help?  Using "Class::Container", each class ("Parent",
       "Child", and "GrandChild") will declare what arguments they take, and declare their
       relationships to the other classes ("Parent" creates/contains a "Child", and "Child"
       creates/contains a "GrandChild").  Then, when you create a "Parent" object, you can pass
       "Parent->new()" all the parameters for all three classes, and they will trickle down to
       the right places.  Furthermore, "Parent" and "Child" won't have to know anything about the
       parameters of its contained objects.  And finally, if you replace "GrandChild" with
       "GrandDaughter", no changes to "Parent" or "Child" will likely be necessary.

METHODS

   new()
       Any class that inherits from "Class::Container" should also inherit its "new()" method.
       You can do this simply by omitting it in your class, or by calling "SUPER::new(@_)" as
       indicated in the SYNOPSIS.  The "new()" method ensures that the proper parameters and
       objects are passed to the proper constructor methods.

       At the moment, the only possible constructor method is "new()".  If you need to create
       other constructor methods, they should call "new()" internally.

   __PACKAGE__->contained_objects()
       This class method is used to register what other objects, if any, a given class creates.
       It is called with a hash whose keys are the parameter names that the contained class's
       constructor accepts, and whose values are the default class to create an object of.

       For example, consider the "HTML::Mason::Compiler" class, which uses the following code:

         __PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );

       This defines the relationship between the "HTML::Mason::Compiler" class and the class it
       creates to go in its "lexer" slot.  The "HTML::Mason::Compiler" class "has a" "lexer".
       The "HTML::Mason::Compiler->new()" method will accept a "lexer" parameter and, if no such
       parameter is given, an object of the "HTML::Mason::Lexer" class should be constructed.

       We implement a bit of magic here, so that if "HTML::Mason::Compiler->new()" is called with
       a "lexer_class" parameter, it will load the indicated class (presumably a subclass of
       "HTML::Mason::Lexer"), instantiate a new object of that class, and use it for the
       Compiler's "lexer" object.  We're also smart enough to notice if parameters given to
       "HTML::Mason::Compiler->new()" actually should go to the "lexer" contained object, and it
       will make sure that they get passed along.

       Furthermore, an object may be declared as "delayed", which means that an object won't be
       created when its containing class is constructed.  Instead, these objects will be created
       "on demand", potentially more than once.  The constructors will still enjoy the automatic
       passing of parameters to the correct class.  See the "create_delayed_object()" for more.

       To declare an object as "delayed", call this method like this:

         __PACKAGE__->contained_objects( train => { class => 'Big::Train',
                                                    delayed => 1 } );

   __PACKAGE__->valid_params(...)
       Specifies the parameters accepted by this class's "new()" method as a set of key/value
       pairs.  Any parameters accepted by a superclass/subclass will also be accepted, as well as
       any parameters accepted by contained objects.  This method is a get/set accessor method,
       so it returns a reference to a hash of these key/value pairs.  As a special case, if you
       wish to set the valid params to an empty set and you previously set it to a non-empty set,
       you may call "__PACKAGE__->valid_params(undef)".

       "valid_params()" is called with a hash that contains parameter names as its keys and
       validation specifications as values.  This validation specification is largely the same as
       that used by the "Params::Validate" module, because we use "Params::Validate" internally.

       As an example, consider the following situation:

         use Class::Container;
         use Params::Validate qw(:types);
         __PACKAGE__->valid_params
             (
              allow_globals        => { type => ARRAYREF, parse => 'list',   default => [] },
              default_escape_flags => { type => SCALAR,   parse => 'string', default => '' },
              lexer                => { isa => 'HTML::Mason::Lexer' },
              preprocess           => { type => CODEREF,  parse => 'code',   optional => 1 },
              postprocess_perl     => { type => CODEREF,  parse => 'code',   optional => 1 },
              postprocess_text     => { type => CODEREF,  parse => 'code',   optional => 1 },
             );

         __PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );

       The "type", "default", and "optional" parameters are part of the validation specification
       used by "Params::Validate".  The various constants used, "ARRAYREF", "SCALAR", etc. are
       all exported by "Params::Validate".  This means that any of these six parameter names,
       plus the "lexer_class" parameter (because of the "contained_objects()" specification given
       earlier), are valid arguments to the Compiler's "new()" method.

       Note that there are also some "parse" attributes declared.  These have nothing to do with
       "Class::Container" or "Params::Validate" - any extra entries like this are simply ignored,
       so you are free to put extra information in the specifications as long as it doesn't
       overlap with what "Class::Container" or "Params::Validate" are looking for.

   $self->create_delayed_object()
       If a contained object was declared with "delayed => 1", use this method to create an
       instance of the object.  Note that this is an object method, not a class method:

          my $foo =       $self->create_delayed_object('foo', ...); # YES!
          my $foo = __PACKAGE__->create_delayed_object('foo', ...); # NO!

       The first argument should be a key passed to the "contained_objects()" method.  Any
       additional arguments will be passed to the "new()" method of the object being created,
       overriding any parameters previously passed to the container class constructor.  (Could I
       possibly be more alliterative?  Veni, vedi, vici.)

   $self->delayed_object_params($name, [params])
       Allows you to adjust the parameters that will be used to create any delayed objects in the
       future.  The first argument specifies the "name" of the object, and any additional
       arguments are key-value pairs that will become parameters to the delayed object.

       When called with only a $name argument and no list of parameters to set, returns a hash
       reference containing the parameters that will be passed when creating objects of this
       type.

   $self->delayed_object_class($name)
       Returns the class that will be used when creating delayed objects of the given name.  Use
       this sparingly - in most situations you shouldn't care what the class is.

   __PACKAGE__->decorates()
       Version 0.09 of Class::Container added [as yet experimental] support for so-called
       "decorator" relationships, using the term as defined in Design Patterns by Gamma, et al.
       (the Gang of Four book).  To declare a class as a decorator of another class, simply set
       @ISA to the class which will be decorated, and call the decorator class's "decorates()"
       method.

       Internally, this will ensure that objects are instantiated as decorators.  This means that
       you can mix & match extra add-on functionality classes much more easily.

       In the current implementation, if only a single decoration is used on an object, it will
       be instantiated as a simple subclass, thus avoiding a layer of indirection.

   $self->validation_spec()
       Returns a hash reference suitable for passing to the "Params::Validate" "validate"
       function.  Does not include any arguments that can be passed to contained objects.

   $class->allowed_params(\%args)
       Returns a hash reference of every parameter this class will accept, including parameters
       it will pass on to its own contained objects.  The keys are the parameter names, and the
       values are their corresponding specifications from their "valid_params()" definitions.  If
       a parameter is used by both the current object and one of its contained objects, the
       specification returned will be from the container class, not the contained.

       Because the parameters accepted by "new()" can vary based on the parameters passed to
       "new()", you can pass any parameters to the "allowed_params()" method too, ensuring that
       the hash you get back is accurate.

   $self->container()
       Returns the object that created you.  This is remembered by storing a reference to that
       object, so we use the "Scalar::Utils" "weakref()" function to avoid persistent circular
       references that would cause memory leaks.  If you don't have "Scalar::Utils" installed, we
       don't make these references in the first place, and calling "container()" will result in a
       fatal error.

       If you weren't created by another object via "Class::Container", "container()" returns
       "undef".

       In most cases you shouldn't care what object created you, so use this method sparingly.

   $object->show_containers
   $package->show_containers
       This method returns a string meant to describe the containment relationships among
       classes.  You should not depend on the specific formatting of the string, because I may
       change things in a future release to make it prettier.

       For example, the HTML::Mason code returns the following when you do
       "$interp->show_containers":

        HTML::Mason::Interp=HASH(0x238944)
          resolver -> HTML::Mason::Resolver::File
          compiler -> HTML::Mason::Compiler::ToObject
            lexer -> HTML::Mason::Lexer
          request -> HTML::Mason::Request (delayed)
            buffer -> HTML::Mason::Buffer (delayed)

       Currently, containment is shown by indentation, so the Interp object contains a resolver
       and a compiler, and a delayed request (or several delayed requests).  The compiler
       contains a lexer, and each request contains a delayed buffer (or several delayed buffers).

   $object->dump_parameters
       Returns a hash reference containing a set of parameters that should be sufficient to re-
       create the given object using its class's "new()" method.  This is done by fetching the
       current value for each declared parameter (i.e. looking in $object for hash entries of the
       same name), then recursing through all contained objects and doing the same.

       A few words of caution here.  First, the dumped parameters represent the current state of
       the object, not the state when it was originally created.

       Second, a class's declared parameters may not correspond exactly to its data members, so
       it might not be possible to recover the former from the latter.  If it's possible but
       requires some manual fudging, you can override this method in your class, something like
       so:

        sub dump_parameters {
          my $self = shift;
          my $dump = $self->SUPER::dump_parameters();

          # Perform fudgery
          $dump->{incoming} = $self->{_private};
          delete $dump->{superfluous};
          return $dump;
        }

SEE ALSO

       Params::Validate

AUTHOR

       Originally by Ken Williams <ken@mathforum.org> and Dave Rolsky <autarch@urth.org> for the
       HTML::Mason project.  Important feedback contributed by Jonathan Swartz
       <swartz@pobox.com>.  Extended by Ken Williams for the AI::Categorizer project.

       Currently maintained by Ken Williams.

COPYRIGHT

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