[libbread-board-perl] 04/66: Beginning to add per-method docs to Bread::Board

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to branch master
in repository libbread-board-perl.

commit 1fa88c6380544f42c1453ac0f9519034fb400720
Author: Sterling Hanenkamp <hanenkamp at cpan.org>
Date:   Thu Jul 19 22:48:27 2012 -0500

    Beginning to add per-method docs to Bread::Board
---
 lib/Bread/Board.pm |  108 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)

diff --git a/lib/Bread/Board.pm b/lib/Bread/Board.pm
index f0bf221..204c600 100644
--- a/lib/Bread/Board.pm
+++ b/lib/Bread/Board.pm
@@ -317,24 +317,132 @@ Want to know more? See the L<Bread::Board::Manual>.
   | o o | 28 o-o-o-o-o ^ o-o-o-o-o 28 | o o |
   +-----------------------------------------+
 
+Loading this package will automatically load the rest of the packages needed by
+any Bread::Board configuration.
+  
 =head1 EXPORTED FUNCTIONS
 
+The functions of this package provide syntactic sugar to help you build your
+Bread::Board configuration. You can build such a configuration by constructing
+each of the classes directly instead, but your code may be more difficult to
+understand.
+
 =over 4
 
 =item I<container ($name, &body)>
 
+This function provides a shortcut for defining your containers. This function
+constructs and returns an instance of L<Bread::Board::Container>. The C<&body>
+block may be used to add services or sub-containers within the newly constructed
+container. The block is optional. Usually, the block is not passed direclty, but
+passed using the C<as> function.
+
+For example,
+
+  container 'MyWebApp' => as {
+      service my_dispatcher => (
+          class => 'MyWebApp::Dispatcher',
+      );
+  };
+
 =item I<container ($container_instance, &body)>
 
+In many cases, subclassing L<Bread::Board::Container> is the easiest route to
+getting access to this framework. You can do this and still get all the
+benefites of the syntactic sugar for configuring that class by passing an
+instance of your contianer subclass to C<container>.
+
+You could, for example, configure your container inside the C<BUILD> method of your class.
+
+  package MyWebApp;
+  use Moose;
+
+  extends 'Bread::Board::Container';
+
+  sub BUILD {
+      my $self = shift;
+
+      container $self => as {
+          service dbh => ( ... );
+      };
+  }
+
 =item I<container ($name, [ @parameters ], &body)>
 
+A third way of using the C<container> method is to build a parameterized
+container. These are useful as a way of providing a placeholder for parts of
+the configuration that may be provided later. You may not use an instance
+object in place of the C<$name> in this case.
+
+For more detail on how you might use parameterized containers, see
+L<Bread::Board::Manual::Concepts::Advanced/Parameterized Containers>.
+
 =item I<as (&body)>
 
+This is just a replacement for the C<sub> keyword that is easier to read when
+defining containers.
+
 =item I<service ($name, $literal | %service_description)>
 
+Within the C<as> blocks for your containers, you may construct services using
+the C<service> function. This will construct any kind of service based upon
+how it is defined.
+
+To build a literal service using L<Bread::Board::Literal>, just specify a
+scalar value or reference you want to use as the literal value:
+
+  # In case you need to adjust the gravitational constant of the Universe
+  service gravitational_constant => 6.673E-11;
+
+To build a service using one of the injection services, just fill in all the
+details required to use that sort of injection:
+
+  service search_service => (
+      class => 'MyApp::Search',
+      block => sub {
+          my $s = shift;
+          MyApp::Search->new($s->param('url'), $s->param('type'));
+      },
+      dependencies => {
+          url => 'http://example.com/search',
+      },
+      parameters => {
+          type => { isa => 'Str', default => 'text' },
+      },
+  );
+
+The type of injection performed depends on the parameters used. You may use
+the C<service_class> parameter to pick a specific injector class. For
+instance, this is useful if you need to use L<Bread::Board::SetterInjection>
+or have defined a custom injection service.  If you specify a C<block>, block
+injection will be performed using L<Bread::Board::BlockInjection>. If neither
+of these is present, constructor injection will be used with
+L<Bread::Board::ConstructorInjection>.
+      
 =item I<depends_on ($service_path)>
 
+The C<depends_on> function creates a L<Bread::Board::Dependency> object for the named C<$service_path> and returns it.
+
 =item I<wire_names (@service_names)>
 
+This function is just a shortcut for passing a hash reference of dependencies into the service.
+
+  service foo => (
+      class => "Pity::TheFoo',
+      dependencies => wire_names(qw( foo bar baz )),
+  );
+
+The above is identical to:
+
+  service foo => (
+      class => 'Pity::TheFoo',
+      dependencies => {
+          foo => depends_on('foo'),
+          bar => depends_on('bar'),
+          baz => depends_on('baz'),
+      },
+  );
+
 =item I<typemap ($type, $service | $service_path)>
 
 =item I<infer (?%hints)>

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libbread-board-perl.git