/ 
DCI-0.013
/ DCI::Meta::Cast

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.