local-lib5/man/man3/Parse::Method::Signatures.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Parse::Method::Signatures 3"
 127 .TH Parse::Method::Signatures 3 "2009-09-13" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Parse::Method::Signatures \- Perl6 like method signature parser
 134 .SH "DESCRIPTION"
 135 .IX Header "DESCRIPTION"
 136 Inspired by Perl6::Signature but streamlined to just support the subset
 137 deemed useful for TryCatch and MooseX::Method::Signatures.
 138 .SH "TODO"
 139 .IX Header "TODO"
 140 .IP "\(bu" 4
 141 Document the parameter return types.
 142 .IP "\(bu" 4
 143 Probably lots of other things
 144 .SH "METHODS"
 145 .IX Header "METHODS"
 146 There are only two public methods to this module, both of which should be
 147 called as class methods. Both methods accept  either a single (non-ref) scalar
 148 as the value for the \*(L"input\*(R" attribute, or normal new style arguments (hash
 149 or hash-ref).
 150 .SS "signature"
 151 .IX Subsection "signature"
 152 .Vb 1
 153 \& my $sig = Parse::Method::Signatures\->signature( \*(Aq(Str $foo)\*(Aq )
 154 .Ve
 155 .PP
 156 Attempts to parse the (bracketed) method signature. Returns a value or croaks
 157 on error.
 158 .SS "param"
 159 .IX Subsection "param"
 160 .Vb 1
 161 \&  my $param = Parse::Method::Signatures\->param( \*(AqStr $foo where { length($_) < 10 }\*(Aq)
 162 .Ve
 163 .PP
 164 Attempts to parse the specification for a single parameter. Returns value or
 165 croaks on error.
 166 .SH "ATTRIBUTES"
 167 .IX Header "ATTRIBUTES"
 168 All the attributes on this class are read-only.
 169 .SS "input"
 170 .IX Subsection "input"
 171 \&\fBType:\fR Str
 172 .PP
 173 The string to parse.
 174 .SS "offset"
 175 .IX Subsection "offset"
 176 \&\fBType:\fR Int
 177 .PP
 178 Offset into \*(L"input\*(R" at which to start parsing. Useful for using with
 179 Devel::Declare linestring
 180 .SS "signature_class"
 181 .IX Subsection "signature_class"
 182 \&\fBDefault:\fR Parse::Method::Signatures::Sig
 183 .PP
 184 \&\fBType:\fR Str (loaded on demand class name)
 185 .SS "param_class"
 186 .IX Subsection "param_class"
 187 \&\fBDefault:\fR Parse::Method::Signatures::Param
 188 .PP
 189 \&\fBType:\fR Str (loaded on demand class name)
 190 .SS "type_constraint_class"
 191 .IX Subsection "type_constraint_class"
 192 \&\fBDefault:\fR Parse::Method::Signatures::TypeConstraint
 193 .PP
 194 \&\fBType:\fR Str (loaded on demand class name)
 195 .PP
 196 Class that is used to turn the parsed type constraint into an actual
 197 Moose::Meta::TypeConstraint object.
 198 .SS "from_namespace"
 199 .IX Subsection "from_namespace"
 200 \&\fBType:\fR ClassName
 201 .PP
 202 Let this module know which package it is parsing signatures form. This is
 203 entirely optional, and the only effect is has is on parsing type constraints.
 204 .PP
 205 If this attribute is set it is passed to \*(L"type_constraint_class\*(R" which can
 206 use it to introspect the package (commmonly for MooseX::Types exported
 207 types). See
 208 \&\*(L"find_registered_constraint\*(R" in Parse::Method::Signature::TypeConstraints for
 209 more details.
 210 .SS "type_constraint_callback"
 211 .IX Subsection "type_constraint_callback"
 212 \&\fBType:\fR CodeRef
 213 .PP
 214 Passed to the constructor of \*(L"type_constraint_class\*(R". Default implementation
 215 of this callback asks Moose for a type constrain matching the name passed in.
 216 If you have more complex requirements, such as parsing types created by
 217 MooseX::Types then you will want a callback similar to this:
 218 .PP
 219 .Vb 7
 220 \& # my $target_package defined elsewhere.
 221 \& my $tc_cb = sub {
 222 \&   my ($pms_tc, $name) = @_;
 223 \&   my $code = $target_package\->can($name);
 224 \&   $code ? eval { $code\->() }
 225 \&         : $pms_tc\->find_registered_constraint($name);
 226 \& }
 227 .Ve
 228 .PP
 229 Note that the above example is better provided by providing the
 230 \&\*(L"from_namespace\*(R" attribute.
 231 .SH "CAVEATS"
 232 .IX Header "CAVEATS"
 233 Like Perl6::Signature, the parsing of certain constructs is currently only a
 234 \&'best effort' \- specifically default values and where code blocks might not
 235 successfully for certain complex cases. Patches/Failing tests welcome.
 236 .PP
 237 Additionally, default value specifications are not evaluated which means that
 238 no such lexical or similar errors will not be produced by this module.
 239 Constant folding will also not be performed.
 240 .PP
 241 There are certain constructs that are simply too much hassle to avoid when the
 242 work around is simple. Currently the only cases that are known to parse wrong
 243 are when using anonymous variables (i.e. just sigils) in unpacked arrays. Take
 244 the following example:
 245 .PP
 246 .Vb 1
 247 \& method foo (ArrayRef [$, $], $some_value_we_care_about) {
 248 .Ve
 249 .PP
 250 In this case the \f(CW$]\fR is treated as one of perl's magic variables
 251 (specifically, the patch level of the Perl interpreter) rather than a \f(CW\*(C`$\*(C'\fR
 252 followed by a \f(CW\*(C`]\*(C'\fR as was almost certainly intended. The work around for this
 253 is simple: introduce a space between the charcters:
 254 .PP
 255 .Vb 1
 256 \& method foo (ArrayRef [ $, $ ], $some_value_we_care_about) {
 257 .Ve
 258 .PP
 259 The same applies
 260 .SH "AUTHOR"
 261 .IX Header "AUTHOR"
 262 Ash Berlin <ash@cpan.org>.
 263 .PP
 264 Thanks to Florian Ragwitz <rafl@debian.org>.
 265 .PP
 266 Many thanks to Piers Crawley to showing me the way to refactor my spaghetti
 267 code into something more manageable.
 268 .SH "SEE ALSO"
 269 .IX Header "SEE ALSO"
 270 Devel::Declare which is used by most modules that use this (currently by
 271 all modules known to the author.)
 272 .PP
 273 <http://github.com/ashb/trycatch/tree>.
 274 .SH "LICENSE"
 275 .IX Header "LICENSE"
 276 Licensed under the same terms as Perl itself.
 277 .PP
 278 This distribution copyright 2008\-2009, Ash Berlin <ash@cpan.org>