—

              
HideShow 709 lines of Pod
=pod
=head1 NAME
autobox - call methods on native types
=head1 SYNOPSIS
    use autobox;
    # integers
        my $range = 10->to(1); # [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
    # floats
        my $error = 3.1415927->minus(22/7)->abs();
    # strings
        my @list = 'SELECT * FROM foo'->list();
        my $greeting = "Hello, world!"->upper(); # "HELLO, WORLD!"
        $greeting->for_each(\&character_handler);
    # arrays and array refs
        my $schwartzian = @_->map(...)->sort(...)->map(...);
        my $hash = [ 'SELECT * FROM foo WHERE id IN (?, ?)', 1, 2 ]->hash();
    # hashes and hash refs
        { alpha => 'beta', gamma => 'vlissides' }->for_each(...);
        %hash->keys();
    # code refs
        my $plus_five = (\&add)->curry()->(5);
        my $minus_three = sub { $_[0] - $_[1] }->reverse->curry->(3);
    # can, isa, VERSION, import and unimport can be accessed via autobox_class
        42->autobox_class->isa('MyNumber');
        say []->autobox_class->VERSION;
=head1 DESCRIPTION
The autobox pragma allows methods to be called on integers, floats, strings, arrays,
hashes, and code references in exactly the same manner as blessed references.
Autoboxing is transparent: values are not blessed into their (user-defined)
implementation class (unless the method elects to bestow such a blessing) - they simply
use its methods as though they are.
The classes (packages) into which the native types are boxed are fully configurable.
By default, a method invoked on a non-object value is assumed to be
defined in a class whose name corresponds to the C<ref()> type of that
value - or SCALAR if the value is a non-reference.
This mapping can be overridden by passing key/value pairs to the C<use autobox>
statement, in which the keys represent native types, and the values
their associated classes.
As with regular objects, autoboxed values are passed as the first argument of the specified method.
Consequently, given a vanilla C<use autobox>:
    "Hello, world!"->upper()
is invoked as:
    SCALAR::upper("hello, world!")
while:
    [ 1 .. 10 ]->for_each(sub { ... })
resolves to:
    ARRAY::for_each([ 1 .. 10 ], sub { ... })
Values beginning with the array C<@> and hash C<%> sigils are passed by
reference, i.e. under the default bindings:
    @array->join(', ')
    @{ ... }->length()
    %hash->keys()
    %$hash->values()
are equivalent to:
    ARRAY::join(\@array, ', ')
    ARRAY::length(\@{ ... })
    HASH::keys(\%hash)
    HASH::values(\%$hash)
Multiple C<use autobox> statements can appear in the same scope. These are merged both "horizontally" (i.e.
multiple classes can be associated with a particular type) and "vertically" (i.e. multiple classes can be associated
with multiple types).
Thus:
    use autobox SCALAR => 'Foo';
    use autobox SCALAR => 'Bar';
- associates SCALAR types with a synthetic class whose C<@ISA> includes both Foo and Bar (in that order).
Likewise:
    use autobox SCALAR => 'Foo';
    use autobox SCALAR => 'Bar';
    use autobox ARRAY  => 'Baz';
and
    use autobox SCALAR => [ 'Foo', 'Bar' ];
    use autobox ARRAY  => 'Baz';
- bind SCALAR types to the Foo and Bar classes and ARRAY types to Baz.
autobox is lexically scoped, and bindings for an outer scope
can be extended or countermanded in a nested scope:
    {
        use autobox; # default bindings: autobox all native types
        ...
        {
            # appends 'MyScalar' to the @ISA associated with SCALAR types
            use autobox SCALAR => 'MyScalar';
            ...
        }
        # back to the default (no MyScalar)
        ...
    }
Autoboxing can be turned off entirely by using the C<no> syntax:
    {
        use autobox;
        ...
        no autobox;
        ...
    }
- or can be selectively disabled by passing arguments to the C<no autobox> statement:
    use autobox; # default bindings
    no autobox qw(SCALAR);
    []->foo(); # OK: ARRAY::foo([])
    "Hello, world!"->bar(); # runtime error
Autoboxing is not performed for barewords, i.e.
    my $foo = Foo->new();
and:
    my $foo = new Foo;
behave as expected.
Methods are called on native types by means of the L<arrow operator|perlop/"The Arrow Operator">. As with
regular objects, the right hand side of the operator can either be a bare method name or a variable containing
a method name or subroutine reference. Thus the following are all valid:
    sub method1 { ... }
    my $method2 = 'some_method';
    my $method3 = sub { ... };
    my $method4 = \&some_method;
    " ... "->method1();
    [ ... ]->$method2();
    { ... }->$method3();
    sub { ... }->$method4();
A native type is only associated with a class if the type => class mapping
is supplied in the C<use autobox> statement. Thus the following will not work:
    use autobox SCALAR => 'MyScalar';
    @array->some_array_method();
- as no class is specified for the ARRAY type. Note: the result of calling a method
on a native type that is not associated with a class is the usual runtime error message:
    Can't call method "some_array_method" on unblessed reference at ...
As a convenience, there is one exception to this rule. If C<use autobox> is invoked with no arguments
(ignoring the DEBUG option) the four main native types are associated with classes of the same name.
Thus:
    use autobox;
- is equivalent to:
    use autobox {
        SCALAR => 'SCALAR',
        ARRAY  => 'ARRAY',
        HASH   => 'HASH',
        CODE   => 'CODE',
    }
