virility 0.0.6 → 0.1.0

data/README.md

@@ -16,18 +16,23 @@ Or install it yourself as:
 
     $ gem install virility
 
-## Usage
+## Basic Usage
 
-The Excitation object will collect the data from all of the available strategies. 
+If all you need is the raw shares numbers for a URL, Virility has some very simple methods you can use right out of the box:
 
-    stats = Virility::Excitation.new("http://rubygems.org")
-    stats.poll # returns a hash with the collected output of all data sources
-    stats.counts # returns a hash of just the virility counts => {:delicious=>943, :facebook=>72, :pinterest=>0, :plusone=>137, :stumbleupon=>1488, :twitter=>2319} 
-    stats.total # returns the sum of all virility counts
+    Virility.poll("http://rubygems.org")   # => Returns a hash with the collected results from all of the social network strategies
+    Virility.counts("http://rubygems.org") # => {:delicious=>0, :facebook=>72, :pinterest=>0, :plus_one=>138, :stumble_upon=>1488, :twitter=>2322}
+    Virility.total("http://rubygems.org")  # => 4020
+    Virility.url("http://rubygems.org")    # => Returns a Virility::Excitation object that you can manipulate
 
-One common implementation would be to collect the total count of all social shares for a given URL
+## More Granular Usage
 
-    Virility::Excitation.new("http://rubygems.org").total # => 4959
+The Virility::Excitation object does the heavy lifting of collecting the data from all of the available strategies.
+
+    virility = Virility::Excitation.new("http://rubygems.org")
+    virility.poll   # returns a hash with the collected output of all data sources
+    virility.counts # returns a hash of just the virility counts => {:delicious=>943, :facebook=>72, :pinterest=>0, :plusone=>137, :stumbleupon=>1488, :twitter=>2319}
+    virility.total  # returns the sum of all virility counts
 
 ## Individual Strategies
 
@@ -39,19 +44,35 @@ Currently there is support for the following social resources:
 * Google Plus One
 * Stumble Upon
 
-Each social resources is implemented as a strategy and contains at least two methods: poll and count.  
+Each social resource is implemented as a Virility::Strategy and contains at least three methods: poll, results and count.  __poll__ does the work of querying the API to get the data and returns the same hash as the results method, __results__ returns the hashed values that were provided by the social network and __count__ pulls out the individual number of shares for that social network.
+
+#### Strategy Initialization
+
+There are several ways you can access the object for an individual strategy.
+
+The Virility object has a __factory__ method that will return the strategy object:
+
+    tweets = Virility.factory(:twitter, "http://rubygems.org") # => returns a Virility::Twitter object with the rubygems url
+
+You can also instate the Virility::Twitter object directly:
+
+    tweets = Virility::Twitter.new("http://rubygems.org")
 
-_poll_ does the work of querying the API to get the data 
-_count_ pulls out the individual number of shares for that social
+#### Individual Usage Example
 
 Let's say you only need to get the number of tweets for a URL, you could use the Virility::Twitter class by itself:
 
     tweets = Virility::Twitter.new("http://rubygems.org")
-    tweets.poll # returns a hash with the collected output from Twitter => {"url"=>"http://rubygems.org/", "count"=>2319} 
-    tweets.count # returns the number of tweets for that URL => 2319 
+    tweets.poll    # returns a hash with the collected output from Twitter => {"url"=>"http://rubygems.org/", "count"=>2319}
+    tweets.results # returns a hash with the collected output from Twitter => {"url"=>"http://rubygems.org/", "count"=>2319}
+    tweets.count   # returns the number of tweets for that URL => 2319
 
 ## Facebook Usage
 
+    fb = Virility::Facebook.new("http://rubygems.org")
+    fb.poll  # returns a hash with the collected output from Facebook
+    fb.count # returns the total_count for that URL
+
 The Facebook strategy leverages the FQL query against the link_stat table. Because of this, the following data fields are available:
 * like_count
 * click_count
@@ -59,16 +80,61 @@ The Facebook strategy leverages the FQL query against the link_stat table. Becau
 * comment_count
 * commentsbox_count
 * total_count (used as the default count for all Facebook activity)
-* comments_fbid
 
