Assembly line interface

From Apibot
Revision as of 03:34, 5 November 2014 by Grigor Gatchev (talk | contribs) (link to common features and better wordings)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This is an interface that consists of many objects, each one tailored to a specific task. You assemble from them a processing line, much as a factory assembly line, tailored to your task. (Or, for the Unix / Linux heads, like a command line piping data from one command to another.)

You can see some examples for it here.

Line objects

Every assembly line object belongs to one of the following types:

  • Feeders - supply data to the assembly line
  • Fetchers - fetch full wiki objects by some identifier (eg. pages by titles)
  • Filters - let through only data that matches given criteria, or reorder the data
  • Workers - process the data in one way or another
  • Writers - write the processed data (back to the wiki, or to a file, etc.)

For each of those types there is a subtree named after it, inside the /line subdirectory in the bot.

In addition, there data the assembly line objects fetch, process and write is passed between them attached to special objects - signals. These cannot be attached to the line, and are not considered as proper assembly line objects.

(Until Apibot 0.40.20, there was one more type - Signal modifiers, or Sigmods. As their tasks are essentially the same as that of the Workers, they were merged into that family.)

You can read more about the common features of the assembly line objects here, and about each object type by clicking at its name in the list above.

Line structure and creation

An assembly line typically starts with a feeder object and ends with a writer object, typically with some other objects (workers etc) in between.

Objects are strung one to another via two procedures:

  • $worker->link_to ( $feeder ); will link $worker after $feeder in the line.
  • $worker->link_with ( $writer ); will link $worker before $writer in the line.

Several different objects can be linked after and / or before one object:

$filter1->link_to ( $feeder );
$filter2->link_to ( $feeder );
$filter3->link_to ( $feeder );

$worker->link_to ( $filter1 );
$worker->link_to ( $filter2 );
$worker->link_to ( $filter3 );

In this line, each of the three filters can have a different condition to let data through. So, data from $feeder will get to $worker if it matches any of the three conditions. (Every data portion gets an unique identifier from its feeder, and the line objects never accept the same data portion for a second time. So, $worker will process this data portion only once, even if it matches more than one of the filter conditions and thus comes from more than one filter.)

All line objects require at least one parameter - the bot $core object - on creation. Most require and/or can take more parameters.

Line signals

The assembly line you create will process its data in portions. For example, a line that reads pages from the wiki, edits them and writes them back, will process the pages one after another. The data is carried between the line objects packed to a special type of objects called signals.

Three types of signals are defined - start signal, end signal and data signal. A start signal marks the opening of a data stream. An end signal notified the end of the stream. A data signal carries a data portion, eg. a wiki page, or an user name. Only data signals carry data.

A feeder will typically send data in streams called in Apibot parlance feeds. Each feed starts with a start signal, followed by zero or more data signals, and finally by an end signal. Most other line objects will process only the data signals and will just let through the start and end signals. Some, however, perform neat tricks by processing start and end signals in a specific way.

You can read more about the assembly line signals here.

See also