tweetstream 1.1.2 → 1.1.3

data/README.md

@@ -15,38 +15,42 @@ Usage
 
 Using TweetStream is quite simple:
 
-    require 'rubygems'
-    require 'tweetstream'
-
-    TweetStream.configure do |config|
-      config.consumer_key = 'abcdefghijklmnopqrstuvwxyz'
-      config.consumer_secret = '0123456789'
-      config.oauth_token = 'abcdefghijklmnopqrstuvwxyz'
-      config.oauth_token_secret = '0123456789'
-      config.auth_method = :oauth
-      config.parser   = :yajl
-    end
-
-    # This will pull a sample of all tweets based on
-    # your Twitter account's Streaming API role.
-    TweetStream::Client.new.sample do |status|
-      # The status object is a special Hash with
-      # method access to its keys.
-      puts "#{status.text}"
-    end
+```ruby
+require 'rubygems'
+require 'tweetstream'
+
+TweetStream.configure do |config|
+  config.consumer_key = 'abcdefghijklmnopqrstuvwxyz'
+  config.consumer_secret = '0123456789'
+  config.oauth_token = 'abcdefghijklmnopqrstuvwxyz'
+  config.oauth_token_secret = '0123456789'
+  config.auth_method = :oauth
+  config.parser   = :yajl
+end
+
+# This will pull a sample of all tweets based on
+# your Twitter account's Streaming API role.
+TweetStream::Client.new.sample do |status|
+  # The status object is a special Hash with
+  # method access to its keys.
+  puts "#{status.text}"
+end
+```
 
 You can also use it to track keywords or follow a given set of
 user ids:
 
-    # Use 'track' to track a list of single-word keywords
-    TweetStream::Client.new.track('term1', 'term2') do |status|
-      puts "#{status.text}"
-    end
+```ruby
+# Use 'track' to track a list of single-word keywords
+TweetStream::Client.new.track('term1', 'term2') do |status|
+  puts "#{status.text}"
+end
 
-    # Use 'follow' to follow a group of user ids (integers, not screen names)
-    TweetStream::Client.new.follow(14252, 53235) do |status|
-      puts "#{status.text}"
-    end
+# Use 'follow' to follow a group of user ids (integers, not screen names)
+TweetStream::Client.new.follow(14252, 53235) do |status|
+  puts "#{status.text}"
+end
+```
 
 The methods available to TweetStream::Client will be kept in parity
 with the methods available on the Streaming API wiki page.
@@ -56,26 +60,30 @@ Using the Twitter Userstream
 
 Using the Twitter userstream works similarly to the regular streaming, except you use the userstream method.
 
-    # Use 'userstream' to get message from your stream
-    TweetStream::Client.new.userstream do |status|
-      puts status.text
-    end
+```ruby
+# Use 'userstream' to get message from your stream
+TweetStream::Client.new.userstream do |status|
+  puts status.text
+end
+```
 
 You also can use method hooks for both regular timeline statuses and direct messages.
 
-    client = TweetStream::Client.new
+```ruby
+client = TweetStream::Client.new
 
-    client.on_direct_message do |direct_message|
-      puts "direct message"
-      puts direct_message.text
-    end
+client.on_direct_message do |direct_message|
+  puts "direct message"
+  puts direct_message.text
+end
 
-    client.on_timeline_status do |status|
-      puts "timeline status"
-      puts status.text
-    end
+client.on_timeline_status do |status|
+  puts "timeline status"
+  puts status.text
+end
 
-    client.userstream
+client.userstream
+```
 
 Configuration and Changes in 1.1.0
 ----------------------------------
@@ -84,27 +92,33 @@ As of version 1.1.0.rc1 TweetStream supports OAuth.  Please note that in order
 to support OAuth, the `TweetStream::Client` initializer no longer accepts a
 username/password.  `TweetStream::Client` now accepts a hash:
 
-    TweetStream::Client.new(:username => 'you', :password => 'pass')
+```ruby
+TweetStream::Client.new(:username => 'you', :password => 'pass')
+```
 
 Alternatively, you can configure TweetStream via the configure method:
 
