NAME
    Class::Container - Glues object frameworks together transparently

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.