Enabled setting the message color when sending to a room

Introduced an options hash that replaces the old notify boolean flag
transparently and maintains backwards compatibility.

New API is room.send 'nick', 'message', :notify => true, :color => 'red'
Defaults stay the same: notify is false, color is yellow (set explicitly
for simplicity of code, but that is the default of hipchat anyway)

See API docs at https://www.hipchat.com/docs/api/method/rooms/message

Also added a slew of specs for the new functionality, refactoring the
mock for successful posts into a helper so things don't get bloated with
repetitive mock code.

Updated usage instructions in README accordingly.

README.textile

@@ -5,8 +5,10 @@ A very basic wrapper for the HipChat HTTP API.
 h2. Usage
 
 bc.. client = HipChat::Client.new(api_token)
-notify_users = false
-client['my room'].send('username', 'A message!', notify_users)
+client['my room'].send('username', 'I talk')
+client['my room'].send('username', 'I quit!', :notify => true) # Lets hipchat send notifications to users (default false)
+client['my room'].send('username', 'Build failed!', :color => 'red') # or "yellow", "green", "purple", "random". Default: "yellow"
+client['my room'].send('username', 'I quit!', true) # Legacy mode, notifies users but you can't change colors :)
 
 h2. Capistrano
 

lib/hipchat.rb

@@ -39,16 +39,43 @@ def initialize(token, params)
       super(params)
     end
 
-    def send(from, message, notify = false)
+    # Send a message to this room.
+    #
+    # Usage:
+    #
+    #   send 'nickname', 'some message' 
+    #   # => posts without notifying users and with default color (yellow)
+    # 
+    #   send 'nickname', 'some message', :notify => true, :color => 'red' 
+    #   # => Posts notifying users and with color red
+    #
+    # Available options currently only are :color ("yellow", "red", "green", "purple", or "random") and
+    # notify (true or false).
+    #
+    def send(from, message, options_or_notify = false)
+      # The api used to only allow the notify users option, but other things like color should be 
+      # available as parameters too.
+      if options_or_notify == true or options_or_notify == false
+        # warn "DEPRECATED: notify boolean flag has been replaced with room.send(nick, msg, :notify => true/false). Please update your code accordingly!"
+        options = {:notify => options_or_notify }
+      else
+        # Make sure options are available as a hash at this stage, either from a hash given 
+        # as argument or by initializing
+        options = options_or_notify || {}
+      end
+      # Merge in default options
+      options = {:color => 'yellow', :notify => false}.merge(options)
+
       response = self.class.post('/message',
                                  :query => { :auth_token => @token },
                                  :body => {:room_id => room_id,
                                            :from => from,
                                            :message => message,
-                                           :notify => notify ? 1 : 0})
+                                           :color => options[:color],
+                                           :notify => options[:notify] ? 1 : 0})
 
       case response.code
-      when 200; # weee
+      when 200; true
       when 404; raise UnknownRoom,  "Unknown room: `#{room_id}'"
       when 401; raise Unauthorized, "Access denied to room `#{room_id}'"
       else      raise UnknownResponseCode, "Unexpected #{response.code} for " <<

spec/hipchat_spec.rb

@@ -4,21 +4,52 @@
   subject { HipChat::Client.new("blah") }
 
   let(:room) { subject["Hipchat"] }
+
+  # Helper for mocking room message post requests
+  def mock_successful_send(from, message, options={})
+    options = {:color => 'yellow', :notify => 0}.merge(options)
+    mock(HipChat::Room).post("/message",
+                             :query => {:auth_token => "blah"},
+                             :body  => {:room_id => "Hipchat",
+                                        :from    => "Dude",
+                                        :message => "Hello world",
+                                        :color   => options[:color],
+                                        :notify  => options[:notify]}) {
+      OpenStruct.new(:code => 200)
+    }    
+  end
 
   describe "sends a message to a room" do
-    it "successfully" do
-      mock(HipChat::Room).post("/message",
-                               :query => {:auth_token => "blah"},
-                               :body  => {:room_id => "Hipchat",
-                                          :from    => "Dude",
-                                          :message => "Hello world",
-                                          :notify  => 0}) {
-        OpenStruct.new(:code => 200)
-      }
+    it "successfully without custom options" do
+      mock_successful_send 'Dude', 'Hello world'
+
+      room.send("Dude", "Hello world").should be_true
+    end
+
+    it "successfully with notifications on as boolean" do
+      mock_successful_send 'Dude', 'Hello world', :notify => 1
+
+      room.send("Dude", "Hello world", true).should be_true
+    end
+
+    it "successfully with notifications off as boolean" do
+      mock_successful_send 'Dude', 'Hello world', :notify => 0
+
+      room.send("Dude", "Hello world", false).should be_true
+    end
+
+    it "successfully with notifications on as option" do
+      mock_successful_send 'Dude', 'Hello world', :notify => 1
 
-      room.send "Dude", "Hello world"
+      room.send("Dude", "Hello world", :notify => true).should be_true
     end
+
+    it "successfully with custom color" do
+      mock_successful_send 'Dude', 'Hello world', :color => 'red'
 
+      room.send("Dude", "Hello world", :color => 'red').should be_true
+    end
+
     it "but fails when the room doesn't exist" do
       mock(HipChat::Room).post(anything, anything) {
         OpenStruct.new(:code => 404)