NAME
    Perinci::Sub::Gen::Undoable - Generate undoable (transactional,
    dry-runnable, idempotent) function

VERSION
    version 0.06

SYNOPSIS
     # See an example, like in Setup::File::Symlink

DESCRIPTION
    This module helps you write undoable/transactional functions (as well as
    functions that support dry-run and are idempotent).

SEE ALSO
    Rinci::function::Undo, Rinci::function::Transaction, Rinci

    Setup.

DESCRIPTION
    This module has Rinci metadata.

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

  gen_undoable_func(%args) -> [status, msg, result, meta]
    Generate undoable (transactional, dry-runnable, idempotent) function.

    This function is basically a helper for writing undoable (as well as
    transactional, dry-runnable, and idempotent) function. This function
    will generate a function with the basic structure, and you supply the
    'business-logic' bits through the 'build_steps' and 'steps' arguments.

    This generator helps because writing an undoable and transactional
    function is a bit tricky. This helper shields function writer from
    having to interact with the transaction manager, or writing the steps
    loop, or writing the rollback mechanism on his/her own, and just focus
    on writing the actual steps.

    Some notes:

    *   Though it generally should not die(), generated function might still
        die, there is no big eval{} loop inside. But this is usually OK
        since a function wrapper (like Perinci::Sub::Wrapper) has this loop.

    For examples, see Setup::* Perl modules.

    Arguments ('*' denotes required arguments):

    *   args => *hash* (default: {})

        Specification for generated function's arguments.

        This is just like the metadata property 'args'.

    *   build_steps* => *code*

        Code to build steps.

        This is the code that should build the steps. Code will be given
        (\%args) and should return an enveloped response. If response is not
        a success one, it will be used as the function's response.
        Otherwise, code should return the steps (an array). By convention,
        each step should be an array like this: [NAME, ...] where the first
        element is the step name and the rest are step arguments.

    *   description* => *śtr*

        Generated function's description.

    *   hook_check_args* => *code*

        Code to check function's arguments.

        This is a (temporary?) hook to allow the generated function to check
        its arguments. This should later be mostly unnecessary when
        Perinci::Sub::Wrapper already integrates with Data::Sah to generate
        argument-checking code from schema.

        Code is given (\%args) and should return an enveloped response. You
        can modify the args (e.g. set defaults, etc) and it will be carried
        on to the other steps like 'build_steps'. If response is not a
        success one, it will be used as the function's response.

    *   name* => *str*

        Fully qualified function name.

    *   steps* => *hash*

        Steps specification.

    *   summary* => *str*

        Generated function's summary.

    *   trash_dir => *bool* (default: 0)

        Whether function needs undo trash directory.

    *   tx => *hash* (default: {})

        Whether function is transactional.

        Valid values include {use=>1} (meaning function can use transaction
        and will utilize it if given '-tx' special argument), {req=>1}
        (meaning function always require '-tx' and will return error
        response if not given it). Otherwise function will not use
        transaction, undo data will be passed to function via '-undo*data'
        special argument and returned by function in 'undo*data' result
        metadata.

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 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.