-    TweetStream.configure do |config|
-      config.consumer_key = 'cVcIw5zoLFE2a4BdDsmmA'
-      config.consumer_secret = 'yYgVgvTT9uCFAi2IuscbYTCqwJZ1sdQxzISvLhNWUA'
-      config.oauth_token = '4618-H3gU7mjDQ7MtFkAwHhCqD91Cp4RqDTp1AKwGzpHGL3I'
-      config.oauth_token_secret = 'xmc9kFgOXpMdQ590Tho2gV7fE71v5OmBrX8qPGh7Y'
-      config.auth_method = :oauth
-      config.parser   = :yajl
-    end
+```ruby
+TweetStream.configure do |config|
+  config.consumer_key = 'cVcIw5zoLFE2a4BdDsmmA'
+  config.consumer_secret = 'yYgVgvTT9uCFAi2IuscbYTCqwJZ1sdQxzISvLhNWUA'
+  config.oauth_token = '4618-H3gU7mjDQ7MtFkAwHhCqD91Cp4RqDTp1AKwGzpHGL3I'
+  config.oauth_token_secret = 'xmc9kFgOXpMdQ590Tho2gV7fE71v5OmBrX8qPGh7Y'
+  config.auth_method = :oauth
+  config.parser   = :yajl
+end
+```
 
 If you are using Basic Auth:
 
-    TweetStream.configure do |config|
-      config.username = 'username'
-      config.password = 'password'
-      config.auth_method = :basic
-      config.parser   = :yajl
-    end
+```ruby
+TweetStream.configure do |config|
+  config.username = 'username'
+  config.password = 'password'
+  config.auth_method = :basic
+  config.parser   = :yajl
+end
+```
 
 TweetStream assumes OAuth by default.  If you are using Basic Auth, it is recommended
 that you update your code to use OAuth as Twitter is likely to phase out Basic Auth
@@ -116,10 +130,12 @@ Swappable JSON Parsing
 As of version 1.1, TweetStream supports swappable JSON backends via MultiJson. You can
 specify a parser during configuration:
 
-    # Parse tweets using Yajl-Ruby
-    TweetStream.configure do |config|
-      config.parser   = :yajl
-    end.
+```ruby
+# Parse tweets using Yajl-Ruby
+TweetStream.configure do |config|
+  config.parser   = :yajl
+end
+```
 
 Available options are `:yajl`, `:json_gem`, `:json_pure`, and `:ok_json`.
 
@@ -131,37 +147,43 @@ Specifically, it does so when a status is deleted or rate limitations
 have caused some tweets not to appear in the stream. To handle these,
 you can use the on_delete and on_limit methods. Example:
 
-    @client = TweetStream::Client.new
+```ruby
+@client = TweetStream::Client.new
 
-    @client.on_delete do |status_id, user_id|
-      Tweet.delete(status_id)
-    end
+@client.on_delete do |status_id, user_id|
+  Tweet.delete(status_id)
+end
 
-    @client.on_limit do |skip_count|
-      # do something
-    end
+@client.on_limit do |skip_count|
+  # do something
+end
 
-    @client.track('intridea')
+@client.track('intridea')
+```
 
 The on_delete and on_limit methods can also be chained, like so:
 
-    TweetStream::Client.new.on_delete{ |status_id, user_id|
-      Tweet.delete(status_id)
-    }.on_limit { |skip_count|
-      # do something
-    }.track('intridea') do |status|
-      # do something with the status like normal
-    end
+```ruby
+TweetStream::Client.new.on_delete{ |status_id, user_id|
+  Tweet.delete(status_id)
+}.on_limit { |skip_count|
+  # do something
+}.track('intridea') do |status|
+  # do something with the status like normal
+end
+```
 
 You can also provide `:delete` and/or `:limit`
 options when you make your method call:
 
