User:AnomieBOT/source/AnomieBOT/Task.pm/doc

NAME
AnomieBOT::Task - AnomieBOT task base class

SYNOPSIS
use AnomieBOT::Task ; use vars qw/@ISA/; @ISA = qw/AnomieBot::Task/;
 * 1) Implement methods below

DESCRIPTION
is the base class for tasks to be run by AnomieBOT. An actual task should inherit from this and implement the methods noted below.

UTILITY METHODS
Various utility methods are available.

TIME METHODS
These can be imported with the keyword.


 * AnomieBOT&#58;&#58;Task&#58;&#58;timelocal( $sec, $min, $hour, $mday, $mon, $year )
 * Equivalent to Perl's POSIX::mktime.  is zero-based, and   is based in 1900.


 * AnomieBOT&#58;&#58;Task&#58;&#58;timegm( $sec, $min, $hour, $mday, $mon, $year )
 * Like timelocal, but interprets times in UTC instead of the local timezone.


 * AnomieBOT&#58;&#58;Task&#58;&#58;strftime( $fmt, $sec, $min, $hour, $mday, $mon, $year )
 * Equivalent to Perl's POSIX::strftime.  is zero-based, and   is based in 1900.


 * AnomieBOT&#58;&#58;Task&#58;&#58;ISO2timestamp( $string )
 * Converts a timestamp in ISO "yyyy-mm-ddThh:ii:ssZ" format to a timestamp (seconds since the epoch).


 * AnomieBOT&#58;&#58;Task&#58;&#58;timestamp2ISO( $ts )
 * Converts a timestamp to a string in ISO "yyyy-mm-ddThh:ii:ssZ" format.

OTHER METHODS

 * AnomieBOT&#58;&#58;Task&#58;&#58;bunchlist( $count, @values )
 * Groups the items in  into groups of   elements, and returns an arrayref. In other words,

my $list = bunchlist($count, @values);
 * is roughly equivalent to

my $list=[]; push @$list, join('|', splice(@values, 0, $count)) while @values;
 * This can be useful to construct the arrayref for an AnomieBOT::API::Iterator.


 * AnomieBOT&#58;&#58;Task&#58;&#58;onlylist( $key, $limit, @values )
 * If there are  or fewer values in , this function returns a 2-element list  . If there are more than   values, this function returns an empty list.
 * This is intended for use with,  ,  , and the like where the number of values is not known and could exceed the API limits.


 * AnomieBOT&#58;&#58;Task&#58;&#58;ns2cmtype( $ns )
 * Given the value for  (a '|'-separated list of namespace numbers), returns the corresponding value for.

METHODS TO IMPLEMENT

 * AnomieBOT&#58;&#58;Task->new
 * Perform any initialization necessary. If you override this, the blessed object must be a hash with the following properties:
 * order
 * Mainly useful during bot startup, tasks with lower values will run first. Default is 0.
 * Also note that properties with names beginning with  are reserved.


 * $task->approved
 * Return a positive number if the task is officially approved, 0 if it is not, or negative if it is approved but should not run. This is used to keep the bot from running unapproved tasks while they are in development, and to divide tasks among instances of the bot.
 * The default version returns 0, so once you have an approved task you'll need to override it.


 * $task->status
 * Return a short string indicating the job's status. The default is "ok", which will often be sufficient.


 * $task->run( $api )
 * Run the task. Ideally, this should not take particularly long to accomplish; if for example your task is to process a category with 1000 pages, one call to  should process a small number (depending on how long each takes) and then return to allow any other pending tasks to run.
 * The general structure of this function should be as follows:
 * Call  to set the name of your task.
 * Call  and   to set the limits you are approved for.
 * Do some work, and return.
 * The return value is the number of seconds until it is expected that this task will have more work to do, or undef if the task will never have more work. Return 0 if more work is immediately available. Note this is only a recommendation, the task may be called again sooner or later depending on the behavior of other tasks.
 * The default version returns undef.

COPYRIGHT
Copyright 2008–2013 Anomie

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