Add Custom Formatters and Misc Updates

Breaking Changes

Exception classes, which were previously in the top-level Rescuetime (ex. Rescuetime::InvalidQueryError) are now under the Rescuetime::Errors module. This change was made for better code organization.

Updates

Allow Frozen String Literals

If you're using ruby 2.3, rescuetime will now work with the # frozen_string_literals: true option set.

Custom Formatters

The big change in this update is that users can now add/configure custom formatters.

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 within the module
   Rescuetime::Formatters that inherits from Rescuetime::Formatters::BaseFormatter
   or one of its descendants
2. Define the class methods .name and .format
3. Register your formatters using Rescuetime.configure

Writing a Formatter

First, the formatters themselves. Here is a basic formatter:

# 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:

# 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.

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.

Rescuetime.configure do |config|
  config.formatter_paths = [
    'config/formatters/*_formatter.rb',
    'lib/formatters/**/*_formatter.rb',
  ]
end

Documentation

Increased documentation coverage/quality

Test Coverage

Test coverage was increased