NAME

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

VERSION

version 0.23

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).

FUNCTIONS

get_step_spec($name, \%steps) => HASHREF

%steps is optional. Step $name will first be searched in %steps's keys. If found and value is a hashref, that stepspec is returned. If found but value is a string, it is assumed to be the new step name (an alias) and the new step name is searched. If not found in %steps (or %steps if not provided), then an attempt is made to load module Perinci::Sub::Step::<$name>; the module should contain spec() which if called returns the stepspec.

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 (hereby called generator, or helper) is a helper for writing undoable (as well as transactional, dry-runnable, and idempotent) function (hereby called generated function). Undo and transaction features are as described in Rinci::function::Undo and Rinci::function::Transaction. Generator will create the generated function with the basic flow and structure; you just need to supply the necessary "business logics" bits like the check_state and fix_state hooks.

Here is the flow of the generated function:

1. Execute check_args hook if supplied. Hook will be passed ($args). The task of the this hook is to check arguments (and possibly supply defaults). It should return enveloped result. If response is not success, exit with this response. Otherwise, continue.

2. If we are called in do mode (-undo_action => 'do' or undefined):

   2a. Execute C<check_state> hook, to check state. Hook will be passed ($args).
   Hook must return enveloped result, status 304 if checking succeeds and
   fixed state (final, desired state) has been reached so nothing needs to
   be done, status 200 if checking succeeds and we are in a fixable state (a
   non-final state but fixable into the final state, also called an
   acceptable initial state), status 412 if checking succeeds but we are in
   an unfixable state (non-final state which is not fixable into the final
   state, also called an unacceptable initial state). Other status means
   checking has failed. Function should return with this result unless
   status is 200.
   
   If status is 200, hook must also return undo data (a list of calls that
   can be used to I<undo> the 'fix_state' routine back to the initial state)
   in its result metadata, in C<undo_data> key. This means, if we fail during
   fixing, we can rollback to initial state using this information.
   
   The undo data looks like this: C. C
   is the fully-qualified function name to call (required), C is a
   hashref containing arguments for the function (optional, defaults to {}).
   
   2b. If function is called in dry run mode (-dry_run => 1), we return 200
   (along undo data from step 2a in the result metadata).
   
   2c. We execute C<fix_state> hook to fix state to final/fixed state. Hook will
   be passed ($args, $undoI<data), where $undo>data was retrieved from
   C<check_state> hook. Hook must return enveloped result. If we are in
   transaction, function returns with this result (failure will be rolled
   back by TM). Otherwise, if result is failure, we perform our own rollback
   (simulate TM).

3. If we are called in undo mode (-undoaction = 'undo', -undo>data => $calls): if we are in transaction (function is passed transaction manager object in C) then we simply invoke TM's call() to process the undo calls. Otherwise, we loop over $calls ourselves (simulate TM).

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'.

• check_args => code

  Code to check function's arguments.

  See generator's documentation on how this hook should do and return.

• check_or_fix_state => code

  Code to check or fix state.

  An alternative to combine checkstate and fixstate in one code. Code will be called with either ('check', $args) or ('fix', $args, $undo_data), depending on whether check/fix is wanted.

• check_state* => code

  Code to check state.

  See generator's documentation on how this hook should do and return.

• description => str

  Generated function's description.

• fix_state => code

  Code to fix state.

  See generator's documentation on how this hook should do and return.

• install => bool (default: 1)

  Whether to install generated function (and metadata).

  By default, generated function will be installed to the specified (or caller's) package, as well as its generated metadata into %SPEC. Set this argument to false to skip installing.

• name* => str

  Generated function's name, e.g. `myfunc`.

• package => str

  Generated function's package, e.g. `My::Package`.

  This is needed mostly for installing the function. You usually don't need to supply this if you set install to false.

  If not specified, caller's package will be used by default.

• req_tx => bool (default: 0)

  Whether generated function require transaction or not.

• summary => str

  Generated function's summary.

• trash_dir => bool (default: 0)

  Whether function needs undo trash directory.

  If set to true, generator will put -undo_trash_dir in function arguments.

• use_tx => bool (default: 1)

  Whether generated function can use transaction or not.

• v => int (default: 1)

  Interface version.

  When Perinci::Sub::Gen::Undoable 0.22 broke backward-compatibility, v was introduced at v=2 (previous interface at v=1).

  For new interface, must be set to 2.

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