local-lib5/man/man3/MooseX::Declare::Context.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 "MooseX::Declare::Context 3"
 127 .TH MooseX::Declare::Context 3 "2009-12-19" "perl v5.8.8" "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 MooseX::Declare::Context \- Per\-keyword declaration context
 134 .SH "DESCRIPTION"
 135 .IX Header "DESCRIPTION"
 136 This is not a subclass of Devel::Declare::Context::Simple, but it will
 137 delegate all default methods and extend it with some attributes and methods
 138 of its own.
 139 .PP
 140 A context object will be instanciated for every keyword that is handled by
 141 MooseX::Declare. If handlers want to communicate with other handlers (for
 142 example handlers that will only be setup inside a namespace block) it must
 143 do this via the generated code.
 144 .SH "TYPES"
 145 .IX Header "TYPES"
 146 .SS "CodePart"
 147 .IX Subsection "CodePart"
 148 A part of code represented by either a \f(CW\*(C`Str\*(C'\fR or a \*(L"BlockCodePart\*(R".
 149 .SS "BlockCodePart"
 150 .IX Subsection "BlockCodePart"
 151 An \f(CW\*(C`ArrayRef\*(C'\fR with at least one element that stringifies to either \f(CW\*(C`BEGIN\*(C'\fR
 152 or \f(CW\*(C`END\*(C'\fR. The other parts will be stringified and used as the body for the
 153 generated block. An example would be this compiletime role composition:
 154 .PP
 155 .Vb 1
 156 \&  [\*(AqBEGIN\*(Aq, \*(Aqwith q{ MyRole }\*(Aq]
 157 .Ve
 158 .SH "ATTRIBUTES"
 159 .IX Header "ATTRIBUTES"
 160 .SS "caller_file"
 161 .IX Subsection "caller_file"
 162 A required \f(CW\*(C`Str\*(C'\fR containing the file the keyword was encountered in.
 163 .SS "preamble_code_parts"
 164 .IX Subsection "preamble_code_parts"
 165 An \f(CW\*(C`ArrayRef\*(C'\fR of \*(L"CodePart\*(R"s that will be used as preamble. A preamble in
 166 this context means the beginning of the generated code.
 167 .SS "scope_code_parts"
 168 .IX Subsection "scope_code_parts"
 169 These parts will come before the actual body and after the
 170 \&\*(L"preamble_code_parts\*(R". It is an \f(CW\*(C`ArrayRef\*(C'\fR of \*(L"CodePart\*(R"s.
 171 .SS "cleanup_code_parts"
 172 .IX Subsection "cleanup_code_parts"
 173 An \f(CW\*(C`ArrayRef\*(C'\fR of \*(L"CodePart\*(R"s that will not be directly inserted
 174 into the code, but instead be installed in a handler that will run at
 175 the end of the scope so you can do namespace cleanups and such.
 176 .SS "stack"
 177 .IX Subsection "stack"
 178 An \f(CW\*(C`ArrayRef\*(C'\fR that contains the stack of handlers. A keyword that was
 179 only setup inside a scoped block will have the blockhandler be put in
 180 the stack.
 181 .SH "METHODS"
 182 .IX Header "METHODS"
 183 All methods from Devel::Declare::Context::Simple should be available and
 184 will be delegated to an internally stored instance of it.
 185 .ie n .SS "add_preamble_code_parts(CodePart @parts)"
 186 .el .SS "add_preamble_code_parts(CodePart \f(CW@parts\fP)"
 187 .IX Subsection "add_preamble_code_parts(CodePart @parts)"
 188 .ie n .SS "add_scope_code_parts(CodePart @parts)"
 189 .el .SS "add_scope_code_parts(CodePart \f(CW@parts\fP)"
 190 .IX Subsection "add_scope_code_parts(CodePart @parts)"
 191 .ie n .SS "add_cleanup_code_parts(CodePart @parts)"
 192 .el .SS "add_cleanup_code_parts(CodePart \f(CW@parts\fP)"
 193 .IX Subsection "add_cleanup_code_parts(CodePart @parts)"
 194 .Vb 3
 195 \&  Object\->add_preamble_code_parts (CodeRef @parts)
 196 \&  Object\->add_scope_code_parts    (CodeRef @parts)
 197 \&  Object\->add_cleanup_code_parts  (CodeRef @parts)
 198 .Ve
 199 .PP
 200 For these three methods please look at the corresponding \f(CW*_code_parts\fR
 201 attribute in the list above. These methods are merely convenience methods
 202 that allow adding entries to the code part containers.
 203 .SS "inject_code_parts_here"
 204 .IX Subsection "inject_code_parts_here"
 205 .Vb 1
 206 \&  True Object\->inject_code_parts_here (CodePart @parts)
 207 .Ve
 208 .PP
 209 Will inject the passed \*(L"CodePart\*(R"s at the current position in the code.
 210 .SS "peek_next_char"
 211 .IX Subsection "peek_next_char"
 212 .Vb 1
 213 \&  Str Object\->peek_next_char ()
 214 .Ve
 215 .PP
 216 Will return the next char without stripping it from the stream.
 217 .SS "inject_code_parts"
 218 .IX Subsection "inject_code_parts"
 219 .Vb 4
 220 \&  Object\->inject_code_parts (
 221 \&      Bool    :$inject_cleanup_code_parts,
 222 \&      CodeRef :$missing_block_handler
 223 \&  )
 224 .Ve
 225 .PP
 226 This will inject the code parts from the attributes above at the current
 227 position. The preamble and scope code parts will be inserted first. Then
 228 then call to the cleanup code will be injected, unless the options
 229 contain a key named \f(CW\*(C`inject_cleanup_code_parts\*(C'\fR with a false value.
 230 .PP
 231 The \f(CW\*(C`inject_if_block\*(C'\fR method will be called if the next char is a \f(CW\*(C`{\*(C'\fR
 232 indicating a following block.
 233 .PP
 234 If it is not a block, but a semi-colon is found and the options
 235 contained a \f(CW\*(C`missing_block_handler\*(C'\fR key was passed, it will be called
 236 as method on the context object with the code to inject and the
 237 options as arguments. All options that are not recognized are passed
 238 through to the \f(CW\*(C`missing_block_handler\*(C'\fR. You are well advised to prefix
 239 option names in your extensions.
 240 .SS "strip_name_and_options"
 241 .IX Subsection "strip_name_and_options"
 242 .Vb 1
 243 \&  List Object\->strip_name_and_options ()
 244 .Ve
 245 .PP
 246 This will remove an identifier plus any options that follow it from the
 247 stream. Options are things like \f(CW\*(C`is Trait\*(C'\fR, \f(CW\*(C`with Role\*(C'\fR and
 248 \&\f(CW\*(C`extends ParentClass\*(C'\fR. Currently, only these are supported.
 249 .PP
 250 The return value is a list with two values:
 251 .ie n .IP "Str $name" 4
 252 .el .IP "Str \f(CW$name\fR" 4
 253 .IX Item "Str $name"
 254 The name that was read.
 255 .ie n .IP "HashRef $options" 4
 256 .el .IP "HashRef \f(CW$options\fR" 4
 257 .IX Item "HashRef $options"
 258 The options that followed the name. This is the returned format:
 259 .Sp
 260 .Vb 5
 261 \&  Dict[
 262 \&      is      => HashRef[Bool],
 263 \&      extends => ArrayRef[ParentClass],
 264 \&      with    => ArrayRef[Role],
 265 \&  ]
 266 .Ve
 267 .SH "SEE ALSO"
 268 .IX Header "SEE ALSO"
 269 .IP "\(bu" 4
 270 MooseX::Declare
 271 .IP "\(bu" 4
 272 Devel::Declare
 273 .IP "\(bu" 4
 274 Devel::Declare::Context::Simple
 275 .SH "AUTHOR, COPYRIGHT & LICENSE"
 276 .IX Header "AUTHOR, COPYRIGHT & LICENSE"
 277 See MooseX::Declare