The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
List-oo-v0.2.1
River stage zero No dependents
1 ++
/ List::oo

NAME

List::oo - object interface to list (array) methods

SYNOPSIS

Connecting multiple list functions together "reads" from right to left (starting with the data input way over on the right.)

This module provides a chainable method interface to array objects, which can be a bit more readable when multiple operations are involved.

This

  print join(' ', map({"|$_|"} qw(a b c))), "\n";

becomes:

  use List::oo qw(L);
  print L(qw(a b c))->map(sub {"|$_|"})->join(' '), "\n";

There is definitely some cost of execution speed. This is just an experiment. Comments and suggestions welcome.

Constructors

new

  $l = List::oo->new(@array);

L

  $l = L(@array);

Strange Constructors

This is only here because you so frequently need to start with a string op and L(split(...)) is ugly.

Aside: I'm not sure I really like this as an interface point. The need to use qr// is at least a little annoying.

Split

  my $l = Split(qr/\s+/, $string);

Convenience Functions

F

Declare a subroutine.

  F{...};

See also lambda, which lets you use λ{} instead.

About the sub {...} syntax

Sadly, perl5 does not allow prototypes on methods. Thus, we cannot use the undecorated block syntax as with

  map({...} @list);

Rather, you must use the explicit sub {...} syntax

  $l->map(sub {...});

Or, use the F{} or λ{} shortcuts.

  use List::oo qw(F);
  ...
  $l->map(F{...});

With lambda

  use lambda;
  ...
  $l->map(λ{...});

