Tweedle

Lightweight wrapper for the Twitter Streaming API.

Tweedle is a lightweight wrapper for the Twitter Streaming API, written out of the need for a library that does not depend on EventMachine.

The library currently only supports the regular Streaming API Methods. User Streams and Site Streams are currently not implemented.

Installation

The best way to install Tweedle is with RubyGems:

$ [sudo] gem install tweedle

Or add it to your Gemfile:

gem 'tweedle'

And then execute:

$ bundle install

If you’re installing from source, you can use Bundler to pick up all the gems, including those required for running the tests and creating coverage reports:

$ bundle install

Consult the online documentation for more information on Bundler

Dependencies

The goal is to keep Tweedle’s dependencies to a minimum. However, in order to keep the source as simple as possible, it requires the following gems:

  • OAuth to authenticate with Twitter and sign the requests.

  • multi_json to parse the response bodies.

Getting started

First, setup the library to use the desired OAuth credentials:

Tweedle.configure do |config|
  config.consumer_key    = "the_consumer_key"
  config.consumer_secret = "the_consumer_secret"
  config.oauth_token     = "the_oauth_token"
  config.oauth_secret    = "the_oauth_secret"
end

Then, create a client:

client = Tweedle.new

Try things out by streaming Twitter’s sample stream:

client.statuses.sample do |tweet|
  next unless text = tweet[:text]
  puts "#{tweet[:user][:screen_name]}: #{text}"
end

HTTP parameters are supported, too:

client.statuses.sample(stall_warnings: true, count: 1000) do |tweet|
  next unless text = tweet[:text]
  puts "#{tweet[:user][:screen_name]}: #{text}"
end

And the wrapper for the filter stream uses POST requsts, as recommended by Twitter:

predicates = {
  locations: [-122.75, 36.8, -121.75, 37.8, -74,40, -73,41],
      track: ["ruby", "tweedle"]
}

client.statuses.filter(stall_warnings: true, predicates: predicates) do |tweet|
  next unless text = tweet[:text]
  puts "#{tweet[:user][:screen_name]}: #{text}"
end

The full API documentation is available online.

Contributing

If you’d like to contribute to Tweedle, start by forking the repo on GitHub:

github.com/tobiassvn/tweedle

To get all of the dependencies, install the gem first. The best way to getyour changes merged back into core is as follows:

  • Clone down your fork.

  • Create a thoughtfully named topic branch to contain your change.

  • Hack away.

  • Add tests and make sure everything still passes by running rake.

  • If you are adding new functionality, document it in the README.

  • If you add new attributes, classes, constants or methods, document in the TomDoc format.

  • Do not change the version number, I will do that on my end.

  • If necessary, rebase your commits into logical chunks, without errors

  • Push the branch up to GitHub

  • Send a pull request to the tobiassvn/tweedle project.

License

Copyright (c) 2012 Tobias Svensson.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.