Add #escape to allow clients to escape special characters

changelog.md

@@ -1,3 +1,6 @@
+# 1.3.0 - unreleased
+- Add `#escape` to allow clients to escape special characters
+
 # 1.2.1
 - use `#scrub` to (more selectively) strip invalid characters from strings before attempting to format. This allows valid japanese (and more) characters to be used. Thanks to @fukayatsu for reporting.
 

lib/slack-notifier.rb

@@ -46,5 +46,11 @@ def username= username
       default_payload[:username] = username
     end
 
+    HTML_ESCAPE_REGEXP = /[&><]/
+    HTML_ESCAPE = { '&' => '&amp;',  '>' => '&gt;',   '<' => '&lt;' }
+
+    def escape(text)
+      text.gsub(HTML_ESCAPE_REGEXP, HTML_ESCAPE)
+    end
   end
 end

readme.md

@@ -72,6 +72,16 @@ notifier.ping message
 
 You can see [Slack's message documentation here](https://api.slack.com/docs/formatting) 
 
+## Escaping
+
+Since sequences starting with < have special meaning in Slack, you should use `notifier.escape` if your messages may contain &, < or >.
+
+```ruby
+link_text = notifier.escape("User <user@example.com>")
+message = "Write to [#{link_text}](mailto:user@example.com)"
+notifier.ping message
+```
+
 ## Additional parameters
 
 Any key passed to the `ping` method is posted to the webhook endpoint. Check out the [Slack webhook documentation](https://my.slack.com/services/new/incoming-webhook) for the available parameters.

spec/lib/slack-notifier_spec.rb

@@ -109,4 +109,12 @@
       expect( subject.username ).to eq "foo"
     end
   end
+
+  describe "#escape" do
+    it "escapes sequences of < > &, but not quotes" do
+      message = %q(I've heard "Do > with <" & that sounds ridiculous.)
+      expected = %q(I've heard "Do &gt; with &lt;" &amp; that sounds ridiculous.)
+      expect( subject.escape(message) ).to eq expected
+    end
+  end
 end