File Coverage

blib/lib/Verby/Step.pm
Criterion Covered Total %
statement 1 3 33.3
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 2 4 50.0


line stmt bran cond sub pod time code
1             #!/usr/bin/perl
2              
3             package Verby::Step;
4 1     1   1959 use Moose::Role;
  0            
  0            
5              
6             our $VERSION = "0.05";
7              
8             requires "do";
9              
10             requires "depends";
11              
12             requires "is_satisfied";
13              
14             sub provides_cxt {
15             return undef;
16             }
17              
18             sub resources {
19             return ( steps => 1 );
20             }
21              
22             __PACKAGE__
23              
24             __END__
25              
26             =pod
27              
28             =head1 NAME
29              
30             Verby::Step - A base class representing a single thing to be executed by
31             L<Verby::Dispatcher>.
32              
33             =head1 SYNOPSIS
34              
35             package MyStep;
36             use Moose;
37              
38             with qw/Verby::Step/;
39              
40             Or perhaps more easily using:
41              
42             use Verby::Step::Closure qw/step/;
43             my $step = step "Some::Action",
44             sub { warn "before" },
45             sub { warn "after" };
46              
47             =head1 DESCRIPTION
48              
49             A step in the L<Verby> system is like an instance of an action.
50              
51             A step is much like a makefile target. It can depend on other steps, and when
52             appropriate will be told to be executed.
53              
54             The difference between a L<Verby::Step> and a L<Verby::Action> is that an
55             action is usually just reusable code to implement the verification and
56             execution
57              
58             A step manages the invocation of an action, typically by massaging the context
59             before delegating, and re-exporting meaningful data to the parent context when
60             finished. It also tells the system when to execute, by specifying dependencies.
61              
62             The distinction is that an action is something you do, and a step is something
63             you do before and after others.
64              
65             =head1 METHODS
66              
67             This role provides the C<provides_cxt> and C<resources> methods, with sane
68             default values, and requires C<depends>, C<is_satisfied> and C<do>. See
69             L<Verby::Step::Simple> and L<Verby::Step::Closure> for more reusable behavior.
70              
71             =over 4
72              
73             =item B<depends>
74              
75             Subclass this to return a list of other steps to depend on.
76              
77             =item B<is_satisfied>
78              
79             This method should return a true value if the step does not need to be
80             executed.
81              
82             Typically a delegation to L<Verby::Action/verify>. They are named differently,
83             because C<is_satisfied> implies state. The L<Verby::Dispatcher> will sometimes
84             make assumptions, without asking the step to check that it is satisfied.
85              
86             =item B<provides_cxt>
87              
88             =item B<do>
89              
90             This is basically a delegation to the corresponding L<Verby::Action> method.
91              
92             The only interesting thing to do here is to fudge the context up a bit. For
93             example, if your action assumes the C<path> key to be in the context, but you
94             chose C<the_path_to_the_thing> to be in your config, this is the place to do:
95              
96             sub do {
97             my ($self, $c) = @_;
98              
99             # prepare for the action
100             $c->path($c->the_path_to_the_thing);
101              
102             $self->action->do($c);
103              
104             # pass data from the action to the next steps
105             $c->export("some_key_the_action_set");
106             }
107              
108             L<Verby::Step::Closure> provides a convenient way to get this behavior for
109             free.
110              
111             =item B<resources>
112              
113             Returns the list of required resources to allocate with the dispatcher's
114             resource pool, if provided.
115              
116             This defaults to the resource C<steps> with the value C<1>, generally intended
117             to control the maximum number of concurrent jobs.
118              
119             =back
120              
121             =head1 BUGS
122              
123             None that we are aware of. Of course, if you find a bug, let us know, and we
124             will be sure to fix it.
125              
126             =head1 CODE COVERAGE
127              
128             We use B<Devel::Cover> to test the code coverage of the tests, please refer to
129             COVERAGE section of the L<Verby> module for more information.
130              
131             =head1 SEE ALSO
132              
133             =head1 AUTHOR
134              
135             Yuval Kogman, E<lt>nothingmuch@woobling.orgE<gt>
136              
137             =head1 COPYRIGHT AND LICENSE
138              
139             Copyright 2005-2008 by Infinity Interactive, Inc.
140              
141             L<http://www.iinteractive.com>
142              
143             This library is free software; you can redistribute it and/or modify
144             it under the same terms as Perl itself.
145              
146             =cut