boffin 0.2.0 → 0.3.0

data/CHANGELOG.md

@@ -1,7 +1,15 @@
-0.2.0
+**0.3.0**
+
+ * `Hit` can now accept a custom increment, this allows values such as cents to
+   be tracked. (Justin Giancola)
+ * Unique qualities are now passed in as a member in an options hash for
+   `Tracker#hit`, this deprecates the unique qualities argument and allows for
+   other options such as `:increment` to be passed as well. (Justin Giancola)
+
+**0.2.0**
 
  * Support for Ruby 1.8.7 thanks to Justin Giancola
 
-0.1.0
+**0.1.0**
 
  * Initial public release

data/README.md

@@ -51,7 +51,7 @@ Most of Boffin's default configuration options are quite reasonable, but they
 are easy to change if required:
 
 ```ruby
-Boffin.configure do |c|
+Boffin.config do |c|
   c.redis              = MyApp.redis             # Redis.connect by default
   c.namespace          = "tracking:#{MyApp.env}" # Redis key namespace
   c.hours_window_secs  = 3.days     # Time to maintain hourly interval data
@@ -128,7 +128,7 @@ identify hits from particular users or sessions:
 ```ruby
 get '/listings/:id' do
   @listing = Listing[params[:id]]
-  @listing.hit(:views, [current_user, session[:id]])
+  @listing.hit(:views, unique: [current_user, session[:id]])
   haml :'listings/show'
 end
 ```
@@ -144,7 +144,7 @@ we want to hit an instance, so let's create a helper:
 ```ruby
 helpers do
   def hit(trackable, type)
-    trackable.hit(type, [current_user, session[:id]])
+    trackable.hit(type, unique: [current_user, session[:id]])
   end
 end
 ```
@@ -156,7 +156,7 @@ applicable to a Rails application as well:
 class ApplicationController < ActionController::Base
   protected
   def hit(trackable, type)
-    trackable.hit(type, [current_user, session[:session_id]])
+    trackable.hit(type, unique: [current_user, session[:session_id]])
   end
 end
 ```
@@ -238,14 +238,14 @@ track your friends' favourite and least favourite colours:
 ```ruby
 @tracker = Boffin::Tracker.new(:colours, [:faves, :unfaves])
 
-@tracker.hit(:faves,   'red',    ['lena'])
-@tracker.hit(:unfaves, 'blue',   ['lena'])
-@tracker.hit(:faves,   'green',  ['soren'])
-@tracker.hit(:unfaves, 'red',    ['soren'])
-@tracker.hit(:faves,   'green',  ['jens'])
-@tracker.hit(:unfaves, 'yellow', ['jens'])
+@tracker.hit(:faves,   'red',    unique: ['lena'])
+@tracker.hit(:unfaves, 'blue',   unique: ['lena'])
+@tracker.hit(:faves,   'green',  unique: ['soren'])
+@tracker.hit(:unfaves, 'red',    unique: ['soren'])
+@tracker.hit(:faves,   'green',  unique: ['jens'])
+@tracker.hit(:unfaves, 'yellow', unique: ['jens'])
 
-@tracker.top(:faves, months: 1)
+@tracker.top(:faves, days: 1)
 ```
 
 Or, perhaps you'd like to clone Twitter? Using Boffin, all the work is
@@ -263,7 +263,7 @@ end
 post '/tweets' do
   @tweet = Tweet.create(params[:tweet])
   if @tweet.valid?
-    @tweet.words.each { WordsTracker.hit(:tweets, word) }
+    @tweet.words.each { |word| WordsTracker.hit(:tweets, word) }
     redirect to("/tweets/#{@tweet.id}")
   else
     haml :'tweets/form'
