.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::Default 3pm"
.TH Class::Default 3pm "2016-08-18" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::Default \- Static calls apply to a default instantiation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # Create the defaulted class
\&  package Foo::Base;
\&  
\&  use base \*(AqClass::Default\*(Aq;
\&  
\&  sub new { bless {}, $_[0] }
\&  
\&  sub show {
\&      my $self = shift\->_self;  
\&      "$self";
\&  }
\&  
\&  # Do something to the default object
\&  
\&  package main;
\&  
\&  print Foo::Bar\->show;
\&  
\&  # Prints \*(AqFoo::Bar=HASH(0x80d22f8)\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1API\s0 that allows it to be used more confortably in
different situations.
.PP
A good example of this technique in use is \s-1CGI\s0.pm. When you use a static
method, like \f(CW\*(C`CGI\-\*(C'\fRheader>, your call is being applied to a default
instantiation of a \s-1CGI\s0 object.
.PP
This technique appears to be especially useful when writing modules that you
want to be used in either a single use or a persistent environment. In a \s-1CGI\s0
like environment, you want the simplicity of a static interface. You can
call \f(CW\*(C`Class\-\*(C'\fRmethod> directly, without having to pass an instantiation 
around constantly.
.SH "USING THE MODULES"
.IX Header "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.
.SS "Inheriting from Class::Default"
.IX Subsection "Inheriting from Class::Default"
To start, you will need to inherit from Class::Default. You do this in the
normal manner, using something like \f(CW\*(C`use base \*(AqClass::Default\*(Aq\*(C'\fR, or setting
the \f(CW@ISA\fR value directly. \f(CW\*(C`Class::Default\*(C'\fR 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.
.SS "Making method work"
.IX Subsection "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.
.PP
A typical method will look something like the following
.PP
.Vb 2
\&  sub foobar {
\&      my $self = shift;
\&      
\&      # Do whatever the method does
\&  }
.Ve
.PP
To make the method work with Class::Default, you should change it to 
the following
.PP
.Vb 2
\&  sub foobar {
\&      my $self = shift\->_self;
\&      
\&      # Do whatever the method does
\&  }
.Ve
.PP
This change is very low impact, easy to use, and will not make any other
differences to the way your code works.
.SS "Control over the default object"
.IX Subsection "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 \f(CW\*(C`Class\-\*(C'\fR\fInew()\fR> with no arguments.
.PP
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 \f(CW\*(C`new\*(C'\fR method.
.PP
Enter the \f(CW\*(C`_create_default_object\*(C'\fR method. By overloading the 
\&\f(CW\*(C`_create_default_object\*(C'\fR 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 \f(CW\*(C`_create_default_object\*(C'\fR to set some values in the default 
object.
.PP
.Vb 1
\&  package Slashdot::User;
\&  
\&  use base \*(AqClass::Default\*(Aq;
\&  
\&  # Constructor
\&  sub new {
\&        my $class = shift;
\&        my $name = shift;
\&        
\&        my $self = {
\&                name => $name,
\&                favourite_color => \*(Aq\*(Aq,
\&        };
\&        
\&        return bless $self, $class;
\&  }
\&  
\&  # Default constructor
\&  sub _create_default_object {
\&        my $class = shift;
\&        
\&        my $self = $class\->new( \*(AqAnonymous Coward\*(Aq );
\&        $self\->{favourite_color} = \*(AqOrange\*(Aq;
\&        
\&        return $self;
\&  }
\&  
\&  sub name {
\&        $_[0]\->_self\->{name};
\&  }
\&  
\&  sub favourite_color {
\&        $_[0]\->_self\->{favourite_color};
\&  }
.Ve
.PP
That provides a statically accessible default object that could be used as in
the following manner.
.PP
.Vb 2
\&  print "The default slashdot user is " . Slashdot::User\->name
\&      . " and they like the colour " . Slashdot::User\->favourite_color;
.Ve
.PP
Remember that the default object is persistent, so changes made to the
statically accessible object can be recovered later.
.SS "Getting access to the default object"
.IX Subsection "Getting access to the default object"
There are a few ways to do this, but the easiest way is to simple do
the following
.PP
.Vb 1
\&  my $default = Slashdot::User\->_get_default;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "_self"
.IX Subsection "_self"
Used by methods to make the method apply to the default object if called
statically without affecting normal object methods.
.SS "_class"
.IX Subsection "_class"
The \f(CW\*(C`_class\*(C'\fR method provides the opposite of the \f(CW\*(C`_self\*(C'\fR method. Instead
of always getting an object, \f(CW\*(C`_class\*(C'\fR will always get the class name, so
a method can be guaranteed to run in a static context. This is not
essential to the use of a \f(CW\*(C`Class::Default\*(C'\fR module, but is provided as a
convenience.
.SS "_get_default"
.IX Subsection "_get_default"
Used to get the default object directly.
.SS "_create_default_object"
.IX Subsection "_create_default_object"
To be overloaded by your class to set any properties to the default
object at creation time.
.SH "BUGS"
.IX Header "BUGS"
No known bugs, but suggestions are welcome
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs should be reported via the \s-1CPAN\s0 bug tracker at
.PP
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class\-Default>
.PP
For other issues, contact the author
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
<http://ali.as/>, Class::Singleton
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2002 \- 2006 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.