twords 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: deb67eadb91095b9a3ef2a0cefe7c9452038c0f1
-  data.tar.gz: 7cb612c4aa544038bfb9eb2c88c5367269b1c4c6
+  metadata.gz: bd0f26ec512e5184542436f0313c827888abed77
+  data.tar.gz: fc38f75b82aefeac2b695398f22659ebe251743c
 SHA512:
-  metadata.gz: 615f31dd12aea64aa8ff1304e947f36706a2e23145ca35153227aac72999359d87bfa2ef97c5f6beaae258be2f97f403c1cba7c78502e7c28991318da081768c
-  data.tar.gz: 49357b0e2060a1726956fb5c1f996ff2281eb2306a4f2ebe1fa2176851d95af5181c5c4c2f5610cd36db782193f6c60776a374d7a7ac70d8f73b79b3a3802394
+  metadata.gz: 79960eed5ede9ea409a0b60cda01e383fba21d960a6c9112a67e6495d840b78cc26bc5593ee1fdce56ee9d34544b73484ab3de27e78f7f9ad9106b199e9a9f5e
+  data.tar.gz: 2f1f574ffb732f92a0fa2d7e5b1c1dc4665b2e4bc799e7ff31b16b8598fdee5549b36f2eb0c392a5cd49f84198a5dc911ad559819163559c5b000c2cb59d36f0

data/README.md

@@ -4,6 +4,8 @@
 
 Count the occurrences of words in a tweeter's tweets.
 
