rescuetime 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ce870b11b2ff5bc0257b76ef6e494a279dedd5b8
-  data.tar.gz: 5d2a5e4e0884b38c321cdd6a64dcb4a00da2d57c
+  metadata.gz: 91580bf8d38de0e666474a0997d3e0ec3c556c83
+  data.tar.gz: b6e82c5ceaad582f0294ad7dde9e0e50aedfd38f
 SHA512:
-  metadata.gz: ec48c9a8f5c98ffe39c1e43ff2342d617b20ffc95fb785ed25d171dd0d3f43184234064d1488aebd4f5a274a38bda29f1febb3e2e365c249d518a2baa96acf63
-  data.tar.gz: 3f24d854c6e41263ac3ad2012e55743eefd7c72d1a7960e3749c8002d59c0213bbf33cecc2a20891ad569ad50aec8fe84dabad5cae115b4ea290743b6be27540
+  metadata.gz: 8dbb49c2e711c4f66c35a501253b3e491b933acee14f2232d147f33056cffd108856a98fa6c8b0751891649d0cb7b3332ee0577667b004d1c496783da706fed8
+  data.tar.gz: ecbedb46b28cf5861b16b61b9006a61d88952328f77654e1b0b1db28fc3e15b279eab88639bfff8f38036876fb81d033af86c895807675edf555e71b596ddc32

data/.rubocop.yml

@@ -1 +1,4 @@
-inherit_from: .rubocop_todo.yml
+inherit_from: .rubocop_todo.yml
+
+Style/SignalException:
+  EnforcedStyle: only_raise

data/.rubocop_todo.yml

@@ -1,80 +1,58 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2016-05-22 00:42:00 -0400 using RuboCop version 0.40.0.
+# on 2016-05-26 15:32:03 -0400 using RuboCop version 0.40.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-Lint/AmbiguousOperator:
-  Exclude:
-    - 'lib/rescuetime/collection.rb'
+# Offense count: 23
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes.
+# URISchemes: http, https
+Metrics/LineLength:
+  Max: 91
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
   Max: 13
 
-# Offense count: 1
+# Offense count: 8
 # Cop supports --auto-correct.
-Performance/StringReplacement:
+# Configuration parameters: EnforcedStyle, SupportedStyles, ProceduralMethods, FunctionalMethods, IgnoredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# IgnoredMethods: lambda, proc, it
+Style/BlockDelimiters:
   Exclude:
-    - 'lib/rescuetime/date_parser.rb'
+    - 'spec/rescuetime/core_extensions/object/blank_spec.rb'
+    - 'spec/rescuetime/date_parser_spec.rb'
+    - 'spec/rescuetime/formatters/array_formatter_spec.rb'
+    - 'spec/rescuetime/formatters/csv_formatter_spec.rb'
+    - 'spec/rescuetime/report_formatters_spec.rb'
+    - 'spec/rescuetime/requester_spec.rb'
 
-# Offense count: 1
-# Cop supports --auto-correct.
+# Offense count: 7
 # Configuration parameters: EnforcedStyle, SupportedStyles.
-# SupportedStyles: always, conditionals
-Style/AndOr:
+# SupportedStyles: nested, compact
+Style/ClassAndModuleChildren:
   Exclude:
-    - 'lib/rescuetime/query_buildable.rb'
+    - 'lib/rescuetime/core_extensions/object.rb'
+    - 'lib/rescuetime/core_extensions/object/blank.rb'
+    - 'lib/rescuetime/core_extensions/string.rb'
+    - 'lib/rescuetime/formatters/array_formatter.rb'
+    - 'lib/rescuetime/formatters/base_formatter.rb'
+    - 'lib/rescuetime/formatters/csv_formatter.rb'
+    - 'spec/fixtures/formatters/fake_formatter.rb'
 