@@ -277,18 +277,52 @@ end
 ```
 _*This is a joke._
 
-TODO
-----
+
+Custom increments
+-----------------
+
+For some applications you might want to track something beyond simple hits.
+To accomodate this you can specify a custom increment to any hit you record.
+For example, if you run an ecommerce site it might be nice to know which
+products are your bestsellers:
+
+```ruby
+class Product < ActiveRecord::Base
+  Boffin.track(self, [:sales])
+end
+
+class Order < ActiveRecord::Base
+  after_create :track_sales
+
+  private
+
+  def track_sales
+    line_items.each do |line_item|
+      product = line_item.product
+      amount  = product.amount.cents * line_item.quantity
+      product.hit :sales, increment: amount
+    end
+  end
+end
+```
+
+Then, when you want to check on your sales over the last day:
+
+```ruby
+Product.top_ids(:sales, hours: 24, counts: true)
+```
+
+The Future&trade;
+-----------------
 
  * Ability to hit multiple instances in one command
  * Ability to get hit-count range for an instance
  * Some nice examples with pretty things
- * ORM adapters for niceness and tighter integration
+ * Maybe ORM adapters for niceness and tighter integration
  * Examples of how to turn IDs back into instances
  * Reporting DSL thingy
- * Web framework integration (helpers for tracking hits)
- * Ability to blend unique hits with raw hits
- * Ability to unhit an instance (if a model instance is destroyed for example)
+ * Web framework integration (helpers for tracking hits, console type ditty.)
+ * Ability to union on unique hits and raw hits
 
 FAQ
 ---

data/lib/boffin/hit.rb

@@ -12,10 +12,21 @@ module Boffin
     # @param [Object] instance
     #   The instance that is being hit, any object that responds to
     #   `#to_member`, `#id`, or `#to_s`
-    # @param [Array] uniquenesses
-    #   An array of which the first object is used to generate a session
-    #   identifier for hit uniqueness
-    def initialize(tracker, type, instance, uniquenesses = [])
+    # @param [Hash] options
+    # @option options [Array] :unique ([]) An array of which the first
+    #   object is used to generate a session identifier for hit uniqueness
+    # @option options [Fixnum] :increment (1) The hit increment
+    def initialize(tracker, type, instance, opts = {})
+      if opts.is_a?(Array)
+        warn "This constructor is deprecated and will soon be unavailable\n" \
+             "please create Hits with: \n" \
+             "Hit.new(@tracker, :type, @instance, :unique => [1,2,3,4])\n"
+        uniquenesses = opts
+        @increment   = 1
+      else
+        uniquenesses = opts.delete(:unique) || []
+        @increment   = opts.delete(:increment) || 1
+      end
       @now      = Time.now
       @sessid   = Utils.uniquenesses_as_session_identifier(uniquenesses)
       @type     = type
@@ -54,7 +65,7 @@ module Boffin
     #   `true` if this hit is unique, `false` if it has been made before by the
     #   same session identifer.
     def track_hit
-      redis.incr(keyspace.hit_count(@type, @instance))
+      redis.incrby(keyspace.hit_count(@type, @instance), @increment)
       redis.zincrby(keyspace.hits(@type, @instance), 1, @sessid) == '1'
     end
 
@@ -75,7 +86,7 @@ module Boffin
     #   Changes keyspace scope to keys under .uniq
     def set_window_interval(interval, uniq = false)
       key = keyspace(uniq).hits_time_window(@type, interval, @now)
-      redis.zincrby(key, 1, @member)
+      redis.zincrby(key, @increment, @member)
       redis.expire(key, @tracker.config.send("#{interval}_window_secs"))
     end
 

data/lib/boffin/trackable.rb

@@ -40,8 +40,8 @@ module Boffin
 
     # @see Tracker#hit
     # @return [Hit]
-    def hit(type, uniquenesses = [])
-      self.class.boffin.hit(type, self, uniquenesses)
+    def hit(type, opts = {})
+      self.class.boffin.hit(type, self, opts)
     end
 
     # @see Tracker#hit_count

data/lib/boffin/tracker.rb

@@ -25,14 +25,16 @@ module Boffin
 
     # @param [Symbol] hit_type
     # @param [#as_member, #id, #to_s] instance
-    # @param [Array] uniquenesses
+    # @param [Hash] options
+    # @option options [Array] :unique ([]) uniquenesses
+    # @option options [Fixnum] :increment (1) hit increment
     # @return [Hit]
     # @raise Boffin::UndefinedHitTypeError
     #   Raised if a list of hit types is available and the provided hit type is
     #   not in the list.
-    def hit(hit_type, instance, uniquenesses = [])
+    def hit(hit_type, instance, opts = {})
       validate_hit_type(hit_type)
-      Hit.new(self, hit_type, instance, uniquenesses)
+      Hit.new(self, hit_type, instance, opts)
     end
 
     # @param [Symbol] hit_type

data/lib/boffin/utils.rb

@@ -54,7 +54,11 @@ module Boffin
       # NOTE: this feels like a hack. I'm sure there is a more elegant way
       # to determine whether the :id method is the built in Object#id but
       # I can't think of it
-      obj.respond_to?(:id) and obj.id != obj.object_id
+      if RUBY_VERSION < "1.9"
+        obj.respond_to?(:id) and obj.id != obj.object_id
+      else
+        obj.respond_to?(:id)
+      end
     end
 
     # Pulls time interval information from a hash of options.

data/lib/boffin/version.rb

@@ -1,4 +1,4 @@
 module Boffin
   # Version of this Boffin release
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/spec/boffin/hit_spec.rb

@@ -14,7 +14,7 @@ describe Boffin::Hit, '::new' do
   end
 
   it 'stores hit data under the appropriate keys' do
-    Boffin::Hit.new(@tracker, :tests, @ditty, [nil, @user])
+    Boffin::Hit.new(@tracker, :tests, @ditty, :unique => [nil, @user])
     [:hours, :days, :months].each do |interval|
       @tracker.top(:tests, interval => 1, :counts => true).
         should == [['1', 1]]
@@ -26,8 +26,8 @@ describe Boffin::Hit, '::new' do
   end
 
   it 'does not store data under unique keys if the hit is not unique' do
-    Boffin::Hit.new(@tracker, :tests, @ditty, [nil, @user])
-    Boffin::Hit.new(@tracker, :tests, @ditty, [nil, @user])
+    Boffin::Hit.new(@tracker, :tests, @ditty, :unique => [nil, @user])
+    Boffin::Hit.new(@tracker, :tests, @ditty, :unique => [nil, @user])
     [:hours, :days, :months].each do |interval|
       @tracker.top(:tests, interval => 1, :counts => true).
         should == [['1', 2]]
@@ -39,4 +39,14 @@ describe Boffin::Hit, '::new' do
     @tracker.uhit_count(:tests, @ditty).should == 1
   end
 
+  it 'allows arbitrary hit increments' do
+    Boffin::Hit.new(@tracker, :tests, @ditty, :unique => [nil, @user], :increment => 5)
+    Boffin::Hit.new(@tracker, :tests, @ditty, :unique => [nil, @user], :increment => 5)
+    [:hours, :days, :months].each do |interval|
+      @tracker.top(:tests, interval => 1, :counts => true).
+        should == [['1', 10]]
+      @tracker.top(:tests, interval => 1, :counts => true, :unique => true).
+        should == [['1', 5]]
+    end
+  end
 end

data/spec/boffin/trackable_spec.rb

@@ -4,8 +4,8 @@ describe Boffin::Trackable do
   before :all do
     SpecHelper.flush_keyspace!
     @mock = MockTrackableInjected.new(1)
-    @mock.hit(:views, ['sess.1'])
-    @mock.hit(:views, ['sess.1'])
+    @mock.hit(:views, :unique => ['sess.1'])
+    @mock.hit(:views, :unique => ['sess.1'])
   end
 
   it 'can be included' do

data/spec/boffin/tracker_spec.rb

@@ -14,43 +14,43 @@ describe Boffin::Tracker do
 
     Timecop.freeze(@date - 2) do
       @tracker.hit(:views, @instance3)
-      @tracker.hit(:likes, @instance3, [@user1])
-      @tracker.hit(:views, @instance3, ['sess.1'])
-      @tracker.hit(:views, @instance3, ['sess.2'])
-      @tracker.hit(:views, @instance3, [@user2])
-      @tracker.hit(:likes, @instance1, [nil, nil])
-      @tracker.hit(:views, @instance3, ['sess.4'])
-      @tracker.hit(:views, @instance3, [@user1])
-      @tracker.hit(:views, @instance2, [@user2])
-      @tracker.hit(:views, @instance3, [@user2])
+      @tracker.hit(:likes, @instance3, :unique => [@user1])
+      @tracker.hit(:views, @instance3, :unique => ['sess.1'])
+      @tracker.hit(:views, @instance3, :unique => ['sess.2'])
+      @tracker.hit(:views, @instance3, :unique => [@user2])
+      @tracker.hit(:likes, @instance1, :unique => [nil, nil])
+      @tracker.hit(:views, @instance3, :unique => ['sess.4'])
+      @tracker.hit(:views, @instance3, :unique => [@user1])
+      @tracker.hit(:views, @instance2, :unique => [@user2])
+      @tracker.hit(:views, @instance3, :unique => [@user2])
       @tracker.hit(:likes, @instance3)
-      @tracker.hit(:views, @instance3, ['sess.1'])
+      @tracker.hit(:views, @instance3, :unique => ['sess.1'])
       @tracker.hit(:views, @instance3)
-      @tracker.hit(:likes, @instance3, [@user1])
-      @tracker.hit(:views, @instance3, ['sess.1'])
+      @tracker.hit(:likes, @instance3, :unique => [@user1])
+      @tracker.hit(:views, @instance3, :unique => ['sess.1'], :increment => 2)
     end
 
     Timecop.freeze(@date - 1) do
       @tracker.hit(:views, @instance1)
-      @tracker.hit(:likes, @instance2, [@user1])
-      @tracker.hit(:views, @instance2, ['sess.4'])
-      @tracker.hit(:views, @instance2, [nil, @user1])
-      @tracker.hit(:views, @instance2, ['sess.3'])
-      @tracker.hit(:views, @instance1, ['sess.3'])
-      @tracker.hit(:views, @instance1, [@user1])
-      @tracker.hit(:views, @instance2, ['sess.2'])
-      @tracker.hit(:views, @instance1, [@user1])
-      @tracker.hit(:views, @instance1, [@user2])
-    end
-
-    @tracker.hit(:views, @instance3, ['sess.2'])
-    @tracker.hit(:views, @instance2, [@user2])
+      @tracker.hit(:likes, @instance2, :unique => [@user1])
+      @tracker.hit(:views, @instance2, :unique => ['sess.4'])
+      @tracker.hit(:views, @instance2, :unique => [nil, @user1])
+      @tracker.hit(:views, @instance2, :unique => ['sess.3'])
+      @tracker.hit(:views, @instance1, :unique => ['sess.3'])
+      @tracker.hit(:views, @instance1, :unique => [@user1])
+      @tracker.hit(:views, @instance2, :unique => ['sess.2'])
+      @tracker.hit(:views, @instance1, :unique => [@user1])
+      @tracker.hit(:views, @instance1, :unique => [@user2])
+    end
+
+    @tracker.hit(:views, @instance3, :unique => ['sess.2'])
+    @tracker.hit(:views, @instance2, :unique => [@user2])
     @tracker.hit(:likes, @instance2)
-    @tracker.hit(:views, @instance2, [@user1])
-    @tracker.hit(:views, @instance1, ['sess.4'])
-    @tracker.hit(:views, @instance3, ['sess.3'])
-    @tracker.hit(:views, @instance1, [@user1])
-    @tracker.hit(:views, @instance1, [@user2])
+    @tracker.hit(:views, @instance2, :unique => [@user1])
+    @tracker.hit(:views, @instance1, :unique => ['sess.4'])
+    @tracker.hit(:views, @instance3, :unique => ['sess.3'])
+    @tracker.hit(:views, @instance1, :unique => [@user1])
+    @tracker.hit(:views, @instance1, :unique => [@user2])
   end
 
   describe '#hit' do
@@ -134,7 +134,7 @@ describe Boffin::Tracker do
     it 'returns ids and counts when passed { counts: true } as an option' do
       ids = @tracker.top(:views, :days => 3, :counts => true)
       ids.should == [
-        ['300', 12],
+        ['300', 13],
         ['100', 8],
         ['200', 7]
       ]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boffin
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-08 00:00:00.000000000Z
+date: 2011-09-12 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
-  requirement: &70347564151120 !ruby/object:Gem::Requirement
+  requirement: &70276273568860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '2.2'
   type: :runtime
   prerelease: false
-  version_requirements: *70347564151120
+  version_requirements: *70276273568860
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70347564150300 !ruby/object:Gem::Requirement
+  requirement: &70276273568280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '2.6'
   type: :development
   prerelease: false
-  version_requirements: *70347564150300
+  version_requirements: *70276273568280
 - !ruby/object:Gem::Dependency
   name: timecop
-  requirement: &70347564149720 !ruby/object:Gem::Requirement
+  requirement: &70276273567900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70347564149720
+  version_requirements: *70276273567900
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70347564149100 !ruby/object:Gem::Requirement
+  requirement: &70276273567340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: 1.0.14
   type: :development
   prerelease: false
-  version_requirements: *70347564149100
+  version_requirements: *70276273567340
 description: ! 'Boffin is a library for tracking hits to things in your Ruby application.
   Things
 
@@ -111,7 +111,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3845958252376638612
+      hash: -2879744131493119363
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -120,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3845958252376638612
+      hash: -2879744131493119363
 requirements: []
 rubyforge_project: boffin
 rubygems_version: 1.8.6