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

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.

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

  $l = L(@array);

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.

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

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.)

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'.)

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

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

  $l = $l->reverse;

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.

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.

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;

Returns the new length of the list.

  $l->push(@stuff);

Removes and returns the last item.

  $l->pop;

Removes and returns the first item.

  $l->shift;

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

  $l->unshift(@stuff);

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

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

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

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

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

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

Add new values to the start and end.

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

Is just:

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

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.

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

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

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

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

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

If you really like to type.

  @list = $l->flatten;

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

  @list = $l->l;

These only work at the end of a chain.

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

Length of the list.

  $l->length;

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.

INSERT_AUTODOC (if you find this in the .pod file, something went wrong)

Eric Wilhelm @ <ewilhelm at cpan dot org>

http://scratchcomputing.com/

Thanks to

Jim Keenan for contributions to the test suite.

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 (C) 2006-2007 Eric L. Wilhelm, All Rights Reserved.

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.

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

  EO::Array