rescuetime 0.3.3 → 0.4.0

data/lib/rescuetime/formatters.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'rescuetime/formatters/base_formatter'
+
+module Rescuetime
+  # Contains all Rescuetime formatters and formatter-loading behavior
+  # @since v0.4.0
+  module Formatters
+    # The superclass for all valid Rescuetime formatters
+    BASE_FORMATTER       = Rescuetime::Formatters::BaseFormatter
+    # The path where local in-gem formatters are stored. Expands to
+    # lib/rescuetime/formatters/*_formatter.rb
+    LOCAL_FORMATTER_PATH = '../formatters/*_formatter.rb'.freeze
+
+    # Returns a list of known formatters. A known formatter is either in the
+    # local gem folder lib/rescuetime/formatters/ and ends in '_formatter.rb',
+    # or it follows the path-matching options provided by the user using
+    # Rescuetime.configure.
+    #
+    # @param  [Class#descendents] base_formatter  the formatter superclass -
+    #                                             #load_formatters returns all
+    #                                             classes that inherit from this
+    #                                             class
+    # @return [Array<Class>]                      known report formatters
+    #
+    # @see Rescuetime::Configuration.formatter_paths
+    def load_formatters(base_formatter: BASE_FORMATTER)
+      load_formatter_files
+      base_formatter.descendents
+    end
+
+    private
+
+    # Requires all formatter files, determined by the local path for formatters
+    # plus any additional paths set in the Rescuetime configuration.
+    #
+    # @param  [String] local_path  the location of the local in-gem formatters
+    #
+    # @see Rescuetime::Configuration.formatter_paths
+    def load_formatter_files(local_path: LOCAL_FORMATTER_PATH)
+      # require all formatters, local and configured
+      paths = Rescuetime.configuration.formatter_paths << local_path
+      paths.each do |path|
+        Dir[File.expand_path(path, __FILE__)].each { |file| require file }
+      end
+    end
+  end
+end

data/lib/rescuetime/formatters/array_formatter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rescuetime::Formatters
+  # Formats a rescuetime report as an array of hashes.
+  #
+  # @since v0.4.0
+  class ArrayFormatter < BaseFormatter
+    # Returns the name of your formatter
+    #
+    # @return [String]  a name for your report formatter ("array")
+    def self.name
+      'array'
+    end
+
+    # Formats the rescuetime report from CSV to a user-defined format
+    #
+    # @param  [#to_a]       report  a csv-formatted report
+    # @return [Array<Hash>]         a report formatted as an array of hashes
+    def self.format(report)
+      report.to_a.map(&:to_hash)
+    end
+  end
+end

data/lib/rescuetime/formatters/base_formatter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rescuetime::Formatters
+  # Base class for report formatters
+  #
+  # @abstract Subclass and override {.name} and {.format} to implement a custom
+  #           formatter
+  # @see Rescuetime::Formatters::CSVFormatter
+  # @see Rescuetime::Formatters::ArrayFormatter
+  # @since v0.4.0
+  class BaseFormatter
+    # Returns the name of your formatter
+    #
+    # @return [String]  a name for your report formatter
+    #
+    # @raise  [NotImplementedError] this method is not yet implemented
+    def self.name
+      raise NotImplementedError, 'you have not defined a report name'
+    end
+
+    # Formats the rescuetime report from CSV to a user-defined format
+    #
+    # @param  [CSV] _report  a csv-formatted report
+    # @return                a report formatted to your specifications
+    #
+    # @raise  [NotImplementedError] this method is not yet implemented
+    def self.format(_report)
+      raise NotImplementedError,
+            'you have not defined report formatting instructions'
+    end
+
+    # Returns all classes descended from the current class
+    #
+    # @example
+    #   require 'rescuetime/formatters/array_formatter'
+    #   base_formatter = Rescuetime::Formatters::BaseFormatter
+    #
+    #   base_formatter.descendents
+    #   #=> [Rescuetime::Formatters::ArrayFormatter]
+    #
+    # @return [Array<Class>]  all loaded descendents of the current class
+    def self.descendents
+      ObjectSpace.each_object(Class).select { |klass| klass < self }
+    end
+  end
+end