-    fb = Virility::Facebook.new("http://rubygems.org")
-    fb.poll # returns a hash with the collected output from Facebook 
-    fb.count # returns the total_count for that URL => 72 
+## Dynamic Finders
+
+#### Virility::Excitation
+
+If you have a Virility::Excitation object, there are dynamic finders that will return the individual Virility::Strategy object for a social network. Simply call the name of the strategy against the Virility::Excitation object and that strategy will be returned:
+
+    virility     = Virility::Excitation.new("http://rubygems.org")
+    facebook     = virility.facebook
+    twitter      = virility.twitter
+    delicious    = virility.delicious
+    pinterest    = virility.pinterest
+    plus_one     = virility.plus_one
+    stumble_upon = virility.stumble_upon
+
+#### Virility::Strategy
+
+If you have a Strategy object, any of the attributes that are commonly returned through the API call will be available as a dynamic finder.  This is particularly useful with the Facebook strategy:
+
+    fb = Virility::Facebook.new("http://rubygems.org/")
+    fb.like_count    # => 12
+    fb.share_count   # => 40
+    fb.comment_count # => 20
+    fb.total_count   # => 72
+
+#### Combined Finders
+
+Leveraging both sets of dynamic finders allows you to build an Excitation object and get all the way through to an attribute for a specific strategy:
+
+    Virility.url("http://google.com/").facebook.like_count # => 979662
+    Virility.url("http://google.com/").stumble_upon.info_link # => "http://www.stumbleupon.com/url/www.google.com/"
 
 ## Important Notes
 
 URL's are very specific in the context of a social media.  For example, http://rubygems.org will return different results than http://rubygems.org/ with a trailing slash.  Also, http vs https will give you different numbers. This actually has a lot to do with why we created this gem.  When testing be sure to investigate all of the URL variations in order to get the most complete picture of your data.
 
+#### Case Study
+
+Compare the total count results for http://ruby-lang.org/en. One has the trailing slash and one does not.
+
+    Virility::Excitation.new("http://www.ruby-lang.org/en").total # => 247695
+    Virility::Excitation.new("http://www.ruby-lang.org/en/").total # => 253190
+
+On this particular day, there was a 5,495 count difference between the two values. Inspecting the actual results shows you which of the social networks takes the varying forms of the urls into account:
+
+    Virility::Excitation.new("http://www.ruby-lang.org/en").counts
+    # => {:delicious=>37, :facebook=>3, :pinterest=>0, :plusone=>20, :stumbleupon=>246937, :twitter=>698}
+
+    Virility::Excitation.new("http://www.ruby-lang.org/en/").counts
+    # => {:delicious=>4314, :facebook=>813, :pinterest=>22, :plusone=>406, :stumbleupon=>246937, :twitter=>698}
+
+Stumbleupon and Twitter are consistent while Delicious, Facebook, Pinterest and Google Plus One return different results. Depending on your needs, you could craft an algorithm that takes all of this into account and attempts to deliver an accurate number by combining the data sets that are different and trusting the ones that are the same.
+
+Based on this logic, it is possible to consider that the true total share count is closer to _253,250_. Not only is this an opinionated number, it's accuracy is questionable based on assumptions, however if you are just trying to get a ballpark feeling of the virility of your content, this number should suffice.
+
 ## Contributing
 
 1. Fork it

data/lib/virility.rb

@@ -1,11 +1,43 @@
 require 'cgi'
 require 'httparty'
 
-require "virility/version"
+require 'virility/version'
+require 'virility/supporter'
 require 'virility/excitation'
-require 'virility/context'
+require 'virility/strategy'
+require 'virility/exceptions'
+
 Dir["#{File.dirname(__FILE__)}/virility/strategies/**/*.rb"].each {|f| require f}
 
 module Virility
-  # Your code goes here...
+
+	#
+	# Public API
+	#
+
+	def self.counts(url)
+		Virility::Excitation.new(url).counts
+	end
+
+	def self.total(url)
+		Virility::Excitation.new(url).total
+	end
+
+	def self.poll(url)
+		Virility::Excitation.new(url).poll
+	end
+
+	def self.url(url)
+		virility = Virility::Excitation.new(url)
+		virility.poll
+		virility
+	end
+
+	#
+	# Factory
+	#
+
+	def self.factory(strategy, url)
+		Virility::Excitation.new(url).send(strategy)
+	end
 end