This facilitates one-liners and prototypes:
    use autobox;
    sub SCALAR::split { [ split '', $_[0] ] }
    sub ARRAY::length { scalar @{$_[0]} }
    print "Hello, world!"->split->length();
However, using these default bindings is not recommended as there's no guarantee that another
piece of code won't trample over the same namespace/methods.
=head1 OPTIONS
A mapping from native types to their user-defined classes can be specified
by passing a hashref or a list of key/value pairs to the C<use autobox> statement.
The following example shows the range of valid arguments:
    use autobox {
        SCALAR    => 'MyScalar'                     # class name
        ARRAY     => 'MyNamespace::',               # class prefix (ending in '::')
        HASH      => [ 'MyHash', 'MyNamespace::' ], # one or more class names and/or prefixes
        CODE      => ...,                           # any of the 3 value types above
        INTEGER   => ...,                           # any of the 3 value types above
        FLOAT     => ...,                           # any of the 3 value types above
        NUMBER    => ...,                           # any of the 3 value types above
        STRING    => ...,                           # any of the 3 value types above
        UNDEF     => ...,                           # any of the 3 value types above
        UNIVERSAL => ...,                           # any of the 3 value types above
        DEFAULT   => ...,                           # any of the 3 value types above
        DEBUG     => ...                            # boolean or coderef
    }
The INTEGER, FLOAT, NUMBER, STRING, SCALAR, ARRAY, HASH, CODE, UNDEF, DEFAULT and UNIVERSAL options can take
three different types of value:
=over
=item *
A class name, e.g.
    use autobox INTEGER => 'MyInt';
This binds the specified native type to the specified class. All methods invoked on
values of type C<key> will be dispatched as methods of the class specified in
the corresponding C<value>.
=item *
A namespace: this is a class prefix (up to and including the final '::')
to which the specified type name (INTEGER, FLOAT, STRING etc.) will be appended:
Thus:
    use autobox ARRAY => 'Prelude::';
is equivalent to:
    use autobox ARRAY => 'Prelude::ARRAY';
=item *
A reference to an array of class names and/or namespaces. This associates multiple classes with the
specified type.
=back
=head2 DEFAULT
The C<DEFAULT> option specifies bindings for any of the four default types (SCALAR, ARRAY, HASH and CODE)
not supplied in the C<use autobox> statement. As with the other options, the C<value> corresponding to
the C<DEFAULT> C<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 etc.
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    => 'MyHash',
        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
=head2 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
=head2 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 C<unimport> via the C<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' ], # ... etc.
  }
=head2 DEBUG
C<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 C<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 C<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, ...
=head1 METHODS
=head2 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 C<use autobox>.
This is done by subclassing autobox and overriding C<import>. This allows extensions to effectively
translate C<use MyModule> into a bespoke C<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 C<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 C<STRING> types.
This module can now be used without a C<use autobox> statement to enable the C<trim> method in the current
lexical scope, e.g.:
    #!/usr/bin/env perl
    use String::Trim;
    print "  Hello, world!  "->trim();
=head1 UNIVERSAL METHODS FOR AUTOBOXED TYPES
=head2 autobox_class
autobox adds a single method to all autoboxed types: C<autobox_class>. This can be used to
call L<UNIVERSAL|UNIVERSAL> methods, i.e. C<can>, C<DOES>, C<import>, C<isa>, C<unimport> and C<VERSION>, e.g.
    if (sub { ... }->autobox_class->can('curry')) ...
    if (42->autobox_class->isa('SCALAR')) ...
Note: C<autobox_class> must B<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') # "" (interpreted as "42"->isa("NUMBER"))
    []->can('push')   # Error: Can't call method "can" on unblessed reference
=head1 EXPORTS
=head2 type
autobox includes an additional module, autobox::universal, which exports a single subroutine, C<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 C<type> method for autoboxed values, e.g.
    use autobox UNIVERSAL => 'autobox::universal';
    42->type        # INTEGER
    3.1415927->type # FLOAT
    %ENV->type      # HASH
=head1 CAVEATS
=head2 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!")
=head2 Gotchas
=head3 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);
=head3 print BLOCK
Perl's special-casing for the C<print BLOCK ...> syntax (see L<perlsub>) means that C<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 C<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);
=head3 eval EXPR
Like most pragmas, autobox performs operations at compile time, and,
as a result, runtime string C<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 C<eval>, e.g.
    eval <<'EOS';
        use autobox;
        42->foo();
    EOS
Note that the C<eval BLOCK> form works as expected:
    use autobox;
    eval { 42->foo() }; # OK
=head3 Operator Overloading
Operator overloading via the L<overload> pragma doesn't (automatically) work.
autobox works by lexically overriding the L<arrow operator|perlop/"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.
=head1 VERSION
3.0.2
=head1 SEE ALSO
=over
=item * L<autobox::Core|autobox::Core>
=item * L<Moose::Autobox>
=item * L<perl5i|perl5i>
=item * L<Scalar::Properties|Scalar::Properties>
=back
=head1 AUTHOR
chocolateboy <chocolate@cpan.org>
=head1 COPYRIGHT AND LICENSE
Copyright (c) 2003-2024 by chocolateboy.
This library is free software; you can redistribute it and/or modify it under the
terms of the L<Artistic License 2.0|https://www.opensource.org/licenses/artistic-license-2.0.php>.
=cut