From 365ea7e974e669547ee2c4a1b8f394149349c3ce Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Mon, 21 Feb 2011 16:58:32 -0600 Subject: add docs --- lib/Bread/Board/Declare.pm | 95 +++++++++++++++++++++++++ lib/Bread/Board/Declare/BlockInjection.pm | 4 ++ lib/Bread/Board/Declare/ConstructorInjection.pm | 4 ++ lib/Bread/Board/Declare/Literal.pm | 4 ++ lib/Bread/Board/Declare/Meta/Role/Attribute.pm | 21 ++++++ lib/Bread/Board/Declare/Meta/Role/Class.pm | 5 ++ lib/Bread/Board/Declare/Role/Service.pm | 10 +++ 7 files changed, 143 insertions(+) (limited to 'lib') diff --git a/lib/Bread/Board/Declare.pm b/lib/Bread/Board/Declare.pm index 93f063d..0a94e2a 100644 --- a/lib/Bread/Board/Declare.pm +++ b/lib/Bread/Board/Declare.pm @@ -7,10 +7,105 @@ use Bread::Board (); =head1 SYNOPSIS package MyApp; + use Moose; use Bread::Board::Declare; + has dsn => ( + is => 'ro', + isa => 'Str', + value => 'dbi:mysql:my_db', + ); + + has dbic => ( + is => 'ro', + isa => 'MyApp::Model::DBIC', + dependencies => ['dsn'], + lifecycle => 'Singleton', + ); + + has tt => ( + is => 'ro', + isa => 'MyApp::View::TT', + ); + + has controller => ( + is => 'ro', + isa => 'MyApp::Controller', + dependencies => { + model => 'dbic', + view => 'tt', + }, + ); + + MyApp->new->controller; # new controller object with new model and view + MyApp->new( + model => MyApp::Model::KiokuDB->new, + )->controller; # new controller object with new view and kioku model + =head1 DESCRIPTION +This module is a L extension which allows for declaring L +container classes in a more straightforward and natural way. It sets up +L as the superclass, and creates services associated +with each attribute that you create, according to these rules: + +=over 4 + +=item + +If the C<< service => 0 >> option is passed to C, no service is created. + +=item + +If the C option is passed to C, a L +service is created, with the given value. + +=item + +If the C option is passed to C, a L +service is created, with the given coderef as the block. In addition to +receiving the service object (as happens in Bread::Board), this coderef will +also be passed the container object. + +=item + +If the attribute has a type constraint corresponding to a class, a +L service is created, with the class +corresponding to the type constraint. + +=item + +Otherwise, no service is created. + +=back + +Constructor parameters for services (C, C, etc) can +also be passed into the attribute definition; these will be forwarded to the +service constructor. + +In addition to creating the services, this module also modifies the attribute +reader generation, so that if the attribute has no value, a value will be +resolved from the associated service. It also modifies the C method on +services so that if the associated attribute has a value, that value will be +returned immediately. This allows for overriding service values by passing +replacement values into the constructor, or by calling setter methods. + +Note that C/C doesn't make a lot of sense in this setting, so +they are explicitly disabled. In addition, multiple inheritance would just +cause a lot of problems, so it is also disabled (although single inheritance +and role application works properly). + +NOTE: When using this module in roles with Moose versions prior to 2.0, the +attribute trait will need to be applied explicitly to attributes that should +become services, as in: + + has attr => ( + traits => ['Service'], + is => 'ro', + isa => 'Str', + value => 'value', + ) + =cut my (undef, undef, $init_meta) = Moose::Exporter->build_import_methods( diff --git a/lib/Bread/Board/Declare/BlockInjection.pm b/lib/Bread/Board/Declare/BlockInjection.pm index 4ea4f56..7ff4a9f 100644 --- a/lib/Bread/Board/Declare/BlockInjection.pm +++ b/lib/Bread/Board/Declare/BlockInjection.pm @@ -4,6 +4,10 @@ use Moose; =head1 DESCRIPTION +This is a custom subclass of L which does the +L role. See those two modules for more +details. + =cut extends 'Bread::Board::BlockInjection'; diff --git a/lib/Bread/Board/Declare/ConstructorInjection.pm b/lib/Bread/Board/Declare/ConstructorInjection.pm index 3d2a2c5..32b6f95 100644 --- a/lib/Bread/Board/Declare/ConstructorInjection.pm +++ b/lib/Bread/Board/Declare/ConstructorInjection.pm @@ -4,6 +4,10 @@ use Moose; =head1 DESCRIPTION +This is a custom subclass of L which does +the L role. See those two modules for +more details. + =cut extends 'Bread::Board::ConstructorInjection'; diff --git a/lib/Bread/Board/Declare/Literal.pm b/lib/Bread/Board/Declare/Literal.pm index c2269b1..a8574d2 100644 --- a/lib/Bread/Board/Declare/Literal.pm +++ b/lib/Bread/Board/Declare/Literal.pm @@ -4,6 +4,10 @@ use Moose; =head1 DESCRIPTION +This is a custom subclass of L which does the +L role. See those two modules for more +details. + =cut extends 'Bread::Board::Literal'; diff --git a/lib/Bread/Board/Declare/Meta/Role/Attribute.pm b/lib/Bread/Board/Declare/Meta/Role/Attribute.pm index 82d90db..4ae6a94 100644 --- a/lib/Bread/Board/Declare/Meta/Role/Attribute.pm +++ b/lib/Bread/Board/Declare/Meta/Role/Attribute.pm @@ -12,10 +12,15 @@ use Bread::Board::Declare::Literal; =head1 DESCRIPTION +This role adds functionality to the attribute metaclass for +L objects. + =cut =attr service +Whether or not to create a service for this attribute. Defaults to true. + =cut has service => ( @@ -26,6 +31,8 @@ has service => ( =attr block +The block to use when creating a L service. + =cut has block => ( @@ -36,6 +43,9 @@ has block => ( =attr literal_value +The value to use when creating a L service. Note that +the parameter that should be passed to C is C. + =cut # has_value is already a method @@ -48,6 +58,9 @@ has literal_value => ( =attr lifecycle +The lifecycle to use when creating the service. See L +and L. + =cut has lifecycle => ( @@ -58,6 +71,9 @@ has lifecycle => ( =attr dependencies +The dependency specification to use when creating the service. See +L. + =cut has dependencies => ( @@ -69,6 +85,9 @@ has dependencies => ( =attr constructor_name +The constructor name to use when creating L +services. Defaults to C. + =cut has constructor_name => ( @@ -79,6 +98,8 @@ has constructor_name => ( =attr associated_service +The service object that is associated with this attribute. + =cut has associated_service => ( diff --git a/lib/Bread/Board/Declare/Meta/Role/Class.pm b/lib/Bread/Board/Declare/Meta/Role/Class.pm index 57a9db9..3ece152 100644 --- a/lib/Bread/Board/Declare/Meta/Role/Class.pm +++ b/lib/Bread/Board/Declare/Meta/Role/Class.pm @@ -7,10 +7,15 @@ use List::MoreUtils qw(any); =head1 DESCRIPTION +This role adds functionality to the metaclass of L +classes. + =cut =method get_all_services +Returns all of the services that are associated with attributes in this class. + =cut sub get_all_services { diff --git a/lib/Bread/Board/Declare/Role/Service.pm b/lib/Bread/Board/Declare/Role/Service.pm index a428dfd..e0b36f9 100644 --- a/lib/Bread/Board/Declare/Role/Service.pm +++ b/lib/Bread/Board/Declare/Role/Service.pm @@ -4,10 +4,17 @@ use Moose::Role; =head1 DESCRIPTION +This role modifies L objects for use in +L. It holds a reference to the attribute object that the +service is associated with, and overrides the C method to prefer to return +the value in the attribute, if it exists. + =cut =attr associated_attribute +The attribute metaobject that this service is associated with. + =cut has associated_attribute => ( @@ -32,6 +39,9 @@ around get => sub { =method parent_container +Returns the Bread::Board::Declare container object that this service is +contained in. + =cut sub parent_container { -- cgit v1.2.3-54-g00ecf