-    TweetStream::Client.new.track('intridea',
-      :delete => Proc.new{ |status_id, user_id| # do something },
-      :limit => Proc.new{ |skip_count| # do something }
-    ) do |status|
-      # do something with the status like normal
-    end
+```ruby
+TweetStream::Client.new.track('intridea',
+  :delete => Proc.new{ |status_id, user_id| # do something },
+  :limit => Proc.new{ |skip_count| # do something }
+) do |status|
+  # do something with the status like normal
+end
+```
 
 Twitter recommends honoring deletions as quickly as possible, and
 you would likely be wise to integrate this functionality into your
@@ -177,16 +199,28 @@ by you in `on_error` will be called. Note that this does not
 indicate something is actually wrong, just that Twitter is momentarily
 down. It could be for routine maintenance, etc.
 
-    TweetStream::Client.new.on_error do |message|
-      # Log your error message somewhere
-    end.track('term') do |status|
-      # Do things when nothing's wrong
-    end
+```ruby
+TweetStream::Client.new.on_error do |message|
+  # Log your error message somewhere
+end.track('term') do |status|
+  # Do things when nothing's wrong
+end
+```
 
 However, if the maximum number of reconnect attempts has been reached,
 TweetStream will raise a `TweetStream::ReconnectError` with
 information about the timeout and number of retries attempted.
 
+On reconnect, the block specified by you in `on_reconnect` will be called:
+
+```ruby
+TweetStream::Client.new.on_reconnect do |timeout, retries|
+  # Do something with the reconnect
+end.track('term') do |status|
+  # Do things when nothing's wrong
+end
+```
+
 Terminating a TweetStream
 -------------------------
 
@@ -195,12 +229,14 @@ track or follow tweet streams. In the case that you need to terminate
 a stream, you may add a second argument to your block that will yield
 the client itself:
 
-    # Stop after collecting 10 statuses
-    @statuses = []
-    TweetStream::Client.new.sample do |status, client|
-      @statuses << status
-      client.stop if @statuses.size >= 10
-    end
+```ruby
+# Stop after collecting 10 statuses
+@statuses = []
+TweetStream::Client.new.sample do |status, client|
+  @statuses << status
+  client.stop if @statuses.size >= 10
+end
+```
 
 When `stop` is called, TweetStream will return from the block
 the last successfully yielded status, allowing you to make note of
@@ -212,10 +248,12 @@ Daemonizing
 It is also possible to create a daemonized script quite easily
 using the TweetStream library:
 
-    # The third argument is an optional process name
-    TweetStream::Daemon.new('tracker').track('term1', 'term2') do |status|
-      # do something in the background
-    end
+```ruby
+# The third argument is an optional process name
+TweetStream::Daemon.new('tracker').track('term1', 'term2') do |status|
+  # do something in the background
+end
+```
 
 If you put the above into a script and run the script with `ruby scriptname.rb`,
 you will see a list of daemonization commands such as start, stop, and run.

data/lib/tweetstream/client.rb

@@ -254,6 +254,22 @@ module TweetStream
       end
     end
 
+    # Set a Proc to be run on reconnect.
+    #
+    #     @client = TweetStream::Client.new
+    #     @client.on_reconnect do |timeout, retries|
+    #       # Make note of the reconnection
+    #     end
+    #
+    def on_reconnect(&block)
+      if block_given?
+        @on_reconnect = block
+        self
+      else
+        @on_reconnect
+      end
+    end
+
     # Set a Proc to be run when connection established.
     # Called in EventMachine::Connection#post_init
     #
@@ -294,6 +310,7 @@ module TweetStream
       delete_proc = query_parameters.delete(:delete) || self.on_delete
       limit_proc = query_parameters.delete(:limit) || self.on_limit
       error_proc = query_parameters.delete(:error) || self.on_error
+      reconnect_proc = query_parameters.delete(:reconnect) || self.on_reconnect
       inited_proc = query_parameters.delete(:inited) || self.on_inited
       direct_message_proc = query_parameters.delete(:direct_message) || self.on_direct_message
       timeline_status_proc = query_parameters.delete(:timeline_status) || self.on_timeline_status
@@ -374,6 +391,10 @@ module TweetStream
           error_proc.call(message) if error_proc.is_a?(Proc)
         end
 
+        @stream.on_reconnect do |timeout, retries|
+          reconnect_proc.call(timeout, retries) if reconnect_proc.is_a?(Proc)
+        end
+
         @stream.on_max_reconnects do |timeout, retries|
           raise TweetStream::ReconnectError.new(timeout, retries)
         end

data/lib/tweetstream/version.rb

@@ -1,3 +1,3 @@
 module TweetStream
-  VERSION = '1.1.2'
+  VERSION = '1.1.3'
 end

data/spec/tweetstream/client_spec.rb

@@ -54,6 +54,7 @@ describe TweetStream::Client do
         :each_item => true,
         :on_error => true,
         :on_max_reconnects => true,
+        :on_reconnect => true,
         :connection_completed => true
       )
       EM.stub!(:run).and_yield
@@ -287,7 +288,7 @@ describe TweetStream::Client do
     end
   end
 
-  %w(on_delete on_limit on_inited).each do |proc_setter|
+  %w(on_delete on_limit on_inited on_reconnect).each do |proc_setter|
     describe "##{proc_setter}" do
       it 'should set when a block is given' do
         proc = Proc.new{|a,b| puts a }
@@ -369,6 +370,7 @@ describe TweetStream::Client do
           :each_item => true,
           :on_error => true,
           :on_max_reconnects => true,
+          :on_reconnect => true,
           :connection_completed => true
         )
         EM.stub!(:run).and_yield