data/lib/rescuetime/formatters/csv_formatter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rescuetime::Formatters
+  # Formats a rescuetime report as a CSV object
+  #
+  # @since v0.4.0
+  class CSVFormatter < BaseFormatter
+    # Returns the name of your formatter
+    #
+    # @return [String]  a name for your report formatter ("csv")
+    def self.name
+      'csv'
+    end
+
+    # Returns the rescuetime report in raw form
+    #
+    # @param  [CSV]  report  a csv-formatted report
+    # @return [CSV]          a csv-formatted report
+    def self.format(report)
+      report
+    end
+  end
+end

data/lib/rescuetime/query_buildable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rescuetime/date_parser'
 
 module Rescuetime
@@ -10,14 +12,14 @@ module Rescuetime
     # Parameters that are included by default in every query
     BASE_PARAMS = { format:     'csv',
                     operation:  'select',
-                    version:    0 }
+                    version:    0 }.freeze
 
     # Valid values for the :order and :interval parameters
     # @see #order_by
     VALID = {
       order_by: %w(time rank member),
       interval: %w(minute hour day week month)
-    }
+    }.freeze
 
     # Returns a Rescuetime overview report, grouping activities into their
     # top-level categories
@@ -167,10 +169,10 @@ module Rescuetime
     # @example Invalid Values Raise Errors
     #   client = Rescuetime::Client.new
     #   client.order_by 'invalid'
-    #   # => Rescuetime::InvalidQueryError: invalid is not a valid order
+    #   # => Rescuetime::Errors::InvalidQueryError: invalid is not a valid order
     #
     #   client.order_by 'time', interval: 'invalid'
-    #   # => Rescuetime::InvalidQueryError: invalid is not a valid interval
+    #   # => Rescuetime::Errors::InvalidQueryError: invalid is not a valid interval
     #
     # @param  [#to_s]        order      an order for the results (ex. 'time')
     # @param  [#intern, nil] interval   a chunking interval for results
@@ -179,7 +181,7 @@ module Rescuetime
     # @return [Rescuetime::Collection]  a Rescuetime Collection specifying order
     #                                   and interval (if set)
     #
-    # @raise [Rescuetime::InvalidQueryError] if either order or interval are
+    # @raise [Rescuetime::Errors::InvalidQueryError] if either order or interval are
     #                                        invalid
     #
     # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
@@ -193,11 +195,11 @@ module Rescuetime
 
       # guards against invalid order or interval
       unless valid_order? order
-        fail InvalidQueryError, "#{order} is not a valid order"
+        raise Errors::InvalidQueryError, "#{order} is not a valid order"
       end
 
       unless valid_interval? interval
-        fail InvalidQueryError, "#{interval} is not a valid interval"
+        raise Errors::InvalidQueryError, "#{interval} is not a valid interval"
       end
 
       add_to_query perspective: (order == 'time' ? 'interval' : order),
@@ -225,7 +227,7 @@ module Rescuetime
     # @return [Rescuetime::Collection]       a Rescuetime Collection specifying
     #                                        report date
     #
-    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    # @raise [Rescuetime::Errors::InvalidQueryError] if the date format is invalid
     #
     # @see #from
     # @see #to
@@ -256,7 +258,7 @@ module Rescuetime
     # @return [Rescuetime::Collection]       a Rescuetime Collection specifying
     #                                        report date
     #
-    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    # @raise [Rescuetime::Errors::InvalidQueryError] if the date format is invalid
     #
     # @see #to
     # @see #date
@@ -286,13 +288,13 @@ module Rescuetime
     #   #=> [ ... ]
     #
     #   client.to(1.week.ago).all                   # invalid!
-    #   #=> Rescuetime::InvalidQueryError
+    #   #=> Rescuetime::Errors::InvalidQueryError
     #
     # @param  [#strftime, String]      date  a valid date-like object
     # @return [Rescuetime::Collection]       a Rescuetime Collection specifying
     #                                        report date
     #
-    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    # @raise [Rescuetime::Errors::InvalidQueryError] if the date format is invalid
     #
     # @see #from
     # @see #date
@@ -302,7 +304,7 @@ module Rescuetime
     #                                                   (see: restrict_end)
     # @since v0.3.0
     def to(date)
-      add_to_query restrict_end:    to_formatted_s(date)
+      add_to_query restrict_end: to_formatted_s(date)
     end
 
     # Limits the Rescuetime report to specific activities and documents.
@@ -348,7 +350,7 @@ module Rescuetime
     #
     # @return [Rescuetime::Collection]  a Rescuetime Collection specifying
     #                                   category name and (optionally) document
