hipbot 1.0.0.rc2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 817d131f49971f64a368aa7f2da59edc03707fd8
-  data.tar.gz: ead66146d16bae22138ac8b80bd36c5efdfe2433
+  metadata.gz: ef74572ebd12e87ab892010a3c8c0bae5b146584
+  data.tar.gz: 03a8912f6c9958a88d3e2294844f6fc5fa5b7bc9
 SHA512:
-  metadata.gz: 84968ca38161cdd6ea4ed251b8bc3dc692d7eba6e92bb237bbe934339dbb2204e1371a4ac8d0d97a008e3c3fed1de33ac7c9c52d1ce27f1f2f75795a42c46046
-  data.tar.gz: dc0807cab3a8b9b70b19d941839406e4c0e7055a41226814fa0729f5907fd3ae301fe5cb38d86be5006677a9ede886ee676e94eb2e6ac7e77cfe0773027f1dab
+  metadata.gz: e8f9b8bd967a44c5b0b09057c63b257418f988a616e02cb63d91f55a26115f72da08ff3d82ead405ed48f38d7e24d8bf458bf6ed45d49bd16ab483c77d4e0bd2
+  data.tar.gz: e174318fef49cc39dc116ce31057d5377a015c35989f4b2be9451fbb7737b98dae68f6de96bd1a2c8111be5dbaa245e61ae081f938a3bee1b43078e625a315ce

data/.gitignore

@@ -1,3 +1,4 @@
 *.gem
