NAME

MooseX::Lists - treat arrays and hashes as lists

SYNOPSIS

   package Stuff;

   use Moose;
   use MooseX::Lists;

   has_list a => ( is => 'rw', isa => 'ArrayRef');
   has_list h => ( is => 'rw', isa => 'HashRef' );

   has_list same_as_a => ( is => 'rw' );

   ...

   my $s = Stuff-> new(
        a => [1,2,3],
        h => { a => 1, b => 2 }
   );

Mixed list/scalar context

   has_list a => ( is => 'rw', isa => 'ArrayRef');
   has_list h => ( is => 'rw', isa => 'HashRef' );

   ...

   my @list   = $s-> a;     # ( 1 2 3 )
   my $scalar = $s-> a;     # [ 1 2 3 ]

   $s-> a(1,2,3);           # 1 2 3
   $s-> a([1,2,3]);         # 1 2 3
   $s-> a([]);              # empty array
   $s-> a([[]]);            # []

   my %list = $s-> h;       # ( a => 1, b => 2 )
   my $sc   = $s-> h;       # { a => 1, b => 2 }

   $s-> h(1,2,3,4);         # 1 2 3 4
   $s-> h({1,2,3,4});       # 1 2 3 4
   $s-> h({});              # empty hash

Separated list/scalar context

   has_list a => ( 
        is  => 'rw', 
        isa => 'ArrayRef',
        writer  => 'wa',
        clearer => 'ca',
        );
   has_list h => ( 
        is  => 'rw', 
        isa => 'HashRef',
        writer  => 'wh',
        clearer => 'ch',
        );

    ...

   # reading part is identical to the above

   $s-> wa(1,2,3);          # 1 2 3
   $s-> wa([1,2,3]);        # [1 2 3]
   $s-> wa();               # empty array
   $s-> ca();               # empty array
   $s-> wa([]);             # []

   $s-> wh(1,2,3,4);        # 1 2 3 4
   $s-> wh({1,2,3,4});      # error, odd number of elements
   $s-> wh();               # empty hash
   $s-> ch();               # empty hash

DESCRIPTION

Provides asymmetric list access for arrays and hashes.

The problem this module tries to solve is to provide an acceptable API for setting and accessing array and hash properties in list context. The problem in implementing such interface is when a handler accepts both arrays and arrayrefs, how to set an empty array, and differentiate between a set-call with an empty list or a get-call. Depending on the way a method is declared, two different setting modes are proposed.

The first method, when writer is not explictly set (default), tries to deduce if it needs to dereference the arguments. It does so by checking if the argument is an arrayref. This means that the only way to clear an array or hash it to call it with [] or {}, respectively.

The second method is turned on if writer was explicitly specified, which means that if it is called with no arguments, this means an empty list. This method never dereferences array- and hashrefs.

METHODS

has_list

Replacement for has, with exactly same syntax, expect for isa, which must begin either with ArrayRef or HashRef. If isa is omitted, array is assumed.

When a method is declared with has_list, internally it is a normal perl array or hash. The method behaves differently if called in scalar or list context. See below for details.

ArrayRef

In get-mode, behaves like auto_deref: in scalar context, returns direct reference to the array; in the list context, returns defererenced array.

In set-mode without writer specified, behaves asymmetrically: if passed one argument, and this argument is an arrayref, treats it as an arrayref, otherwise dereferences the arguments and creates a new arrayref, which is stored internally. I.e. the only way to clear the array is to call ->method([]).

In set-mode with writer specified always treats input as a list.

HashRef

In get-mode, behaves like auto_deref: in scalar context, returns direct reference to the hash; in the list context, returns defereenced hash.

In set-mode without writer specified behaves asymmetrically: if passed one argument, and this argument is a hashref, treats it as a hashref, otherwise dereferences the arguments and creates a new hashref, which is stored internally. I.e. the only way to clear the hash is to call ->method({}).

In set-mode with writer specified always treats input as a list.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.

THANKS

Karen Etheridge, Jesse Luehrs, Stevan Little.