Merge pull request #344 from nesQuick/events

Allow hubot to react on events

README.md

@@ -103,6 +103,33 @@ callback function that accepts a request and a response.
 In addition, if you set `CONNECT_STATIC`, the HTTP listener will serve static
 files from this directory.
 
+## Eventsystem
+
+Hubot has also an node.js [EventEmitter][event-emitter] attached. It can be used for data exchange between scripts.
+
+```coffeescript
+# src/scripts/github-commits.coffee
+module.exports = (robot) ->
+  robot.router.post "/hubot/gh-commits", (req, res) ->
+  	#code goes here
+    robot.emit "commit", {
+        user    : {}, #hubot user object
+        repo    : 'https://github.com/github/hubot',
+        hash  : '2e1951c089bd865839328592ff673d2f08153643'
+    }
+```
+```coffeescript
+# src/scripts/heroku.coffee
+module.exports = (robot) ->
+  robot.on "commit", (commit) ->
+    robot.send commit.user, "Will now deploy #{commit.hash} from #{commit.repo}!"
+    #deploy code goes here
+```
+
+If you'll provide an event, it's very recommended to include a hubot user object in data. In case of other reacting scripts want to respond to chat.
+
+[event-emitter]: http://nodejs.org/api/events.html#events_class_events_eventemitter 
+
 ## Testing hubot locally
 
 Install all of the required dependencies by running `npm install`.

src/robot.coffee

@@ -1,7 +1,8 @@
-Fs         = require 'fs'
-Log        = require 'log'
-Path       = require 'path'
-HttpClient = require 'scoped-http-client'
+Fs           = require 'fs'
+Log          = require 'log'
+Path         = require 'path'
+HttpClient   = require 'scoped-http-client'
+EventEmitter = require('events').EventEmitter;
 
 User                                                    = require './user'
 Brain                                                   = require './brain'
@@ -36,6 +37,7 @@ class Robot
   constructor: (adapterPath, adapter, httpd, name = 'Hubot') ->
     @name         = name
     @brain        = new Brain
+    @events      = new EventEmitter
     @alias        = false
     @adapter      = null
     @Response     = Response
@@ -323,6 +325,27 @@ class Robot
     user = { room: room }
     @adapter.send user, strings...
 
+  # Public: A wrapper around the EventEmitter API to make usage 
+  # semanticly better.
+  #
+  # event    - The event name.
+  # listener - A Function that is called with the event parameter
+  #            when event happens.
+  #
+  # Returns nothing.
+  on: (event, args...) ->
+    @events.on event, args...
+
+  # Public: A wrapper around the EventEmitter API to make usage 
+  # semanticly better.
+  #
+  # event   - The event name.
+  # args...  - Arguments emitted by the event
+  #
+  # Returns nothing.
+  emit: (event, args...) ->
+    @events.emit event, args...
+
   # Public: Kick off the event loop for the adapter
   #
   # Returns nothing.

src/scripts/events.coffee

@@ -0,0 +1,19 @@
+# Description:
+#   Event system related utilities
+#
+# Commands:
+#   hubot fake event <event> - Triggers the <event> event for debugging reasons
+#
+# Events:
+#   debug - {user: <user object to send message to>}
+
+util = require 'util'
+
+module.exports = (robot) ->
+
+  robot.respond /FAKE EVENT (.*)/i, (msg) ->
+    msg.send "fake event '#{msg.match[1]}' triggered"
+    robot.emit msg.match[1], {user: msg.message.user}
+
+  robot.on 'debug', (event) ->
+    robot.send event.user, util.inspect event