+Configurable - set the words to ignore, the range of dates to look at, and whether to include hashtags, @-mentions, and URLs. Customize your Twitter configuration, too. Sensible defaults are provided for all options. Look at the data in different ways. Easily convert and/or export to CSV and JSON. Change configuration options on the fly and re-audit with ease.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -77,6 +79,22 @@ twords.words
 # => { "#TACOSTACOSTACOS"=>14321, "pizza"=>32, "burger"=>28, "pups"=>36, ... }
 ```
 
+Other useful methods:
+
+```ruby
+twords = Twords.new 'user'
+twords.audit
+twords.tweets # An array of the Twitter::Tweet objects included in the count
+twords.total_word_count # The total combined occurrences of the included words
+twords.percentages # Replace word count with the word's percentage of total words
+twords.sort_percentages # Sort the above results in descending order
+twords.to_[csv|json] # Generate CSV || JSON for results
+twords.write_to_[csv|json](opts) # Write CSV || JSON to file.
+                                 # Options - :filename writes the file to the 
+                                 # specified relative path (default = 'twords_report.[csv|json]').
+                                 # Other options are passed along to File#open
+
+```
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/twords.rb

@@ -4,42 +4,61 @@ require 'twords/configuration'
 require 'twords/instance_methods'
 require 'twords/version'
 
-# Twords.config do |config|
-#   config.rejects = %w[my us we an w/ because b/c or are this is from
-#                       be on the for to and at our of in rt a with &
-#                       that it by as if was]
-
-#   config.range   = 30
-#   config.up_to { Time.now }
-#   config.include_hashtags = false
-#   config.include_uris     = false
-#   config.include_mentions = false
+# Count the occurrences of words in a tweeter's tweets
+#
+#   Twords.config do |config|
+#     config.rejects = %w[my us we an w/ because b/c or are this is from
+#                         be on the for to and at our of in rt a with &
+#                         that it by as if was]
+#
+#     config.range   = 30
+#     config.up_to { Time.now }
+#     config.include_hashtags = false
+#     config.include_uris     = false
+#     config.include_mentions = false
 #
-#   config.twitter_client do |twitter|
-#     twitter.consumer_key        = YOUR_TWITTER_CONSUMER_KEY
-#     twitter.consumer_secret     = YOUR_TWITTER_CONSUMER_SECRET
-#     twitter.access_token        = YOUR_TWITTER_ACCESS_TOKEN
-#     twitter.access_token_secret = YOUR_TWITTER_ACCESS_TOKEN_SECRET
+#     config.twitter_client do |twitter|
+#       twitter.consumer_key        = YOUR_TWITTER_CONSUMER_KEY
+#       twitter.consumer_secret     = YOUR_TWITTER_CONSUMER_SECRET
+#       twitter.access_token        = YOUR_TWITTER_ACCESS_TOKEN
+#       twitter.access_token_secret = YOUR_TWITTER_ACCESS_TOKEN_SECRET
+#     end
 #   end
-# end
 #
-# twords = Twords.new 'user_one', 'user_two'
+#   twords = Twords.new 'user_one', 'user_two'
 #
-# twords.audit
-# # => true
+#   twords.audit
+#   # => true
 #
-# twords.words
-# # => { "pizza"=>32, "burger"=>28, "pups"=>36, ... }
+#   twords.words
+#   # => { "pizza"=>32, "burger"=>28, "pups"=>36, ... }
 class Twords
+  # Set configuration options. The same configuration is shared accross all objects in the
+  # Twords namespace. Configuration can be changed on the fly and will affect all instantiated
+  # objects.
+  #
+  # @api public
+  # for block { |config| ... }
+  # @yield [Twords::Configuration] call methods on an instance of Twords::Configuration to override
+  # the default configuration settings.
+  # @return [Twords::Configuration]
   def self.config
     @configuration ||= Configuration.new
     @configuration.tap { |config| yield config if block_given? }
   end
 
+  # Resets all configuration options to default settings
+  #
+  # @api public
+  # @return [Twords::Configuration]
   def self.reset_config!
     config.reset!
   end
 
+  # Access the Twitter client
+  #
+  # @api public
+  # @return [Twords::TwitterClient]
   def self.client
     config.client
   end

data/lib/twords/config_accessible.rb

@@ -5,6 +5,9 @@ class Twords
   module ConfigAccessible
     module_function
 
+    # Provides a private method to access the shared config when included in a Module or Class
+    #
+    # @return [Twords::Configuration]
     def config
       Twords.config
     end

data/lib/twords/configuration.rb

@@ -78,18 +78,18 @@ class Twords
 
     private
 
-    # private method
+    # @api private
     def set_defaults
       ivars = %i[include_uris include_hashtags include_mentions range client up_to_block rejects]
       ivars.each { |ivar| instance_variable_set("@#{ivar}", DEFAULT_OPTIONS[ivar]) }
     end
 
-    # private method
+    # @api private
     def a_boolean?(other)
       [true, false].include?(other)
     end
 
-    # private method
+    # @api private
     def not_a_boolean_error(boolean)
       raise ArgumentError, 'argument must be a booolean value' unless a_boolean?(boolean)
     end

data/lib/twords/instance_methods.rb

@@ -10,65 +10,133 @@ require 'twords/word_matcher'
 class Twords
   include ConfigAccessible
 
-  attr_reader :screen_names, :words
-
+  # The screen names included in the analysis
+  #
+  # @api public
+  # @return [Array<String>] if names are provided to #initialize
+  # @return [Array] if no names are provided to #initialize
+  attr_reader :screen_names
+
+  # The words and their number of occurrences
+  #
+  # @api public
+  # @return [Hash] returns the word(String) and counts(Integer) as key-value pairs
+  attr_reader :words
+
+  # Initializes a new Twords object
+  #
+  # @api public
+  # @param screen_names [Array<String>] any number of screen names to include in the analysis
+  # @return [Twords]
   def initialize(*screen_names)
     @screen_names = screen_names.flatten
     @words        = {}
+    @audited      = false
   end
 
+  # Have the #screen_names already been audited?
+  #
+  # @api public
+  # @return [true] if already audited
+  # @return [false] if not audited yet
   def audited?
     @audited
   end
 
+  # Fetch tweets and count words. Short circuits and returns true if already audited.
+  #
+  # @api public
+  # @return [true]
   def audit
     count_words unless audited?
     @audited = true
   end
 
+  # Clear all results and audit from scratch
+  #
+  # @api public
+  # @return [true] always returns true unless an error is raised
   def audit!
     instance_variables.reject { |ivar| %i[@screen_names @words].include?(ivar) }.each do |ivar|
       instance_variable_set(ivar, nil)
     end
 
+    @audited = false
+
     audit
   end
 
+  # Sort words by frequency in descending order
+  #
+  # @api public
+  # @return [Array<Array<String, Integer>>]
   def sort_words
     @_sort_words ||= words.sort { |a, b| b.last <=> a.last }
   end
   alias words_forward sort_words
 
+  # Returns all of the tweets that fall within the configured time range
+  #
+  # @api public
+  # @return [Array<Twitter::Tweet>]
   def tweets
     @_tweets ||= client.filter_tweets(screen_names)
   end
 
+  # Returns an array of #tweets sorted by time created in descending order
+  #
+  # @api public
+  # @return [Array<Twitter::Tweet>]
   def sort_tweets
     tweets.sort { |a, b| b.created_at <=> a.created_at }
   end
 
+  # #sort_tweets destructively
+  #
+  # @api public
+  # @return [Array<Twitter::Tweet>]
   def sort_tweets!
     tweets.sort! { |a, b| b.created_at <=> a.created_at }
   end
 
+  # Number of tweets being analyzed
+  #
+  # @api public
+  # @return [Integer]
   def tweets_count
     @_tweets_count ||= tweets.count
   end
 
+  # Total occurrences of all words included in analysis, i.e. sum of the count of all words.
+  #
+  # @api public
+  # @return [Integer]
   def total_word_count
     @_total_word_count ||= words.values.reduce(:+)
   end
 
+  # The frequency of each word as a share of the #total_word_count
+  #
+  # @api public
+  # @return [Hash] returns the word(String) and percentage(Float) as key-value pairs
   def percentages
     @_percentages ||= words.each_with_object({}) do |word_count, hash|
       hash[word_count.first] = percentage(word_count.last)
     end
   end
 
+  # Sorts #percentages in descending order
+  #
+  # @api public
+  # @return [Array<Array<String, Float>>]
   def sort_percentages
     @_sort_percentages ||= percentages.sort { |a, b| b.last <=> a.last }
   end
 
+  # Generate a CSV formatted String of the sorted results, with column headers "word, count"
+  #
+  # @api public
+  # @return [String] in CSV format
   def to_csv
     CSV.generate do |csv|
       csv << %w[word count]
@@ -78,15 +146,32 @@ class Twords
     end
   end
 
+  # Write the output of #to_csv to a file.
+  #
+  # @api public
+  # @return [Integer] representing the byte count of the file
+  # @param opts [Hash] customizable file writing options. All but :filename are passed to File#open
+  # @option opts [String] :filename A relative pathname to define the destination of the new file
   def write_to_csv(opts = {})
     filename = opts.fetch(:filename) { 'twords_report.csv' }
     write_file(filename, :to_csv, opts)
   end
 
+  # Generate a JSON formatted String of the sorted results, as one hash object with word-count
+  # key-value pairs.
+  #
+  # @api public
+  # @return [String] in JSON format
   def to_json
     sort_words.to_h.to_json
   end
 
+  # Write the output of #to_json to a file.
+  #
+  # @api public
+  # @return [Integer] representing the byte count of the file
+  # @param opts [Hash] customizable file writing options. All but :filename are passed to File#open
+  # @option opts [String] :filename A relative pathname to define the destination of the new file
   def write_to_json(opts = {})
     filename = opts.fetch(:filename) { 'twords_report.json' }
     write_file(filename, :to_json, opts)
@@ -94,12 +179,12 @@ class Twords
 
   private
 
-  # private method
+  # @api private
   def client
     config.client
   end
 
-  # private method
+  # @api private
   def count_words
     words.clear
     tweets.each do |tweet|
@@ -110,17 +195,17 @@ class Twords
     end
   end
 
-  # private method
+  # @api private
   def words_array(tweet)
     tweet.attrs[:full_text].downcase.split(' ')
   end
 
-  # private method
+  # @api private
   def percentage(count)
     (count / total_word_count.to_f * 100)
   end
 
-  # private method
+  # @api private
   def write_file(filename, method, opts = {})
     File.open(filename, 'w', opts) { |file| file.write send(method) }
   end

data/lib/twords/twitter_client.rb

@@ -7,12 +7,34 @@ class Twords
   class TwitterClient
     include ConfigAccessible
 
+    # A Twitter::REST::Client that provides an interface to the Twitter API
+    #
+    # @api public
+    # @returns [Twitter::REST::Client]
     attr_reader :client
 
+    # Initializes a new Twords::TwitterClient object and assigns to the @client instance variable
+    #
+    #   Twords::TwitterClient.new do |twitter|
+    #     twitter.consumer_key        = "YOUR_CONSUMER_KEY"
+    #     twitter.consumer_secret     = "YOUR_CONSUMER_SECRET"
+    #     twitter.access_token        = "YOUR_ACCESS_TOKEN"
+    #     twitter.access_token_secret = "YOUR_ACCESS_SECRET"
+    #   end
+    #
+    # @api public
+    # for block { |twitter| ... }
+    # @yield [Twitter::REST::Client] yields the Twitter::REST::Client for configuration
+    # @see https://github.com/sferik/twitter#configuration
     def initialize(&block)
       @client = Twitter::REST::Client.new(&block)
     end
 
+    # Fetches the timelines for an array of screen names and filters them
+    # by the configured time range.
+    #
+    # @api public
+    # @param screen_names [Array<String>] the twitter screen names from which to pull the tweets
     def filter_tweets(screen_names)
       full_timeline(screen_names).each_with_object([]) do |tweet, memo|
         next if tweet.created_at > up_to_time
@@ -22,12 +44,12 @@ class Twords
 
     private
 
-    # private method
+    # @api private
     def full_timeline(screen_names)
       screen_names.map { |screen_name| fetch_user_timeline(screen_name) }.flatten.uniq
     end
 
-    # private method
+    # @api private
     def fetch_user_timeline(screen_name)
       return [] if screen_name.to_s.empty?
       user_timeline = client.user_timeline(screen_name, tweet_mode: 'extended', count: 200)
@@ -40,22 +62,22 @@ class Twords
       fetch_user_timeline(screen_name)
     end
 
-    # private method
+    # @api private
     def age_of_tweet_in_days(tweet)
       (up_to_time - tweet.created_at) / 86_400
     end
 
-    # private method
+    # @api private
     def up_to_time
       config.up_to_time
     end
 
-    # private method
+    # @api private
     def range
       config.range
     end
 
-    # private method
+    # @api private
     def fetch_older_tweets(user_timeline, screen_name)
       return user_timeline if age_of_tweet_in_days(user_timeline.last) > range
       first_count = user_timeline.count

data/lib/twords/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Twords
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.2.1'.freeze
 end

data/lib/twords/word_matcher.rb

@@ -8,26 +8,51 @@ class Twords
     class << self
       include ConfigAccessible
 
+      # Check if a word should not be counted.
+      #
+      # @api public
+      # @return [true] if word should be skipped
+      # @return [false] if word should not be skipped
       def should_be_skipped?(word)
         reject?(word) || hashtag?(word) || uri?(word) || mention?(word)
       end
 
+      # Check if a word is one of the configured rejects to ignore
+      #
+      # @api public
+      # @return [true] if word is a reject
+      # @return [false] if word is not a reject
       def reject?(word)
         config.rejects.include?(word)
       end
 
+      # Check if a word is a hashtag.
+      #
+      # @api public
+      # @return [true] if hashtags should not be included and word is a hashtag
+      # @return [false] if all hashtags should be included or word is not a hashtag
       def hashtag?(word)
-        return if config.include_hashtags
+        return false if config.include_hashtags
         !(word =~ /#(\w+)/).nil?
       end
 
+      # Check if a word is a URI. Uses URI#regexp to match URIs
+      #
+      # @api public
+      # @return [true] if URIs should not be included and word is a URI
+      # @return [false] if all URIs should be included or word is not a URI
       def uri?(word)
-        return if config.include_uris
+        return false if config.include_uris
         !(word =~ URI.regexp).nil?
       end
 
+      # Check if a word is a @-mention.
+      #
+      # @api public
+      # @return [true] if @-mentions should not be included and word is a @-mention
+      # @return [false] if all @-mentions should be included or word is not a @-mention
       def mention?(word)
-        return if config.include_mentions
+        return false if config.include_mentions
         !(word =~ /@(\w+)/).nil?
       end
     end

data/twords.gemspec

@@ -12,7 +12,13 @@ Gem::Specification.new do |spec|
   spec.email         = ['msimonborg@gmail.com']
 
   spec.summary       = 'Twitter word clouds'
-  spec.description   = 'Twitter word clouds'
+  spec.description   = 'Twitter word clouds. Analyse the frequency of word occurrences for a '\
+    'user or list of users. Configurable - set the words to ignore, the range of dates to look '\
+    'at, and whether to include hashtags, @-mentions, and URLs. Customize your Twitter '\
+    'configuration, too. Sensible defaults are provided for all options. Look at the data in '\
+    'different ways. Easily convert and/or export to CSV and JSON. Change configuration options '\
+    'on the fly and re-audit with ease.'
+
   spec.homepage      = 'https://github.com/msimonborg/twords'
   spec.license       = 'MIT'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twords
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - M. Simon Borg
@@ -52,7 +52,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: Twitter word clouds
+description: Twitter word clouds. Analyse the frequency of word occurrences for a
+  user or list of users. Configurable - set the words to ignore, the range of dates
+  to look at, and whether to include hashtags, @-mentions, and URLs. Customize your
+  Twitter configuration, too. Sensible defaults are provided for all options. Look
+  at the data in different ways. Easily convert and/or export to CSV and JSON. Change
+  configuration options on the fly and re-audit with ease.
 email:
 - msimonborg@gmail.com
 executables: []