NAME
    Setup::Multi - Setup using a series of other setup routines

VERSION
    version 0.03

SYNOPSIS
     use Setup::Multi     'setup_multi';
     use Setup::File::Dir 'setup_dir';
     use Setup::File      'setup_file';

     # simple usage (doesn't save undo data)
     my $res = setup_multi
         subs => [
             setup_dir  => [{name=>'/foo',         should_exist=>1},
                            {name=>'/foo/bar',     should_exist=>1},
                            {name=>'/foo/bar/baz', should_exist=>1}],
             setup_file =>  {name=>"/foo/bar/baz/qux", should_exist=>1},
         ];
     die unless $res->[0] == 200 || $res->[0] == 304;

     # perform setup and save undo data (undo data should be serializable)
     $res = setup_multi ..., -undo_action => 'do';
     die unless $res->[0] == 200 || $res->[0] == 304;
     my $undo_data = $res->[3]{undo_data};

     # perform undo
     $res = setup_multi ..., -undo_action => "undo", -undo_data=>$undo_data;
     die unless $res->[0] == 200 || $res->[0] == 304;

DESCRIPTION
    This module provides one function: setup_multi.

    This module is part of the Setup modules family.

    This module uses Log::Any logging framework.

    This module's functions have Sub::Spec specs.

THE SETUP MODULES FAMILY
    I use the "Setup::" namespace for the Setup modules family. See
    Setup::File for more details on the goals, characteristics, and
    implementation of Setup modules family.

FUNCTIONS
    None are exported by default, but they are exportable.

  setup_multi(%args) -> [STATUS_CODE, ERR_MSG, RESULT]
    Setup using a series of other setup routines.

    Accept a list of setup subroutine name and arguments, or coderefs, and
    call them each sequentially as steps. If one step fails, the whole steps
    will be rolled back using the undo data. If all steps succeed, return
    the concatenated undo data from each step.

    This function is declared as supporting the 'undo' and 'dry_run'
    features, so all setup routines mentioned in 'subs' argument must also
    support those two features (but this is not currently checked).

    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.

    This function supports dry-run (simulation) mode. To run in dry-run
    mode, add argument "-dry_run" => 1.

    Arguments ("*" denotes required arguments):

    *   subs* => *array*

        List of setup subroutine (names/refs) and arguments.

        Setup subroutine can be a string (its name) or a coderef. If
        subroutine is a non-qualified name (i.e., foo instead of
        Package::foo), it will be qualified with caller's package. Argument
        can be a single hashref or arrayref (of hashrefs). Example, if subs
        are:

         [
           'Pkg::func1'  => \%args,
           'func2'       => [\%args2, \%args3, \%args4],
           \&func3       => [\%args5],
           sub{...}      => \%args6,
         ]

        then the subs which will be called:

         Pkg::func1->(%args);
         func2->(%args2);
         func2->(%args3);
         func2->(%args4);
         func3(%args5);
         (sub{...})->(%args6);

FAQ
  When to use coderef (routine refs) or string (routine names) in subs?
    Since the routine name is included in undo data, use string to make it
    easily serializable.

SEE ALSO
    Other modules in Setup:: namespace.

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.