local-lib5/man/man3/MooseX::Declare::Syntax::NamespaceHandling.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::Syntax::NamespaceHandling 3"
 127 .TH MooseX::Declare::Syntax::NamespaceHandling 3 "2009-09-22" "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::Syntax::NamespaceHandling \- Handle namespaced blocks
 134 .SH "DESCRIPTION"
 135 .IX Header "DESCRIPTION"
 136 Allows the implementation of namespaced blocks like the
 137 role and
 138 class keyword handlers.
 139 .PP
 140 Namespaces are automatically nested. Meaning that, for example, a \f(CW\*(C`class Bar\*(C'\fR
 141 declaration inside another \f(CW\*(C`class Foo\*(C'\fR block gives the inner one actually the
 142 name \f(CW\*(C`Foo::Bar\*(C'\fR.
 143 .SH "CONSUMES"
 144 .IX Header "CONSUMES"
 145 .IP "\(bu" 4
 146 MooseX::Declare::Syntax::KeywordHandling
 147 .IP "\(bu" 4
 148 MooseX::Declare::Syntax::InnerSyntaxHandling
 149 .SH "REQUIRED METHODS"
 150 .IX Header "REQUIRED METHODS"
 151 .SS "handle_missing_block"
 152 .IX Subsection "handle_missing_block"
 153 .Vb 1
 154 \&  Object\->handle_missing_block (Object $context, Str $body, %args)
 155 .Ve
 156 .PP
 157 This must be implemented to decide what to do in case the statement is
 158 terminated rather than followed by a block. It will receive the context
 159 object, the produced code that needs to be injected, and all the arguments
 160 that were passed to the call to \*(L"inject_code_parts\*(R" in MooseX::Declare::Context.
 161 .PP
 162 The return value will be ignored.
 163 .SH "EXTENDABLE STUB METHODS"
 164 .IX Header "EXTENDABLE STUB METHODS"
 165 .SS "add_namespace_customizations"
 166 .IX Subsection "add_namespace_customizations"
 167 .SS "add_optional_customizations"
 168 .IX Subsection "add_optional_customizations"
 169 .Vb 2
 170 \&  Object\->add_namespace_customizations (Object $context, Str $package, HashRef $options)
 171 \&  Object\->add_optional_customizations  (Object $context, Str $package, HashRef $options)
 172 .Ve
 173 .PP
 174 These will be called (in this order) by the \*(L"parse\*(R" method. They allow specific hooks
 175 to attach before/after/around the customizations for the namespace and the provided
 176 options that are not attached to the namespace directly.
 177 .PP
 178 While this distinction might seem superficial, we advise library developers faciliating
 179 this role to follow the precendent. This ensures that when another component needs to
 180 tie between the namspace and any additional customizations everythign will run in the
 181 correct order. An example of this separation would be
 182 .PP
 183 .Vb 1
 184 \&  class Foo is mutable ...
 185 .Ve
 186 .PP
 187 being an option of the namespace generation, while
 188 .PP
 189 .Vb 1
 190 \&  class Foo with Bar ...
 191 .Ve
 192 .PP
 193 is an additional optional customization.
 194 .SS "handle_post_parsing"
 195 .IX Subsection "handle_post_parsing"
 196 .Vb 1
 197 \&  Object\->handle_post_parsing (Object $context, Str $package, Str | Object $name)
 198 .Ve
 199 .PP
 200 Allows for additional modifications to te namespace after everything else has been
 201 done. It will receive the context, the fully qualified package name, and either a
 202 string with the name that was specified (might not be fully qualified, since
 203 namespaces can be nested) or the anonymous metaclass instance if no name was
 204 specified.
 205 .PP
 206 The return value of this method will be the value returned to the user of the
 207 keyword. If you always return the \f(CW$package\fR argument like this:
 208 .PP
 209 .Vb 4
 210 \&  sub handle_post_parsing {
 211 \&      my ($self, $context, $package, $name) = @_;
 212 \&      return $package;
 213 \&  }
 214 .Ve
 215 .PP
 216 and set this up in a \f(CW\*(C`foo\*(C'\fR keyword handler, you can use it like this:
 217 .PP
 218 .Vb 1
 219 \&  foo Cthulhu {
 220 \&
 221 \&      my $fhtagn = foo Fhtagn { }
 222 \&      my $anon   = foo { };
 223 \&
 224 \&      say $fhtagn;  # Cthulhu::Fhtagn
 225 \&      say $anon;    # some autogenerated package name
 226 \&  }
 227 .Ve
 228 .SS "make_anon_metaclass"
 229 .IX Subsection "make_anon_metaclass"
 230 .Vb 1
 231 \&  Class::MOP::Class Object\->make_anon_metaclass ()
 232 .Ve
 233 .PP
 234 This method should be overridden if you want to provide anonymous namespaces.
 235 .PP
 236 It does not receive any arguments for customization of the metaclass, because
 237 the configuration and customization will be done by MooseX::Declare in the
 238 package of the generated class in the same way as in those that have specified
 239 names. This way ensures that anonymous and named namespaces are always handled
 240 equally.
 241 .PP
 242 If you do not extend this method (it will return nothing by default), an error
 243 will be thrown when a user attempts to declare an anonymous namespace.
 244 .SH "METHODS"
 245 .IX Header "METHODS"
 246 .SS "parse"
 247 .IX Subsection "parse"
 248 .Vb 1
 249 \&  Any Object\->parse (Object $context)
 250 .Ve
 251 .PP
 252 This is the main handling routine for namespaces. It will remove the namespace
 253 name and its options. If the handler was invoked without a name, options or
 254 a following block, it is assumed that this is an instance of an autoquoted
 255 bareword like \f(CW\*(C`class =\*(C'\fR \*(L"Foo\*(R">.
 256 .PP
 257 The return value of the \f(CW\*(C`parse\*(C'\fR method is also the value that is returned
 258 to the user of the keyword.
 259 .SH "SEE ALSO"
 260 .IX Header "SEE ALSO"
 261 .IP "\(bu" 4
 262 MooseX::Declare
 263 .IP "\(bu" 4
 264 MooseX::Declare::Syntax::MooseSetup
 265 .SH "AUTHOR, COPYRIGHT & LICENSE"
 266 .IX Header "AUTHOR, COPYRIGHT & LICENSE"
 267 See MooseX::Declare