local-lib5/man/man3/autobox.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 "autobox 3"
 127 .TH autobox 3 "2008-05-25" "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 autobox \- call methods on native types
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use autobox;
 138 \&
 139 \&    # integers
 140 \&
 141 \&        my $range = 10\->to(1); # [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
 142 \&
 143 \&    # floats
 144 \&
 145 \&        my $error = 3.1415927\->minus(22/7)\->abs();
 146 \&
 147 \&    # strings
 148 \&
 149 \&        my @list = \*(AqSELECT * FROM foo\*(Aq\->list();
 150 \&        my $greeting = "Hello, world!"\->upper(); # "HELLO, WORLD!"
 151 \&
 152 \&        $greeting\->for_each(\e&character_handler);
 153 \&
 154 \&    # arrays and array refs
 155 \&
 156 \&        my $schwartzian = @_\->map(...)\->sort(...)\->map(...);
 157 \&        my $hash = [ \*(AqSELECT * FROM foo WHERE id IN (?, ?)\*(Aq, 1, 2 ]\->hash();
 158 \&
 159 \&    # hashes and hash refs
 160 \&
 161 \&        { alpha => \*(Aqbeta\*(Aq, gamma => \*(Aqvlissides\*(Aq }\->for_each(...);
 162 \&        %hash\->keys();
 163 \&
 164 \&    # code refs
 165 \&
 166 \&        my $plus_five = (\e&add)\->curry()\->(5);
 167 \&        my $minus_three = sub { $_[0] \- $_[1] }\->reverse\->curry\->(3);
 168 \&
 169 \&    # can() and isa() work as expected
 170 \&
 171 \&        if ("Hello, world!"\->can(\*(Aqfoo\*(Aq)) ...
 172 \&        if (3.1415927\->isa(\*(AqSCALAR\*(Aq)) ...
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 The autobox pragma allows methods to be called on integers, floats, strings, arrays,
 177 hashes, and code references in exactly the same manner as blessed references.
 178 .PP
 179 The autoboxing is transparent: boxed values are not blessed into their (user-defined)
 180 implementation class (unless the method elects to bestow such a blessing) \- they simply
 181 use its methods as though they are.
 182 .PP
 183 The classes (packages) into which the native types are boxed are fully configurable.
 184 By default, a method invoked on a non-object is assumed to be
 185 defined in a class whose name corresponds to the \f(CW\*(C`ref()\*(C'\fR type of that
 186 value \- or \s-1SCALAR\s0 if the value is a non-reference.
 187 .PP
 188 This mapping can be overriden by passing key/value pairs to the \f(CW\*(C`use autobox\*(C'\fR
 189 statement, in which the keys represent native types, and the values
 190 their associated classes.
 191 .PP
 192 As with regular objects, autoboxed values are passed as the first argument of the specified method.
 193 Consequently, given a vanilla \f(CW\*(C`use autobox\*(C'\fR:
 194 .PP
 195 .Vb 1
 196 \&    "Hello, world!"\->upper()
 197 .Ve
 198 .PP
 199 is invoked as:
 200 .PP
 201 .Vb 1
 202 \&    SCALAR::upper("hello, world!")
 203 .Ve
 204 .PP
 205 while:
 206 .PP
 207 .Vb 1
 208 \&    [ 1 .. 10 ]\->for_each(sub { ... })
 209 .Ve
 210 .PP
 211 resolves to:
 212 .PP
 213 .Vb 1
 214 \&    ARRAY::for_each([ 1 .. 10 ], sub { ... })
 215 .Ve
 216 .PP
 217 Values beginning with the array \f(CW\*(C`@\*(C'\fR and hash \f(CW\*(C`%\*(C'\fR sigils are passed by reference, i.e. under the default bindings:
 218 .PP
 219 .Vb 4
 220 \&    @array\->join(\*(Aq, \*(Aq)
 221 \&    @{ ... }\->length()
 222 \&    %hash\->keys()
 223 \&    %$hash\->values()
 224 .Ve
 225 .PP
 226 are equivalent to:
 227 .PP
 228 .Vb 4
 229 \&    ARRAY::join(\e@array, \*(Aq, \*(Aq)
 230 \&    ARRAY::length(\e@{ ... })
 231 \&    HASH::keys(\e%hash)
 232 \&    HASH::values(\e%$hash)
 233 .Ve
 234 .PP
 235 Multiple \f(CW\*(C`use autobox\*(C'\fR statements can appear in the same scope. These are merged both \*(L"horizontally\*(R" (i.e.
 236 mutiple classes can be associated with a particular type) and \*(L"vertically\*(R" (i.e. multiple classes can be associated
 237 with multiple types).
 238 .PP
 239 Thus:
 240 .PP
 241 .Vb 2
 242 \&    use autobox SCALAR => \*(AqFoo\*(Aq;
 243 \&    use autobox SCALAR => \*(AqBar\*(Aq;
 244 .Ve
 245 .PP
 246 \&\- associates \s-1SCALAR\s0 types with a synthetic class whose \f(CW@ISA\fR includes both \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR (in that order).
 247 .PP
 248 Likewise:
 249 .PP
 250 .Vb 3
 251 \&    use autobox SCALAR => \*(AqFoo\*(Aq;
 252 \&    use autobox SCALAR => \*(AqBar\*(Aq;
 253 \&    use autobox ARRAY  => \*(AqBaz\*(Aq;
 254 .Ve
 255 .PP
 256 and
 257 .PP
 258 .Vb 2
 259 \&    use autobox SCALAR => [ \*(AqFoo\*(Aq, \*(AqBar\*(Aq ];
 260 \&    use autobox ARRAY  => \*(AqBaz\*(Aq;
 261 .Ve
 262 .PP
 263 \&\- bind \s-1SCALAR\s0 types to the \f(CW\*(C`Foo\*(C'\fR and \f(CW\*(C`Bar\*(C'\fR classes and \s-1ARRAY\s0 types to \f(CW\*(C`Baz\*(C'\fR.
 264 .PP
 265 \&\f(CW\*(C`autobox\*(C'\fR is lexically scoped, and bindings for an outer scope
 266 can be extended or countermanded in a nested scope:
 267 .PP
 268 .Vb 3
 269 \&    {
 270 \&        use autobox; # default bindings: autobox all native types
 271 \&        ...
 272 \&
 273 \&        {
 274 \&            # appends \*(AqMyScalar\*(Aq to the @ISA associated with SCALAR types
 275 \&            use autobox SCALAR => \*(AqMyScalar\*(Aq;
 276 \&            ...
 277 \&        }
 278 \&
 279 \&        # back to the default (no MyScalar)
 280 \&        ...
 281 \&    }
 282 .Ve
 283 .PP
 284 Autoboxing can be turned off entirely by using the \f(CW\*(C`no\*(C'\fR syntax:
 285 .PP
 286 .Vb 6
 287 \&    {
 288 \&        use autobox;
 289 \&        ...
 290 \&        no autobox;
 291 \&        ...
 292 \&    }
 293 .Ve
 294 .PP
 295 \&\- or can be selectively disabled by passing arguments to the \f(CW\*(C`no autobox\*(C'\fR statement:
 296 .PP
 297 .Vb 1
 298 \&    use autobox; # default bindings
 299 \&
 300 \&    no autobox qw(SCALAR);
 301 \&
 302 \&    []\->foo(); # OK: ARRAY::foo([])
 303 \&
 304 \&    "Hello, world!"\->bar(); # runtime error
 305 .Ve
 306 .PP
 307 Autoboxing is not performed for barewords i.e.
 308 .PP
 309 .Vb 1
 310 \&    my $foo = Foo\->new();
 311 .Ve
 312 .PP
 313 and:
 314 .PP
 315 .Vb 1
 316 \&    my $foo = new Foo;
 317 .Ve
 318 .PP
 319 behave as expected.
 320 .PP
 321 Methods are called on native types by means of the arrow operator. As with
 322 regular objects, the right hand side of the operator can either be a bare method name or a variable containing
 323 a method name or subroutine reference. Thus the following are all valid:
 324 .PP
 325 .Vb 4
 326 \&    sub method1 { ... }
 327 \&    my $method2 = \*(Aqsome_method\*(Aq;
 328 \&    my $method3 = sub { ... };
 329 \&    my $method4 = \e&some_method;
 330 \&
 331 \&    " ... "\->method1();
 332 \&    [ ... ]\->$method2();
 333 \&    { ... }\->$method3();
 334 \&    sub { ... }\->$method4();
 335 .Ve
 336 .PP
 337 A native type is only asociated with a class if the type => class mapping
 338 is supplied in the \f(CW\*(C`use autobox\*(C'\fR statement. Thus the following will not work:
 339 .PP
 340 .Vb 1
 341 \&    use autobox SCALAR => \*(AqMyScalar\*(Aq;
 342 \&
 343 \&    @array\->some_array_method();
 344 .Ve
 345 .PP
 346 \&\- as no class is specified for the \s-1ARRAY\s0 type. Note: the result of calling a method
 347 on a native type that is not associated with a class is the usual runtime error message:
 348 .PP
 349 .Vb 1
 350 \&    Can\*(Aqt call method "some_array_method" on unblessed reference at ...
 351 .Ve
 352 .PP
 353 As a convenience, there is one exception to this rule. If \f(CW\*(C`use autobox\*(C'\fR is invoked with no arguments
 354 (ignoring the \s-1DEBUG\s0 option) the four main native types are associated with classes of the same name.
 355 .PP
 356 Thus:
 357 .PP
 358 .Vb 1
 359 \&    use autobox;
 360 .Ve
 361 .PP
 362 \&\- is equivalent to:
 363 .PP
 364 .Vb 5
 365 \&    use autobox
 366 \&        SCALAR => \*(AqSCALAR\*(Aq,
 367 \&        ARRAY  => \*(AqARRAY\*(Aq,
 368 \&        HASH   => \*(AqHASH\*(Aq,
 369 \&        CODE   => \*(AqCODE\*(Aq;
 370 .Ve
 371 .PP
 372 This facilitates one-liners and prototypes:
 373 .PP
 374 .Vb 1
 375 \&    use autobox;
 376 \&
 377 \&    sub SCALAR::split { [ split \*(Aq\*(Aq, $_[0] ] }
 378 \&    sub ARRAY::length { scalar @{$_[0]} }
 379 \&
 380 \&    print "Hello, world!"\->split\->length();
 381 .Ve
 382 .PP
 383 However, using these default bindings is not recommended as there's no guarantee that another
 384 piece of code won't trample over the same namespace/methods.
 385 .SH "OPTIONS"
 386 .IX Header "OPTIONS"
 387 A mapping from native types to their user-defined classes can be specified
 388 by passing a list of key/value pairs to the \f(CW\*(C`use autobox\*(C'\fR statement.
 389 .PP
 390 The following example shows the range of valid arguments:
 391 .PP
 392 .Vb 10
 393 \&    use autobox
 394 \&        SCALAR    => \*(AqMyScalar\*(Aq                     # class name
 395 \&        ARRAY     => \*(AqMyNamespace::\*(Aq,               # class prefix (ending in \*(Aq::\*(Aq)
 396 \&        HASH      => [ \*(AqMyHash\*(Aq, \*(AqMyNamespace::\*(Aq ], # one or more class names and/or prefixes
 397 \&        CODE      => ...,                           # any of the 3 value types above
 398 \&        INTEGER   => ...,                           # any of the 3 value types above
 399 \&        FLOAT     => ...,                           # any of the 3 value types above
 400 \&        NUMBER    => ...,                           # any of the 3 value types above
 401 \&        STRING    => ...,                           # any of the 3 value types above
 402 \&        UNDEF     => ...,                           # any of the 3 value types above
 403 \&        UNIVERSAL => ...,                           # any of the 3 value types above
 404 \&        DEFAULT   => ...,                           # any of the 3 value types above
 405 \&        DEBUG     => ...;                           # boolean or coderef
 406 .Ve
 407 .PP
 408 The \s-1INTEGER\s0, \s-1FLOAT\s0, \s-1NUMBER\s0, \s-1STRING\s0, \s-1SCALAR\s0, \s-1ARRAY\s0, \s-1HASH\s0, \s-1CODE\s0, \s-1UNDEF\s0, \s-1DEFAULT\s0 and \s-1UNIVERSAL\s0 options can take
 409 three different types of value:
 410 .IP "\(bu" 4
 411 A class name e.g.
 412 .Sp
 413 .Vb 1
 414 \&    use autobox INTEGER => \*(AqMyInt\*(Aq;
 415 .Ve
 416 .Sp
 417 This binds the specified native type to the specified class. All methods invoked on
 418 literals or values of type \f(CW\*(C`key\*(C'\fR will be dispatched as methods of the class specified in
 419 the corresponding \f(CW\*(C`value\*(C'\fR.
 420 .IP "\(bu" 4
 421 A namespace: this is a class prefix (up to and including the final '::')
 422 to which the specified type name (\s-1INTEGER\s0, \s-1FLOAT\s0, \s-1STRING\s0 &c.) will be appended:
 423 .Sp
 424 Thus:
 425 .Sp
 426 .Vb 1
 427 \&    use autobox ARRAY => \*(AqPrelude::\*(Aq;
 428 .Ve
 429 .Sp
 430 is equivalent to:
 431 .Sp
 432 .Vb 1
 433 \&    use autobox ARRAY => \*(AqPrelude::ARRAY\*(Aq;
 434 .Ve
 435 .IP "\(bu" 4
 436 A reference to an array of class names and/or namespaces. This associates multiple classes with the
 437 specified type.
 438 .SS "\s-1DEFAULT\s0"
 439 .IX Subsection "DEFAULT"
 440 The \f(CW\*(C`DEFAULT\*(C'\fR option specifies bindings for any of the four default types (\s-1SCALAR\s0, \s-1ARRAY\s0, \s-1HASH\s0 and \s-1CODE\s0)
 441 not supplied in the \f(CW\*(C`use autobox\*(C'\fR statement. As with the other options, the \f(CW\*(C`value\*(C'\fR corresponding to
 442 the \f(CW\*(C`DEFAULT\*(C'\fR \f(CW\*(C`key\*(C'\fR can be a class name, a namespace, or a reference to an array containing one or
 443 more class names and/or namespaces.
 444 .PP
 445 Thus:
 446 .PP
 447 .Vb 3
 448 \&    use autobox
 449 \&        STRING  => \*(AqMyString\*(Aq,
 450 \&        DEFAULT => \*(AqMyDefault\*(Aq;
 451 .Ve
 452 .PP
 453 is equivalent to:
 454 .PP
 455 .Vb 6
 456 \&    use autobox
 457 \&        STRING  => \*(AqMyString\*(Aq,
 458 \&        SCALAR  => \*(AqMyDefault\*(Aq,
 459 \&        ARRAY   => \*(AqMyDefault\*(Aq,
 460 \&        HASH    => \*(AqMyDefault\*(Aq,
 461 \&        CODE    => \*(AqMyDefault\*(Aq;
 462 .Ve
 463 .PP
 464 Which in turn is equivalent to:
 465 .PP
 466 .Vb 7
 467 \&    use autobox
 468 \&        INTEGER => \*(AqMyDefault\*(Aq,
 469 \&        FLOAT   => \*(AqMyDefault\*(Aq,
 470 \&        STRING  => [ \*(AqMyString\*(Aq, \*(AqMyDefault\*(Aq ],
 471 \&        ARRAY   => \*(AqMyDefault\*(Aq,
 472 \&        HASH    => \*(AqMyDefault\*(Aq,
 473 \&        CODE    => \*(AqMyDefault\*(Aq;
 474 .Ve
 475 .PP
 476 Namespaces in \s-1DEFAULT\s0 values have the default type name appended, which, in the case of defaulted \s-1SCALAR\s0 types,
 477 is \s-1SCALAR\s0 rather than \s-1INTEGER\s0, \s-1FLOAT\s0 &c.
 478 .PP
 479 Thus:
 480 .PP
 481 .Vb 5
 482 \&    use autobox
 483 \&        ARRAY   => \*(AqMyArray\*(Aq,
 484 \&        HASH    => \*(AqMyHash\*(Aq,
 485 \&        CODE    => \*(AqMyCode\*(Aq,
 486 \&        DEFAULT => \*(AqMyNamespace::\*(Aq;
 487 .Ve
 488 .PP
 489 is equivalent to:
 490 .PP
 491 .Vb 7
 492 \&    use autobox
 493 \&        INTEGER => \*(AqMyNamespace::SCALAR\*(Aq,
 494 \&        FLOAT   => \*(AqMyNamespace::SCALAR\*(Aq,
 495 \&        STRING  => \*(AqMyNamespace::SCALAR\*(Aq,
 496 \&        ARRAY   => \*(AqMyArray\*(Aq,
 497 \&        HASH    => \*(AqMyArray\*(Aq,
 498 \&        CODE    => \*(AqMyCode\*(Aq;
 499 .Ve
 500 .PP
 501 Any of the four default types can be exempted from defaulting to the \s-1DEFAULT\s0 value by supplying a value of undef:
 502 .PP
 503 .Vb 3
 504 \&    use autobox
 505 \&        HASH    => undef,
 506 \&        DEFAULT => \*(AqMyDefault\*(Aq;
 507 \&
 508 \&    42\->foo # ok: MyDefault::foo
 509 \&    []\->bar # ok: MyDefault::bar
 510 \&
 511 \&    %INC\->baz # not ok: runtime error
 512 .Ve
 513 .SS "\s-1UNDEF\s0"
 514 .IX Subsection "UNDEF"
 515 The pseudotype, \s-1UNDEF\s0, can be used to autobox undefined values. These are not autoboxed by default.
 516 .PP
 517 This doesn't work:
 518 .PP
 519 .Vb 1
 520 \&    use autobox;
 521 \&
 522 \&    undef\->foo() # runtime error
 523 .Ve
 524 .PP
 525 This works:
 526 .PP
 527 .Vb 1
 528 \&    use autobox UNDEF => \*(AqMyUndef\*(Aq;
 529 \&
 530 \&    undef\->foo(); # ok
 531 .Ve
 532 .PP
 533 So does this:
 534 .PP
 535 .Vb 1
 536 \&    use autobox UNDEF => \*(AqMyNamespace::\*(Aq;
 537 \&
 538 \&    undef\->foo(); # ok
 539 .Ve
 540 .SS "\s-1NUMBER\s0, \s-1SCALAR\s0 and \s-1UNIVERSAL\s0"
 541 .IX Subsection "NUMBER, SCALAR and UNIVERSAL"
 542 The virtual types \s-1NUMBER\s0, \s-1SCALAR\s0 and \s-1UNIVERSAL\s0 function as macros or shortcuts which create
 543 bindings for their subtypes. The type hierarchy is as follows:
 544 .PP
 545 .Vb 10
 546 \&  UNIVERSAL \-+
 547 \&             |
 548 \&             +\- SCALAR \-+
 549 \&             |          |
 550 \&             |          +\- NUMBER \-+
 551 \&             |          |          |
 552 \&             |          |          +\- INTEGER
 553 \&             |          |          |
 554 \&             |          |          +\- FLOAT
 555 \&             |          |
 556 \&             |          +\- STRING
 557 \&             |
 558 \&             +\- ARRAY
 559 \&             |
 560 \&             +\- HASH
 561 \&             |
 562 \&             +\- CODE
 563 .Ve
 564 .PP
 565 Thus:
 566 .PP
 567 .Vb 1
 568 \&    use autobox NUMBER => \*(AqMyNumber\*(Aq;
 569 .Ve
 570 .PP
 571 is equivalent to:
 572 .PP
 573 .Vb 3
 574 \&    use autobox
 575 \&        INTEGER => \*(AqMyNumber\*(Aq,
 576 \&        FLOAT   => \*(AqMyNumber\*(Aq;
 577 .Ve
 578 .PP
 579 And:
 580 .PP
 581 .Vb 1
 582 \&    use autobox SCALAR => \*(AqMyScalar\*(Aq;
 583 .Ve
 584 .PP
 585 is equivalent to:
 586 .PP
 587 .Vb 4
 588 \&    use autobox
 589 \&        INTEGER => \*(AqMyScalar\*(Aq,
 590 \&        FLOAT   => \*(AqMyScalar\*(Aq,
 591 \&        STRING  => \*(AqMyScalar\*(Aq;
 592 .Ve
 593 .PP
 594 Virtual types can also be passed to \f(CW\*(C`unimport\*(C'\fR via the \f(CW\*(C`no autobox\*(C'\fR syntax. This disables autoboxing
 595 for the corresponding subtypes e.g.
 596 .PP
 597 .Vb 1
 598 \&    no autobox qw(NUMBER);
 599 .Ve
 600 .PP
 601 is equivalent to:
 602 .PP
 603 .Vb 1
 604 \&    no autobox qw(INTEGER FLOAT);
 605 .Ve
 606 .PP
 607 Virtual type bindings can be mixed with ordinary bindings to provide fine-grained control over
 608 inheritance and delegation. For instance:
 609 .PP
 610 .Vb 4
 611 \&    use autobox
 612 \&        INTEGER => \*(AqMyInteger\*(Aq,
 613 \&        NUMBER  => \*(AqMyNumber\*(Aq,
 614 \&        SCALAR  => \*(AqMyScalar\*(Aq;
 615 .Ve
 616 .PP
 617 would result in the following bindings:
 618 .PP
 619 .Vb 3
 620 \&    42\->foo             \-> [ MyInteger, MyNumber, MyScalar ]
 621 \&    3.1415927\->bar      \-> [ MyNumber, MyScalar ]
 622 \&    "Hello, world!\->baz \-> [ MyScalar ]
 623 .Ve
 624 .PP
 625 Note that \s-1DEFAULT\s0 bindings take precedence over virtual type bindings i.e.
 626 .PP
 627 .Vb 3
 628 \&    use autobox
 629 \&        UNIVERSAL => \*(AqMyUniversal\*(Aq,
 630 \&        DEFAULT   => \*(AqMyDefault\*(Aq; # default SCALAR, ARRAY, HASH and CODE before UNIVERSAL
 631 .Ve
 632 .PP
 633 is equivalent to:
 634 .PP
 635 .Vb 3
 636 \&  use autobox
 637 \&      INTEGER => [ \*(AqMyDefault\*(Aq, \*(AqMyUniversal\*(Aq ],
 638 \&      FLOAT   => [ \*(AqMyDefault\*(Aq, \*(AqMyUniversal\*(Aq ], # ... &c.
 639 .Ve
 640 .SS "\s-1DEBUG\s0"
 641 .IX Subsection "DEBUG"
 642 \&\f(CW\*(C`DEBUG\*(C'\fR exposes the current bindings for the scope in which \f(CW\*(C`use autobox\*(C'\fR is called by means
 643 of a callback, or a static debugging function.
 644 .PP
 645 This allows the computed bindings to be seen in \*(L"longhand\*(R".
 646 .PP
 647 The option is ignored if the value corresponding to the \f(CW\*(C`DEBUG\*(C'\fR key is false.
 648 .PP
 649 If the value is a \s-1CODE\s0 ref, then this sub is called with a reference to
 650 the hash containing the computed bindings for the current scope.
 651 .PP
 652 Finally, if \f(CW\*(C`DEBUG\*(C'\fR is true but not a \s-1CODE\s0 ref, the bindings are dumped
 653 to \s-1STDERR\s0.
 654 .PP
 655 Thus:
 656 .PP
 657 .Vb 1
 658 \&    use autobox DEBUG => 1, ...
 659 .Ve
 660 .PP
 661 or
 662 .PP
 663 .Vb 1
 664 \&    use autobox DEBUG => sub { ... }, ...
 665 .Ve
 666 .PP
 667 or
 668 .PP
 669 .Vb 4
 670 \&    sub my_callback ($) {
 671 \&        my $hashref = shift;
 672 \&        ...
 673 \&    }
 674 \&
 675 \&    use autobox DEBUG => \e&my_callback, ...
 676 .Ve
 677 .SH "METHODS"
 678 .IX Header "METHODS"
 679 .SS "import"
 680 .IX Subsection "import"
 681 On its own, \f(CW\*(C`autobox\*(C'\fR doesn't implement any methods that can be called on native types.
 682 However, its static method, \f(CW\*(C`import\*(C'\fR, can be used to implement \f(CW\*(C`autobox\*(C'\fR extensions i.e.
 683 lexically scoped modules that provide \f(CW\*(C`autobox\*(C'\fR bindings for one or more native types without requiring
 684 calling code to \f(CW\*(C`use autobox\*(C'\fR.
 685 .PP
 686 This is done by subclassing \f(CW\*(C`autobox\*(C'\fR and overriding \f(CW\*(C`import\*(C'\fR. This allows extensions to effectively
 687 translate \f(CW\*(C`use MyModule\*(C'\fR into a bespoke \f(CW\*(C`use autobox\*(C'\fR call. e.g.:
 688 .PP
 689 .Vb 1
 690 \&    package String::Trim;
 691 \&
 692 \&    use base qw(autobox);
 693 \&
 694 \&    sub import {
 695 \&        my $class = shift;
 696 \&        $class\->SUPER::import(STRING => \*(AqString::Trim::Scalar\*(Aq);
 697 \&    }
 698 \&
 699 \&    package String::Trim::Scalar;
 700 \&
 701 \&    sub trim {
 702 \&        my $string = shift;
 703 \&        $string =~ s/^\es+//;
 704 \&        $string =~ s/\es+$//;
 705 \&        $string;
 706 \&    }
 707 \&
 708 \&    1;
 709 .Ve
 710 .PP
 711 Note that \f(CW\*(C`trim\*(C'\fR is defined in an auxilliary class rather than in \f(CW\*(C`String::Trim\*(C'\fR itself to prevent
 712 \&\f(CW\*(C`String::Trim\*(C'\fR's own methods (i.e. the methods it inherits from \f(CW\*(C`autobox\*(C'\fR) being exposed to \s-1SCALAR\s0 types.
 713 .PP
 714 This module can now be used without a \f(CW\*(C`use autobox\*(C'\fR statement to enable the \f(CW\*(C`trim\*(C'\fR method in the current
 715 lexical scope. e.g.:
 716 .PP
 717 .Vb 1
 718 \&    #!/usr/bin/env perl
 719 \&
 720 \&    use String::Trim;
 721 \&
 722 \&    print "  Hello, world!  "\->trim();
 723 .Ve
 724 .SH "EXPORTS"
 725 .IX Header "EXPORTS"
 726 Although \f(CW\*(C`autobox\*(C'\fR doesn't export anything, it includes an additional module, \f(CW\*(C`autobox::universal\*(C'\fR,
 727 which exports a single subroutine, \f(CW\*(C`type\*(C'\fR.
 728 .SS "type"
 729 .IX Subsection "type"
 730 This sub returns the type of its argument within \f(CW\*(C`autobox\*(C'\fR (which is essentially longhand for the type names
 731 used within perl). This value is used by \f(CW\*(C`autobox\*(C'\fR to associate a method invocant with its designated classes. e.g.
 732 .PP
 733 .Vb 1
 734 \&    use autobox::universal qw(type);
 735 \&
 736 \&    type("Hello, world!") # STRING
 737 \&    type(42)              # INTEGER
 738 \&    type([ ])             # ARRAY
 739 \&    type(sub { })         # CODE
 740 .Ve
 741 .PP
 742 \&\f(CW\*(C`autobox::universal\*(C'\fR is loaded automatically by \f(CW\*(C`autobox\*(C'\fR, and, as its name suggests, can be used to install
 743 a universal method (i.e. a method for all \f(CW\*(C`autobox\*(C'\fR types) e.g.
 744 .PP
 745 .Vb 1
 746 \&    use autobox UNIVERSAL => \*(Aqautobox::universal\*(Aq;
 747 \&
 748 \&    42\->type        # INTEGER
 749 \&    3.1415927\->type # FLOAT
 750 \&    %ENV\->type      # HASH
 751 .Ve
 752 .SH "CAVEATS"
 753 .IX Header "CAVEATS"
 754 .SS "Performance"
 755 .IX Subsection "Performance"
 756 Autoboxing comes at a price. Calling
 757 .PP
 758 .Vb 1
 759 \&    "Hello, world!"\->length()
 760 .Ve
 761 .PP
 762 is slightly slower than the equivalent method call on a string-like object, and significantly slower than
 763 .PP
 764 .Vb 1
 765 \&    length("Hello, world!")
 766 .Ve
 767 .SS "Gotchas"
 768 .IX Subsection "Gotchas"
 769 \fIPrecedence\fR
 770 .IX Subsection "Precedence"
 771 .PP
 772 Due to Perl's precedence rules, some autoboxed literals may need to be parenthesized:
 773 .PP
 774 For instance, while this works:
 775 .PP
 776 .Vb 1
 777 \&    my $curried = sub { ... }\->curry();
 778 .Ve
 779 .PP
 780 this doesn't:
 781 .PP
 782 .Vb 1
 783 \&    my $curried = \e&foo\->curry();
 784 .Ve
 785 .PP
 786 The solution is to wrap the reference in parentheses:
 787 .PP
 788 .Vb 1
 789 \&    my $curried = (\e&foo)\->curry();
 790 .Ve
 791 .PP
 792 The same applies for signed integer and float literals:
 793 .PP
 794 .Vb 2
 795 \&    # this works
 796 \&    my $range = 10\->to(1);
 797 \&
 798 \&    # this doesn\*(Aqt work
 799 \&    my $range = \-10\->to(10);
 800 \&
 801 \&    # this works
 802 \&    my $range = (\-10)\->to(10);
 803 .Ve
 804 .PP
 805 \fIprint \s-1BLOCK\s0\fR
 806 .IX Subsection "print BLOCK"
 807 .PP
 808 Perl's special-casing for the \f(CW\*(C`print BLOCK ...\*(C'\fR syntax (see perlsub) means that \f(CW\*(C`print { expression() } ...\*(C'\fR
 809 (where the curly brackets denote an anonymous \s-1HASH\s0 ref) may require some further disambiguation:
 810 .PP
 811 .Vb 2
 812 \&    # this works (
 813 \&    print { foo => \*(Aqbar\*(Aq }\->foo();
 814 \&
 815 \&    # and this
 816 \&    print { \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq }\->foo();
 817 \&
 818 \&    # and even this
 819 \&    print { \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, @_ }\->foo();
 820 \&
 821 \&    # but this doesn\*(Aqt
 822 \&    print { @_ }\->foo() ? 1 : 0
 823 .Ve
 824 .PP
 825 In the latter case, the solution is to supply something
 826 other than a \s-1HASH\s0 ref literal as the first argument
 827 to \f(CW\*(C`print()\*(C'\fR:
 828 .PP
 829 .Vb 2
 830 \&    # e.g.
 831 \&    print STDOUT { @_ }\->foo() ? 1 : 0;
 832 \&
 833 \&    # or
 834 \&    my $hashref = { @_ };
 835 \&    print $hashref\->foo() ? 1 : 0;
 836 \&
 837 \&    # or
 838 \&    print \*(Aq\*(Aq, { @_ }\->foo() ? 1 : 0;
 839 \&
 840 \&    # or
 841 \&    print \*(Aq\*(Aq . { @_ }\->foo() ? 1 : 0;
 842 \&
 843 \&    # or even
 844 \&    { @_ }\->print_if_foo(1, 0);
 845 .Ve
 846 .PP
 847 \fI\s-1VERSION\s0, import and unimport\fR
 848 .IX Subsection "VERSION, import and unimport"
 849 .PP
 850 Although \f(CW\*(C`can\*(C'\fR and \f(CW\*(C`isa\*(C'\fR work as expected for autoboxed values, the \f(CW\*(C`VERSION\*(C'\fR method doesn't.
 851 Thus, while these work:
 852 .PP
 853 .Vb 1
 854 \&    [ ... ]\->can(\*(Aqpop\*(Aq)
 855 \&
 856 \&    3.1415\->isa(\*(AqMyScalar\*(Aq)
 857 .Ve
 858 .PP
 859 This doesn't:
 860 .PP
 861 .Vb 2
 862 \&    use MyScalar 1.23;
 863 \&    use autobox SCALAR => \*(AqMyScalar\*(Aq;
 864 \&
 865 \&    print "Hello, world!"\->VERSION();
 866 .Ve
 867 .PP
 868 Though, of course:
 869 .PP
 870 .Vb 1
 871 \&    print MyScalar\->VERSION();
 872 .Ve
 873 .PP
 874 and
 875 .PP
 876 .Vb 1
 877 \&    print $MyScalar::VERSION;
 878 .Ve
 879 .PP
 880 continue to work.
 881 .PP
 882 Likewise, \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`unimport\*(C'\fR are unaffected by the autobox pragma:
 883 .PP
 884 .Vb 2
 885 \&    # equivalent to Foo\->import() rather than MyScalar\->import(\*(AqFoo\*(Aq)
 886 \&    \*(AqFoo\*(Aq\->import()
 887 \&
 888 \&    # error: Can\*(Aqt call method "import" on unblessed reference
 889 \&    []\->import()
 890 .Ve
 891 .PP
 892 \fIeval \s-1EXPR\s0\fR
 893 .IX Subsection "eval EXPR"
 894 .PP
 895 Like most pragmas autobox performs some of its operations at compile time, and,
 896 as a result, runtime string \f(CW\*(C`eval\*(C'\fRs are not executed within its scope i.e. this
 897 doesn't work:
 898 .PP
 899 .Vb 1
 900 \&    use autobox;
 901 \&
 902 \&    eval "42\->foo";
 903 .Ve
 904 .PP
 905 The workaround is to use autobox within the \f(CW\*(C`eval\*(C'\fR e.g.
 906 .PP
 907 .Vb 4
 908 \&    eval <<\*(AqEOS\*(Aq;
 909 \&        use autobox;
 910 \&        42\->foo();
 911 \&    EOS
 912 .Ve
 913 .PP
 914 Note that the \f(CW\*(C`eval BLOCK\*(C'\fR form works as expected:
 915 .PP
 916 .Vb 1
 917 \&    use autobox;
 918 \&
 919 \&    eval { 42\->foo() }; # OK
 920 .Ve
 921 .SH "VERSION"
 922 .IX Header "VERSION"
 923 2.55
 924 .SH "SEE ALSO"
 925 .IX Header "SEE ALSO"
 926 .IP "\(bu" 4
 927 autobox::Closure::Attributes
 928 .IP "\(bu" 4
 929 autobox::Core
 930 .IP "\(bu" 4
 931 autobox::DateTime::Duration
 932 .IP "\(bu" 4
 933 autobox::Encode
 934 .IP "\(bu" 4
 935 Moose::Autobox
 936 .IP "\(bu" 4
 937 Perl6::Contexts
 938 .IP "\(bu" 4
 939 Scalar::Properties
 940 .IP "\(bu" 4
 941 Shell::Autobox
 942 .SH "AUTHOR"
 943 .IX Header "AUTHOR"
 944 chocolateboy <chocolate.boy@email.com>
 945 .SH "COPYRIGHT"
 946 .IX Header "COPYRIGHT"
 947 Copyright (c) 2003\-2008, chocolateboy.
 948 .PP
 949 This module is free software. It may be used, redistributed
 950 and/or modified under the same terms as Perl itself.