1autobox(3) User Contributed Perl Documentation autobox(3)
2
6 autobox - call methods on native types
7
9 use autobox;
10 # integers
12 my $range = 10->to(1); # [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
14 # floats
16 my $error = 3.1415927->minus(22/7)->abs();
18 # strings
20 my @list = 'SELECT * FROM foo'->list();
22 my $greeting = "Hello, world!"->upper(); # "HELLO, WORLD!"
23 $greeting->for_each(\&character_handler);
25 # arrays and array refs
27 my $schwartzian = @_->map(...)->sort(...)->map(...);
29 my $hash = [ 'SELECT * FROM foo WHERE id IN (?, ?)', 1, 2 ]->hash();
30 # hashes and hash refs
32 { alpha => 'beta', gamma => 'vlissides' }->for_each(...);
34 %hash->keys();
35 # code refs
37 my $plus_five = (\&add)->curry()->(5);
39 my $minus_three = sub { $_[0] - $_[1] }->reverse->curry->(3);
40 # can, isa, VERSION, import and unimport can be accessed via autobox_class
42 42->autobox_class->isa('MyNumber')
44 say []->autobox_class->VERSION
45
47 The autobox pragma allows methods to be called on integers, floats,
48 strings, arrays, hashes, and code references in exactly the same manner
49 as blessed references.
50 Autoboxing is transparent: values are not blessed into their (user-
52 defined) implementation class (unless the method elects to bestow such
53 a blessing) - they simply use its methods as though they are.
54 The classes (packages) into which the native types are boxed are fully
56 configurable. By default, a method invoked on a non-object value is
57 assumed to be defined in a class whose name corresponds to the "ref()"
58 type of that value - or SCALAR if the value is a non-reference.
59 This mapping can be overridden by passing key/value pairs to the "use
61 autobox" statement, in which the keys represent native types, and the
62 values their associated classes.
63 As with regular objects, autoboxed values are passed as the first
65 argument of the specified method. Consequently, given a vanilla "use
66 autobox":
67 "Hello, world!"->upper()
69 is invoked as:
71 SCALAR::upper("hello, world!")
73 while:
75 [ 1 .. 10 ]->for_each(sub { ... })
77 resolves to:
79 ARRAY::for_each([ 1 .. 10 ], sub { ... })
81 Values beginning with the array "@" and hash "%" sigils are passed by
83 reference, i.e. under the default bindings:
84 @array->join(', ')
86 @{ ... }->length()
87 %hash->keys()
88 %$hash->values()
89 are equivalent to:
91 ARRAY::join(\@array, ', ')
93 ARRAY::length(\@{ ... })
94 HASH::keys(\%hash)
95 HASH::values(\%$hash)
96 Multiple "use autobox" statements can appear in the same scope. These
98 are merged both "horizontally" (i.e. multiple classes can be
99 associated with a particular type) and "vertically" (i.e. multiple
100 classes can be associated with multiple types).
101 Thus:
103 use autobox SCALAR => 'Foo';
105 use autobox SCALAR => 'Bar';
106 - associates SCALAR types with a synthetic class whose @ISA includes
108 both Foo and Bar (in that order).
109 Likewise:
111 use autobox SCALAR => 'Foo';
113 use autobox SCALAR => 'Bar';
114 use autobox ARRAY => 'Baz';
115 and
117 use autobox SCALAR => [ 'Foo', 'Bar' ];
119 use autobox ARRAY => 'Baz';
120 - bind SCALAR types to the Foo and Bar classes and ARRAY types to Baz.
122 autobox is lexically scoped, and bindings for an outer scope can be
124 extended or countermanded in a nested scope:
125 {
127 use autobox; # default bindings: autobox all native types
128 ...
129 {
131 # appends 'MyScalar' to the @ISA associated with SCALAR types
132 use autobox SCALAR => 'MyScalar';
133 ...
134 }
135 # back to the default (no MyScalar)
137 ...
138 }
139 Autoboxing can be turned off entirely by using the "no" syntax:
141 {
143 use autobox;
144 ...
145 no autobox;
146 ...
147 }
148 - or can be selectively disabled by passing arguments to the "no
150 autobox" statement:
151 use autobox; # default bindings
153 no autobox qw(SCALAR);
155 []->foo(); # OK: ARRAY::foo([])
157 "Hello, world!"->bar(); # runtime error
159 Autoboxing is not performed for barewords i.e.
161 my $foo = Foo->new();
163 and:
165 my $foo = new Foo;
167 behave as expected.
169 Methods are called on native types by means of the arrow operator. As
171 with regular objects, the right hand side of the operator can either be
172 a bare method name or a variable containing a method name or subroutine
173 reference. Thus the following are all valid:
174 sub method1 { ... }
176 my $method2 = 'some_method';
177 my $method3 = sub { ... };
178 my $method4 = \&some_method;
179 " ... "->method1();
181 [ ... ]->$method2();
182 { ... }->$method3();
183 sub { ... }->$method4();
184 A native type is only associated with a class if the type => class
186 mapping is supplied in the "use autobox" statement. Thus the following
187 will not work:
188 use autobox SCALAR => 'MyScalar';
190 @array->some_array_method();
192 - as no class is specified for the ARRAY type. Note: the result of
194 calling a method on a native type that is not associated with a class
195 is the usual runtime error message:
196 Can't call method "some_array_method" on unblessed reference at ...
198 As a convenience, there is one exception to this rule. If "use autobox"
200 is invoked with no arguments (ignoring the DEBUG option) the four main
201 native types are associated with classes of the same name.
202 Thus:
204 use autobox;
206 - is equivalent to:
208 use autobox {
210 SCALAR => 'SCALAR',
211 ARRAY => 'ARRAY',
212 HASH => 'HASH',
213 CODE => 'CODE',
214 }
215 This facilitates one-liners and prototypes:
217 use autobox;
219 sub SCALAR::split { [ split '', $_[0] ] }
221 sub ARRAY::length { scalar @{$_[0]} }
222 print "Hello, world!"->split->length();
224 However, using these default bindings is not recommended as there's no
226 guarantee that another piece of code won't trample over the same
227 namespace/methods.
228
230 A mapping from native types to their user-defined classes can be
231 specified by passing a hashref or a list of key/value pairs to the "use
232 autobox" statement.
233 The following example shows the range of valid arguments:
235 use autobox {
237 SCALAR => 'MyScalar' # class name
238 ARRAY => 'MyNamespace::', # class prefix (ending in '::')
239 HASH => [ 'MyHash', 'MyNamespace::' ], # one or more class names and/or prefixes
240 CODE => ..., # any of the 3 value types above
241 INTEGER => ..., # any of the 3 value types above
242 FLOAT => ..., # any of the 3 value types above
243 NUMBER => ..., # any of the 3 value types above
244 STRING => ..., # any of the 3 value types above
245 UNDEF => ..., # any of the 3 value types above
246 UNIVERSAL => ..., # any of the 3 value types above
247 DEFAULT => ..., # any of the 3 value types above
248 DEBUG => ... # boolean or coderef
249 }
250 The INTEGER, FLOAT, NUMBER, STRING, SCALAR, ARRAY, HASH, CODE, UNDEF,
252 DEFAULT and UNIVERSAL options can take three different types of value:
253 • A class name e.g.
255 use autobox INTEGER => 'MyInt';
257 This binds the specified native type to the specified class. All
259 methods invoked on values of type "key" will be dispatched as
260 methods of the class specified in the corresponding "value".
261 • A namespace: this is a class prefix (up to and including the final
263 '::') to which the specified type name (INTEGER, FLOAT, STRING &c.)
264 will be appended:
265 Thus:
267 use autobox ARRAY => 'Prelude::';
269 is equivalent to:
271 use autobox ARRAY => 'Prelude::ARRAY';
273 • A reference to an array of class names and/or namespaces. This
275 associates multiple classes with the specified type.
276 DEFAULT
278 The "DEFAULT" option specifies bindings for any of the four default
279 types (SCALAR, ARRAY, HASH and CODE) not supplied in the "use autobox"
280 statement. As with the other options, the "value" corresponding to the
281 "DEFAULT" "key" can be a class name, a namespace, or a reference to an
282 array containing one or more class names and/or namespaces.
283 Thus:
285 use autobox {
287 STRING => 'MyString',
288 DEFAULT => 'MyDefault',
289 }
290 is equivalent to:
292 use autobox {
294 STRING => 'MyString',
295 SCALAR => 'MyDefault',
296 ARRAY => 'MyDefault',
297 HASH => 'MyDefault',
298 CODE => 'MyDefault',
299 }
300 Which in turn is equivalent to:
302 use autobox {
304 INTEGER => 'MyDefault',
305 FLOAT => 'MyDefault',
306 STRING => [ 'MyString', 'MyDefault' ],
307 ARRAY => 'MyDefault',
308 HASH => 'MyDefault',
309 CODE => 'MyDefault',
310 }
311 Namespaces in DEFAULT values have the default type name appended,
313 which, in the case of defaulted SCALAR types, is SCALAR rather than
314 INTEGER, FLOAT &c.
315 Thus:
317 use autobox {
319 ARRAY => 'MyArray',
320 HASH => 'MyHash',
321 CODE => 'MyCode',
322 DEFAULT => 'MyNamespace::',
323 }
324 is equivalent to:
326 use autobox {
328 INTEGER => 'MyNamespace::SCALAR',
329 FLOAT => 'MyNamespace::SCALAR',
330 STRING => 'MyNamespace::SCALAR',
331 ARRAY => 'MyArray',
332 HASH => 'MyArray',
333 CODE => 'MyCode',
334 }
335 Any of the four default types can be exempted from defaulting to the
337 DEFAULT value by supplying a value of undef:
338 use autobox {
340 HASH => undef,
341 DEFAULT => 'MyDefault',
342 }
343 42->foo # ok: MyDefault::foo
345 []->bar # ok: MyDefault::bar
346 %INC->baz # not ok: runtime error
348 UNDEF
350 The pseudotype, UNDEF, can be used to autobox undefined values. These
351 are not autoboxed by default.
352 This doesn't work:
354 use autobox;
356 undef->foo() # runtime error
358 This works:
360 use autobox UNDEF => 'MyUndef';
362 undef->foo(); # ok
364 So does this:
366 use autobox UNDEF => 'MyNamespace::';
368 undef->foo(); # ok
370 NUMBER, SCALAR and UNIVERSAL
372 The virtual types NUMBER, SCALAR and UNIVERSAL function as macros or
373 shortcuts which create bindings for their subtypes. The type hierarchy
374 is as follows:
375 UNIVERSAL -+
377 |
378 +- SCALAR -+
379 | |
380 | +- NUMBER -+
381 | | |
382 | | +- INTEGER
383 | | |
384 | | +- FLOAT
385 | |
386 | +- STRING
387 |
388 +- ARRAY
389 |
390 +- HASH
391 |
392 +- CODE
393 Thus:
395 use autobox NUMBER => 'MyNumber';
397 is equivalent to:
399 use autobox {
401 INTEGER => 'MyNumber',
402 FLOAT => 'MyNumber',
403 }
404 And:
406 use autobox SCALAR => 'MyScalar';
408 is equivalent to:
410 use autobox {
412 INTEGER => 'MyScalar',
413 FLOAT => 'MyScalar',
414 STRING => 'MyScalar',
415 }
416 Virtual types can also be passed to "unimport" via the "no autobox"
418 syntax. This disables autoboxing for the corresponding subtypes e.g.
419 no autobox qw(NUMBER);
421 is equivalent to:
423 no autobox qw(INTEGER FLOAT);
425 Virtual type bindings can be mixed with ordinary bindings to provide
427 fine-grained control over inheritance and delegation. For instance:
428 use autobox {
430 INTEGER => 'MyInteger',
431 NUMBER => 'MyNumber',
432 SCALAR => 'MyScalar',
433 }
434 would result in the following bindings:
436 42->foo -> [ MyInteger, MyNumber, MyScalar ]
438 3.1415927->bar -> [ MyNumber, MyScalar ]
439 "Hello, world!"->baz -> [ MyScalar ]
440 Note that DEFAULT bindings take precedence over virtual type bindings
442 i.e.
443 use autobox {
445 UNIVERSAL => 'MyUniversal',
446 DEFAULT => 'MyDefault', # default SCALAR, ARRAY, HASH and CODE before UNIVERSAL
447 }
448 is equivalent to:
450 use autobox {
452 INTEGER => [ 'MyDefault', 'MyUniversal' ],
453 FLOAT => [ 'MyDefault', 'MyUniversal' ], # ... &c.
454 }
455 DEBUG
457 "DEBUG" allows the autobox bindings for the current scope to be
458 inspected, either by dumping them to the console or passing them to a
459 callback function. This allows the computed bindings to be seen in
460 "longhand".
461 The option is ignored if the value corresponding to the "DEBUG" key is
463 false.
464 If the value is a CODE ref, it is called with a reference to the hash
466 containing the computed bindings for the current scope.
467 Finally, if "DEBUG" is true but not a CODE ref, the bindings are dumped
469 to STDERR.
470 Thus:
472 use autobox DEBUG => 1, ...
474 or
476 use autobox DEBUG => sub { ... }, ...
478 or
480 sub my_callback ($) {
482 my $hashref = shift;
483 ...
484 }
485 use autobox DEBUG => \&my_callback, ...
487
489 import
490 This method sets up autobox bindings for the current lexical scope. It
491 can be used to implement autobox extensions i.e. lexically-scoped
492 modules that provide autobox bindings for one or more native types
493 without requiring calling code to "use autobox".
494 This is done by subclassing autobox and overriding "import". This
496 allows extensions to effectively translate "use MyModule" into a
497 bespoke "use autobox" call e.g.:
498 package String::Trim;
500 use base qw(autobox);
502 sub import {
504 my $class = shift;
505 $class->SUPER::import(
507 STRING => 'String::Trim::String'
508 );
509 }
510 package String::Trim::String;
512 sub trim {
514 my $string = shift;
515 $string =~ s/^\s+//;
516 $string =~ s/\s+$//;
517 $string;
518 }
519 1;
521 Note that "trim" is defined in an auxiliary class rather than in
523 String::Trim itself to prevent String::Trim's own methods (i.e. the
524 methods it inherits from autobox) being exposed to "STRING" types.
525 This module can now be used without a "use autobox" statement to enable
527 the "trim" method in the current lexical scope e.g.:
528 #!/usr/bin/env perl
530 use String::Trim;
532 print " Hello, world! "->trim();
534
536 autobox_class
537 autobox adds a single method to all autoboxed types: "autobox_class".
538 This can be used to call UNIVERSAL methods i.e. "can", "DOES",
539 "import", "isa", "unimport" and "VERSION" e.g.
540 if (sub { ... }->autobox_class->can('curry')) ...
542 if (42->autobox_class->isa('SCALAR')) ...
543 Note: "autobox_class" must always be used when calling these methods.
545 Calling them directly on native types produces the same results as
546 calling them with autobox disabled e.g.:
547 42->isa('NUMBER') # "" (interpeted as "42"->isa("NUMBER"))
549 []->can('push') # Error: Can't call method "can" on unblessed reference
550
552 type
553 autobox includes an additional module, autobox::universal, which
554 exports a single subroutine, "type".
555 This sub returns the type of its argument within autobox (which is
557 essentially longhand for the type names used within perl). This value
558 is used by autobox to associate a method invocant with its designated
559 classes e.g.
560 use autobox::universal qw(type);
562 type("42") # STRING
564 type(42) # INTEGER
565 type(42.0) # FLOAT
566 type(undef) # UNDEF
567 autobox::universal is loaded automatically by autobox, and, as its name
569 suggests, can be used to install a universal "type" method for
570 autoboxed values e.g.
571 use autobox UNIVERSAL => 'autobox::universal';
573 42->type # INTEGER
575 3.1415927->type # FLOAT
576 %ENV->type # HASH
577
579 Performance
580 Calling
581 "Hello, world!"->length()
583 is slightly slower than the equivalent method call on a string-like
585 object, and significantly slower than
586 length("Hello, world!")
588 Gotchas
590 Precedence
591 Due to Perl's precedence rules, some autoboxed literals may need to be
593 parenthesized:
594 For instance, while this works:
596 my $curried = sub { ... }->curry();
598 this doesn't:
600 my $curried = \&foo->curry();
602 The solution is to wrap the reference in parentheses:
604 my $curried = (\&foo)->curry();
606 The same applies for signed integer and float literals:
608 # this works
610 my $range = 10->to(1);
611 # this doesn't work
613 my $range = -10->to(10);
614 # this works
616 my $range = (-10)->to(10);
617 print BLOCK
619 Perl's special-casing for the "print BLOCK ..." syntax (see perlsub)
621 means that "print { expression() } ..." (where the curly brackets
622 denote an anonymous HASH ref) may require some further disambiguation:
623 # this works
625 print { foo => 'bar' }->foo();
626 # and this
628 print { 'foo', 'bar' }->foo();
629 # and even this
631 print { 'foo', 'bar', @_ }->foo();
632 # but this doesn't
634 print { @_ }->foo() ? 1 : 0
635 In the latter case, the solution is to supply something other than a
637 HASH ref literal as the first argument to "print()":
638 # e.g.
640 print STDOUT { @_ }->foo() ? 1 : 0;
641 # or
643 my $hashref = { @_ };
644 print $hashref->foo() ? 1 : 0;
645 # or
647 print '', { @_ }->foo() ? 1 : 0;
648 # or
650 print '' . { @_ }->foo() ? 1 : 0;
651 # or even
653 { @_ }->print_if_foo(1, 0);
654 eval EXPR
656 Like most pragmas, autobox performs operations at compile time, and, as
658 a result, runtime string "eval"s are not executed within its scope i.e.
659 this doesn't work:
660 use autobox;
662 eval "42->foo";
664 The workaround is to use autobox within the "eval" e.g.
666 eval <<'EOS';
668 use autobox;
669 42->foo();
670 EOS
671 Note that the "eval BLOCK" form works as expected:
673 use autobox;
675 eval { 42->foo() }; # OK
677 Operator Overloading
679 Operator overloading via the overload pragma doesn't (automatically)
681 work. autobox works by lexically overriding the arrow operator. It
682 doesn't bless native types into objects, so overloading - or any other
683 kind of "magic" which depends on values being blessed - doesn't apply.
684
686 3.0.1
687
689 • autobox::Core
690 • Moose::Autobox
692 • perl5i
694 • Scalar::Properties
696
698 chocolateboy <chocolate@cpan.org>
699
701 Copyright (c) 2003-2018 by chocolateboy.
702 This library is free software; you can redistribute it and/or modify it
704 under the terms of the Artistic License 2.0
705 <http://www.opensource.org/licenses/artistic-license-2.0.php>.
706perl v5.36.0 2022-07-22 autobox(3)