(If the above doesn't render as the greek character lambda, your pod viewer is not playing nice.)

List Methods

These methods are mostly analogous to the perl builtins. Where the builtin would return a list, we return a List::oo object. Where the builtin returns a scalar or some data which was not the primary list (e.g. push, pop, splice, etc.), you'll find some ifoo() methods (the 'i' prefix is for 'inline'.)

grep

  $l = $l->grep(sub {...});

map

  $l = $l->map(sub {...});

reverse

  $l = $l->reverse;

dice

Does things that can't be done with map.

  $l2 = $l->dice(sub {my @a = @_; ... return(@a);});

Feeds @$l into sub, which should return a perl list. Puts the results in a new List::oo object.

The purpose is simply to allow you to write an unbroken chain when you need to feed the entire list through some function which doesn't operate per-element.

Without this, you would have to break the chain of thought

  L(that_function($l->map(\&fx)->l))->map(\&fy);

With dice, simply insert it where it is needed.

  $l->map(\&fx)->dice(sub {that_function(@_)})->map(\&fy);

Note that in contrast to map() and grep() methods, dice() does not define the $_ variable.

What sort of functions need the whole list? Say you want to reverse the front and back half of a list, or maybe break a list of 20 items into 5 references of 4 items each. See the tests for examples.

sort

A lot like CORE::sort.

  $l->sort;

  $l->sort(sub {$a <=> $b});

Unfortunately, we don't get the sort $a/$b package variable magic. So, I set your package's $a and $b just like sort would. This means you might get "used only once" warnings, but you can silence these with:

  use List::oo qw($a $b);

The $a and $b imports have no other effect.

splice

Splices into @$l and returns the removed elements (or last element in scalar context) ala CORE::splice.

  $l->splice($offset, $length, @list);

With no replacement:

  $l->splice($offset, $length);

Remove everything from $offset onward

  $l->splice($offset);

Empties the list

  $l->splice;

Head and Tail Methods

push

Returns the new length of the list.

  $l->push(@stuff);

pop

Removes and returns the last item.

  $l->pop;

shift

Removes and returns the first item.

  $l->shift;

unshift

Prepends @stuff to @$l and returns the new length of @$l.

  $l->unshift(@stuff);

Inlined Methods

If you want to keep chaining calls together (and don't need to retrieve the pop/shift/splice data.)

ipush

  $l->map(sub {...})->ipush($val)->map(sub {...});

ipop

  $l->map(sub {...})->ipop->map(sub {...});

ishift

  $l->map(sub {...})->ishift->map(sub {...});

iunshift

  $l->map(sub {...})->iunshift($val)->map(sub {...});

isplice

  $l->map(sub {...})->isplice($offset, ...)->map(sub {...});

wrap

Add new values to the start and end.

  $l = $l->wrap($head,$tail);

Is just:

  $l->iunshift($head)->ipush($tail);

Additions to List::MoreUtils

The lack of prototypes means I can't do everything that List::MoreUtils does in exactly the same way. I've chosen to make the bindings to multi-list methods take only single lists and added mfoo() methods here.

mmesh

Meshes @$l, @a, @b, @c, ...

  my $l = $l->mmesh(\@a, \@b, \@c, ...);

meach_array

Just the binding to List::MoreUtils::each_arrayref;

  my $iterator = $l->meach_array(\@a, \@b, \@c);

Give Me Back My List

You can wrap the call chain in @{} or use one of the following methods.

flatten

If you really like to type.

  @list = $l->flatten;

l

The l is pretty flat and is the lowercase (less special) version of our terse constructor L().

  @list = $l->l;

Scalar Result Methods

These only work at the end of a chain.

join

  $string = $l->join("\n");

length

Length of the list.

  $l->length;

List::Util / List::MoreUtils

The following method documentation is autogenerated along with the wrappers of functions from List::Util and List::MoreUtils. The supported usage is shown (in some cases, these methods only support a subset of the function usage (due to the lack of method prototype support.)

The clusters of sigils (e.g. l=&l) are included as a shorthand reference. These sigils are what drive the code generation (see the source of List::oo::Extras and the build_extras.pl tool in the source repository for the dirty details.) The sigil on the left of the '=' represents the return value, the sigils on the right of the '=' represent what is passed to the wrapped function.

  l - a List::oo object (the $self when found on the right)
  L - an array of List::oo objects
  $ - a scalar
  @ - an array
  & - a subroutine reference (λ)

See List::Util and List::MoreUtils for more info.

Aliases

each_arrayref

alias to "meach_array"

first_index

alias to "firstidx"

first_value

alias to "firstval"

last_index

alias to "lastidx"

last_value

alias to "lastval"

zip

alias to "mesh"

Methods

after

l=&l

  my $list_obj = $list->after($block);

See List::MoreUtils::after()

after_incl

l=&l

  my $list_obj = $list->after_incl($block);

See List::MoreUtils::after_incl()

all

$=&l

  my $answer = $list->all($block);

See List::MoreUtils::all()

any

$=&l

  my $answer = $list->any($block);

See List::MoreUtils::any()

apply

l=&l

  my $list_obj = $list->apply($block);

See List::MoreUtils::apply()

before

l=&l

  my $list_obj = $list->before($block);

See List::MoreUtils::before()

before_incl

l=&l

  my $list_obj = $list->before_incl($block);

See List::MoreUtils::before_incl()

each_array

$=l@

  my $answer = $list->each_array(@list);

See List::MoreUtils::each_array()

false

$=&l

  my $answer = $list->false($block);

See List::MoreUtils::false()

first

$=&l

  my $answer = $list->first($block);

See List::Util::first()

firstidx

$=&l

  my $answer = $list->firstidx($block);

See List::MoreUtils::firstidx()

firstval

$=&l

  my $answer = $list->firstval($block);

See List::MoreUtils::firstval()

indexes

l=&l

  my $list_obj = $list->indexes($block);

See List::MoreUtils::indexes()

insert_after

l=&$l

  my $list_obj = $list->insert_after($block, $var1);

See List::MoreUtils::insert_after()

insert_after_string

l=$$l

  my $list_obj = $list->insert_after_string($var1, $var2);

See List::MoreUtils::insert_after_string()

lastidx

$=&l

  my $answer = $list->lastidx($block);

See List::MoreUtils::lastidx()

lastval

$=&l

  my $answer = $list->lastval($block);

See List::MoreUtils::lastval()

max

$=l

  my $answer = $list->max();

See List::Util::max()

maxstr

$=l

  my $answer = $list->maxstr();

See List::Util::maxstr()

mesh

l=l@

  my $list_obj = $list->mesh(@list);

See List::MoreUtils::mesh()

min

$=l

  my $answer = $list->min();

See List::Util::min()

minmax

@=l

  my @answers = $list->minmax();

See List::MoreUtils::minmax()

minstr

$=l

  my $answer = $list->minstr();

See List::Util::minstr()

natatime

$=$l

  my $answer = $list->natatime($var1);

See List::MoreUtils::natatime()

none

$=&l

  my $answer = $list->none($block);

See List::MoreUtils::none()

notall

$=&l

  my $answer = $list->notall($block);

See List::MoreUtils::notall()

pairwise

l=&l@

  my $list_obj = $list->pairwise($block, @list);

See List::MoreUtils::pairwise()

part

L=&l

  my @list_objs = $list->part($block);

See List::MoreUtils::part()

reduce

$=&l

  my $answer = $list->reduce($block);

See List::Util::reduce()

shuffle

l=l

  my $list_obj = $list->shuffle();

See List::Util::shuffle()

sum

$=l

  my $answer = $list->sum();

See List::Util::sum()

true

$=&l

  my $answer = $list->true($block);

See List::MoreUtils::true()

uniq

l=l

  my $list_obj = $list->uniq();

See List::MoreUtils::uniq()

AUTHOR

Eric Wilhelm @ <ewilhelm at cpan dot org>

http://scratchcomputing.com/

Thanks to

Jim Keenan for contributions to the test suite.

BUGS

If you found this module on CPAN, please report any bugs or feature requests through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

If you pulled this development version from my /svn/, please contact me directly.

COPYRIGHT

Copyright (C) 2006-2007 Eric L. Wilhelm, All Rights Reserved.

NO WARRANTY

Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

  EO::Array