/ 
CatalystX-Imports-0.05
River stage zero No dependents
/ CatalystX::Imports::Context

NAME

CatalystX::Imports::Context - Exports Context Helper Functions

BASE CLASSES

CatalystX::Imports

SYNOPSIS

package MyApp::Controller::Foo;
use base 'Catalyst::Controller';

# Export everything minus the 'captures' function. Also load
# the additional 'Foo' library and a config value
use CatalystX::Imports
    Context => {
        Default => [qw( :all -captures +Foo )],
        Config  => [qw( model_name )],
    };

sub list: Local {
    stash( rs => model(model_name)->search_rs );
}

sub edit: Local {
    stash(
        foo      => model(model_name)->find(args[0]),
        list_uri => uri_for(action('list')),
    );
}

1;

DESCRIPTION

This package represents the base class and export manager for all libraries. The default library can be found under the package name CatalystX::Imports::Context::Default.

The exports will be removed after compiletime. By then, the calls to them in your controller will already be bound to the right code slots by perl. This keeps these functions from being available as methods on your controller object.

IMPORT SYNTAX

You can specify what library parts you want to import into your controller on the use line to CatalystX::Imports:

use CatalystX::Imports Context => [qw(:all -captures +Foo)];

This would import all functions from the default library CatalystX::Imports::Context::Default, except the captures function. See "Tags" in CatalystX::Imports::Context::Default for all available tags in the default library.

Additionally, it will search and load the Foo library, which would be CatalystX::Imports::Context::Foo. This notation doesn't accept any arguments, so the library specific default symbols will be exported.

If you just want some specific functions imported, you can also specify them explicitly:

use CatalystX::Imports
    Context => [qw(action uri_for model config stash)];

At last, to be specific about more than one library, you can pass a hash reference:

use CatalystX::Imports
    Context => { Default => ':all', Config => [qw(model_name)] };

See the libraries documentation for further syntax information.

ALIASES

If documented, you can also import a function with one of it's aliases. If you import a function via a tag, it will only be exported under its real name, not its aliased names. Therefor, to use an aliase you have to specify aliases explicitly at any time to use them:

# load aliases for short forms of 'request' and 'response'
use CatalystX::Imports Context => [qw( req res )];

INCLUDED LIBRARIES

CatalystX::Imports::Context::Default

Contains default shortcuts and inline accessors.

CatalystX::Imports::Context::Config

Allows you to import local controller (instance) configuration accessors as inline functions into your namespace.

METHODS

register_export

This method registers a new export in the library it's called upon. You will mostly only need this function for creating your own libraries:

package CatalystX::Imports::Context::MyOwnLibrary;
use base 'CatalystX::Imports::Context';

__PACKAGE__->register_export(
    name      => 'double',
    alias     => 'times_two',
    prototype => '$',
    tags      => [qw( math )],
    code      => sub {
        my ($library, $ctrl, $ctx, $action_args, @args) = @_;
        return $args[0] * 2;
    },
);

The code and name parameters are mandatory. If you specify an alias, it can be imported explicitly, but will not be included in the :all tag.

The prototype is the usual prototpe you could stuff on perl subroutines. If you specify tags as an array reference, the export will be included in those tag sets by it's name and aliases. It will be included in the :all tag in any case, but only under it's name, not it's aliases.

The specified code reference will get the library class name, the controller and context objects (like a Catalyst action), and an array reference of the arguments passed to the last action and then it's own actual arguments passed in. You could call the above with

double(23); # 46

_export_map

Returns the libraries export map as a hash reference. This will be stored in your library class (if you build your own, otherwise you don't have to care) in the %CATALYSTX_IMPORTS_EXPORT_MAP package variable.

get_export

Expects the name of an export in the library and will return the information it stored with it. An export will be stored under its actual name as well as its aliases.

export_into

Called by CatalystX::Imports' import method. Takes a target and a set of commands specified in "IMPORT SYNTAX". This will forward the commands to the actual libraries and the "context_export_into" method in them.

context_export_into

Takes a target and an actual command set for a library (no +Foo stuff) and cleans that (flattens out tags, removes -substractions). It will utilise "context_install_export_into" to actually export the final set of functions.

context_install_export_into

Takes a target class and the name of an export to install the function in the specified class.

default_exports

Should be overridden by subclasses if they want to export something by default. This will be used if the library is specified without any arguments at all. E.g. this:

use CatalystX::Imports Context => [qw( +Foo )];

will export Foo's defaults, but

use CatalystX::Imports Context => { Foo => [] };

will not. Without an overriding method, the default is set to export nothing at all.

DIAGNOSTICS

register_export expects key/value pairs as arguments

You passed an odd number of values into the register_export method call, but it expects key and value pairs of named options. See L>/register_export> for available options and calling syntax.

register_export: Missing required parameter: 'foo'

The "register_export" method expects a few parameters that can't be omitted, including foo. Pass in the parameter as specified in the section about the "register_export" method.

Unknown Context tag: ':foo'

You specified to import the functions in the tag :foo on your use line, but no tag with the name :foo was registered in the library.

Unknown Context export: 'foo'

You asked for export of the function foo, but no function under this name was registered in the library. Please consult your library documentation for a list of available exports. The default library can be found under CatalystX::Imports::Context::Default.

SEE ALSO

Catalyst, Filter::EOF, CatalystX::Imports::Context::Default, CatalystX::Imports::Context::Config, CatalystX::Imports::Vars, CatalystX::Imports

AUTHOR AND COPYRIGHT

Robert 'phaylon' Sedlacek <rs@474.at>

LICENSE

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