view release on metacpan or  search on metacpan

lib/App.pm  view on Meta::CPAN

                &printdepth($depth-1, 0, %{$_[$narg]});
            }
            print "}";
        }
        else {
            print $_[$narg];
        }
    }
}

#############################################################################
# CONSTRUCTOR METHODS
#############################################################################

=head1 Constructor Methods:

=cut

#############################################################################
# new()
#############################################################################

=head2 new()

The App->new() method is not a constructor for
an App class.  Rather, it is a Factory-style constructor, returning
an object of the class given as the first parameter.

If no parameters are given,
it is simply a synonym for "App->context()".

    * Signature: $context = App->new()
    * Signature: $object = App->new($class)
    * Signature: $object = App->new($class,$method)
    * Signature: $object = App->new($class,$method,@args)
    * Param:  $class       class  [in]
    * Param:  $method      string [in]
    * Return: $context     App::Context
    * Return: $object      ref
    * Throws: Exception::Class::Base
    * Since:  0.01

    Sample Usage: 

    $context = App->new();
    $dbh = App->new("DBI", "new", "dbi:mysql:db", "dbuser", "xyzzy");
    $cgi = App->new("CGI", "new");

=cut

sub new {
    &App::sub_entry if ($App::trace);
    my $self = shift;
    if ($#_ == -1) {
        my $context = $self->context();
        &App::sub_exit($context) if ($App::trace);
        return($context);
    }
    my $class = shift;
    if ($class =~ /^([A-Za-z0-9:_]+)$/) {
        $class = $1;  # untaint the $class
        if (! $used{$class}) {
            $self->use($class);
        }
        my $method = ($#_ > -1) ? shift : "new";
        if (wantarray) {
            my @values = $class->$method(@_);
            &App::sub_exit(@values) if ($App::trace);
            return(@values);
        }
        else {
            my $value = $class->$method(@_);
            &App::sub_exit($value) if ($App::trace);
            return($value);
        }
    }
    print STDERR "Illegal Class Name: [$class]\n";
    &App::sub_exit(undef) if ($App::trace);
    return undef;
}

#############################################################################
# context()
#############################################################################

=head2 context()

    * Signature: $context = App->context();      # most common, used in "app"
    * Signature: $context = App->context(%named);                 # also used
    * Signature: $context = App->context($named, %named);         # variation
    * Signature: $context = App->context($name, %named);               # rare
    * Signature: $context = App->context($named, $name, %named);       # rare
    * Param:     context_class   class  [in]
    * Param:     config_file     string [in]
    * Param:     prefix          string [in]
    * Return:    $context        App::Context
    * Throws:    App::Exception::Context
    * Since:     0.01

    Sample Usage: 

    $context = App->context();
    $context = App->context(
        context_class => "App::Context::HTTP",
        config_file => "app.xml",
    );

This static (class) method returns the $context object
of the context in which you are running.
It tries to use some intelligence in determining which
context is the right one to instantiate, although you
can override it explicitly.

It implements a "Factory" design pattern.  Instead of using the
constructor of a class itself to get an instance of that
class, the context() method of App is used.  The former
technique would require us to know at development time
which class was to be instantiated.  Using the factory
style constructor, the developer need not ever know what physical class
is implementing the "Context" interface.  Rather, it is
configured at deployment-time, and the proper physical class