NAME
    Array::Functions::Undoable - Array manipulation functions which supports
    undo operation

VERSION
    version 0.01

SYNOPSIS
     use Array::Functions::Undoable qw(afu);

     # raw "low-level" functional interface
     my $ary = [0, 1, 2, 3];
     my $res1 = afu(op=>'pop'    , ary=>$ary);          # ary now [0, 1, 2]
     my $res2 = afu(op=>'pluck'  , ary=>$ary);          # ary now [0, 2]
     my $res3 = afu(op=>'unshift', ary=>$ary, item=>4); # ary now [4, 0, 2]

     # undo
     afu(op=>'unshift', ary=>$ary, -undo_action=>'undo',
         -undo_data=>$res3->[3]{undo_data});      # ary now [0, 2]
     afu(op=>'pluck'  , ary=>$ary, -undo_action=>'undo',
         -undo_data=>$res2->[3]{undo_data});      # ary now [0, 1, 2]
     afu(op=>'pop'    , ary=>$ary, -undo_action=>'undo',
         -undo_data=>$res1->[3]{undo_data});      # ary now [0, 1, 2, 3]

     # nicer OO interface, which provides an undo stack. not yet implemented.

     my $afu = Array::Functions::Undoable->new;
     $ary = [0, 1, 2, 3]

     $afu->pop($ary);        # ary now [0, 1, 2]
     $afu->pluck($ary);      # ary now [0, 2]
     $afu->unshift($ary, 4); # ary now [4, 0, 2]

     $afu->undo;             # ary now [0, 2]
     $afu->redo;             # ary now [4, 0, 2]

     $afu->undo;             # ary now [0, 2]
     $afu->undo;             # ary now [0, 1, 2]
     $afu->undo;             # ary now [0, 1, 2, 3]

     $afu->undo;             # does nothing, undo stack empty

DESCRIPTION
    This module provides the usual array manipulation functionalities like
    for popping, pushing, splicing, but with undo capability. It is
    currently used just for testing the Sub::Spec undo protocol and other
    Sub::Spec modules like Sub::Spec::Runner.

FUNCTIONS
    None of the functions are exported by default, but they are exportable.

  afu(%args) -> [STATUS_CODE, ERR_MSG, RESULT]
    Perform undoable array operations.

    Returns a 3-element arrayref. STATUS_CODE is 200 on success, or an error
    code between 3xx-5xx (just like in HTTP). ERR_MSG is a string containing
    error message, RESULT is the actual result.

    This function supports undo operation. See Sub::Spec::Clause::features
    for details on how to perform do/undo/redo.

    Arguments ("*" denotes required arguments):

    *   ary* => *array*

        The array.

    *   item => **

        Item to insert to array.

        Required when doing these operations: unshift, push.

    *   op* => *str*

        Value must be one of:

         ["pop", "push", "shift", "unshift", "pluck"]

        Operation on array.

SEE ALSO
    Sub::Spec

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Steven Haryanto.

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