data/spec/tweetstream_spec.rb

@@ -13,6 +13,7 @@ describe TweetStream do
         :each_item => true,
         :on_error => true,
         :on_max_reconnects => true,
+        :on_reconnect => true,
         :connection_completed => true
       )
       EM.stub!(:run).and_yield

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tweetstream
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-21 00:00:00.000000000Z
+date: 2011-11-12 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: twitter-stream
-  requirement: &2153351480 !ruby/object:Gem::Requirement
+  requirement: &2156592560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.1.14
   type: :runtime
   prerelease: false
-  version_requirements: *2153351480
+  version_requirements: *2156592560
 - !ruby/object:Gem::Dependency
   name: daemons
-  requirement: &2153351020 !ruby/object:Gem::Requirement
+  requirement: &2156592100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.1.4
   type: :runtime
   prerelease: false
-  version_requirements: *2153351020
+  version_requirements: *2156592100
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &2153350560 !ruby/object:Gem::Requirement
+  requirement: &2156591640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 1.0.3
   type: :runtime
   prerelease: false
-  version_requirements: *2153350560
+  version_requirements: *2156591640
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2153350100 !ruby/object:Gem::Requirement
+  requirement: &2156591180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *2153350100
+  version_requirements: *2156591180
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &2153349640 !ruby/object:Gem::Requirement
+  requirement: &2156579120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 0.5.4
   type: :development
   prerelease: false
-  version_requirements: *2153349640
+  version_requirements: *2156579120
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &2153349180 !ruby/object:Gem::Requirement
+  requirement: &2156578620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: '0.7'
   type: :development
   prerelease: false
-  version_requirements: *2153349180
+  version_requirements: *2156578620
 - !ruby/object:Gem::Dependency
   name: rdiscount
-  requirement: &2153348720 !ruby/object:Gem::Requirement
+  requirement: &2156578160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,10 +87,10 @@ dependencies:
         version: '1.6'
   type: :development
   prerelease: false
-  version_requirements: *2153348720
+  version_requirements: *2156578160
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2153348260 !ruby/object:Gem::Requirement
+  requirement: &2156577520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -98,10 +98,10 @@ dependencies:
         version: '2.7'
   type: :development
   prerelease: false
-  version_requirements: *2153348260
+  version_requirements: *2156577520
 - !ruby/object:Gem::Dependency
   name: yajl-ruby
-  requirement: &2153347800 !ruby/object:Gem::Requirement
+  requirement: &2156576840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -109,10 +109,10 @@ dependencies:
         version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *2153347800
+  version_requirements: *2156576840
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &2153347340 !ruby/object:Gem::Requirement
+  requirement: &2156576120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -120,10 +120,10 @@ dependencies:
         version: 1.5.1
   type: :development
   prerelease: false
-  version_requirements: *2153347340
+  version_requirements: *2156576120
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &2153346840 !ruby/object:Gem::Requirement
+  requirement: &2156575520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -131,7 +131,7 @@ dependencies:
         version: 0.4.3
   type: :development
   prerelease: false
-  version_requirements: *2153346840
+  version_requirements: *2156575520
 description: TweetStream allows you to easily consume the Twitter Streaming API utilizing
   the YAJL Ruby gem.
 email: