=head1 NAME

App::Wubot::Guide::Overview - wtf is wubot?

=head1 DESCRIPTION

'wubot' is the code name for a distributed personal reactive
automation tool I've been working on for the last several years.  It
is built in modern Perl 5 using L<Moose>, L<AnyEvent>, L<LWP::UserAgent>, L<YAML>,
L<DBI>, L<DBD::SQLite>, L<Mojolicious>, and many others.

The simplest way to think of this project is to compare it to email
filters.  Most email clients allow you to set rules to perform actions
when a new email arrives.

This project allows you to have a set of monitors that collect data
from a variety of sources, including:

  - email boxes
  - RSS/Atom feeds
  - IM
  - log files
  - system monitors
  - OS X idle time
  - local sunrise/sunset times
  - monitors running on remote hosts
  - your own custom monitor plugin written in perl

Data collected from each monitor is sent through a set of rules that
can perform actions such as:

  - pop up an alert, e.g. using Growl
  - send a colorized message to stdout
  - store the message in a mailbox
  - add the message to a SQLite database
  - store data from the message in RRD and graph the data over time
  - add the message to outgoing RSS feeds
  - send a private or public message to IRC
  - forward the message to another host for further processing
  - your own custom action written in perl
  - ignore the message, the equivalent of routing it to /dev/null

=back

Beyond just doing something with the message or portions of the
message, you also have the option to modify the message, e.g.:

  - set a color to be used for notifications
  - transform some field in the message with a regexp
  - capture data from a field and store it in another field
  - strip images or HTML
  - fetch related content, e.g. fetch a complete article if the feed only provides a summary

Unlike previous generations of this project, the rules are entirely
controlled by configuration.  So it is not necessary to write any perl
code to use the rules.  In the future there will be a user interface
for configuring the rules.  See L<App::Wubot::Guide::Rules>.

Rules can be nested, so that when a rule matches, it can cause
additional sub-rules to run.  Nesting rules makes the rules processing
much more efficient so that not every rule needs to be run on every
message.  Rules processing is recursive so rules can be nested
arbitrarily deep.  For more information on rule conditions, see
L<App::Wubot::Conditions>.

Distributed operation currently relies on XMPP.  Using XMPP, messages
can be sent between wubot instances on multiple hosts.  Monitors
generate messages that may be reacted upon locally, and/or may be
forwarded to other hosts for further reaction.  See
L<App::Wubot::Guide::MultipleBots>.

This project is still under construction.

To get started, see L<App::Wubot::Guide::GettingStarted>.

=head1 REACTIVE AUTOMATION

I have struggled with a way to describe wubot in a sentence.  Recently
I have been calling it a personal distributed reactive automation
tool.

By 'personal', I mean that it acts as a sort of personal assistant.

By 'distributed', I mean that it can run on multiple hosts, and that
those hosts can communicate information about events by forwarding the
event messages.

When I use the word 'reactor', I am not necessarily implying the
'Reactor pattern'.

  http://en.wikipedia.org/wiki/Reactor_pattern

While it is possible to use this pattern in the wubot reactor plugins
(as it is built on AnyEvent), it is not the main pattern that has been
used so far.  I have settled on using an ordered procedural rules tree
as the primary reactive pattern because I find the behavior to be more
understandable, predicatable, and deterministic, and it is more than
sufficient to handle most of the cases in this problem domain.

I expect 'automation' is self-explanatory, but it really just means
that wubot can take action based on the observed events.  The
automation extends from filtering out events that are not interesting
to complex workflows that require executing external commands.

=head1 SEE ALSO

AtomsMasher: Personal Reactive Automation for the Web

    - http://eprints.ecs.soton.ac.uk/16788/

Haystack: Research on Information Access, Analysis, Management, and Distribution

    - http://groups.csail.mit.edu/haystack/

Esper: Complex Event Processing

    - http://esper.codehaus.org/


Atomate: an information assistance engine enabling end-user personal
reactive automation for the web.

    - http://code.google.com/p/atomate/