-# Offense count: 5
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles, IndentationWidth.
-# SupportedStyles: aligned, indented
-Style/MultilineMethodCallIndentation:
-  Enabled: false
-
-# Offense count: 9
-# Cop supports --auto-correct.
-Style/MutableConstant:
-  Exclude:
-    - 'lib/rescuetime/collection.rb'
-    - 'lib/rescuetime/date_parser.rb'
-    - 'lib/rescuetime/errors.rb'
-    - 'lib/rescuetime/query_buildable.rb'
-    - 'lib/rescuetime/requester.rb'
-    - 'lib/rescuetime/version.rb'
-    - 'spec/sample_secret.rb'
-    - 'spec/secret.rb'
-
-# Offense count: 3
-# Cop supports --auto-correct.
-Style/NestedParenthesizedCalls:
+# Offense count: 1
+Style/DoubleNegation:
   Exclude:
-    - 'spec/rescuetime/query_buildable_spec.rb'
+    - 'lib/rescuetime/core_extensions/object/blank.rb'
 
 # Offense count: 1
 # Cop supports --auto-correct.
 Style/ParallelAssignment:
   Exclude:
     - 'spec/rescuetime/query_buildable_spec.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-Style/RedundantSelf:
-  Exclude:
-    - 'lib/rescuetime/query_buildable.rb'
-
-# Offense count: 10
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-# SupportedStyles: only_raise, only_fail, semantic
-Style/SignalException:
-  Exclude:
-    - 'lib/rescuetime/collection.rb'
-    - 'lib/rescuetime/date_parser.rb'
-    - 'lib/rescuetime/query_buildable.rb'
-    - 'lib/rescuetime/requester.rb'

data/Gemfile

@@ -1,10 +1,8 @@
 source 'https://rubygems.org'
 
-gem 'rubocop', require: false
-
 group :test do
   gem 'codeclimate-test-reporter', '~> 0.4.7'
-  gem 'simplecov', '~> 0.9.2'
+  gem 'simplecov', '~> 0.11.2'
 end
 
 # Specify your gem's dependencies in rescuetime.gemspec

data/README.md

