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
       # 'frog' or 'vegetables' objects
       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, Component, Buffer, and several
    other objects must create each other transparently, passing the appropriate
    parameters to the right class, possibly substituting their own subclass for
    any of these objects.

    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 and transparently

  Scenario

    Suppose you've got a class called "Parent", which creates object of the
    class "Child", which in turn creates objects of the class "GrandChild". Each
    class 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 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 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.

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

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

