NAME Perinci::Sub::Gen::Undoable - Generate undoable (transactional, dry-runnable, idempotent) function VERSION version 0.04 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 the whole function's arguments 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 arguments as a *hashref* to be able to modify them (e.g. set defaults, etc) and should return an enveloped response. 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 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.