Update README.org with instructions on writing a plugin

2 files changed, 68 insertions, 1 deletions

diff --git a/README.org b/README.org
index a968cbf..4d8bf43 100644
--- a/README.org
+++ b/README.org
@@ -1,3 +1,5 @@
+#  LocalWords: asyncio async plugin
+
 * Setting up the bot
 D'bolla is a no bullshit extensible IRC/Slack bot written for Python 3.5 using
 asyncio.
@@ -21,6 +23,56 @@ Simply run the command:
 #+END_SRC
 
 * Writing a Plugin
+To write a new plugin you must inherit from
+~warmachine.addons.base.WarMachinePlugin~. This class defines an interface you
+must implement in order to interact with connections. If you override ~__init__~
+you must call ~super()~.
+** ~self._loop~
+This is given to you access to the asyncio loop. This is useful for scheduling
+tasks to be run later.
+** ~self.log~
+This is a logger that you should use when logging messages.
+** ~recv_msg(channel, message)~
+~recv_msg~ is the only required method for a plugin. It is called for every
+plugin every time a connection receives a message. It takes the arguments
+~connection~ and ~message~. ~connection~ is the Connection object which allows
+you to interact with that chat server. ~message~ is a dictionary containing
+information about the message received. It has the following format:
+
+#+BEGIN_SRC python
+{
+    'sender': 'sender nickname',
+    'channel': '#channel_name or None for private messages',
+    'message': 'The message that was received',
+}
+#+END_SRC
+
+You will parse ~message['message']~ for what you are interested in and take some
+action based on what was found.
+
+For example:
+
+#+BEGIN_SRC python
+async def recv_msg(connection, message):
+    """
+    A simple echo 'server'.
+    """
+    # if the message starts with !echo, and it was said in a channel (not a
+    # private message)...
+    if message['message'].startswith('!echo') and message['channel']:
+        # Strip the command !echo from the message
+        try:
+            msg_to_repeat = ' '.join(message['message'].split(' ')[1:])
+        except IndexError:
+            # There was nothing to echo
+            return
+        # Repeat the remainder of the received message
+        await connection.say(msg_to_repeat, message['channel'])
+#+END_SRC
+** ~on_connect(connection)~
+This method is called when a connection successfully connects and takes the
+single argument ~connection~. Use this method to do any start up initialization
+you may want to do such as create configuration files that don't exist yet.
 * Writing a Connection
 To write a new connection protocol you must inherit from
 ~warmachine.connections.base.Connection~. This class defines an interface you
diff --git a/warmachine/addons/base.py b/warmachine/addons/base.py
index e605c2c..0a02df7 100644
--- a/warmachine/addons/base.py
+++ b/warmachine/addons/base.py
@@ -3,6 +3,21 @@ import logging
 
 
 class WarMachinePlugin(object):
-    def __init__(self):
+    def __init__(self, *args, **kwargs):
         self._loop = asyncio.get_event_loop()
         self.log = logging.getLogger(self.__class__.__name__)
+
+    def recv_msg(self, *args, **kwargs):
+        """
+        Called when a connection receives a message. Arguments are
+        ``connection`` and ``message``.
+
+        ``connection`` is a :class:`warmachine.connections.base.Connection`
+            object used to interact with the connection to a chat server.
+        ``message`` is a dictionary that contains information about a message
+            that was received on the connection. See
+            :class:`warmachine.connections.base.Connection.read` for more
+            information.
+        """
+        raise NotImplementedError('{} must implement `recv_msg` method'.format(
+            self.__class__.__name__))