--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" 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" ''
+'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 turned on, 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.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "MooseX::Method::Signatures 3"
+.TH MooseX::Method::Signatures 3 "2010-02-04" "perl v5.8.8" "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"
+MooseX::Method::Signatures \- Method declarations with type constraints and no source filter
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& package Foo;
+\&
+\& use Moose;
+\& use MooseX::Method::Signatures;
+\&
+\& method morning (Str $name) {
+\& $self\->say("Good morning ${name}!");
+\& }
+\&
+\& method hello (Str :$who, Int :$age where { $_ > 0 }) {
+\& $self\->say("Hello ${who}, I am ${age} years old!");
+\& }
+\&
+\& method greet (Str $name, Bool :$excited = 0) {
+\& if ($excited) {
+\& $self\->say("GREETINGS ${name}!");
+\& }
+\& else {
+\& $self\->say("Hi ${name}!");
+\& }
+\& }
+\&
+\& $foo\->morning(\*(AqResi\*(Aq); # This works.
+\&
+\& $foo\->hello(who => \*(Aqworld\*(Aq, age => 42); # This too.
+\&
+\& $foo\->greet(\*(AqResi\*(Aq, excited => 1); # And this as well.
+\&
+\& $foo\->hello(who => \*(Aqworld\*(Aq, age => \*(Aqfortytwo\*(Aq); # This doesn\*(Aqt.
+\&
+\& $foo\->hello(who => \*(Aqworld\*(Aq, age => \-23); # This neither.
+\&
+\& $foo\->morning; # Won\*(Aqt work.
+\&
+\& $foo\->greet; # Will fail.
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Provides a proper method keyword, like \*(L"sub\*(R" but specifically for making methods
+and validating their arguments against Moose type constraints.
+.SH "SIGNATURE SYNTAX"
+.IX Header "SIGNATURE SYNTAX"
+The signature syntax is heavily based on Perl 6. However not the full Perl 6
+signature syntax is supported yet and some of it never will be.
+.SS "Type Constraints"
+.IX Subsection "Type Constraints"
+.Vb 3
+\& method foo ( $affe) # no type checking
+\& method bar (Animal $affe) # $affe\->isa(\*(AqAnimal\*(Aq)
+\& method baz (Animal|Human $affe) # $affe\->isa(\*(AqAnimal\*(Aq) || $affe\->isa(\*(AqHuman\*(Aq)
+.Ve
+.SS "Positional vs. Named"
+.IX Subsection "Positional vs. Named"
+.Vb 3
+\& method foo ( $a, $b, $c) # positional
+\& method bar (:$a, :$b, :$c) # named
+\& method baz ( $a, $b, :$c) # combined
+.Ve
+.SS "Required vs. Optional"
+.IX Subsection "Required vs. Optional"
+.Vb 2
+\& method foo ($a , $b!, :$c!, :$d!) # required
+\& method bar ($a?, $b?, :$c , :$d?) # optional
+.Ve
+.SS "Defaults"
+.IX Subsection "Defaults"
+.Vb 1
+\& method foo ($a = 42) # defaults to 42
+.Ve
+.SS "Constraints"
+.IX Subsection "Constraints"
+.Vb 1
+\& method foo ($foo where { $_ % 2 == 0 }) # only even
+.Ve
+.SS "Invocant"
+.IX Subsection "Invocant"
+.Vb 3
+\& method foo ( $moo) # invocant is called $self and is required
+\& method bar ($self: $moo) # same, but explicit
+\& method baz ($class: $moo) # invocant is called $class
+.Ve
+.SS "Labels"
+.IX Subsection "Labels"
+.Vb 2
+\& method foo (: $affe ) # called as $obj\->foo(affe => $value)
+\& method bar (:apan($affe)) # called as $obj\->foo(apan => $value)
+.Ve
+.SS "Traits"
+.IX Subsection "Traits"
+.Vb 2
+\& method foo (Affe $bar does trait)
+\& method foo (Affe $bar is trait)
+.Ve
+.PP
+The only currently supported trait is \f(CW\*(C`coerce\*(C'\fR, which will attempt to coerce
+the value provided if it doesn't satisfy the requirements of the type
+constraint.
+.SS "Placeholders"
+.IX Subsection "Placeholders"
+.Vb 1
+\& method foo ($bar, $, $baz)
+.Ve
+.PP
+Sometimes you don't care about some params you're being called with. Just put
+the bare sigil instead of a full variable name into the signature to avoid an
+extra lexical variable to be created.
+.SS "Complex Example"
+.IX Subsection "Complex Example"
+.Vb 3
+\& method foo ( SomeClass $thing where { $_\->can(\*(Aqstuff\*(Aq) }:
+\& Str $bar = "apan",
+\& Int :$baz! = 42 where { $_ % 2 == 0 } where { $_ > 10 } )
+\&
+\& # the invocant is called $thing, must be an instance of SomeClass and
+\& has to implement a \*(Aqstuff\*(Aq method
+\& # $bar is positional, required, must be a string and defaults to "apan"
+\& # $baz is named, required, must be an integer, defaults to 42 and needs
+\& # to be even and greater than 10
+.Ve
+.SH "BUGS, CAVEATS AND NOTES"
+.IX Header "BUGS, CAVEATS AND NOTES"
+This module is as stable now, but this is not to say that it is entirely bug
+free. If you notice any odd behaviour (messages not being as good as they could
+for example) then please raise a bug.
+.SS "Fancy signatures"
+.IX Subsection "Fancy signatures"
+Parse::Method::Signatures is used to parse the signatures. However, some
+signatures that can be parsed by it aren't supported by this module (yet).
+.SS "No source filter"
+.IX Subsection "No source filter"
+While this module does rely on the hairy black magic of Devel::Declare it
+does not depend on a source filter. As such, it doesn't try to parse and
+rewrite your source code and there should be no weird side effects.
+.PP
+Devel::Declare only effects compilation. After that, it's a normal subroutine.
+As such, for all that hairy magic, this module is surprisingly stable.
+.SS "What about regular subroutines?"
+.IX Subsection "What about regular subroutines?"
+Devel::Declare cannot yet change the way \f(CW\*(C`sub\*(C'\fR behaves. However, the
+signatures module can. Right now it only provides very basic
+signatures, but it's extendable enough that plugging MooseX::Method::Signatures
+signatures into that should be quite possible.
+.SS "What about the return value?"
+.IX Subsection "What about the return value?"
+Type constraints for return values can be declared using
+.PP
+.Vb 1
+\& method foo (Int $x, Str $y) returns (Bool) { ... }
+.Ve
+.PP
+however, this feature only works with scalar return values and is still
+considered to be experimental.
+.SS "Interaction with Moose::Role"
+.IX Subsection "Interaction with Moose::Role"
+\fIMethods not seen by a role's \f(CI\*(C`requires\*(C'\fI\fR
+.IX Subsection "Methods not seen by a role's requires"
+.PP
+Because the processing of the MooseX::Method::Signatures
+\&\f(CW\*(C`method\*(C'\fR and the Moose \f(CW\*(C`with\*(C'\fR keywords are both
+done at runtime, it can happen that a role will require
+a method before it is declared (which will cause
+Moose to complain very loudly and abort the program).
+.PP
+For example, the following will not work:
+.PP
+.Vb 1
+\& # in file Canine.pm
+\&
+\& package Canine;
+\&
+\& use Moose;
+\& use MooseX::Method::Signatures;
+\&
+\& with \*(AqWatchdog\*(Aq;
+\&
+\& method bark { print "Woof!\en"; }
+\&
+\& 1;
+\&
+\&
+\& # in file Watchdog.pm
+\&
+\& package Watchdog;
+\&
+\& use Moose::Role;
+\&
+\& requires \*(Aqbark\*(Aq; # will assert! evaluated before \*(Aqmethod\*(Aq is processed
+\&
+\& sub warn_intruder {
+\& my $self = shift;
+\& my $intruder = shift;
+\&
+\& $self\->bark until $intruder\->gone;
+\& }
+\&
+\& 1;
+.Ve
+.PP
+A workaround for this problem is to use \f(CW\*(C`with\*(C'\fR only
+after the methods have been defined. To take our previous
+example, \fBCanine\fR could be reworked thus:
+.PP
+.Vb 1
+\& package Canine;
+\&
+\& use Moose;
+\& use MooseX::Method::Signatures;
+\&
+\& method bark { print "Woof!\en"; }
+\&
+\& with \*(AqWatchdog\*(Aq;
+\&
+\& 1;
+.Ve
+.PP
+A better solution is to use MooseX::Declare instead of plain
+MooseX::Method::Signatures. It defers application of roles until the end
+of the class definition. With it, our example would becomes:
+.PP
+.Vb 1
+\& # in file Canine.pm
+\&
+\& use MooseX::Declare;
+\&
+\& class Canine with Watchdog {
+\& method bark { print "Woof!\en"; }
+\& }
+\&
+\& 1;
+\&
+\& # in file Watchdog.pm
+\&
+\& use MooseX::Declare;
+\&
+\& role Watchdog {
+\& requires \*(Aqbark\*(Aq;
+\&
+\& method warn_intruder ( $intruder ) {
+\& $self\->bark until $intruder\->gone;
+\& }
+\& }
+\&
+\& 1;
+.Ve
+.PP
+\fI\fISubroutine redefined\fI warnings\fR
+.IX Subsection "Subroutine redefined warnings"
+.PP
+When composing a Moose::Role into a class that uses
+MooseX::Method::Signatures, you may get a \*(L"Subroutine redefined\*(R"
+warning. This happens when both the role and the class define a
+method/subroutine of the same name. (The way roles work, the one
+defined in the class takes precedence.) To eliminate this warning,
+make sure that your \f(CW\*(C`with\*(C'\fR declaration happens after any
+method/subroutine declarations that may have the same name as a
+method/subroutine within a role.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+MooseX::Declare
+.PP
+Method::Signatures::Simple
+.PP
+Method::Signatures
+.PP
+Perl6::Subs
+.PP
+Devel::Declare
+.PP
+Parse::Method::Signatures
+.PP
+Moose
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Florian Ragwitz <rafl@debian.org>
+.PP
+With contributions from:
+.IP "Ash Berlin <ash@cpan.org>" 4
+.IX Item "Ash Berlin <ash@cpan.org>"
+.PD 0
+.IP "Cory Watson <gphat@cpan.org>" 4
+.IX Item "Cory Watson <gphat@cpan.org>"
+.IP "Hakim Cassimally <hakim.cassimally@gmail.com>" 4
+.IX Item "Hakim Cassimally <hakim.cassimally@gmail.com>"
+.IP "Jonathan Scott Duff <duff@pobox.com>" 4
+.IX Item "Jonathan Scott Duff <duff@pobox.com>"
+.IP "Justin Hunter <justin.d.hunter@gmail.com>" 4
+.IX Item "Justin Hunter <justin.d.hunter@gmail.com>"
+.IP "Kent Fredric <kentfredric@gmail.com>" 4
+.IX Item "Kent Fredric <kentfredric@gmail.com>"
+.IP "Maik Hentsche <maik.hentsche@amd.com>" 4
+.IX Item "Maik Hentsche <maik.hentsche@amd.com>"
+.IP "Matt Kraai <kraai@ftbfs.org>" 4
+.IX Item "Matt Kraai <kraai@ftbfs.org>"
+.IP "Rhesa Rozendaal <rhesa@cpan.org>" 4
+.IX Item "Rhesa Rozendaal <rhesa@cpan.org>"
+.IP "Ricardo \s-1SIGNES\s0 <rjbs@cpan.org>" 4
+.IX Item "Ricardo SIGNES <rjbs@cpan.org>"
+.IP "Steffen Schwigon <ss5@renormalist.net>" 4
+.IX Item "Steffen Schwigon <ss5@renormalist.net>"
+.IP "Yanick Champoux <yanick@babyl.dyndns.org>" 4
+.IX Item "Yanick Champoux <yanick@babyl.dyndns.org>"
+.IP "Nicholas Perez <nperez@cpan.org>" 4
+.IX Item "Nicholas Perez <nperez@cpan.org>"
+.PD
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright (c) 2008, 2009 Florian Ragwitz
+.PP
+Code based on the tests for Devel::Declare.
+.PP
+Documentation based on MooseX::Method and Method::Signatures.
+.PP
+Licensed under the same terms as Perl itself.
projects / catagits/Gitalist.git / blobdiff