view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

  on your system as well as in the share/ directory of this repository.

- At this point, you can run RoboBot in-place from your Git clone  without
  having to fully install it: `dzil run bin/robobot -c <config file path> -m`.
  This is currently recommended, just in case there are any further significant
  changes to the distribution before its formal release, just so you don't have
  an outdated, pre-release version cluttering up your system.

## Main Features

### S-Expression Syntax

The command syntax for RoboBot is based on S-Expressions, familiar to anyone
with basic knowledge of Lisp style languages. RoboBot's syntax should not be
confused for an actual Lisp, however, as it does not implement many of the more
advanced features of a real Lisp - only a thin and cheap imitation of their
visual style.

Every expression is a list of symbols, strings, and/or numbers. That list may
contain any number of elements, from *0* to *n*. If the first element of the list
is a symbol that matches a function name, it is considered a function expression,
and the remainder of the list will be supplied to that function as its arguments.

List elements may themselves be expressions, permitting the nesting of function
calls. As a simple example, we can express the mathematical operations of "Add
the numbers two and three together, then multiply their sum by five" by writing
the following:

```
(* (+ 2 3) 5)
```

This syntax applies to all interactions with RoboBot, except in cases where a
plugin hooks into the pre-evaluation phase and parses text from the raw incoming
messages itself (see the *Karma* plugin for an example of parsing meaning from
the raw messages directly).

### Multi-Network

RoboBot can be configured to connect to many chat networks simultaneously, all
managed by the same parent process. The event loop is managed through AnyEvent
to provide a portable interface for possibly embedding RoboBot into other code
which uses any of the common Perl event libraries. Internally, RoboBot
constructs a new RoboBot::Network object (actually, a sub-class specific to the
protocol used by the individual networks) for each connection made. Aside from
memory and the volume of incoming messages, there is no real limit on the
number of networks a single instance of RoboBot may listen on.

### Multi-Protocol

RoboBot is not strictly limited to IRC. Any text-based chat protocol can be
supported via the network plugin interface. Out of the box, RoboBot supports
standard IRC networks (with or without SSL), the Slack RTM API, and Mattermost
WebSockets/Web Services APIs. A single instance of RoboBot may mix and match
connections to as many different chat protocols as you wish.

Other chat protocols, such as the various instant messaging platforms, could be
added fairly easily, providing there is already a CPAN module (compatible with
AnyEvent) or you are willing to write one. Network plugins need only implement
a handful of methods (connect, disconnect, join\_channel, and send) as well as
register any callbacks required to deal with messages coming in over the wire.
Any functionality beyond that is generally optional, though some protocols may
require some additional support (e.g. Slack support requires ID<->name mappings
via Slack API calls for both channels and participants).

### Plugins

The bulk of RoboBot's functionality is implemented through a generic plugin
interface, allowing developers to export functions for direct use by channel
members, or to hook into message and response parsing phases before and after
expression evaluation.

RoboBot itself handles all the work of parsing input, passing arguments between
functions, enforcing access restrictions, and properly formatting and limiting
its output back to channels or individual recipients. Plugin authors need only
focus on the implementation details of their specific functions.

Refer to the section *Developing Plugins* below for more details.

### Macros

RoboBot provides a basic evaluation-phase macro system, which permits any
authorized users to extend the functionality of RoboBot directly from channels
without having to author a plugin. Macros can invoke functions or other macros.
Macros can even define other macros.

```
(defmacro add-one [n] '(+ n 1))
(add-one 5)
6
```

### Message Variables

The Variables plugin provides functions for setting and unsetting variables in
the context of a single message. These variables may then be reused anywhere else
in the message, though they will be discarded at the end and no longer accessible
(or defined) for subsequent messages.

Currently, you may not store a function in a variable (only the result of the
function), though support for functions as variables is planned for a future
release.

### Programmability

Combining the features already mentioned, RoboBot provides what amounts to a full
(though fairly simplified) programming environment within each message sent to
it. Variable state is reset with every message (unless a plugin were written to
provide a state-preserving feature), so programs are effectively limited to the
size of your chat server's message limit (typically a few hundred characters on
IRC, or about 16 kilobytes on Slack; other networks will vary).

But between the built-in functions, and the writing of macros by users, it is in
theory possible to develop non-trivial functionality entirely within the context
of a chat message.

### Access Control

RoboBot provides basic access control functionality, allowing you to define who
is permitted to call individual functions. It is recommended that sensitive
functions (such as those granting operator status, changing topics, and particularly