data/lib/virility/exceptions.rb

@@ -0,0 +1,5 @@
+module Virility
+
+	class UnknownStrategy < StandardError; end
+
+end

data/lib/virility/excitation.rb

@@ -1,5 +1,7 @@
 module Virility
 	class Excitation
+		include Virility::Supporter
+		
 		attr_accessor :url, :results, :strategies, :counts
 
 		#
@@ -7,7 +9,7 @@ module Virility
 		#
 
 		def initialize url
-			@url = encode url
+			@url = url
 			@strategies = {}
 			@results = {}
 			@counts = {}
@@ -19,7 +21,7 @@ module Virility
 		#
 
 		def poll
-			if @results.empty?	
+			if @results.empty?
 				@strategies.each do |name, strategy|
 					begin
 						@results[symbolize_for_key(strategy)] = strategy.poll
@@ -34,14 +36,14 @@ module Virility
 		def get_response(strategy)
 			@strategies[strategy].response if @strategies[strategy]
 		end
-		
+
 		#
 		# Return Collected Counts as a Hash
 		#
-		
+
 		def counts
 			poll
-			if @counts.empty?		
+			if @counts.empty?
 				@strategies.each do |name, strategy|
 					begin
 						@counts[symbolize_for_key(strategy)] = strategy.count.to_i
@@ -52,7 +54,7 @@ module Virility
 			end
 			@counts
 		end
-		
+
 		def total_virility
 			counts.values.inject(0) { |result, count| result + count }
 		end
@@ -67,51 +69,35 @@ module Virility
 		end
 
 		#
-		# URL Encoding / Decoding Methods
-		#
-
-		def encode url
-			CGI.escape url
-		end
-
-		def url
-			CGI.unescape @url
-		end
-
-		def escaped_url
-			@url
-		end
-
-		#
-		# Camelize
+		# Reflection
 		#
 
-		def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
-		  if first_letter_in_uppercase
-		    lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
-		  else
-		    lower_case_and_underscored_word.first + camelize(lower_case_and_underscored_word)[1..-1]
-		  end
+		def attributes
+			{:url => @url, :available_strategies => @strategies.keys}
 		end
 
 		#
-		# Convert Class Name To Appropriate Key Symbol
+		# Dynamic Methods
 		#
 
-		def symbolize_for_key(klass)
-			klass.class.to_s.gsub(/Virility::/, '').downcase.to_sym
+		def get_strategy strategy
+			if strategy_exists?(strategy)
+				@strategies[strategy.to_sym]
+			else
+				raise UnknownStrategy, "#{strategy} Is Not A Known Strategy"
+			end
 		end
 
-		def get_class_string(klass)
-			File.basename(klass).gsub(/\.rb/,'')
+		def strategy_exists? strategy
+			!@strategies[strategy.to_sym].nil?
 		end
 
-		#
-		# Reflection
-		#
-
-		def attributes
-			{:url => @url, :available_strategies => @strategies.keys}
+		def method_missing(name, *args, &block)
+			if strategy_exists?(name)
+				get_strategy(name)
+			else
+				raise UnknownStrategy, "#{name} Is Not A Known Strategy"
+			end
 		end
 
 	end

data/lib/virility/strategies/delicious.rb

@@ -1,14 +1,13 @@
 module Virility
-	class Delicious < Context
-	
-		def poll
-			@response = self.class.get("http://feeds.delicious.com/v2/json/urlinfo/data?url=#{@url}")
-			@results = @response.parsed_response.empty? ? {"total_posts" => 0} : @response.parsed_response.first
+	class Delicious < Strategy
+
+		def census
+			self.class.get("http://feeds.delicious.com/v2/json/urlinfo/data?url=#{@url}")
 		end
-		
+
 		def count
-			@results["total_posts"] || 0
+			results["total_posts"] || 0
 		end
-	
+
 	end
 end

data/lib/virility/strategies/facebook.rb

@@ -1,14 +1,21 @@
 module Virility