-    # @raises [ArgumentError] if name is not set
+    # @raise [ArgumentError] if name is not set
     #
     # @see #overview
     # @see #activities
@@ -359,7 +361,7 @@ module Rescuetime
     # @since v0.3.0
     def where(name: nil, document: nil)
       # Stand-in for required keyword arguments
-      name or fail ArgumentError, 'missing keyword: name'
+      name || raise(ArgumentError, 'missing keyword: name')
 
       add_to_query restrict_thing:  name,
                    restrict_thingy: document
@@ -372,7 +374,7 @@ module Rescuetime
     # @param  [Hash] terms             a set of terms to add to the query
     # @return [Rescuetime::Collection]
     def add_to_query(**terms)
-      if self.is_a? Rescuetime::Collection
+      if is_a? Rescuetime::Collection
         self << terms
         self
       else
@@ -422,7 +424,7 @@ module Rescuetime
     #                                          Rescuetime::DateParser
     # @return [String]            a string in 'YYYY-MM-DD' format
     #
-    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    # @raise [Rescuetime::Errors::InvalidQueryError] if the date format is invalid
     #
     # @see Rescuetime::DateParser
     # @see Rescuetime::DateParser::DATE_FORMATS         Valid date formats

data/lib/rescuetime/report_formatters.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'rescuetime/formatters'
+
+module Rescuetime
+  # Represents the collection of report formatters. Autoloads all formatters
+  # based on filename and file location.
+  # @since v0.4.0
+  class ReportFormatters
+    include Rescuetime::Formatters
+
+    # Returns or loads a memoized list of formatters
+    #
+    # @example
+    #   report_formatters = Rescuetime::ReportFormatters.new.formatters
+    #   #=> [Rescuetime::Formatters::ArrayFormatter,
+    #   #    Rescuetime::Formatters::CSVFormatter]
+    #
+    # @return [Array<Class>]  list of available report formatters
+    def formatters
+      @formatters ||= load_formatters
+    end
+
+    # Force a reload of report formatters
+    #
+    # @example
+    #   report_formatters = Rescuetime::ReportFormatters.new
+    #   report_formatters.formatters
+    #   #=> [Rescuetime::Formatters::ArrayFormatter,
+    #   #    Rescuetime::Formatters::CSVFormatter]
+    #
+    #   Rescuetime.configure do |config|
+    #     config.formatter_paths << 'local/formatters/html_formatter.rb'
+    #   end
+    #
+    #   report_formatters.reload
+    #   #=> [Rescuetime::Formatters::ArrayFormatter,
+    #   #    Rescuetime::Formatters::CSVFormatter,
+    #   #    Rescuetime::Formatters::HTMLFormatter]
+    #
+    #   report_formatters.formatters
+    #   #=> [Rescuetime::Formatters::ArrayFormatter,
+    #   #    Rescuetime::Formatters::CSVFormatter,
+    #   #    Rescuetime::Formatters::HTMLFormatter]
+    #
+    # @return [Array<Class>]  list of available report formatters
+    def reload
+      @formatters = load_formatters
+    end
+
+    # Returns a list of available formatter names
+    #
+    # @example
+    #   report_formatters = Rescuetime::ReportFormatters.new
+    #   report_formatters.all
+    #   #=> ["array", "csv"]
+    #
+    # @return [Array<String>]  a list of formatter names
+    def all
+      formatters.map(&:name)
+    end
+
+    # Returns the formatter with the specified name or, if not found, raises
+    # an exception
+    #
+    # @param  [String] name  the name of the desired formatter
+    # @return [Class]        the specified formatter
+    #
+    # @raise [Rescuetime::Errors::InvalidFormatError]
+    def find(name)
+      formatter = formatters.find do |f|
+        standardize(f.name) == standardize(name)
+      end
+      formatter || raise(Rescuetime::Errors::InvalidFormatError)
+    end
+
+    private
+
+    def standardize(str)
+      str.to_s.downcase
+    end
+  end
+end

data/lib/rescuetime/requester.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require 'rescuetime/core_extensions/string'
+
 module Rescuetime
   # The Rescuetime::Requestable module contains client methods relating to
   # sending HTTP requests
@@ -10,7 +14,7 @@ module Rescuetime
       key_not_found: '"error":"# key not found","messages":"key not found"',
       query: '"error": "# query error",'\
       '"messages": "Error: Likely a badly formatted or missing parameter"'
