.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 "Kavorka::Manual::ExtendingKavorka 3pm"
.TH Kavorka::Manual::ExtendingKavorka 3pm "2019-01-17" "perl v5.28.1" "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"
Kavorka::Manual::ExtendingKavorka \- extending Kavorka with traits and new keywords
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Traits"
.IX Subsection "Traits"
Many of the code constructs handled by Kavorka allow a list of traits
to be given. Subs can have traits:
.PP
.Vb 1
\&   method xyz ($x, $y, $z) is friendly { ... }
.Ve
.PP
So can parameters within signatures:
.PP
.Vb 1
\&   method xyz ($x is hot, $y does warm, $z but cool) { ... }
.Ve
.PP
And return types:
.PP
.Vb 1
\&   method get_age (Date $date → Num $age is years) { ... }
.Ve
.PP
When a trait is used which isn't natively handled by Kavorka::Sub,
Kavorka::Parameter or Kavorka::ReturnType, Kavorka will attempt
to load a Moo::Role to handle the trait. These will be loaded from
the following namespaces, as appropriate:
.IP "\(bu" 4
\&\f(CW\*(C`Kavorka::TraitFor::Sub::*\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`Kavorka::TraitFor::Parameter::*\*(C'\fR
.IP "\(bu" 4
\&\f(CW\*(C`Kavorka::TraitFor::ReturnType::*\*(C'\fR
.PP
For example, \f(CW\*(C`Kavorka::TraitFor::Sub::friendly\*(C'\fR.
.SS "Trait Parameters"
.IX Subsection "Trait Parameters"
Although none of Kavorka's native traits make use of this syntax,
traits can be followed by trait parameters in parentheses:
.PP
.Vb 10
\&   BEGIN {
\&      package Kavorka::TraitFor::Parameter::debug;
\&      use Moo::Role;
\&      around injection => sub
\&      {
\&         my $next = shift;
\&         my $self = shift;
\&         my $code = $self\->$next(@_);
\&         $code .= sprintf(
\&            "printf STDERR %s, %s, %s;",
\&            B::perlstring($self\->traits\->{debug}[0]),
\&            B::perlstring($self\->name),
\&            $self\->name,
\&         );
\&         return $code;
\&      };
\&   }
\&   
\&   use Kavorka;
\&   
\&   fun foo ( $x but debug("%s is %s\en") ) {
\&      ## Injected:
\&      ## printf STDERR "%s is %s\en", "\e$x", $x;
\&      return $x;
\&   }
\&   
\&   foo(42);  # says to STDERR: \*(Aq$x is 42\*(Aq
.Ve
.SS "Keywords"
.IX Subsection "Keywords"
Traits are not applied to subs until \fIafter\fR they've been parsed,
which means that traits cannot, say, alter how the signature is parsed,
because the signature occurs before the traits.
.PP
For more advanced control over the parsing and behaviour of subs, you
would need to create a new keyword. A keyword is just a Moo class
which consumes the Kavorka::Sub role. Kavorka::Sub::Method and
Kavorka::Sub::Fun are simple examples of such keyword classes.
.PP
People can use your new keyword like this:
.PP
.Vb 1
\&   use Kavorka yourkeyword => { implementation => "Your::Class" };
.Ve
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs to
<http://rt.cpan.org/Dist/Display.html?Queue=Kavorka>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Kavorka::Manual.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2017 by Toby Inkster.
.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.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0