@@ -21,6 +21,7 @@ For more information about RescueTime, visit [the RescueTime homepage](https://w
 * [Usage](#usage)
    * [Prerequisites](#prerequisites)
    * [In a Nutshell](#in-a-nutshell) (skip to here if you want to see the syntax)
+   * [Custom Report Formatters](#custom-report-formatters)
    * [Finding Answers (Documentation)](#finding-answers-documentation)
    * [Defaults](#defaults)
    * [Rescuetime Exceptions](#rescuetime-exceptions)
@@ -51,7 +52,7 @@ Or install it yourself as:
 
 ### Prerequisites
 
-Ensure that you are using a [supported ruby version](https://github.com/leesharma/rescuetime/wiki/Supported-Rubies) for your project. 
+Ensure that you are using a [supported ruby version](https://github.com/leesharma/rescuetime/wiki/Supported-Rubies) for your project.
 
 In order to use access your RescueTime data, you will need an API key. If you do not already have a key, visit the [API key management page](https://www.rescuetime.com/anapi/manage).
 
@@ -66,7 +67,7 @@ require 'rescuetime'
 
 # Rescuetime uses lazy evaluation, so until you either manipulate the collection
 # or explicitly call for it (with #all), it will remain in the Rescuetime::Collection
-# format. 
+# format.
 @client.overview.class      #=> Rescuetime::Collection
 @client.overview.all.class  #=> Array
 @client.overview.map {...}  #=> Array
@@ -89,9 +90,9 @@ require 'rescuetime'
 #   - Object#strftime
 @client.overview                      # Fetches results from today
 @client.overview.date('2014-12-31')   # Fetches results from Dec 31, 2014.
-@client.overview.from('2015-01-01').to('2015-02-01')         
-@client.overview.from('2015-04-01')            
-       
+@client.overview.from('2015-01-01').to('2015-02-01')
+@client.overview.from('2015-04-01')
+
 
 ##
 # Report Order (:order_by)
@@ -99,7 +100,7 @@ require 'rescuetime'
 # Defaults:
 #   Efficiency defaults to chronological order; everything else defaults to "rank" order
 #
-# You can order_by: 
+# You can order_by:
 #   :rank, :time, or :member (note: efficiency can't be sorted by :rank)
 #
 # When ordering by time, default interval is 1 hour.
@@ -107,15 +108,15 @@ require 'rescuetime'
 #   :minute (5-minute chunks), :hour, :day, :week, :month
 @client.efficiency    # Defaults to :time
 @client.productivity  # Defaults to :rank
-                                          
-@client.productivity.order_by(:rank)       
-@client.productivity.order_by(:time)      
-@client.productivity.order_by(:member)    
-                                          
+
+@client.productivity.order_by(:rank)
+@client.productivity.order_by(:time)
+@client.productivity.order_by(:member)
+
 @client.productivity.order_by(:time)  # Defaults to :hour
-@client.productivity.order_by(:time, interval: :minute)     
-@client.productivity.order_by(:time, interval: :hour)       
-@client.productivity.order_by(:time, interval: :day)        
+@client.productivity.order_by(:time, interval: :minute)
+@client.productivity.order_by(:time, interval: :hour)
+@client.productivity.order_by(:time, interval: :day)
 @client.productivity.order_by(:time, interval: :week)
 @client.productivity.order_by(:time, interval: :month)
 
@@ -131,10 +132,10 @@ require 'rescuetime'
 #   Try the query sans document for a list of valid options
 #
 # Names must be exact matches.
-@client.activities.where(name: 'github.com')    
-@client.categories.where(name: 'Intelligence')  
-@client.overview.where(name: 'Utilities')       
-@client.activities.where(name: 'github.com', document: 'vcr/vcr')                   
+@client.activities.where(name: 'github.com')
+@client.categories.where(name: 'Intelligence')
+@client.overview.where(name: 'Utilities')
+@client.activities.where(name: 'github.com', document: 'vcr/vcr')
 
 ##
 # Formatting options (:csv, :array)
@@ -144,9 +145,98 @@ require 'rescuetime'
 @client.efficiency.format(:array)   # Returns Array<Hash>
 ```
 
+### Custom Report Formatters
+
+*Feature available in v0.4.0 and later*
+
+Rescuetime ships with two report formats: CSV and Array. If you would like your
+report in a different format, don't worry–it's easy to add a custom formatter.
+
+Four things are required to add a custom formatter:
+
+1. [Write a class](#writing-a-formatter) within the module
+   `Rescuetime::Formatters` that inherits from `Rescuetime::Formatters::BaseFormatter`
+   or one of its descendants
+2. Define the class methods `.name` and `.format`
+4. [Register your formatters](#registering-your-formatters) using `Rescuetime.configure`
+
+#### Writing a Formatter
+
+First, the formatters themselves. Here is a basic formatter:
+
+```ruby
+# config/formatters/nil_formatter.rb
+module Rescuetime::Formatters
+  # Turns a productivity report into nothing useful.
+  class NilFormatter < BaseFormatter
+    # @return [String]  name of this report format
+    def self.name
+      'nil'
+    end
+
+    # @param  [CSV] _report  the raw CSV report from Rescuetime
+    # @return [nil]          the formatted output (in this case, nil)
+    def self.format(_report)
+      nil
+    end
+  end
+end
+```
+
+You can even inherit from an existing formatter:
+
+```ruby
+# config/formatters/shouty_array_formatter.rb
+module Rescuetime::Formatters
+  # Formats a rescuetime report as an array of hashes, except shouting.
+  class ShoutyArrayFormatter < ArrayFormatter
+    # @return [String]  name of this report format
+    def self.name
+      'shouty_array'
+    end
+
+    # @param  [CSV]         report  the raw CSV report from Rescuetime
+    # @return [Array<Hash>]         the formatted output (in this case, a shouty
+    #                               array of hashes)
+    def self.format(report)
+      array = super(report)
+      array.map do |hash|
+        terms = hash.map { |key, value| [key.to_s.upcase, value.to_s.upcase] }
+        Hash[terms]
+      end
+    end
+  end
+end
+```
+
+#### Registering your Formatters
+
+Before setting your report format, add the path to your formatter(s) to the
+Rescuetime configuration using the `Rescuetime.configure` method. You will be
+able to set, append to, or manipulate the `formatter_paths` setting.
+
+```ruby
+Rescuetime.configure do |config|
+  path = File.expand_path('../my_custom_formatter.rb', __FILE__)
+  config.formatter_paths = [path]
+end
+```
+
+Now Rescuetime will look for the `my_custom_formatter.rb` file. Multiple paths
+may be added as well.
+
+```ruby
+Rescuetime.configure do |config|
+  config.formatter_paths = [
+    'config/formatters/*_formatter.rb',
+    'lib/formatters/**/*_formatter.rb',
+  ]
+end
+```
+
 ### Finding Answers (Documentation)
 
-For more details, please see [official gem documentation](http://www.rubydoc.info/gems/rescuetime) or [read the wiki](https://github.com/leesharma/rescuetime/wiki). 
+For more details, please see [official gem documentation](http://www.rubydoc.info/gems/rescuetime) or [read the wiki](https://github.com/leesharma/rescuetime/wiki).
 
 ### Defaults
 
@@ -162,27 +252,32 @@ The `Rescuetime::Client#activities` action has the following defaults:
 
 ### Rescuetime Exceptions
 
-There are a number of exceptions that extend from the custom Rescuetime::Error class:
+*Note: In v0.4.0, custom exceptions were moved from the base `Rescuetime`
+namespace to the `Rescuetime::Errors` namespace. For example, in v0.3.3,
+a bad request was represented by `Rescuetime::BadRequest`. In >= v0.4.0,
+it is represented by `Rescuetime::Errors::BadRequest`.*
+
+There are a number of exceptions that extend from the `Rescuetime::Errors::Error` class:
 
-* **Rescuetime::MissingCredentialsError** is raised when a request is attempted by a client with no credentials. Try setting credentials with `@client.api_key = <YOUR_API_KEY>`.
-* **Rescuetime::InvalidCredentialsError** is raised when a request is attempted by a client with invalid credentials. Double-check your API key and fix your client with `@client.api_key = <VALID_API_KEY>`.
-* **Rescuetime::InvalidQueryError** is raised if you enter an invalid value for any of the RescueTime query methods (or if the server returns a bad query error)
-* **Rescuetime::InvalidFormatError** is raised if you pass a disallowed format to the client
+* **`Rescuetime::Errors::MissingCredentialsError`** is raised when a request is attempted by a client with no credentials. Try setting credentials with `@client.api_key = <YOUR_API_KEY>`.
+* **`Rescuetime::Errors::InvalidCredentialsError`** is raised when a request is attempted by a client with invalid credentials. Double-check your API key and fix your client with `@client.api_key = <VALID_API_KEY>`.
+* **`Rescuetime::Errors::InvalidQueryError`** is raised if you enter an invalid value for any of the RescueTime query methods (or if the server returns a bad query error)
+* **`Rescuetime::Errors::InvalidFormatError`** is raised if you pass a disallowed format to the client
 * HTTP Response Errors:
-  * **4xx => Rescuetime:: ClientError**
-  * 400 => Rescuetime::BadRequest
-  * 401 => Rescuetime::Unauthorized
-  * 403 => Rescuetime::Forbidden
-  * 404 => Rescuetime::NotFound
-  * 406 => Rescuetime::NotAcceptable
-  * 422 => Rescuetime::UnprocessableEntity
-  * 429 => Rescuetime::TooManyRequests
-  * **5xx => Rescuetime:: ServerError**
-  * 500 => Rescuetime::InternalServerError
-  * 501 => Rescuetime::NotImplemented
-  * 502 => Rescuetime::BadGateway
-  * 503 => Rescuetime::ServiceUnavailable
-  * 504 => Rescuetime::GatewayTimeout
+    * **4xx => `Rescuetime::Errors::ClientError`**
+    * 400 => `Rescuetime::Errors::BadRequest`
+    * 401 => `Rescuetime::Errors::Unauthorized`
+    * 403 => `Rescuetime::Errors::Forbidden`
+    * 404 => `Rescuetime::Errors::NotFound`
+    * 406 => `Rescuetime::Errors::NotAcceptable`
+    * 422 => `Rescuetime::Errors::UnprocessableEntity`
+    * 429 => `Rescuetime::Errors::TooManyRequests`
+    * **5xx => `Rescuetime::Errors::ServerError`**
+    * 500 => `Rescuetime::Errors::InternalServerError`
+    * 501 => `Rescuetime::Errors::NotImplemented`
+    * 502 => `Rescuetime::Errors::BadGateway`
+    * 503 => `Rescuetime::Errors::ServiceUnavailable`
+    * 504 => `Rescuetime::Errors::GatewayTimeout`
 
 ## Development
 

data/Rakefile

@@ -11,7 +11,7 @@ defaults = [:spec]
 begin
   require 'rubocop/rake_task'
   RuboCop::RakeTask.new(:rubocop)
-  # defaults << :rubocop
+  defaults << :rubocop
 rescue LoadError
   puts 'Rubocop is not installed; please install it for code quality checks.'
 end

data/lib/rescuetime.rb

@@ -1,10 +1,75 @@
+# frozen_string_literal: true
+
 require 'rescuetime/version'
+require 'rescuetime/configuration'
 require 'rescuetime/client'
 require 'rescuetime/errors'
 
-# lib/rescuetime.rb
+# Wrapper module for rescuetime gem
+#
+# @since v0.1.0
 module Rescuetime
-  # Wrapper module for rescuetime gem
+  # class << self
+  #   attr_writer :configuration
+  # end
+
+  # Passes a block to the Rescuetime configuration, allowing configuration
+  # options to be set.
+  #
+  # @example
+  #   # In an initializer or before any report formatters are called:
+  #   Rescuetime.configure do |config|
+  #     config.formatter_paths += ['path/to/local/formatters/*_formatter.rb']
+  #   end
+  #
+  #   # Let's say that directory contains the valid formatters pdf_formatter.rb
+  #   # and json_formatter.rb
+  #   report_formatters = Rescuetime::ReportFormatters.new
+  #   puts report_formatters.all
+  #   #=> ["array", "csv", "pdf", "json"]
+  #
+  # @see Rescuetime.configuration
+  # @see Rescuetime::Configuration
+  # @since v0.4.0
+  def self.configure
+    yield(configuration)
+  end
+
+  # Returns either the current configuration (if set) or initializes a new
+  # default configuration.
+  #
+  # @example
+  #   Rescuetime.configuration.formatter_paths
+  #   #=> []
+  #
+  #   Rescuetime.configure do |config|
+  #     config.formatter_paths += ['formatters/*.rb']
+  #   end
+  #   Rescuetime.configuration.formatter_paths
+  #   #=> ["formatters/*.rb"]
+  #
+  # @see Rescuetime::Configuration
+  # @return [Rescuetime::Configuration]  the current Rescuetime configuration
+  # @since v0.4.0
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Resets the configuration back to the initial state. Mainly useful for
+  # resetting the class after testing, making specs order-independent.
+  #
+  # @example
+  #   before :each do
+  #     Rescuetime.configure { |c| c.formatter_paths += ['formatters/*.rb'] }
+  #   end
+  #
+  #   after :each do
+  #     Rescuetime.reset
+  #   end
   #
-  # @since v0.1.0
+  # @see Rescuetime::Configuration#initialize
+  # @since v0.4.0
+  def self.reset
+    @configuration = Configuration.new
+  end
 end