twords 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bd0f26ec512e5184542436f0313c827888abed77
-  data.tar.gz: fc38f75b82aefeac2b695398f22659ebe251743c
+  metadata.gz: 201fe822e2fdd8c1ec5168fd73deb7cfb8dd29db
+  data.tar.gz: e3b057e402b2b3f1c5f47235de4f687836322c55
 SHA512:
-  metadata.gz: 79960eed5ede9ea409a0b60cda01e383fba21d960a6c9112a67e6495d840b78cc26bc5593ee1fdce56ee9d34544b73484ab3de27e78f7f9ad9106b199e9a9f5e
-  data.tar.gz: 2f1f574ffb732f92a0fa2d7e5b1c1dc4665b2e4bc799e7ff31b16b8598fdee5549b36f2eb0c392a5cd49f84198a5dc911ad559819163559c5b000c2cb59d36f0
+  metadata.gz: 0b55531d7030c0fce27b3cd0e54c82f739c7cc3ff5b90596d087a7a8cf73d2ec3b5434c21daed60423b3fb3fcf55f724f6a3bf0dd65f8460348eab92f0a0f8d9
+  data.tar.gz: 85ebd69ab5677bf649cb618ae491f9bba4b3868c2030dd6254891bde8939f5509a3ac0e9d6ea2e3530a1cc0834e833d4a4e448d17dd6788cec442b30fd1bc506

data/README.md

@@ -22,6 +22,12 @@ Or install it yourself as:
 
     $ gem install twords
 
