NAME

DCI::Meta::Cast - Metadata object for Cast classes.

DESCRIPTION

The meta object used to build a cast object.

SYNOPSIS

PRIMARY USAGE

    package Example::Cast::A;
    use strict;
    use warnings;

    # Automatically sets DCI::Cast as a base class.
    use DCI::Meta::Cast;

    # Creates methods that pass through to the core object.
    delegate qw/foo bar/;

    # Restrict what type of objects can be used to build the cast.
    require_core qw/ Test::CoreA Test::CoreB Test::CoreC/;

    # Generate some accessors for tracking state in the Cast without modifying
    # the core object.
    accessors qw/cast_state_a cast_state_b/;

    sub call_delegate_methods {
        my $self = shift;
        $self->foo();
        $self->bar();
        return 1;
    }

    sub unique_numeric_id {
        my $self = shift;
        my $state = $self->dci_state;
        return $state->{something}++
    }

    1;

AUTO-DELEGATE

This example uses -auto_delegate to automatically delegate any methods not defined by the Cast to the core class.

    package Example::Cast::N;
    use strict;
    use warnings;

    # Automatically sets DCI::Cast as a base class.
    use DCI::Meta::Cast '-auto_delegate';

    sub call_delegate_methods {
        my $self = shift;
        $self->foo();
        $self->bar();
        return 1;
    }

USE BY PROXY

This is essentially what DCI.pm does.

    require DCI::Meta::Cast;

    # Create the meta object and inject 'dci_meta()' into the taget class.
    my $meta = DCI::Meta::Cast->new( $target_class );

    # Export the sugar methods into the target class.
    DCI::Meta::Cast->export_to( $target_class );

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.

EXPORT GROUPS

'-auto_delegate'

Brings in AUTOLOAD(), can(), and all default exports.

'-default'

Used when no arguments are provided. Brings in all exported fuctions except AUTOLOAD() and can().

EXPORTED FUNCTIONS

delegate( @METHODS )

Sets up delegation methods for the specified list of methods.

This is sugar, essentially:

    sub { caller()->dci_meta->delegate( @_ ) }

require_core( @CLASSES )

Restricts the cast so that it can only be built using core objects of the specified type(s).

This is sugar, essentially:

    sub { caller()->dci_meta->require_core( @_ ) }

accessors( @ACCESSORS )

Create accessors that store state in a state object bound to the cast object.

This is sugar, essentially:

    sub { caller()->dci_meta->accessors( @_ ) }

AUTOLOAD()

Not exported by default.

Auto-delegates all methods (requires can()).

can()

Not exported by default.

Does the heavy lifting of auto-delegation.

METHODS

Also see the methods for DCI::Meta

$instance = $class->new( $TARGET_PACKAGE )

Create a new instance for the target package. Will turn the target into a subclass of DCI::Cast.

$package = $class->anonymous( %PARAMS )

Create a new Cast type without writing your own package (it is auto-generated).

    my $cast_package = DCI::Meta::Cast->anonymous(
        delegate => \@METHODS,
        require_core => \@PACKAGES,
        accessors => \@ACCESSORS,
        custom_method => sub { ... },
        ...
    );

    $cast_package->dci_new( $some_core );

$package = $self->target()

Return the target package name.

$self->allowed_cores()

Return a list of allowed cores.

$self->require_core( @CORES )

Add one or more allowed core types.

$self->delegate( @METHODS )

Create delegate methods.

$self->accessors( @ACCESSORS )

Create accessors.

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.