Skip to content

omgitsads/Scamp

Repository files navigation

Scamp

A framework for writing Campfire bots. Scamp is in early development so use it at your own risk, pull requests welcome.

Scamp is designed to be simple, to get out of your way and to let you do what you want. It doesn't have any baggage, so no administration web interfaces, no built in commands. It's a blank slate for you to build on.

If you like or use Scamp I'd love to hear from you. Drop me at line at will at 37signals dot com and tell me how you are using it.

Requirements

Ruby >= 1.9.2 (At least for the named captures)

Installation

gem install scamp or put gem 'scamp' in your Gemfile.

Usage and Examples

The most simple example:

require'scamp'scamp=Scamp.new(:api_key=>"YOUR API KEY",:subdomain=>"yoursubdomain",:verbose=>true)scamp.behaviourdo# Simple matching based on regex or string:match"ping"dosay"pong"endend# Connect and join some roomsscamp.connect!([293788,"Monitoring"])

Everyone wants an image search

require'scamp'require'cgi'scamp=Scamp.new(:api_key=>"YOUR API KEY",:subdomain=>"yoursubdomain",:verbose=>true)scamp.behaviourdomatch/^artme (?<search>\w+)/dourl="http://ajax.googleapis.com/ajax/services/search/images?rsz=large&start=0&v=1.0&q=#{CGI.escape(search)}"http=EventMachine::HttpRequest.new(url).gethttp.errback{say"Couldn't get #{url}: #{http.response_status.inspect}"}http.callback{ifhttp.response_header.status == 200results=Yajl::Parser.parse(http.response)ifresults['responseData']['results'].size > 0sayresults['responseData']['results'][0]['url']elsesay"No images matched #{search}"endelse# logger.warn "Couldn't get #{url}"say"Couldn't get #{url}"end}endend# Connect and join some roomsscamp.connect!([293788,"Monitoring"])

A more in-depth run through

Matchers are tested in order and all that satisfy the match and conditions will be run. Careful, Scamp listens to itself, you could easily create an infinite loop. Look in the examples dir for more.

require'scamp'# Add :verbose => true to get debug output, otherwise the logger will output INFOscamp=Scamp.new(:api_key=>"YOUR API KEY",:subdomain=>"yoursubdomain",:verbose=>true)scamp.behaviourdo# # Simple matching based on regex or string:# match/^repeat (\w+), (\w+)$/dosay"You said #{matches[0]} and #{matches[1]}"end## You can specifically paste text: #match"paste stuff"dopaste"Awesome texts"# say()'ing multiline strings will paste automatically however:say<<-EOSThis will be pastedeven though you called say EOSend# # A special user and room method is available in match blocks.# match"a user said"dosay"#{user} said something in room #{room}"endmatch"Hello!"dosay"Hi there"end# # You can play awesome sounds# match"ohmy"doplay"yeah"end# # Limit the match to certain rooms, users or both.# match/^Lets match (.+)$/,:conditions=>{:room=>"Some Room"}dosay"Only said if room name matches 'Some Room'"endmatch"some text",:conditions=>{:user=>"Some User"}dosay"Only said if user name matches 'Some User'"endmatch/some other text/,:conditions=>{:user=>"Some User",:room=>123456}dosay"You can mix conditions"endmatch"some text",:conditions=>{:room=>["Some Room","Some Other Room"]}dosay"You can list multiple rooms"end# # Named captures become available in your match block# match/^say (?<yousaid>.+)$/dosay"You said #{yousaid}"end# # You can say multiple times, and you can specify an alternate room.# Default behaviour is to 'say' in the room that caused the match.# match"something"dosay"#{user} said something in room #{room}"say"#{user} said something in room #{room}",237872say"#{user} said something in room #{room}","System Administration"end# # A list of commands is available as command_list this matcher uses it# to format a help text# match"help"domax_command_length=command_list.map{|cl| cl.first.to_s}.max_by(&:size).sizeformat_string="%#{max_command_length + 1}s"formatted_commands=command_list.map{|action,conds| "#{sprintf(format_string,action)} | #{conds.size == 0 ? '' : conds.inspect}"}say<<-EOS#{sprintf("%-#{max_command_length + 1}s","Command match")} | Conditions--------------------------------------------------------------------------------#{formatted_commands.join("\n")} EOSendend# Connect and join some roomsscamp.connect!([293788,"Monitoring"])

In the room/user conditions and say/play commands you can use the name or ID of a user or room, eg:

:conditions=>{:room=>"some string"}:conditions=>{:room=>123456}:conditions=>{:user=>"some string"}:conditions=>{:user=>123456}say"#{user} said something in room #{room}",237872say"#{user} said something in room #{room}","System Administration"

By default Scamp listens to itself. This could either be fun, or dangerous, you decide. You can turn this off by passing :ignore_self => true in the initialisation options:

scamp=Scamp.new(:api_key=>"YOUR API KEY",:subdomain=>"yoursubdomain",:ignore_self=>true)

Scamp will also run all match blocks that an input string matches, you can make Scamp only run the first block it matches by passing in :first_match_only => true:

scamp=Scamp.new(:api_key=>"YOUR API KEY",:subdomain=>"yoursubdomain",:first_match_only=>true)

Scamp will listen to all messages that are sent on the rooms it is listening on and doesn't need to be addressed by name. If you prefer to only trigger bot commands when you address your bot directly add the :required_prefix initialisation option:

scamp=Scamp.new(:api_key=>"YOUR API KEY",:subdomain=>"yoursubdomain",:required_prefix=>'Bot: ')

Scamp will now require commands to begin with 'Bot: ' (or whatever you have specified), and will strip out this prefix before handing the message onto your match block.

TODO

* Allow multiple values for conditions, eg: :conditions =>{:user => ["Some User", "Some Other User"]} 

How to contribute

Here's the most direct way to get your work merged into the project:

  1. Fork the project
  2. Clone down your fork
  3. Create a feature branch
  4. Add your feature + tests
  5. Document new features in the README
  6. Make sure everything still passes by running the tests
  7. If necessary, rebase your commits into logical chunks, without errors
  8. Push the branch up
  9. Send a pull request for your branch

Take a look at the TODO list or known issues for some inspiration if you need it.

Thanks

First class support, commits and pull requests, thanks guys!

License

See LICENSE.md

About

A framework for writing Campfire bots.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Ruby100.0%