-	class Facebook < Context
-		BASE_URL = "https://api.facebook.com/method/fql.query?query=SELECT+url%2C+normalized_url%2C+share_count%2C+like_count%2C+comment_count%2C+total_count%2C+commentsbox_count%2C+comments_fbid%2C+click_count+FROM+link_stat+WHERE+url%3D"
+	class Facebook < Strategy
+		BASE_URL = "https://api.facebook.com/method/fql.query?query=SELECT+share_count%2C+like_count%2C+comment_count%2C+total_count%2C+commentsbox_count%2C+click_count+FROM+link_stat+WHERE+url%3D"
 
 		def poll
 			@response = self.class.get("#{BASE_URL}%22#{@url}%22")
-			@results = @response.parsed_response["fql_query_response"]["link_stat"]
+			@results = valid_response_test ? @response.parsed_response["fql_query_response"]["link_stat"] : {"total_count" => 0}
 		end
-		
+
 		def count
-			@results["total_count"] || 0
+			results["total_count"] || 0
 		end
+		
+	private
+	
+		def valid_response_test
+			@response.respond_to?(:parsed_response) and @response.parsed_response.is_a?(Hash) and !@response.parsed_response["fql_query_response"].nil? and !@response.parsed_response["fql_query_response"]["link_stat"].nil?
+		end
+
 	end
 end

data/lib/virility/strategies/pinterest.rb

@@ -1,20 +1,19 @@
 module Virility
-	class Pinterest < Context
-	
+	class Pinterest < Strategy
+
 	  parser(
 	    Proc.new do |body, format|
 	      MultiJson.decode(body.scan(/(\{.+\})/).flatten.first)
 	    end
 	  )
-	
-		def poll
-			@response = self.class.get("http://api.pinterest.com/v1/urls/count.json?url=#{@url}")
-			@results = @response.parsed_response
+
+		def census
+			self.class.get("http://api.pinterest.com/v1/urls/count.json?url=#{@url}")
 		end
-		
+
 		def count
-			@results["count"] || 0
+			results["count"] || 0
 		end
-	
+
 	end
 end

data/lib/virility/strategies/plus_one.rb

@@ -1,6 +1,6 @@
 # http://stackoverflow.com/questions/7403553/how-do-i-get-the-counter-of-a-google-plus-1-button
 module Virility
-	class PlusOne < Context
+	class PlusOne < Strategy
 	
 	  parser(
 	    Proc.new do |body, format|
@@ -8,13 +8,12 @@ module Virility
 	    end
 	  )
 	
-		def poll
-			@response = self.class.get("https://plusone.google.com/_/+1/fastbutton?url=#{@url}")
-			@results = @response.parsed_response
+		def census
+			self.class.get("https://plusone.google.com/_/+1/fastbutton?url=#{@url}")
 		end
 		
 		def count
-			@results["shares"] || 0
+			results["shares"].to_i || 0
 		end
 	
 	end

data/lib/virility/strategies/stumble_upon.rb

@@ -1,5 +1,5 @@
 module Virility
-	class StumbleUpon < Context
+	class StumbleUpon < Strategy
 
 	  parser(
 	    Proc.new do |body, format|
@@ -7,13 +7,12 @@ module Virility
 	    end
 	  )
 	
-		def poll
-			@response = self.class.get("http://www.stumbleupon.com/services/1.01/badge.getinfo?url=#{@url}")
-			@results = @response.parsed_response
+		def census
+			self.class.get("http://www.stumbleupon.com/services/1.01/badge.getinfo?url=#{@url}")
 		end
 		
 		def count
-			@results["views"] || 0
+			results["views"] || 0
 		end
 	
 	end

data/lib/virility/strategies/twitter.rb

@@ -1,13 +1,12 @@
 module Virility
-	class Twitter < Context
+	class Twitter < Strategy
 	
-		def poll
-			@response = self.class.get("http://urls.api.twitter.com/1/urls/count.json?url=#{@url}")
-			@results = @response.parsed_response
+		def census
+			self.class.get("http://urls.api.twitter.com/1/urls/count.json?url=#{@url}")
 		end
 		
 		def count
-			@results["count"] || 0
+			results["count"] || 0
 		end
 	
 	end