-    }
+    }.freeze
 
     class << self
       # Performs the GET request to the specified host. Before making the
@@ -19,58 +23,75 @@ module Rescuetime
       #
       # @param  [String] host    request host
       # @param  [Hash]   params  request parameters
-      # @param  [#get]   http    HTTP requester
       # @return [String]
       #
-      # @raise [Rescuetime::MissingCredentialsError] if no api key is present
-      # @raise [Rescuetime::InvalidCredentialsError] if api key is incorrect
-      # @raise [Rescuetime::InvalidQueryError]       if query is badly formed
-      # @raise [Rescuetime::Error]                   if response HTTP status is
+      # @raise [Rescuetime::Errors::MissingCredentialsError] if no api key is present
+      # @raise [Rescuetime::Errors::InvalidCredentialsError] if api key is incorrect
+      # @raise [Rescuetime::Errors::InvalidQueryError]       if query is badly formed
+      # @raise [Rescuetime::Errors::Error]                   if response HTTP status is
       #                                              not 200
       #
+      # @see http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html#method-c-get_response
+      #      Net::HTTP.get_response
       # @see Rescuetime::Client#api_key=
-      def get(host, params, http: Net::HTTP)
-        # Fail if no api key is provided
-        unless params[:key] && !params[:key].to_s.empty?
-          fail(Rescuetime::MissingCredentialsError)
-        end
+      def get(host, params)
+        # guard clause: fail if no API key is present
+        key = CoreExtensions::String.new params[:key].to_s # adds #present?
+        key.present? || raise(Errors::MissingCredentialsError)
 
         uri = set_uri host, params
-        response = http.get_response uri
+        response = Net::HTTP.get_response uri
 
         fail_or_return_body response
       end
 
       private
 
+      # Takes a host and collection of parameters and returns the associated
+      # URI object. Required for the Net::HTTP.get_response method.
+      #
+      # @param  [String] host    target API endpoint
+      # @param  [Hash]   params  collection of query parameters
+      # @return [URI]            URI object with host and query parameters
+      #
+      # @see Requester#get
+      # @see http://ruby-doc.org/stdlib/libdoc/net/http/rdoc/Net/HTTP.html#method-c-get_response
+      #      Net::HTTP.get_response
+      # @since v0.3.3
       def set_uri(host, params)
-        req_params = params.delete_if { |_, v| !v || v.to_s.empty? }
-        uri = URI(host)
+        # delete params with empty values
+        req_params = params.delete_if do |_key, value|
+          # type conversion required because symbols/ints can't be extended
+          value = CoreExtensions::String.new value.to_s # add #blank?
+          value.blank?
+        end
+
+        uri       = URI(host)
         uri.query = URI.encode_www_form(req_params)
         uri
       end
 
       # Checks for an error in the Rescuetime response. If an error was recieved
-      # raise the appropriate Rescuetime::Error. Otherwise, return the response.
+      # raise the appropriate Rescuetime::Errors::Error. Otherwise, return the response.
       #
       # @param  [Net::HTTPResponse] response   HTTP response from rescuetime.com
       # @return [String]            valid response body
       #
-      # @raise [Rescuetime::InvalidCredentialsError] if api key is incorrect
-      # @raise [Rescuetime::InvalidQueryError]       if query is badly formed
-      # @raise [Rescuetime::Error] an error that varies based on the
+      # @raise [Rescuetime::Errors::InvalidCredentialsError] if api key is incorrect
+      # @raise [Rescuetime::Errors::InvalidQueryError]       if query is badly formed
+      # @raise [Rescuetime::Errors::Error] an error that varies based on the
       #                             response status
       def fail_or_return_body(response)
         # match the response body to known error messages with 200 status
         case response.body
-        when key_not_found? then fail Rescuetime::InvalidCredentialsError
-        when invalid_query? then fail Rescuetime::InvalidQueryError
+        when key_not_found? then raise Rescuetime::Errors::InvalidCredentialsError
+        when invalid_query? then raise Rescuetime::Errors::InvalidQueryError
         end
 
         # check the response status for errors
         status = response.code.to_i
-        error = Rescuetime::Error::CODES[status]
-        fail(error) if error
+        error = Rescuetime::Errors::Error::CODES[status]
+        raise(error) if error
 
         response.body
       end