view release on metacpan or  search on metacpan

lib/Var/Pairs.pm  view on Meta::CPAN

package Var::Pairs;
use 5.014;

our $VERSION = '0.004002';

use warnings;
no if $] >= 5.018, warnings => "experimental::smartmatch";
use Carp;
use Devel::Callsite;
use Scope::Upper qw< reap UP >;
use PadWalker qw< var_name >;

# Check for autoboxing, and set up pairs() method if applicable..
my $autoboxing;
BEGIN {
    if (eval{ require autobox }) {
        $autoboxing = 1;
        push @Var::Pairs::ISA, 'autobox';

        *Var::Pairs::autobox::pairs        = \&Var::Pairs::pairs;
        *Var::Pairs::autobox::kvs          = \&Var::Pairs::kvs;
        *Var::Pairs::autobox::each_pair    = \&Var::Pairs::each_pair;
        *Var::Pairs::autobox::each_kv      = \&Var::Pairs::each_kv;
        *Var::Pairs::autobox::each_value   = \&Var::Pairs::each_value;
        *Var::Pairs::autobox::invert       = \&Var::Pairs::invert;
        *Var::Pairs::autobox::invert_pairs = \&Var::Pairs::invert_pairs;
    }
}

# API...
my %EXPORTABLE;
@EXPORTABLE{qw< pairs kvs each_pair each_kv each_value to_kv to_pair invert invert_pairs >} = ();

sub import {
    my ($class, @exports) = @_;

    # Check for export requests...
    if (!@exports) {
        @exports = keys %EXPORTABLE;
    }
    else {
        my @bad = grep { !exists $EXPORTABLE{$_} } @exports;
        carp 'Unknown subroutine' . (@bad==1 ? q{} : q{s})  . " requested: @bad"
            if @bad;
    }

    # Export API...
    no strict 'refs';
    my $caller = caller;
    for my $subname (@exports) {
        no strict 'refs';
        *{$caller.'::'.$subname} = \&{$subname};
    }

    # Enable autoboxing of ->pairs() in caller's lexical scope, if possible...
    if ($autoboxing) {
        $class->SUPER::import(
            HASH  => 'Var::Pairs::autobox',
            ARRAY => 'Var::Pairs::autobox',
        );
    }
}

# Track iterators for each call...
state %iterator_for;

# Convert one or more vars into a ('varname', $varname,...) list...

sub to_kv (\[$@%];\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@%]\[$@...

    # Take each var ref and convert to 'name' => 'ref_or_val' pairs...

lib/Var/Pairs.pm  view on Meta::CPAN

=over

=item C<< Argument to %s must be hash or array (not %s) >>

Except for C<to_pair()> and C<to_kv()>, all of the subroutines exported
by this module only operate on hashes, arrays, or references to hashes
or arrays. Asking for the "pairs" insidde a scalar, typeglob, or other entity
is meaningless; they're simply not structured as collections of keyed values.


=item C<< Useless use of pairs() in void context >>

=item C<< Useless use of kvs() in void context >>

=item C<< Useless use of invert() in void context >>

None of these subroutines has any side-effects, so calling them in void
context is a waste of time.

=item C<< Invalid call to pairs() in scalar context >>

=item C<< Invalid call to kvs() in scalar context >>

=item C<< Invalid call to invert() in scalar context >>

All these subroutines return a list, so in scalar context you just
get a count (which there are cheaper and easier ways to obtain).

The most common case where this error is reported is when C<pairs()> or
C<kvs()> is used in a C<while> loop, instead of a C<for> loop. Either
change the type of loop, or else use C<each_pair()> or C<each_kv()>
instead.

=item C<< Can't convert Pair(%s => %s) to a number >>

You attempted to use one of the pair objects returned by C<pairs()>
as a number, but the module has no idea how to do that.

You probably need to use C<< $pair->index >> or C<< $pair->value >> instead.

=back

=head1 CONFIGURATION AND ENVIRONMENT

Var::Pairs requires no configuration files or environment variables.


=head1 DEPENDENCIES

The module requires Perl 5.014 and the following modules:

=over

=item Perl 5.14 or later

=item Devel::Callsite

=item Data::Alias (under Perl 5.20 and earlier)

=item PadWalker

=back

To use the optional C<< $container->pairs >> syntax,
you also need the C<autobox> module.


=head1 INCOMPATIBILITIES

None reported.


=head1 BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to
C<bug-var-pairs@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org>.

C<each_kv()> acts like a true one-time only iterator (in the OO sense),
so there is no way to reset its iteration (i.e. the way that calling
C<keys()> on a hash or array, resets any C<each()> that is iterating
it). If you need to reset partially iterated hashes or arrays, you will
need to use some other mechanism to do so.


=head1 ACKNOWLEDGEMENTS

Based on a suggestion by Karl Brodowsky
and inspired by several features of Perl 6.


=head1 AUTHOR

Damian Conway  C<< <DCONWAY@CPAN.org> >>


=head1 LICENCE AND COPYRIGHT

Copyright (c) 2012, Damian Conway C<< <DCONWAY@CPAN.org> >>. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.


=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR