package Verby::Action;
use Moose::Role;

our $VERSION = "0.05";

use Carp qw/longmess/;

requires "do";

requires "verify";

sub confirm {
	my ( $self, $c, @args ) = @_;

	$self->verify($c, @args) or
		$c->logger->log_and_die(level => "error", message => 
			"verification of $self failed: "
			. ($c->error || "error unknown"));




=head1 NAME

Verby::Action - The base role for an action in Verby.


	package MyAction;
	use Moose;

	with qw/Verby::Action/;

	sub do { ... }

	sub verify { ... }


A Verby::Action is an object encapsulating reusable code. Steps usually
delegate to actions, for the actual grunt work.

=head1 METHODS

=over 4

=item B<new>

Instantiate an action. Actions should be able to live indefinitely, and should
not carry internal state with them. All the parameters for C<do> or C<verify>
are provided within the context.

The action instance data should only be used to configure action "flavours",
controlling behavior that should not be parameter sensitive (configuration

=item B<do $cxt>

The thing that the action really does. For example

	package Verby::Action::Download;

	sub do {
		my ($self, $c) = @_;
		system("wget", "-O", $c->file, $c->url);

Will use wget to download C<< $c->url >> to C<< $c->file >>.

This is a bad example though, you ought to subclass L<Verby::Action::Run> if
you want to run a command.

=item B<verify $cxt>

Perform a boolean check - whether or not the action is completed, for a given
set of arguments.

For example, if C<do> downloads C<< $c->file >> from C<< $c->url >>, then the
verify method would look like:

	sub verify {
		my ($self, $c) = @_;
		-f $c->file;

or it could even make a HEAD request and make sure that C<< $c->file >> is up
to date.

=item B<confirm $cxt>

Typically called at the end of an action's do:

	sub do {
		my ($self, $c) = @_;

It will call C<< $c->logger->log_and_die >> unless C<verify> returns a true value.

If C<< $c->error >> contains a string then it'll be printed as well.



Since L<Verby> is an abstraction layer over L<POE> and every step get's it's
own L<POE::Session>, an actions C<do> method can create child sessions, and the
parent session will wait till they are completed, as per default POE behavior.


Note that this documentation assumes delegation of step methods to action

L<Verby::Dispatcher> actually has nothing to do with L<Verby::Action>, it's
just that typically a L<Verby::Step> is just a thin wrapper for
L<Verby::Action>, so the methods roughly correspond.

See L<Verby::Step::Closure> for a trivial way to generate steps given a
L<Verby::Action> subclass.

=head1 BUGS

None that we are aware of. Of course, if you find a bug, let us know, and we
will be sure to fix it. 


We use B<Devel::Cover> to test the code coverage of the tests, please refer to COVERAGE section of the L<Verby> module for more information.

=head1 SEE ALSO

=head1 AUTHOR

Yuval Kogman, E<lt>nothingmuch@woobling.orgE<gt>


Copyright 2005-2008 by Infinity Interactive, Inc.


This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.