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

NAME edit

AnomieBOT::Task - AnomieBOT task base class

SYNOPSIS edit

 use AnomieBOT::Task ();
 use vars qw/@ISA/;
 @ISA = qw/AnomieBot::Task/;
 
 # Implement methods below

DESCRIPTION edit

AnomieBOT::Task 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 edit

Various utility methods are available.

TIME METHODS edit

These can be imported with the keyword :time.

AnomieBOT::Task::timelocal( $sec, $min, $hour, $mday, $mon, $year ): Equivalent to Perl's POSIX::mktime. $mon is zero-based, and $year is based in 1900.
AnomieBOT::Task::timegm( $sec, $min, $hour, $mday, $mon, $year ): Like timelocal, but interprets times in UTC instead of the local timezone.
AnomieBOT::Task::strftime( $fmt, $sec, $min, $hour, $mday, $mon, $year ): Equivalent to Perl's POSIX::strftime. $mon is zero-based, and $year is based in 1900.
AnomieBOT::Task::ISO2timestamp( $string ): Converts a timestamp in ISO "yyyy-mm-ddThh:ii:ssZ" format to a timestamp (seconds since the epoch).
AnomieBOT::Task::timestamp2ISO( $ts ): Converts a timestamp to a string in ISO "yyyy-mm-ddThh:ii:ssZ" format.

OTHER METHODS edit

AnomieBOT::Task::bunchlist( $count, @values ): Groups the items in @values into groups of $count 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::Task::onlylist( $key, $limit, @values ): If there are $limit or fewer values in @values, this function returns a 2-element list ($key => join('|',@values)). If there are more than $limit values, this function returns an empty list.; This is intended for use with tltemplates, pltitles, clcategories, and the like where the number of values is not known and could exceed the API limits.
AnomieBOT::Task::ns2cmtype( $ns ): Given the value for cmnamespace (a '|'-separated list of namespace numbers), returns the corresponding value for cmtype.

METHODS TO IMPLEMENT edit

AnomieBOT::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 run() 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 $api->task(...) to set the name of your task.
Call $api->read_throttle(...) and $api->edit_throttle 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 edit

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