NAME
    Class::Default - Static calls apply to a default instantiation

SYNOPSIS
      # Create the defaulted class
      package Foo::Base;
      
      use base 'Class::Default';
      
      sub new { bless {}, $_[0] }
      
      sub show {
          my $self = shift->_self;  
          "$self";
      }
      
      # Do something to the default object
      
      package main;
      
      print Foo::Bar->show;
      
      # Prints 'Foo::Bar=HASH(0x80d22f8)'

DESCRIPTION
    Class::Default provides a mechanism to allow your class to take
    static method calls and apply it to a default instantiation of
    an object. It provides a flexibility to an API that allows it to
    be used more confortably in different situations.

    A good example of this technique in use is CGI.pm. When you use
    a static method, like `CGI-'header>, your call is being applied
    to a default instantiation of a CGI object.

    This technique appears to be especially usefull when writing
    modules that you want to be used in either a single use or a
    persistant environment. In a CGI like environment, you want the
    simplicity of a static interface. You can call `Class-'method>
    directly, without having to pass an instantiation around
    constantly.

USING THE MODULES
    Class::Default provides a couple of levels of control. They
    start with simple enabling the method to apply to the default
    instantation, and move on to providing some level of control
    over the creation of the default object.

  Inheriting from Class::Default

    To start, you will need to inherit from Class::Default. You do
    this in the normal manner, using something like `use base
    'Class::Default'', or setting the @ISA value directly.
    `Class::Default' does not have a default constructor or any
    public methods, so you should be able to use it a multiple
    inheritance situation without any implications.

  Making method work

    To make your class work with Class::Default you need to make a
    small adjustment to each method that you would like to be able
    to access the default object.

    A typical method will look something like the following

      sub foobar {
          my $self = shift;
          
          # Do whatever the method does
      }

    To make the method work with Class::Default, you should change
    it to the following

      sub foobar {
          my $self = shift->_self;
          
          # Do whatever the method does
      }

    This change is very low impact, easy to use, and will not make
    any other differences to the way your code works.

  Control over the default object

    When needed, Class::Default will make a new instantation of your
    class and cache it to be used whenever a static call is made. It
    does this in the simplest way possible, by calling `Class-
    'new()> with no arguments.

    This is fine if you have a very pure class that can handle
    creating a new object without any arguments, but many classes
    expect some sort of argument to the the constructor, and indeed
    that the constructor that should be used it the `new' method.

    Enter the `_create_default_object' method. By overloading the
    `_create_default_object' method in your class, you can custom
    create the default object. This will used to create the default
    object on demand, the first time a method is called. For
    example, the following class demonstrate the use of
    `_create_default_object' to set some values in the default
    object.

      package Slashdot::User;
      
      use base 'Class::Default';
      
      # Constructor
      sub new {
            my $class = shift;
            my $name = shift;
            
            my $self = {
                    name => $name,
                    favourite_color => '',
            };
            
            return bless $self, $class;
      }
      
      # Default constructor
      sub _create_default_object {
            my $class = shift;
            
            my $self = $class->new( 'Anonymous Coward' );
            $self->{favourite_color} = 'Orange';
            
            return $self;
      }
      
      sub name { $_[0]->{name} }
      sub favourite_color { $_[0]->{favourite_color} }

    That provides a statically accessible default object that could
    be used as in the following manner.

      print "The default slashdot user is " . Slashdot::User->name
          . " and they like the colour " . Slashdot::User->favourite_color;

    Remember that the default object is persistant, so changes made
    to the statically accessible object can be recovered later.

  Getting access to the default object

    There are a few ways to do this, but the easiest way is to
    simple do the following

      my $default = Slashdot::User->_get_default();

METHODS
  _self()

    Used by methods to make the method apply to the default object
    if called statically without affecting normal object methods.

  _class()

    The `_class' method provides the opposite of the `_self' method.
    Instead of always getting an object, `_class' will always get
    the class name, so a method can be guarenteed to run in a static
    context. This is not essential to the use of a `Class::Default'
    module, but is provided as a convenience.

  _get_default()

    Used to get the default object directly.

  _create_default_object()

    To be overloaded by your class to set any properties to the
    default object at creation time.

BUGS
    No known bugs, but suggestions are welcome

SUPPORT
    Contact the author

AUTHOR
            Adam Kennedy
            cpan@ali.as
            http://ali.as/

SEE ALSO
    Class::*

COPYRIGHT
    Copyright (c) 2002 Adam Kennedy. All rights reserved. This
    program is free software; you can redistribute it and/or modify
    it under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file
    included with this module.

