NAME

DCI::Meta::Context - Primary Interface, and metadata object for Context classes.

DESCRIPTION

This is the Meta object for building Context objects.

SYNOPSIS

    package Test::Context;
    use strict;
    use warnings;

    use DCI::Meta::Context;

    # roles to fill that have no cast type
    casting qw/middle/;

    # roles to fill with existing casts
    cast first => 'Test::Context::First',
         last  => 'Test::Context::Last';

    # create a cast on the fly
    cast punctuation => {
        delegate => 'text',
        render => sub { shift->text },
    };

    # Optional roles (Not used later in this example)
    maybe_casting qw/tail_a tail_b/;
    maybe_cast tail_c => 'Test::Context::First',
               nothing => {
                   delegate => 'text',
                   render => sub { shift->text },
               };

    #############
    # These are various examples of exporting 'sugar' methods that help people
    # to use your Context.
    #############

    sugar render_named => 'render';
    sugar render_custom_named => sub { shift->render };

    sugar render_ordered => (
        method  => 'render',
        ordered => [qw/first middle last punctuation/],
    );

    sugar render_custom_ordered => (
        ordered => [qw/first middle last punctuation/],
        method => sub { shift->render },
    );

    sugar render_mixed => (
        method  => 'render',
        ordered => [qw/first middle last/]
    );

    # You can define any methods you would like on the context. All roles can
    # be accessed via method which shares the roles name.
    sub render {
        my $self = shift;
        join( ", ",
            $self->first->render,
            $self->middle,
            $self->last->render,
        );
    }

EXPORTS

All exports are optional. This class uses Exporter::Declare for exporting, which means you can use any Exporter::Declare feature such as export renaming.

cast( $ROLE => $CAST_TYPE, ... )

Defines required roles that must be provided when building an instance of the context. A cast package name must be provided for each role, or undef can be used for no type. When the cast is built the role will be wrapped in the cast type automatically.

casting( @ROLES )

Define required roles that do not need to be cast into anything.

maybe_cast( $ROLE => $CAST_TYPE, ... )

Same as cast() except roles are optional at construction.

maybe_casting( @ROLES )

Same as casting() except roles are optional at construction.

sugar( $EXPORT_NAME, $METHOD_NAME )

sugar( $EXPORT_NAME, %CONFIG )

Creates an export that will build an instance of your context and then call the specified method. You can also specify an order of arguments so that users do not need to provide role => actor mappings.

    sugar render_named => 'render';

    # How it is used
    render_named(
        first       => $first,
        middle      => $middle,
        last        => $last,
        punctuation => $punctuation,
    ),

    sugar render_ordered => (
        method  => 'render',
        ordered => [qw/first middle last punctuation/],
    );

    # How it is used
    render_ordered( $first, $middle, $last, $punctuation ),

METHODS

Also see DCI::Meta for more methods.

$context = $class->new( $target )

Create a new instance of DCI::Meta::Context.

$package = $context->target()

Target Context package for this instance.

@role_names = $context->roles()

List of required roles.

@role_names = $context->maybe_roles()

List of optional roles.

%EXPORTS = $context->dci_exports()

Get a map of export_name => sub containing all sugar methods.

$cast_class = $context->get_role_cast( $ROLE_NAME )

Get the cast type for a specific role.

$context->cast( $ROLE_NAME, $CAST_TYPE, ... )

$context->maybe_cast( $ROLE_NAME, $CAST_TYPE, ... )

$context->casting( @CAST_LIST )

$context->maybe_casting( @CAST_LIST )

See the cast(), maybe_cast(), casting(), and maybe_casting exports above.

$context->sugar( $SUGAR_NAME => $METHOD )

$context->sugar( $SUGAR_NAME, %PARAMS )

Add a sugar method to the class (See the sugar() export).

PRIVATE METHODS

Do not use these.

_normalize_core

_add_role_method

_cast

ACHNOWLEDGEMENTS

The DCI concept was created by Trygve Reenskaug, (inventor of MVC) and James Coplien.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2011 Chad Granum

DCI is free software; Standard perl licence.

DCI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.