/ 
Google-Spreadsheet-Agent-0.02
River stage zero No dependents
/ Google::Spreadsheet::Agent::Runner

NAME

Google::Spreadsheet::Agent - A Distributed Agent System using Google Spreadsheets

VERSION

Version 0.02

SYNOPSIS use Google::Spreadsheet::Agent::Runner;

# iterate over all pages in the spreadsheet, running agents for each goal of
# each entry that remains to be attempted, using the default skip_entry and
# skip_goal filters (see below).

my $agent_runner = Google::Spreadsheet::Agent::Runner->new();
$agent_runner->run();


# many parameters can be passed either to the constructor, or to an existing
# Google::Spreadsheet::Agent::Runner object using the following parameters or
# methods.

# Instead of using the default entry processor (see below), override it with a
# coderef that iterates over each entry on each page in the spreadsheet to do some
# more appropriate work.  This coderef recieves the entry hashref, and the
# updateable_entry Net::Google::Spreadsheet::Row object (see below) as arguments.
my $agent_runner = Google::Spreadsheet::Agent::Runner->new();
$agent_runner->process_entries_with(\&coderef);

sub coderef = {
    my ($entry_content, $updateable_entry) = @_;
    # use the $entry_content hash of field key => value entries to get needed informaation
    ...
    # if applicable update the entry in the spreadsheet with a hashref of field key => value entries
    $hashref->{somefield} = $somenewvalue;
    $updateable_entry->param($hashref); # this updates the 'somefield' value for that entry
}

# You can modify the runner to skip specific pages
my $agent_runner = Google::Spreadsheet::Agent::Runner->new(skip_pages => ['page1','page2']);

