Prancer(3)

NAME
Prancer - Another PSGI Framework

SYNOPSIS
Prancer is yet another PSGI framework. This one is designed to be a bit smaller and more out of the way than others but it could probably be described best as project derived from NIH syndrome <https://en.wikipedia.org/wiki/Not_Invented_Here>.

Here's how it might be used:

    ==> myapp.psgi

    use Prancer;
    my $app = Prancer->new("/path/to/confdir", "MyApp");
    $app->run();

    ==> MyApp.pm

    package MyApp;

    use Prancer::Application qw(:all);
    use parent qw(Prancer::Application);

    sub handle {
        my $self = shift;

        mount('GET', '/', sub {
            context->header(set => 'Content-Type', value => 'text/plain');
            context->body("hello world");
            context->finalize(200);
        });

        return dispatch;
    }

Full documentation can be found in Prancer::Manual.

INSTALLATION
To install this module, run the following commands:

    perl Makefile.PL
    make
    make test
    make install

If this ever makes it to CPAN you can install it with this simple command:

    perl -MCPAN -e 'install Prancer'

These optional libraries will enhance the functionality of Prancer:

Template
    Without this the Prancer template interface will not work.

DBI Without this the Prancer database interface will not work. You also will need a database driver like DBD::Pg.

Plack::Middleware::Session
    Without this the Prancer session support will not work. If you want to use the YAML session storage you will also need to have YAML (preferably YAML::XS) installed. If you want support to write sessions do the database you will also need DBI installed along with a database driver like DBD::Pg.

EXPORTABLE
The following methods are exportable: "config", "logger", "database", "template". They can all be exported at once using ":all".

METHODS
With the exception of "->new" and "->run", all methods should be called in a static context. Additionally, with the same exception, all methods are exportable individually or with "qw(:all)".

->new CONFIG PACKAGE ARGS
    This will create your application. It takes two arguments:

    CONFIG
        This a path to a directory containing configuration files. How configuration files are loaded is detailed below.

    PACKAGE
        This is the name of a package that implements your application. The package named should extend Prancer::Application though this is not enforced.

    ARGS
        After the name of the package, any number of arguments may be added. Any extra arguments are passed directly to the "new" method on the named package when it is created for a request.

->run
    This starts your application. It takes no arguments.

logger
    This gives access to the logger. For example:

        logger->info("Hello");
        logger->fatal("uh oh");
        logger->debug("here we are");

config
    This gives access to the configuration. For example:

        config->has('foo');
        config->get('foo');
        config->set('foo', value => 'bar');
        config->remove('foo');

    Any changes to the configuration do not persist back to the actual configuration file. Additionally they do not persist between threads or processes.

    Whenever this method is used to get a configuration option and that option is reference, the reference will be cloned by Storable to prevent changes to one copy from affecting other uses. But this could have performance implications if you are routinely getting large data structures out if your configuration files.

template
    This gives access to the configured template engine. For example:

        print template("foo.tt", {
            'title' => 'foobar',
            'var1' => 'val2',
        });

    If no template engines are configured then this method will always return "undef".

database
    This gives access to the configured databases. For example:

        # handle to the database configured as 'default'
        my $dbh = database;

        # handle to the database configured as 'foo'
        my $dbh = database('foo');

        # prepare a statement on connection 'default'
        my $sth = database->prepare("SELECT * FROM foo");

    In all cases, $dbh will be a reference to a DBI handle and anything that can be done with DBI can be done here.

    If no databases are configured then this method will always return "undef".

session
    Configures the session handler. For example:

        session:
            state:
                driver: Prancer::Session::State::Cookie
                options:
                    key: PSESSION
            store:
                driver: Prancer::Session::Store::YAML
                options:
                    path: /tmp/prancer/sessions

    See Prancer::Session::State::Cookie, Prancer::Session::Store::Memory, Prancer::Session::Store::YAML and Prancer::Session::Store::Database for more options.

CONFIGURATION
One doesn't need to create any configuration to use Prancer but then Prancer wouldn't be very useful. Prancer uses Config::Any to process configuration files so anything supported by that will be supported by this. It will load configuration files from given path set when your application initialized. First it will look for a file named "config.ext" where "ext" is something like "yml" or "ini". Then it will look for a file named after the current environment like "develoment.ext" or "production.ext". The environment is derived by looking first for an environment variable called "ENVIRONMENT", then for an environment variable called "PLACK_ENV". If neither of those exist then the default is "development". Configuration files will be merged such that the environment configuration file will take precedence over the global configuration file.

Arbitrary configuration directives can be put into your configuration files and they can be accessed like this:

    config(get => 'foo');

The configuration accessors will only give you configuration directives found at the root of the configuration file. So if you use any data structures you will have to decode them yourself. For example, if you create a YAML file like this:

    foo:
        bar1: asdf
        bar2: fdsa

Then you will only be able to get the value to "bar1" like this:

    my $foo = config(get => 'foo')->{'bar1'};

  Reserved Configuration Options
To support the components of Prancer, these keys are used:

logger
    Configures the logging system. For example:

        logger:
            driver: Prancer::Logger::WhateverLogger
            options:
                level: debug

    For the console logger, see Prancer::Logger::Console for more options.

template
    Configures the templating system. For example:

        template:
            driver: Prancer::Template::WhateverEngine
            options:
                template_dir: /srv/www/site/templates
                encoding: utf8
                start_tag: "<%"
                end_tag: "%>"

    For the Template Toolkit plugin, see Prancer::Template::TemplateToolkit for more options.

database
    Configures database connections. For example:

        database:
            default:
                driver: Prancer::Database::Driver::WhateverDriver
                options:
                    username: test
                    password: test
                    database: test

    See Prancer::Database for more options.

static
    Configures a directory where static documents can be found and served using Plack::Middleware::Static. For example:

        static:
            path: /srv/www/site/static

    The only configuration option for static documents is "path". If this path is not defined your application will not start. If this path does not point to a directory that is readable your application will not start.

CREDITS
Large portions of this library were taken from the following locations and projects:

•   HTTP status code documentation taken from Wikipedia <http://www.wikipedia.org>.

•   Prancer::Config is derived directly from Dancer2::Core::Role::Config. Thank you to the Dancer2 <https://github.com/PerlDancer/Dancer2> team.

•   Prancer::Request, Prancer::Request::Upload and Prancer::Response are but thin wrappers to and reimplementations of Plack::Request, Plack::Request::Upload and Prancer::Response. Thank you to Tatsuhiko Miyagawa.

•   Prancer::Database is derived directly from Dancer::Plugin::Database. Thank you to David Precious.

COPYRIGHT
Copyright 2013, 2014 Paul Lockaby. All rights reserved.

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