.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bread::Board::Manual::Concepts::Typemap 3pm"
.TH Bread::Board::Manual::Concepts::Typemap 3pm "2022-12-12" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bread::Board::Manual::Concepts::Typemap \- An overview of the typemapping feature
.SH "VERSION"
.IX Header "VERSION"
version 0.37
.SH "INTRODUCTION"
.IX Header "INTRODUCTION"
A new (read: experimental) feature of Bread::Board is typemapped services.
These are services which are mapped to a particular type rather then just
a name. This feature has the potential to make obsolete a large amount of the
Bread::Board configuration by simply asking Bread::Board to figure things
out on its own. Here is a small example of how this works.
.PP
.Vb 3
\&  # define the classes making sure
\&  # to specify required items and
\&  # their types
\&
\&  {
\&      package Stapler;
\&      use Moose;
\&
\&      package Desk;
\&      use Moose;
\&
\&      package Chair;
\&      use Moose;
\&
\&      package Cubicle;
\&      use Moose;
\&
\&      has \*(Aqdesk\*(Aq  => ( is => \*(Aqro\*(Aq, isa => \*(AqDesk\*(Aq,  required => 1 );
\&      has \*(Aqchair\*(Aq => ( is => \*(Aqro\*(Aq, isa => \*(AqChair\*(Aq, required => 1 );
\&
\&      package Employee;
\&      use Moose;
\&
\&      has [ \*(Aqfirst_name\*(Aq, \*(Aqlast_name\*(Aq ] => (
\&          is       => \*(Aqro\*(Aq,
\&          isa      => \*(AqStr\*(Aq,
\&          required => 1,
\&      );
\&
\&      has \*(Aqstapler\*(Aq => ( is => \*(Aqrw\*(Aq, isa => \*(AqStapler\*(Aq, predicate => \*(Aqhas_stapler\*(Aq );
\&
\&      has \*(Aqwork_area\*(Aq => ( is => \*(Aqro\*(Aq, isa => \*(AqCubicle\*(Aq, required => 1 );
\&  }
\&
\&  # now create the container, and
\&  # map the Employee type and ask
\&  # Bread::Board to infer all the
\&  # other relationships
\&
\&  my $c = container \*(AqInitech\*(Aq => as {
\&      typemap \*(AqEmployee\*(Aq => infer;
\&  };
\&
\&  # now you can create new Employee objects
\&  # by calling \->resolve with the type and
\&  # supplying the required parameters (see
\&  # below for details).
\&
\&  my $micheal = $c\->resolve(
\&      type       => \*(AqEmployee\*(Aq,
\&      parameters => {
\&          first_name => \*(AqMicheal\*(Aq,
\&          last_name  => \*(AqBolton\*(Aq
\&      }
\&  );
\&
\&  my $cube = $micheal\->work_area; # this will be a Cubicle object
\&  $cube\->desk;  # this will be a Desk object
\&  $cube\->chair; # this will be a Chair object
\&
\&  $micheal\->has_stapler; # this is false
\&
\&  # We can create another Employee object
\&  # and this time we pass in the optional
\&  # parameter for the non\-required \*(Aqstapler\*(Aq
\&  # attribute
\&
\&  my $milton = $c\->resolve(
\&      type       => \*(AqEmployee\*(Aq,
\&      parameters => {
\&          first_name => \*(AqMilton\*(Aq,
\&          last_name  => \*(AqWaddams\*(Aq,
\&          stapler    => Stapler\->new
\&      }
\&  );
\&
\&  $milton\->has_stapler; # this is true
.Ve
.PP
In the above example, we created a number of Moose classes that had
specific required relationships. When we called \f(CW\*(C`infer\*(C'\fR for the
\&\fBEmployee\fR object, Bread::Board figured out those relationships
and set up dependencies and parameters accordingly.
.PP
For the \f(CW\*(C`work_area\*(C'\fR object, we saw the \fBCubicle\fR type and then
basically called \f(CW\*(C`infer\*(C'\fR on the \fBCubicle\fR object. We then saw
the \fBDesk\fR and \fBChair\fR objects and called \f(CW\*(C`infer\*(C'\fR on those as well.
The result of this recursive inference was that the \fBEmployee\fR,
\&\fBCubicle\fR, \fBDesk\fR and \fBChair\fR relationships were modeled in
Bread::Board as dependent services.
.PP
Bread::Board also took it one step further.
.PP
We were able to resolve the \fBCubicle\fR, \fBDesk\fR and \fBChair\fR types
automatically because they were already defined by Moose as subtypes
of the \fIObject\fR type. We knew that it could introspect those classes
and get more information. However, this was not the case with the
\&\fIfirst_name\fR and \fIlast_name\fR attributes of the \fBEmployee\fR object.
In that case, we determined that we couldn't resolve those objects and
(because it was a top-level inference) instead turned them into required
parameters for the inferred \fBEmployee\fR service.
.PP
And lastly, with a top-level inference (not one caused by recursion)
Bread::Board will also look at all the remaining non-required attributes
and turn them into optional parameters. In this case we have a \f(CW\*(C`stapler\*(C'\fR
attribute that is not required and so is listed as an optional parameter,
meaning that it is not required, but still subject to type checking.
.SH "CONCLUSION"
.IX Header "CONCLUSION"
This example should give a good basic overview of this feature and more
details can be found in the test suite (\fIt/07*.t\fR). These show examples
of how to typemap roles to concrete classes and how to supply hints to
\&\f(CW\*(C`infer\*(C'\fR to help Bread::Board figure out specific details.
.PP
As I mentioned above, this feature should be considered experimental
and we are still working out details and writing tests for it. Any
contributions are welcome.
.SH "AUTHOR"
.IX Header "AUTHOR"
Stevan Little <stevan@iinteractive.com>
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests on the bugtracker website
https://github.com/stevan/BreadBoard/issues
.PP
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2019, 2017, 2016, 2015, 2014, 2013, 2011, 2009 by Infinity Interactive.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.