NAME
    Class::Container - Glues object frameworks together transparently

SYNOPSIS
     package Candy;
 
     use Class::Container;
     use base qw(Class::Container);
 
     __PACKAGE__->valid_params
       (
        color  => {default => 'green'},
        flavor => {default => 'hog'},
       );
 
     __PACKAGE__->contained_objects
       (
        frog       =>  'Food::TreeFrog',
        vegetables => { class => 'Food::Ingredient',
                        delayed => 1 },
       );
 
     sub new {
       my $package = shift;
   
       # Build $self, possibly passing elements of @_ to 'ingredient' object
       my $self = $package->SUPER::new(@_);

       ... 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, Buffer, and several other
    objects must create each other transparently, passing the appropriate
    parameters to the right class.

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

    * Declaration of parameters used 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
    * Automatic checking of duplicate class parameter names
    The most important methods provided are "valid_params()" and
    "contained_objects()", both of which are class methods. There is not a
    "new()" method, that is expected to be defined in a derived class.

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.

    A the moment, the only possible constructor method is "new()". If you need
    to create other constructor methods, they should also call "SUPER::new()",
    or possibly even your class's "new()" method.

  __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 also implement a bit of magic here, so that if
    "HTML::Mason::Compiler->new()" is called with a "lexer_class" parameter, it
    will load the class, instantiate a new object of that given class, and use
    that for the "lexer" object. In fact, we're 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 enclosing 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.

  __PACKAGE__->valid_params()

    The "valid_params()" method is similar to the "contained_objects()" method
    in that it is a class method that declares properties of the current class.
    It is called in order to register a set of parameters which are valid for a
    class's "new()" constructor method. It 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, HTML::Mason::Compiler contains the following:

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

    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()

    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.

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

  $self->allowed_params()

    Returns a hash reference of every parameter this class will accept,
    including parameters it will pass on to its own contained objects.

  $self->container()

    Returns the object that created you. This is remembered by storing a
    reference to that object, so we will use the "Scalar::Utils" "weakref()"
    function to avoid persistent circular references that would cause memory
    leaks. If you don't have "Scalar::Utils" installed, you'll need to break
    these references yourself - future versions of this module will probably
    require "Scalar::Utils".

SEE ALSO
    the Params::Validate manpage, the HTML::Mason manpage

AUTHOR
    Ken Williams <ken@mathforum.org>, based extremely heavily on collaborative
    work with Dave Rolsky <autarch@urth.org> and Jonathan Swartz
    <swartz@pobox.com> on the HTML::Mason project.

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

