Google::Spreadsheet::Agent - A Distributed Agent System using Google Spreadsheets
Version 0.02
# 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.
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.
See Google::Spreadsheet::Agent::DB for information about how to configure your Agent.
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.
This method allows you to determine if the object already has a defined skip_pages ARRAYREF.
This method allows you to unset the skip_pages, so that the runner will not skip any pages.
This method allows you to determine if the object has a skip_pages_if attribute set.
This method allows you to unset the skip_pages_if attribute, so that the runner will not skip any pages.
This method allows you to determine if the object already has a defined only_pages ARRAYREF.
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.
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.
This method allows you to determine if the only_pages_if attribute is set.
This method returns true if the object is set to dry_run mode.
This method turns off dry_run mode (though it will not turn off debug mode).
This method returns true if the object is in debug mode (true if in dry_run, as well)
This method turns off debug mode (though it will not turn off dry_run mode).
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.
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.
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.
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.
Darin London, <darin.london at duke.edu>
<darin.london at duke.edu>
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.
bug-google-spreadsheet-agent at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Google::Spreadsheet::Agent
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Google-Spreadsheet-Agent
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Google-Spreadsheet-Agent
Google::Spreadsheet::Agent::DB Google::Spreadsheet::Agent Net::Google::Spreadsheets Moose
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.
To install Google::Spreadsheet::Agent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Google::Spreadsheet::Agent
CPAN shell
perl -MCPAN -e shell install Google::Spreadsheet::Agent
For more information on module installation, please visit the detailed CPAN module installation guide.