NAME
    Action::Generic - Generic actions in a OO way

SYNOPSIS
     my $controller = Action::Generic->new();

     my $action = $controller->action( 
       type => 'System',
       name => 'List Files in my Homedir',
       params => [('ls', '-l', '~')],  
     );

     my $custom_action = $controller->action(
       type => 'Custom',
       name => 'A Custom Action',
       code => sub { ... }
     );

     $controller->add_actions( $action, $custom_action );

     $controller->run;

     use Data::Dumper;
     print Dumper( $controller->results );

DESCRIPTION
    Action::Generic is intended to create a simple framework for executing
    complex bits of code in a slighly modular, OO-ish way.

    It works by creating a "controller" object

     my $controller = Action::Generic->new(
      quiet => 0    # make some noise, baby
     );

    which consumes various actions. First, use the "action" method to create
    an action, passing it any relevent parameters..

     my $action = $controller->action( 
       type => 'Custom',
       name => 'Hello, world!',
       code => sub { print "Hello, world!\n" }
     );

    And push this action to the end of the stack.

     $controller->add_actions( $action );

    Each action is run, in the order added, optionally stopping further
    execution.

    Finally, should any of the actions have any notable result output, it is
    stored in a hashref whose keys are the name of the action.

     print Dumper( $controller->results );  # Lots of stuff

    Action::Generic ships with only a handful of actions. Extending them or
    adding more is a trivial task (see 'Creating Custom Actions').

  Methods
    new()
       Creates a new controller. An optional parameter "quiet" will, when
       true make the thing spit out a lot of extra crap.

    add_actions()
       Takes a list of actions. Adds them to the back of the queue, in order
       passed. Subsequent calls add in order. Order! Returns nothing of
       note.

    run()
       Runs each action in the order added.

    results()
       Returns an ARRAYREF containing the results of the run, in order of
       running. Contents of each element vary depending on the action run.

  Creating New Action Objects
    As mentioned below, there are a few actions that come by default --
    basically what I need to accomplish my goals -- but many may be added
    later. By you. I'm done with this!

    Every action has two required parameters:

    type
       The type of the action determines what sort of action is being
       created. For extending purposes, a type of "Custom" is shorthand for
       "Action::Generic::Plugin::Custom". In fact, any package name may be
       supplied here, as long as it implements a few basic methods (see
       'Creating Custom Actions'). Must always be a name -- not a reference.

    name
       The name of the action. For the most part, this is unused. However,
       the action name is available to the action during execution and is
       also used in any errors that may occur (to help you track that shit
       down).

  Action Types
    System
       The "System" is an easy way to execute some bit of code directly via
       the "system" method. It takes only one parameter, "params" which
       should be an arrayref containing a list of arguments for the "system"
       call.

       No checking is done to ensure you are trying to do something sane. Or
       safe. Don't be stupid.

    Custom
       "Custom" executes some arbitrary coderef, stored in the parameter
       "code".

    Template
       Provides a simple interface to the Template Toolkit (Template)
       rendering engine thinger. You provide the template and the stash, and
       get the rendered results as a scalar. Adventurous persons are welcome
       to reinvent the wheel and re-make TT.

  Results
    The hashref, obtained via the controller's "results" method, contains
    some information about the running of the actions.

    Each key is the name of the action. You should probably make sure your
    action names are unique. I would. But we don't check for that.

    Underneath, there is some information guaranteed to be present:

    type
       The type of the action. This is the fully-qualified name of the
       class. In most cases, it is Action::Generic::$some_action_name

    was_run
       A boolean indicating if this particular action was actually run or
       not. Useful if something horrible went wrong or the call

  Creating Custom Actions
    Actions may be created two different ways. The "action" method will
    first look for plugins located in Action::Generic::Plugin namespace.

    Failing that, it will attempt to "require" the action type as a
    fully-qualified package. In both cases, the resulting object must
    provide a few behaviours. The actions distributed with this package are
    written in Moose and use that particular terminology. This author
    suggests any additional actions also use Moose.

    The constructor "new()" will be called with the arguments passed from
    the "action()" method on the controller, with the "type" removed (you
    already know what sort of thingy you're dealing with if you're making a
    new one, right?).

    A "name" attribute.
       This should be a 'Str'.

    A "_results" attribute.
       This should be a 'HashRef'. The controller object will query each
       action, after running, for the results. Additionally, there should be
       two keys in the "_result" hashref, as described in the section
       "Results".

       Additional information is encouraged where appropriate.

    A method, "run()" must be present.
       "run()" will be called with no arguments. Configuration should be
       done when creating the object, not running it. "run()" should
       probably use the opportunity to set up the "_results" hashref
       properly.

LICENSE AND COPYING
    This library is free softtware; you may redistribute and/or modify it
    under the same terms as Perl itself.

BUGS
    Probably. Patches welcome!

AUTHOR
    Dave Houston "<dhouston@cpan.org>", 2010