DEFAULT

The "DEFAULT" option specifies bindings for any of the four default types (SCALAR, ARRAY, HASH and CODE) not supplied in the "use autobox" statement. As with the other options, the "value" corresponding to the "DEFAULT" "key" can be a class name, a namespace, or a reference to an array containing one or more class names and/or namespaces.

Thus:

    use autobox {
        STRING  => 'MyString',
        DEFAULT => 'MyDefault',
    }

is equivalent to:

    use autobox {
        STRING  => 'MyString',
        SCALAR  => 'MyDefault',
        ARRAY   => 'MyDefault',
        HASH    => 'MyDefault',
        CODE    => 'MyDefault',
    }

Which in turn is equivalent to:

    use autobox {
        INTEGER => 'MyDefault',
        FLOAT   => 'MyDefault',
        STRING  => [ 'MyString', 'MyDefault' ],
        ARRAY   => 'MyDefault',
        HASH    => 'MyDefault',
        CODE    => 'MyDefault',
    }

Namespaces in DEFAULT values have the default type name appended, which, in the case of defaulted SCALAR types, is SCALAR rather than INTEGER, FLOAT &c.

Thus:

    use autobox {
        ARRAY   => 'MyArray',
        HASH    => 'MyHash',
        CODE    => 'MyCode',
        DEFAULT => 'MyNamespace::',
    }

is equivalent to:

    use autobox {
        INTEGER => 'MyNamespace::SCALAR',
        FLOAT   => 'MyNamespace::SCALAR',
        STRING  => 'MyNamespace::SCALAR',
        ARRAY   => 'MyArray',
        HASH    => 'MyArray',
        CODE    => 'MyCode',
    }

Any of the four default types can be exempted from defaulting to the DEFAULT value by supplying a value of undef:

    use autobox {
        HASH    => undef,
        DEFAULT => 'MyDefault',
    }
    42->foo # ok: MyDefault::foo
    []->bar # ok: MyDefault::bar
    %INC->baz # not ok: runtime error

UNDEF

The pseudotype, UNDEF, can be used to autobox undefined values. These are not autoboxed by default.

This doesn't work:

    use autobox;
    undef->foo() # runtime error

This works:

    use autobox UNDEF => 'MyUndef';
    undef->foo(); # ok

So does this:

    use autobox UNDEF => 'MyNamespace::';
    undef->foo(); # ok

NUMBER, SCALAR and UNIVERSAL

The virtual types NUMBER, SCALAR and UNIVERSAL function as macros or shortcuts which create bindings for their subtypes. The type hierarchy is as follows:

  UNIVERSAL -+
             |
             +- SCALAR -+
             |          |
             |          +- NUMBER -+
             |          |          |
             |          |          +- INTEGER
             |          |          |
             |          |          +- FLOAT
             |          |
             |          +- STRING
             |
             +- ARRAY
             |
             +- HASH
             |
             +- CODE

Thus:

    use autobox NUMBER => 'MyNumber';

is equivalent to:

    use autobox {
        INTEGER => 'MyNumber',
        FLOAT   => 'MyNumber',
    }

And:

    use autobox SCALAR => 'MyScalar';

is equivalent to:

    use autobox {
        INTEGER => 'MyScalar',
        FLOAT   => 'MyScalar',
        STRING  => 'MyScalar',
    }

Virtual types can also be passed to "unimport" via the "no autobox" syntax. This disables autoboxing for the corresponding subtypes e.g.

    no autobox qw(NUMBER);

is equivalent to:

    no autobox qw(INTEGER FLOAT);

Virtual type bindings can be mixed with ordinary bindings to provide fine-grained control over inheritance and delegation. For instance:

    use autobox {
        INTEGER => 'MyInteger',
        NUMBER  => 'MyNumber',
        SCALAR  => 'MyScalar',
    }

would result in the following bindings:

    42->foo              -> [ MyInteger, MyNumber, MyScalar ]
    3.1415927->bar       -> [ MyNumber, MyScalar ]
    "Hello, world!"->baz -> [ MyScalar ]

Note that DEFAULT bindings take precedence over virtual type bindings i.e.

    use autobox {
        UNIVERSAL => 'MyUniversal',
        DEFAULT   => 'MyDefault', # default SCALAR, ARRAY, HASH and CODE before UNIVERSAL
    }

is equivalent to:

  use autobox {
      INTEGER => [ 'MyDefault', 'MyUniversal' ],
      FLOAT   => [ 'MyDefault', 'MyUniversal' ], # ... &c.
  }

DEBUG

"DEBUG" allows the autobox bindings for the current scope to be inspected, either by dumping them to the console or passing them to a callback function. This allows the computed bindings to be seen in "longhand".

The option is ignored if the value corresponding to the "DEBUG" key is false.

If the value is a CODE ref, it is called with a reference to the hash containing the computed bindings for the current scope.

Finally, if "DEBUG" is true but not a CODE ref, the bindings are dumped to STDERR.

