RubyGems - javonet-ruby-sdk - Versions diffs - 2.4.9 → 2.4.11 - Mend

javonet-ruby-sdk 2.4.9 → 2.4.11

Files changed (1457) hide show

data/lib/javonet-ruby-sdk/Binaries/Perl/MacOs/X64/deps/lib/perl5/darwin-thread-multi-2level/autobox.pod DELETED Viewed

@@ -1,709 +0,0 @@
-=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