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 '-undodata' special argument and returned by function in 'undodata' 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.

cpanm Perinci::Sub::Gen::Undoable

perl -MCPAN -e shell
install Perinci::Sub::Gen::Undoable