streambot

= Installation

the streambot gem is available on rubygems.org[http://rubygems.org/gems/streambot] to get streambot installed, you simply need to run

== stable release

gem install streambot

== development release

gem install streambot --pre

= Documentation

The full rdoc is available on rdoc.info[http://rdoc.info/projects/gr4y/streambot]

= Usage

require 'streambot'

@params = { 'auth' => { 'username' => 'your username', 'password' => 'your password' },
 			'oauth' => { 'key' => 'your consumer key', 'secret' => 'your consumer secret' },
 			'keywords' => ['nowplaying'] }
bot = StreamBot::Tracker.new(@params)
bot.start

= Configuration

Twitter has finally removed the http basic authentication for the REST API. The Streaming API, which the tracker is using, still works with http basic authentication only. So we still need both, the oauth credentials for retweeting and the http basic authentication credentials for tracking.

You need to register an application of the type desktop application on http://dev.twitter.com first!

=== oauth

key:: The consumer key Twitter provides you secret:: The consumer secret Twitter provides you

=== auth username:: Your login username password:: Your login password

=== keywords :: the list of keywords as an array

=== filters_config :: the path to the filters.yml file

I wrote this stuff into my config.yml and load the params with

require 'yaml'
@params = YAML.load_file('config.yml')

= Events / Callbacks

To receive something from an event, you need to call the receive method on the event and pass a block into this method

tracker.event_name.receive do |params|
	# ...
end

== on_error

is fired when an error occures

tracker.on_error.receive do |message, trace|
	# print the error message and the stacktrace to STDOUT
	puts message
	puts trace
	# and stop the tracker
	tracker.stop
end

== on_match

is fired wenn an filter matched on an status

tracker.on_match.receive do |status, filter_path, filter_value|
	puts "filter matched on #{filter_path} with #{filter_value} in status ##{status['id']}"
end

== before_retweet

is fired before the tracker retweets a status

tracker.before_retweet.receive do |status|
	# print the status to STDOUT
	puts status
end

== after_retweet

is fired after the tracker has retweeted a status

tracker.after_retweet.receive do |status|
	# save the status with active record
	Retweet.new(status)
end

= Filters

You need to configure the filters_config in the params and set the path to the YAML file. At the moment this needs to be an YAML file, cause the tracker is reading this file, every time a new status comes in via the client. I decided to read it on each status, cause I don't wanted to restart the Tracker every time I made a change to the filters.

For example we want to filter all tweets with the source "web", we need to define the following line in our filters.yml

"source": "web"

The Tracker checks if the field "source" of the incoming status includes OR is equal to "web". If you want to filter more than one source, you simply need to write it this way:

"source": ["web", "TweetDeck"]

You can define all fields inside the status object. You want to filter tweets by me, so you need to define

"user/screen_name": "gr4y"

You can even filter all tweets of users with an evil background color.

"user/profile_background_color": "666666"

= Contribution == Testing

All Tests should inherit from StreamBot::BaseTest

== Feature Requests / Issues

If you ran into some errors? Then don't be shy and file an issue in the issue-tracker[http://github.com/gr4y/streambot/issues] Maybe you have a feature request then file an issue too.

== Note on Patches/Pull Requests

You want to add a feature or you want to patch streambot?

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

= Copyright

Copyright (c) 2010 Sascha Wessel. See LICENSE for details.