# or
$agent_runner->skip_pages(['page1','page2'];

# or only run on a specific list of pages
my $agent_runner = Google::Spreadsheet::Agent::Runner->new(only_pages => ['page1','page2']);

# or
$agent_runner->only_pages(['page1','page2']);

# override the default entry filter. (Can be used in conjunction with skip_pages or only_pages
# and with skip_goal).  The entry filter coderef is passed the entry hashref as argument
my $agent_runner = Google::Spreadsheet::Agent::Runner->new(skip_entry => \&coderef);

# or
$agent_runner->skip_entry(\&coderef);

sub coderef { my $entry = shift; # return 1 to skip, undef to accept }

# override the default goal filter. (Can be used in conjunction with skip_pages or only pages,
# and in conjunction with skip_entry). The goal filter coderef is passed the entry hashref
# and goal string as argument.
my $agent_runner = Google::Spreadsheet::Agent::Runner->new(skip_goal => \&coderef);

# or
$agent_runner->skip_goal(\&coderef);

sub coderef { my $entry = shift; my $goal = shift; # return 1 to skip, undef to accept }

# override the default agent_bin where the executable agents are located
my $agent_runner = Google::Spreadsheet::Agent::Runner->new(agent_bin => $path);

# or
$agent_runner->agent_bin($path);

# Once you have a constructed agent_runner, and you have set all the overrides that you
# want to set, run the runner with
$agent_runner->run();

# Note, once you have run the runner, you can then override some of the parameters and run
# it again, as needed.

DESCRIPTION

This object is designed to automate the process of running
Google::Spreadsheet::Agent scripts, or in general, iterating over entries in
the Google::Spreadsheet::Agent::DB and doing useful work on them.  Agent runners
can be run manually, or within a scheduling system, such as cron, at specified
intervals.

CONFIGURATION

See Google::Spreadsheet::Agent::DB for information about how to configure your Agent.

METHODS

new

This method constructs a new instance of a Google::Spreadsheet::Agent::Runner.  It
requires no arguments, but there are several optional arguments which can be passed
in to override its functionality.  Note, any of these parameters can also be called as
setter methods on the object after it is constructed, with the same values as arguments
to the method.

debug => Bool
  If this is true, information about pages, entries, and goals that are checked
  and filtered is printed to STDERR.  This defaults to false.

dry_run => Bool
  If this is true, then run will generate the commands that it would run for all
  runnable entry-goals, print them to STDERR, but not actually run the commands.
  This automatically sets debug to 1.  This defaults to false.  A runner can
  be tested to see if it is in dry_run mode using the is_dry_run method, and
  dry_run mode can be turned off using the no_dry_run method.  Note, if the
  process_entries_with coderef is overridden, this is ignored.

run_in_serial => Bool
 If this is set to true, then the default process_entries_with subroutine runs
 each command in the foreground, rather than in the background, and thus
 runs them in serial.  The default for this is false, and all the commands
 are run in parallel, in the background.  This is not used when process_entries_with
 is set to a different CODEREF.

sleep_between => INT
  This overrides the default amount of time, in seconds, that the runners will
  sleep between each entry that is run. The default is to sleep for 5 seconds.

agent_bin => STR
  This overrides the default agent_bin location, $Findbin::Bin.'/../agent_bin'

skip_pages => ARRAYREF
  This does not attempt any entries on the specified pages.
  It should not be passed with only_pages, or an exception is thrown.
  If the setter method is used to set a skip_pages ARRAYREF on a runner
  that already has an only_pages ARRAYREF, only_pages will take precidence
  over skip_pages.  You should always use the no_only_pages, no_skip_pages_if,
  or no_only_pages_if method before setting the skip_pages using the setter
  method on an already constructed runner object.

skip_pages_if => CODEREF
  If set, this CODEREF is passed each Net::Google::Spreadsheet::Worksheet
  object as argument.  If it returns true for a given Worksheet
  the page will be skipped.  You should always use the no_skip_pages,
  no_only_pages, or no_only_pages_if method before setting the skip_pages_if
  attribute using the setter method on an already constructed runner
  object.

only_pages => ARRAYREF
  This attempts entries only on the specified pages.  It should
  not be passed with skip_pages, or an exception is thrown.
  It is recommended that no_skip_pages, no_skip_pages_if,
  or no_only_pages_if be called before setting
  only_pages on an already constructed runner object.

only_pages_if => CODEREF
  If set, the CODEREF is fed each Net::Google::Spreadsheet::Worksheet
  object as argument.  If this CODEREF returns false for a given Worksheet,
  it will be skipped.  It is recommended that no_skip_pages, no_skip_pages_if,
  or no_only_pages be called before setting only_pages on an already constructed
  runner object.

skip_entry => CODEREF
  This coderef overrides the default entry filter, which filters an entry if
  it is not ready, or is complete.  Returning 1 from the coderef causes the
  entry to be skipped, and not processed by the runner, meaning it will not
  be passed to the process_entries_with coderef.

skip_goal => CODEREF
  This is best used in conjuction with the default process_entries_with
  coderef.  This overrides the default goal filter, which skips each goal that is
  not tied to an executable ${goal}_agent.pl script in the agent_bin, or that is
  running or has already run (success or fail). This can be used alone, or in
  conjunction with only_pages or skip_pages, and also in conjunction with skip_entries.
  It is passed the $entry hashref, and $goal string as arguments.  Returning 1 from the
  coderef causes the goal to be skipped for an entry, and not processed by the default 
  process_entries_with coderef.  If you want it to be used in a supplied process_entries_with
  coderef, you will need to use it explicitly, using something like:

  unless ($runner->skip_goal->($entry->content, $goal)) {
    # do something with this entry and goal
  }

process_entries_with => CODEREF
  This coderef overrides the default agent_runner.  The default agent_runner iterates through
  each entry not skipped by the entry_filter, and each goal not skipped by the goal_filter, and passes
  that entry and goal to the run_entry_goal method.  If a coderef is passed to override this
  default, it will have $entry_content HASHREF of each entry that is not skipped by the skip_entry filter,
  along with the $updateable_entry Net::Google::Spreadsheet::Row object as its argument.  If overridden,
  it does not iterate over individual goals on the entry, nor does it use the skip_goal filter.  
  You will need to write your own goal iterator and filter into the coderef, if you want to run, or skip over
  specific goals.  The $updateable_entry object can be used to fill in, or modify
  values for entry fields in the spreadsheet by passing a hashref with field key - values that
  you want to update to the param method of the $updateable_entry object.  Also, unless
  you make use of $self->dry_run in your coderef, this will also be ignored when the default
  coderef is overridden.

has_skip_pages

This method allows you to determine if the object already has a defined skip_pages ARRAYREF.

no_skip_pages

This method allows you to unset the skip_pages, so that the runner will not skip any pages.

has_skip_pages_if

This method allows you to determine if the object has a skip_pages_if attribute set.

no_skip_pages_if

This method allows you to unset the skip_pages_if attribute, so that the runner will not skip
any pages.

has_only_pages

This method allows you to determine if the object already has a defined only_pages ARRAYREF.

no_only_pages

This method allows you to unset the only_pages, so that the runner will run all pages, or 
skip pages.  It must be called before calling skip_pages on an already constructed object
that has_only_pages.

no_only_pages_if

This method allows you to clear the only_pages_if, so that the runner will run all pages, or
use one of the other page filtering methods.

has_only_pages_if

 This method allows you to determine if the only_pages_if attribute is set.

is_dry_run

This method returns true if the object is set to dry_run mode.

no_dry_run

This method turns off dry_run mode (though it will not turn off debug mode).

is_debug

This method returns true if the object is in debug mode (true if in dry_run, as well)

no_debug

This method turns off debug mode (though it will not turn off dry_run mode).

run_entry_goal

This method takes an entry HashRef, and a goal.  By default, It finds the goal_agent for the goal in agent_bin, and constructs
a commandline to run the goal_agent for the entry.  Unless dry_run is true, it will then execute the command in the background
and sleep sleep_between seconds.  If the goal_agent does not exist, or is not executable in the agent_bin directory, this method
skips attempting to run it.  If debug or dry_run is true, each command is printed to STDERR before attempting to determine if the
goal_agents exists and is executable in agent_bin, and sleep_between is ignored.

get_pages_to_process

This method returns an array of all Net::Google::Spreadsheets::Worksheet objects from the Google::Spreadsheet::Agent::DB
that pass the skip_pages, skip_pages_if, only_pages, or only_pages_if test.  If these are null, this returns every
Net::Google::Spreadsheets::Worksheet object.

get_runnable_entries

This method iterates over each Net::Google::Spreadsheets::Worksheet object returned by get_pages_to_process, and
pushes each Net::Google::Spreadsheet::Row object that passes through the skip_entry filter onto an array, and returns
this array.

run

This method runs the process_entries_with coderef on each entry not skipped by the entry_filter.  It passes the
entry HASHREF and updateable_entry Net::Google::Spreadsheet::Row object as arguments to the coderef.

AUTHOR

Darin London, <darin.london at duke.edu>

BUGS

Please report any bugs or feature requests to bug-google-spreadsheet-agent at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Google-Spreadsheet-Agent. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Google::Spreadsheet::Agent

You can also look for information at:

SEE ALSO

Google::Spreadsheet::Agent::DB Google::Spreadsheet::Agent Net::Google::Spreadsheets Moose

COPYRIGHT & LICENSE

Copyright 2010 Darin London.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.