-test_bot.rb
 coverage/*
+.bundle
+Gemfile.lock

data/.travis.yml

@@ -3,6 +3,12 @@ rvm:
   - 1.9.2
   - 1.9.3
   - 2.0.0
+  - jruby-19mode
+  - rbx-19mode
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
 notifications:
   email:
     recipients:

data/Gemfile

@@ -3,11 +3,10 @@ source 'https://rubygems.org'
 gem 'rake'
 gem 'eventmachine'
 gem 'em-http-request'
-gem 'xmpp4r'
 gem 'httparty'
 gem 'activesupport'
-gem 'i18n'
 gem 'daemons'
+gem 'xmpp4r-hipchat', github: 'bartoszkopinski/xmpp4r-hipchat', branch: 'master'
 
 gem 'rspec'
 gem 'guard-rspec'

data/README.md

@@ -1,161 +1,472 @@
 # Hipbot
 
+Hipbot is a XMPP bot for HipChat, written in Ruby with EventMachine.
+
 [![Build Status](https://secure.travis-ci.org/pewniak747/hipbot.png?branch=master)](http://travis-ci.org/pewniak747/hipbot)
 [![Code Climate](https://codeclimate.com/github/pewniak747/hipbot.png)](https://codeclimate.com/github/pewniak747/hipbot)
 [![Coverage Status](https://coveralls.io/repos/pewniak747/hipbot/badge.png?branch=master)](https://coveralls.io/r/pewniak747/hipbot)
 [![Dependency Status](https://gemnasium.com/pewniak747/hipbot.png)](https://gemnasium.com/pewniak747/hipbot)
 [![Gem Version](https://badge.fury.io/rb/hipbot.png)](http://badge.fury.io/rb/hipbot)
 
-Hipbot is a XMPP bot for HipChat, written in ruby & eventmachine.
+### Compatibility
+Hipbot is tested on:
 
-## Usage
+* Ruby 1.9.2, 1.9.3 and 2.0.0
+* JRuby 1.9 mode
+* Rubinus 1.9 mode
 
-For easy install, follow the instructions on https://github.com/netguru/hipbot-example .
+### Dependencies
 
-### Install
+* daemons >= 1.1.8
+* activesupport >= 3.2.12
+* eventmachine >= 1.0.3
+* em-http-request >= 1.0.3
+* xmpp4r ~> 0.5
 
-```
+## Getting started
+### Installation
+
+```shell
 gem install hipbot
 ```
 
-### Customize
+### 1 minute setup on heroku
 
+Follow the instructions on [hipbot-example](https://github.com/netguru/hipbot-example).
+
+### Custom setup
 Create `bot.rb` file, subclass `Hipbot::Bot` and customize the responses.
 
 ```ruby
 require 'hipbot'
 
-class MyCompanyBot < Hipbot::Bot
+class MyBot < Hipbot::Bot
   configure do |c|
-    c.jid       = 'changeme@chat.hipchat.com' # required
-    c.password  = 'secret' # required
-    c.teams     = { vip: ['John', 'Mike'] }
-    c.rooms     = { project_rooms: ['Project 1', 'Project 2'] }
+    c.jid       = 'changeme@chat.hipchat.com'
+    c.password  = 'secret'
   end
 
-  on /^hello/ do
-    reply('hello!')
+  on /^hello$/ do
+    reply("Hello!")
   end
+end
 
-  on /^restart/, from: :vip do
-    # ...
-    reply('restarting...')
-  end
+MyBot.start!
+```
 
-  on /^deploy/, room: :project_rooms do
-    # ...
-    reply('deploying...')
-  end
+### Running
+Start Hipbot as a daemon by executing:
+
+```shell
+hipbot start
+```
+
+Run `hipbot` to see all available commands.
+
+Start in shell:
+
+```shell
+ruby bot.rb
+```
+
+### Behavior
+* On start and runtime:
+    * Fetches details and presences of all users in Lobby
+    * Pings XMPP server every 60 seconds to keep alive
+* On new message:
+    * Invokes all matching reactions or falls back to default reaction
+
+## Usage
+### Configuration
+Full configuration example:
+```ruby
+class MyBot < Hipbot::Bot
+  configure do |c|
+    # Account JID (required) - see https://hipchat.com/account/xmpp for your JID
+    c.jid      = 'changeme@chat.hipchat.com'
+
+    # Account password (required)
+    c.password = 'secret'
 
-  default do
-    reply('I don\'t understand you!')
+    # Custom helpers module (optional) - see below for examples
+    c.helpers  = MyHipbotHelpers
+
+    # Logger (default: Hipbot::Logger.new($stdout))
+    c.logger   = Hipbot::Logger.new($stdout)
+
+    # Initial status message (default: '')
+    c.status   = "I'm here to help"
+
+    # Storage adapter (default: Hipbot::Storages::Hash)
+    c.storage  = Hipbot::Storages::Hash
+
+    # Predefined room groups (optional)
+    c.rooms    = { project_rooms: ['Project 1', 'Project 2'] }
+
+    # Predefined user groups (optional)
+    c.teams    = { admins: ['John Smith'] }
+
+    # Auto join criteria (default: :all)
+    # Accepted values: :all, :public, :private, :none, "room name"
+    c.join     = :private
   end
 end
+```
+### Reaction helpers
+Inside the reaction block you have access to following context objects:
 
-class PluginClass
-  include Hipbot::Plugin
+* `bot`
+* `room`
+* `sender`
+* `message`
+* `reaction`
 
-  on /^plugin/ do
-    reply('this is from plugin!')
-  end
+### Joining rooms
+Hipbot will join all accessible rooms by default on startup and invite.
+
+To change auto join method use `join` configuration option:
+```ruby
+configure do |c|
+  # ...
+  c.join = :private
+end
+```
+```ruby
+configure do |c|
+  # ...
+  c.join = :none
 end
+```
+```ruby
+configure do |c|
+  # ...
+  c.join = ['Project Room', :public]
+end
+```
+Notice: Archived rooms are always ignored
 
-MyCompanyBot.start!
+### Bot presence
+Use `bot.set_presence` method to change Hipbot presence:
+```ruby
+on /^change status$/ do
+  bot.set_presence("Hello humans")
+end
+```
+```ruby
+on /^go away$/ do
+  bot.set_presence("I'm away", :away)
+end
+```
+```ruby
+on /^do not disturb$/ do
+  bot.set_presence(nil, :dnd)
+end
 ```
 
-You can create a response by providing simple regexp:
+### Rooms
+Use `Hipbot::Room` for collection of available rooms.
+```ruby
+on /^list all rooms$/ do
+  all_rooms = Hipbot::Room.all.map(&:name)
+  reply(all_rooms.join(', '))
+end
+```
+```ruby
+on /^get project room JID$/ do
+  project_room = Hipbot::Room.find_by(name: 'project room')
+  reply(project_room.id)
+end
+```
+Use `room` for current room object (it's `nil` if message is private):
+```ruby
+on /^where am I\?$/ do
+  reply(
+    "You are in #{room}\n" +
+    "JID: #{room.id}\n" +
+    "Topic: #{room.topic}\n" +
+    "Users online: #{room.users.count}\n" +
+    "Privacy: #{room.privacy}\n" +
+    "Hipchat ID: #{room.hipchat_id}\n" +
+    "Archived?: #{room.archived ? 'yes' : 'no'}\n" +
+    "Guest URL: #{room.guest_url}"
+  )
+end
+```
 
+### Users
+Use `Hipbot::User` for collection of all users:
+```ruby
+on /^list all users$/ do
+  all_users = Hipbot::User.all.map(&:name)
+  reply(all_users.join(', '))
+end
+```
+```ruby
+on /^get John Smith's JID$/ do
+  john = Hipbot::Room.find_by(name: 'John Smith')
+  reply(john.id)
+end
+```
+Use `sender` for message sender object:
+```ruby
+on /^who am I\?$/ do
+  reply(
+    "You are #{sender}\n" +
+    "JID: #{sender.id}\n" +
+    "Mention: @#{sender.mention}\n" +
+    "E-mail: #{sender.email}\n" +
+    "Title: #{sender.title}\n" +
+    "Photo: #{sender.photo}"
+  )
+end
+```
+Use `Room#users` method for online users array:
 ```ruby
-on /^hello/ do
-  reply('hello!')
+on /^list online users$/ do
+  reply room.users.map(&:name).join(', ')
 end
 ```
 
-Responses can pass arguments from regexps:
+### Replying
+Use `reply` method to send a message.
+
+Reply in the same room / chat:
+```ruby
+on /^hello$/ do
+  reply("Hello!")
+end
+```
+Reply in "help room":
+```ruby
+on /^I need help$/ do
+  help_room = Hipbot::Room.find_by(name: 'help room')
+  reply("#{sender} needs help in #{room}", help_room)
+end
+```
 
+### Private messaging
+```ruby
+on /^send me private message$/ do
+  sender.send_message("Hello, #{sender}")
+end
+```
 ```ruby
-on /my name is (.*)/ do |user_name|
-  reply('hello #{user_name}!')
+on /^send private message to John$/ do
+  john = Hipbot::User.find_by(name: 'John Smith')
+  john.send_message("Hello, John!")
 end
 ```
 
-Define multiple regexps for a response:
+### Topics
+```ruby
+on /^current topic$/ do
+  reply("Current topic: #{room.topic}")
+end
+```
+```ruby
+on /^change topic here$/ do
+  room.set_topic("New Topic")
+end
+```
+```ruby
+on /^change topic there$/ do
+  there = Hipbot::Room.find_by(name: 'there')
+  there.set_topic("New Topic")
+end
+```
 
+### Regexp matchdata
+```ruby
+on /^My name is (.*)$/ do |user_name|
+  reply("Hello, #{user_name}!")
+end
+```
 ```ruby
-on /my name is (.*)/, /I am (.*)/ do |name|
-  reply('hello #{user_name}!')
+on /^My name is (\S*) (\S*)$/ do |first_name, last_name|
+  reply("Hello, #{first_name} #{last_name}!")
 end
 ```
 
-Use :from to only match messages from certain users or user groups defined in configuration
+### Multiple regexps
+```ruby
+on /^My name is (.*)$/, /^I am (.*)$/ do |user_name|
+  reply("Hello, #{user_name}!")
+end
+```
 
+### Sender restriction
+Use `:from` option to match messages only from certain users or user groups defined in configuration.
+It accepts string, symbol and array values.
 ```ruby
 configure do |c|
   # ...
-  c.teams = { vip: ['John', 'Mike'] }
+  c.teams = { vip: ['John Edward', 'Mike Anderson'] }
 end
 
-on /status report/, from: ['Tom', 'Dave', :vip] do
-  reply('all clear')
+on /^report status$/, from: ['Tom Smith', 'Jane Doe', :vip] do
+  reply('All clear')
 end
 ```
 
-Use :room to only match messages in certain hipchat rooms
-
+### Room restriction
+Use `:room` option to match messages opny from certain HipChat rooms.
+It accepts string, symbol, array and boolean values.
 ```ruby
 configure do |c|
   # ...
   c.rooms = { project_rooms: ['Project 1', 'Project 2'] }
 end
 
-on /hello/, room: ['Public Room', :project_rooms] do
-  reply('hello!')
+on /^hello$/, room: ['Public Room', :project_rooms] do
+  reply('Hello!')
+end
+```
+Match only private messages:
+```ruby
+on /^private hello$/, room: false do
+  reply('Private hello!')
+end
+```
+Match only room messages:
+```ruby
+on /^public hello$/, room: true do
+  reply('Public hello!')
 end
 ```
 
-Use :global to react to messages that are not sent directly to @robot
+### Global reaction
+By default, Hipbot reacts only to its HipChat mention.
+Use `global: true` option to match all messages:
 
 ```ruby
-on /hey I just met you/, global: true do
+on /^Hey I just met you$/, global: true do
   reply('and this is crazy...')
 end
 ```
 
-(Use with caution!)
+### Conditional reaction
+Use `:if` option to specify certain dynamic conditions:
+```ruby
+on /^Is it friday\?$/, if: ->{ Time.now.friday? } do
+  reply('Yes, indeed')
+end
+```
+```ruby
+admins = ['John Smith']
+on /^add admin (.*)$/, if: ->(sender){ admins.include?(sender.name) } do |user_name|
+  admins << user_name
+end
+```
+```ruby
+on /^choose volunteer$/, if: ->(room){ room.users.count > 3 } do
+  reply("Choosing #{room.users.sample}")
+end
+```
 
-For more examples, check out (https://github.com/pewniak747/hipbot/tree/master/examples)
+### Method reaction
+Use symbol instead of block to react with a instance method:
+```ruby
+def hello(user_name)
+  reply("Hello #{user_name}!")
+end
 
-#### Response helpers
+on /^My name is (.*)$/, :hello
+```
 
-Use http helpers (`get`, `post`, `put`, `delete`) to preform a http request:
+### Scopes
+Use `scope` blocks to extract common options:
+```ruby
+configure do |c|
+  # ...
+  c.teams = { admins: ['John Edward', 'Mike Anderson'] }
+end
+
+scope from: :admins, room: true do
+  on /^restart server$/ do
+    # Restarting...
+  end
+
+  scope global: true do
+    on /^deploy production$/ do
+      # Deploying...
+    end
+
+    on /^check status$/ do
+      # Checking...
+    end
+  end
+end
+```
+
+### Default reactions
+Default reaction can take the same options as regular one.
+Hipbot fall backs to default reactions if there is no matching normal reaction.
+```ruby
+default do
+  reply("I don't understand you!")
+end
+```
+```ruby
+default from: 'Mike Johnson' do
+  reply("Not you again, Mike!")
+end
+```
 
+### Descriptions
+Use `desc` modifier to describe following reaction:
+```ruby
+desc '@hipbot restart server_name - Restarts the server'
+on /^restart (.*)$/ do |server|
+  if server.empty?
+    reply("Usage: #{reaction.desc}")
+  else
+    # Restarting...
+  end
+end
+```
+You can fetch the descriptions and create help reaction, eg:
 ```ruby
-on /curl (\S+)/ do |url|
-  get url do |response|
+on /^help$/ do
+  reply Hipbot.reactions.map(&:desc).compact.join("\n")
+end
+```
+
+### User managment
+This behavior is experimental and not officially supported by HipChat. Bot must be an admin in order to perform this actions.
+```ruby
+on /^kick (.*)/ do |user_name|
+  user = Hipbot::User.find_by(name: user_name)
+  room.kick(user)
+end
+```
+```ruby
+on /^invite (.*)$/ do |user_name|
+  user = Hipbot::User.find_by(name: user_name)
+  room.invite(user)
+end
+```
+
+### HTTP helpers
+Use `get`, `post`, `put` and `delete` helpers to preform a HTTP requests:
+```ruby
+on /^curl (\S+)$/ do |url|
+  get(url) do |response|
     reply(response.code)
     reply(response.headers)
     reply(response.body)
   end
 end
 ```
-
 ```ruby
-on /ping site/ do
-  get 'http://example.com', ping: "1" # issues http://example.com?ping=1
+on /^ping site/ do
+  get('http://example.com', ping: '1') # GET http://example.com?ping=1
 end
 ```
 
-Inside response you have access to following variables:
-
-* `message.body` - sent message
-* `message.sender` - user who sent message
-* `message.mentions` - array of @mentions inside message, without bot
-* `room.name` - name of the current room
-
+### Custom response helpers
 You can define your own helpers and use them inside responses like this:
-
 ```ruby
-module HipbotHelpers
+module MyHipbotHelpers
   def project_name
     "#{room.name}-project"
   end
@@ -164,42 +475,40 @@ end
 class Bot < Hipbot::Bot
   configure do |c|
     # ...
-    c.helpers = HipbotHelpers
+    c.helpers = MyHipbotHelpers
   end
 
-  on /what's the project called\?/ do
+  on /^what's the project name\?$/ do
     reply(project_name)
   end
 end
 ```
 
-#### Plugins
-
-To define a plugin, include `Hipbot::Plugin` and add responses like in bot:
-
+### Plugins
+To define a plugin, include `Hipbot::Plugin` module in your class:
 ```ruby
 class GreeterPlugin
   include Hipbot::Plugin
-  on /^hello/ do
-    reply('hello there!')
+
+  on /^hello$/ do
+    reply('Hello there!')
   end
 end
 ```
 
-You can gain access to plugin data inside reaction with `plugin` helper:
-
+You can access plugin data inside reaction with `plugin` helper:
 ```ruby
 class GreeterPlugin
   include Hipbot::Plugin
 
   attr_accessor :language
 
-  on /^hello/ do
+  on /^hello$/ do
     case plugin.language
     when :en
-      reply("hello!")
+      reply("Hello!")
     when :pl
-      reply("cześć!")
+      reply("Cześć!")
     when :jp
       reply("おはよう！")
     end
@@ -210,27 +519,112 @@ GreeterPlugin.configure do |c|
   c.language = :jp
 end
 ```
+For more examples, check out [hipbot-plugins](https://github.com/netguru/hipbot-plugins).
 
-For a collection of open-source plugins, see https://github.com/netguru/hipbot-plugins
+### Exception handling
+Define `on_exception` block in your Hipbot class to handle runtime exceptions:
+```ruby
+class MyBot < Hipbot::Bot
+  on_exception do |e|
+    hipbot_room = Hipbot::Room.find_by(name: 'hipbot room')
+    reply(e.message, hipbot_room)
+    # If exception was raised in reaction, there are some context variables available:
+    reply("#{e.message} raised by #{message.body} from #{sender} in #{room}", hipbot_room)
+  end
+end
+```
 
-### Run
+### Preloader for EventMachine
+In order to use EventMachine runtime methods, define them within `on_preload` block in your Hipbot class:
+```ruby
+class MyBot < Hipbot::Bot
+  on_preload do
+    EM::add_periodic_timer(60) do
+      Updater::update_stock_prices
+      Updater::update_server_statuses
+    end
+  end
+end
+```
 
-Run hipbot as daemon by saying:
+### Storage
+Hipbot uses in-memory hash storage by default, however you can use persistent
+storage adapter to speed up boot time and extend the functionality.
 
+#### MongoDB
+In order to use MongoDB storage, enable Mongoid adapter and add `allow_dynamic_fields: true` to your Mongoid config:
+```ruby
+require 'hipbot/storages/mongoid'
+configure do |c|
+  # ...
+  c.storage = Hipbot::Storages::Mongoid
+end
 ```
-hipbot start
+Sample config file:
+```yaml
+sessions:
+  default:
+    hosts:
+      - localhost:27017
+    database: hipbot
+options:
+  allow_dynamic_fields: true
 ```
+You can optionally override user and room classes with these base models:
+```ruby
+module Hipbot
+  class User
+    include Mongoid::Document
+
+    has_and_belongs_to_many :rooms, class_name: 'Hipbot::User', inverse_of: :users
+
+    field :email,      type: String
+    field :mention,    type: String
+    field :phone,      type: String
+    field :photo,      type: String
+    field :title,      type: String
+    field :is_online,  type: Boolean
+  end
+end
+```
+```ruby
+module Hipbot
+  class Room
+    include Mongoid::Document
 
-Run `hipbot` to see all available commands.
+    has_and_belongs_to_many :users, class_name: 'Hipbot::User', inverse_of: :rooms
 
-## Deploying to Heroku
+    field :archived,   type: Boolean
+    field :guest_url,  type: String
+    field :hipchat_id, type: String
+    field :privacy,    type: String
+    field :topic,      type: String
+  end
+end
+```
+#### Other storage
+Storage adapter is included in room and user classes upon loading.
+Make sure your adapter implements all methods from [Hipbot::Storages::Base](https://github.com/pewniak747/hipbot/blob/master/lib/hipbot/storages/base.rb)
+```ruby
+module MyStorageAdapter
+  include Hipbot::Storages::Base
+  # ...
+end
 
-Follow the instructions on https://github.com/netguru/hipbot-example .
+configure do |c|
+  # ...
+  c.storage = MyStorageAdapter
+end
+```
 
-## TODO:
+## Contributing
+### To do:
 
-### Done:
+* add tests for Match class
+* add testing adapter for testing custom responses with RSpec
+* add HipChat API integration (?)
 
+### Done:
 * ~~add extended logging~~
 * ~~add plugins support~~
 * ~~rewrite SimpleMUCClient~~