Thus:

    use autobox DEBUG => 1, ...

or

    use autobox DEBUG => sub { ... }, ...

or

    sub my_callback ($) {
        my $hashref = shift;
        ...
    }
    use autobox DEBUG => \&my_callback, ...

import

This method sets up autobox bindings for the current lexical scope. It can be used to implement autobox extensions i.e. lexically-scoped modules that provide autobox bindings for one or more native types without requiring calling code to "use autobox".

This is done by subclassing autobox and overriding "import". This allows extensions to effectively translate "use MyModule" into a bespoke "use autobox" call e.g.:

    package String::Trim;
    use base qw(autobox);
    sub import {
        my $class = shift;
        $class->SUPER::import(
            STRING => 'String::Trim::String'
        );
    }
    package String::Trim::String;
    sub trim {
        my $string = shift;
        $string =~ s/^\s+//;
        $string =~ s/\s+$//;
        $string;
    }
    1;

Note that "trim" is defined in an auxiliary class rather than in String::Trim itself to prevent String::Trim's own methods (i.e. the methods it inherits from autobox) being exposed to "STRING" types.

This module can now be used without a "use autobox" statement to enable the "trim" method in the current lexical scope e.g.:

    #!/usr/bin/env perl
    use String::Trim;
    print "  Hello, world!  "->trim();

autobox_class

autobox adds a single method to all autoboxed types: "autobox_class". This can be used to call UNIVERSAL methods i.e. "can", "DOES", "import", "isa", "unimport" and "VERSION" e.g.

    if (sub { ... }->autobox_class->can('curry')) ...
    if (42->autobox_class->isa('SCALAR')) ...

Note: "autobox_class" must always be used when calling these methods. Calling them directly on native types produces the same results as calling them with autobox disabled e.g.:

    42->isa('NUMBER') # "" (interpeted as "42"->isa("NUMBER"))
    []->can('push')   # Error: Can't call method "can" on unblessed reference

type

autobox includes an additional module, autobox::universal, which exports a single subroutine, "type".

This sub returns the type of its argument within autobox (which is essentially longhand for the type names used within perl). This value is used by autobox to associate a method invocant with its designated classes e.g.

    use autobox::universal qw(type);
    type("42")  # STRING
    type(42)    # INTEGER
    type(42.0)  # FLOAT
    type(undef) # UNDEF

autobox::universal is loaded automatically by autobox, and, as its name suggests, can be used to install a universal "type" method for autoboxed values e.g.

    use autobox UNIVERSAL => 'autobox::universal';
    42->type        # INTEGER
    3.1415927->type # FLOAT
    %ENV->type      # HASH

Performance

Calling

    "Hello, world!"->length()

is slightly slower than the equivalent method call on a string-like object, and significantly slower than

    length("Hello, world!")

Gotchas

Precedence

Due to Perl's precedence rules, some autoboxed literals may need to be parenthesized:

For instance, while this works:

    my $curried = sub { ... }->curry();

this doesn't:

    my $curried = \&foo->curry();

The solution is to wrap the reference in parentheses:

    my $curried = (\&foo)->curry();

The same applies for signed integer and float literals:

    # this works
    my $range = 10->to(1);
    # this doesn't work
    my $range = -10->to(10);
    # this works
    my $range = (-10)->to(10);

print BLOCK

Perl's special-casing for the "print BLOCK ..." syntax (see perlsub) means that "print { expression() } ..." (where the curly brackets denote an anonymous HASH ref) may require some further disambiguation:

    # this works
    print { foo => 'bar' }->foo();
    # and this
    print { 'foo', 'bar' }->foo();
    # and even this
    print { 'foo', 'bar', @_ }->foo();
    # but this doesn't
    print { @_ }->foo() ? 1 : 0

In the latter case, the solution is to supply something other than a HASH ref literal as the first argument to "print()":

    # e.g.
    print STDOUT { @_ }->foo() ? 1 : 0;
    # or
    my $hashref = { @_ };
    print $hashref->foo() ? 1 : 0;
    # or
    print '', { @_ }->foo() ? 1 : 0;
    # or
    print '' . { @_ }->foo() ? 1 : 0;
    # or even
    { @_ }->print_if_foo(1, 0);

eval EXPR

Like most pragmas, autobox performs operations at compile time, and, as a result, runtime string "eval"s are not executed within its scope i.e. this doesn't work:

    use autobox;
    eval "42->foo";

The workaround is to use autobox within the "eval" e.g.

    eval <<'EOS';
        use autobox;
        42->foo();
    EOS

Note that the "eval BLOCK" form works as expected:

    use autobox;
    eval { 42->foo() }; # OK

Operator Overloading

Operator overloading via the overload pragma doesn't (automatically) work. autobox works by lexically overriding the arrow operator. It doesn't bless native types into objects, so overloading - or any other kind of "magic" which depends on values being blessed - doesn't apply.