+## Documentation
+
+[http://rdoc.info/gems/twords][documentation]
+
+[documentation]: http://rdoc.info/gems/twords
+
 ## Usage
 
 Twords takes a configuration block, and if it doesn't find one it will set the following defaults:

data/lib/twords/configuration.rb

@@ -4,8 +4,36 @@ require 'twitter'
 require 'twords/twitter_client'
 
 class Twords
-  # Configuration object
+  # Configuration object for the Twords namespace. One instance to rule them all.
+  # All options can be changed with public setter methods. One Twords::Configuration instance
+  # is shared across all objects in the Twords namespace. Changing the configuration will affect
+  # all objects, even those that are already instantiated. To set app configuration, do not
+  # initialize a Twords::Configuration object directly - nothing will happen.
+  # Do it through Twords.config(&block).
+  #
+  # @see Twords.config
+  # @example
+  #   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        = ENV['TWITTER_CONSUMER_KEY']
+  #       twitter.consumer_secret     = ENV['TWITTER_CONSUMER_SECRET']
+  #       twitter.access_token        = ENV['TWITTER_ACCESS_TOKEN']
+  #       twitter.access_token_secret = ENV['TWITTER_ACCESS_TOKEN_SECRET']
+  #     end
+  #   end
   class Configuration
+    # Default words to ignore. Strings must match exactly and are checked with
+    # Array#include?
     DEFAULT_REJECTS = %w[
       my us we an w/ because
       b/c or are this is from
@@ -14,6 +42,10 @@ class Twords
       that it by as if was
     ].freeze
 
+    # Default configuration block to pass to Twords::TwitterClient.new.
+    # Feel free to customize the variables in a configuration block of your own,
+    # but never hard code the values. Or just make the values available at the default
+    # locations.
     DEFAULT_TWITTER_CONFIG = lambda do |twitter|
       twitter.consumer_key        = ENV['TWITTER_CONSUMER_KEY']
       twitter.consumer_secret     = ENV['TWITTER_CONSUMER_SECRET']
@@ -21,6 +53,8 @@ class Twords
       twitter.access_token_secret = ENV['TWITTER_ACCESS_TOKEN_SECRET']
     end
 
+    # Full set of default options that will be passed to the Configuration object
+    # on initialization and reset.
     DEFAULT_OPTIONS = {
       include_uris:     false,
       include_hashtags: false,
@@ -36,42 +70,77 @@ class Twords
 
     attr_accessor :range
 
+    # Initializes a new Twords::Configuration object with default configuration.
+    #
+    # @api public
+    # @return [Twords::Configuration]
     def initialize
       set_defaults
     end
 
+    # Resets all configuration options to "factory" default settings.
+    #
+    # @api public
+    # @return [Twords::Configuration]
+    # @see Twords.reset_config!
     def reset!
       tap { set_defaults }
     end
 
+    # Configure a new Twords::TwitterClient with a configuration block.
+    # If no block is given the existing client is returned unchanged.
+    #
+    # @api public
+    # @return [Twords::TwitterClient]
     def twitter_client(&block)
-      @client = TwitterClient.new(&block)
+      @client = TwitterClient.new(&block) if block_given?
+      @client
     end
 
+    # Set the words to be skipped during analysis.
+    #
+    # @param args [Array<String>] an indefinite list of words to ignore
     def rejects=(*args)
-      @rejects = args.flatten
+      @rejects = args.flatten.map(&:to_s)
     end
 
+    # Set whether hashtags should be counted. If true, any word beginning with "#" will be ignored.
+    #
+    # @param boolean [true, false] will raise an error if the value is not a Boolean value
     def include_hashtags=(boolean)
       not_a_boolean_error(boolean)
       @include_hashtags = boolean
     end
 
+    # Set whether URIs should be counted. If true, uses URI#regexp to match.
+    #
+    # @param boolean [true, false] will raise an error if the value is not a Boolean value
     def include_uris=(boolean)
       not_a_boolean_error(boolean)
       @include_uris = boolean
     end
     alias include_urls= include_uris=
 
+    # Set whether @-mentions should be counted. If true, any word beginning with "@" will be ignored.
+    #
+    # @param boolean [true, false] will raise an error if the value is not a Boolean value
     def include_mentions=(boolean)
       not_a_boolean_error(boolean)
       @include_mentions = boolean
     end
 
+    # Takes a block and stores for lazy evaluation to define the end of the time range being checked.
+    # The return value of the block must respond to #to_time and return a Time object when called.
+    #
+    # @return [Proc]
     def up_to(&time_block)
       @up_to_block = time_block
     end
 
+    # Calls the Proc value of #up_to_block and calls #to_time on the return value. Expects a Time object
+    # to be returned.
+    #
+    # @return [Time]
     def up_to_time
       up_to_block.call.to_time
     end

data/lib/twords/instance_methods.rb

@@ -150,8 +150,8 @@ class Twords
   #
   # @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
+  # @param opts [Hash] File writing options. All except for :filename are passed to File#open.
+  # @option opts [String] :filename A relative pathname. Defaults to 'twords_report.csv'
   def write_to_csv(opts = {})
     filename = opts.fetch(:filename) { 'twords_report.csv' }
     write_file(filename, :to_csv, opts)
@@ -170,8 +170,8 @@ class Twords
   #
   # @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
+  # @param opts [Hash] customizable file writing options. All but :filename arepassed to File#open
+  # @option opts [String] :filename A relative pathname. Defaults to 'twords_report.json'
   def write_to_json(opts = {})
     filename = opts.fetch(:filename) { 'twords_report.json' }
     write_file(filename, :to_json, opts)

data/lib/twords/twitter_client.rb

@@ -7,10 +7,10 @@ class Twords
   class TwitterClient
     include ConfigAccessible
 
-    # A Twitter::REST::Client that provides an interface to the Twitter API
+    # A Twitter::REST::Client that provides a direct interface to the Twitter API
     #
     # @api public
-    # @returns [Twitter::REST::Client]
+    # @return [Twitter::REST::Client]
     attr_reader :client
 
     # Initializes a new Twords::TwitterClient object and assigns to the @client instance variable
@@ -25,6 +25,7 @@ class Twords
     # @api public
     # for block { |twitter| ... }
     # @yield [Twitter::REST::Client] yields the Twitter::REST::Client for configuration
+    # @see Twords::Configuration#twitter_client
     # @see https://github.com/sferik/twitter#configuration
     def initialize(&block)
       @client = Twitter::REST::Client.new(&block)
@@ -35,6 +36,7 @@ class Twords
     #
     # @api public
     # @param screen_names [Array<String>] the twitter screen names from which to pull the tweets
+    # @return [Array<Twitter::Tweet>]
     def filter_tweets(screen_names)
       full_timeline(screen_names).each_with_object([]) do |tweet, memo|
         next if tweet.created_at > up_to_time

data/lib/twords/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 class Twords
-  VERSION = '0.2.1'.freeze
+  # The current gem version
+  VERSION = '0.2.2'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twords
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - M. Simon Borg