Module: Rescuetime::QueryBuildable

Included in:
Client, Collection
Defined in:
lib/rescuetime/query_buildable.rb

Overview

The Rescuetime::Reportable module contains client methods relating to generating requests to fetch reports on the /data endpoint of the Data Analytics API.

Since:

  • v0.1.0

Constant Summary collapse

BASE_PARAMS =

Parameters that are included by default in every query

Since:

  • v0.1.0

{ format:     'csv',
operation:  'select',
version:    0 }.freeze
VALID =

Valid values for the :order and :interval parameters

See Also:

Since:

  • v0.1.0

{
  order_by: %w(time rank member),
  interval: %w(minute hour day week month)
}.freeze

Instance Method Summary collapse

Instance Method Details

#activities ⇒ Rescuetime::Collection

Returns a Rescuetime activity report, grouping activities by their specific application, website, or activity

Defaults:

  • order: rank

  • date range: current day

Examples:

Basic Use

client = Rescuetime::Client.new
client.activities
#=> #<Rescuetime::Collection:0x007f93841681a8>

Returns:

See Also:

Since:

  • v0.1.0



95
96
97
 
# File 'lib/rescuetime/query_buildable.rb', line 95

def activities
  add_to_query restrict_kind: 'activity'
end

#categories ⇒ Rescuetime::Collection

Returns a Rescuetime category report, grouping activities into their second-level (sub-)categories

Defaults:

  • order: rank

  • date range: current day

Examples:

Basic Use

client = Rescuetime::Client.new
client.categories
#=> #<Rescuetime::Collection:0x007f93841681a8>

Returns:

See Also:

Since:

  • v0.1.0



70
71
72
 
# File 'lib/rescuetime/query_buildable.rb', line 70

def categories
  add_to_query restrict_kind: 'category'
end

#date(date) ⇒ Rescuetime::Collection

Limits the Rescuetime report to a specific single date. To specify a date range, use #from and #to.

Examples:

Basic Use

client = Rescuetime::Client.new
client.date Date.parse('1776-07-04')
#=> #<Rescuetime::Collection:0x007f93841681a8>

Valid Date Formats

client.date Time.parse('1776-07-04') # responds to #strftime
client.date '1776-07-04'
client.date '1776/07/04'
client.date '07-04-1776'
client.date '07/04/1776'
client.date '07-04' # defaults to current year
client.date '07/04' # defaults to current year

Parameters:

  • date (#strftime, String) —

    a valid date-like object

Returns:

Raises:

See Also:

Since:

  • v0.3.0



240
241
242
243
 
# File 'lib/rescuetime/query_buildable.rb', line 240

def date(date)
  add_to_query restrict_end:    to_formatted_s(date),
               restrict_begin:  to_formatted_s(date)
end

#efficiency ⇒ Rescuetime::Collection

Returns a Rescuetime efficiency report, featuring efficiency calculations. Defaults to chronological (time) order.

Defaults:

  • order: time

  • date range: current day

Examples:

Basic Use

client = Rescuetime::Client.new
client.efficiency
#=> #<Rescuetime::Collection:0x007f93841681a8>

Returns:

See Also:

Since:

  • v0.1.0



145
146
147
148
 
# File 'lib/rescuetime/query_buildable.rb', line 145

def efficiency
  add_to_query restrict_kind: 'efficiency',
               perspective:   'interval'
end

#from(date) ⇒ Rescuetime::Collection

Limits the Rescuetime report to a specific start date. If the end date is not specified, it defaults to today.

Examples:

Basic Use

client = Rescuetime::Client.new
client.from 3.days.ago
#=> #<Rescuetime::Collection:0x007f93841681a8>

With a specified end date

client.from(2.weeks.ago).to(1.week.ago)
client.from(2.weeks.ago) # defaults to ending today

Parameters:

  • date (#strftime, String) —

    a valid date-like object

Returns:

Raises:

See Also:

Since:

  • v0.3.0



270
271
272
 
# File 'lib/rescuetime/query_buildable.rb', line 270

def from(date)
  add_to_query restrict_begin:  to_formatted_s(date)
end

#order_by(order, interval: nil) ⇒ Rescuetime::Collection

Specifies the ordering and the interval of the returned Rescuetime report. For example, the results can be ordered by time, activity rank, or member; The results can be returned in intervals spanning a month, a week, a day, an hour, or 5-minutes.

Efficiency reports default to :time order; everything else defaults to :rank order.

Examples:

Basic Use

client = Rescuetime::Client.new
client.order_by 'time' # interval is not required
#=> #<Rescuetime::Collection:0x007f93841681a8>

client.order_by 'rank', interval: 'hour'
#=> #<Rescuetime::Collection:0x007f93841681a8>

client.order_by :rank, interval: :hour # Symbols are also valid
#=> #<Rescuetime::Collection:0x007f93841681a8>

Invalid Values Raise Errors

client = Rescuetime::Client.new
client.order_by 'invalid'
# => Rescuetime::Errors::InvalidQueryError: invalid is not a valid order

client.order_by 'time', interval: 'invalid'
# => Rescuetime::Errors::InvalidQueryError: invalid is not a valid interval

Parameters:

  • order (#to_s) —

    an order for the results (ex. ‘time’)

  • interval (#intern, nil) (defaults to: nil) —

    a chunking interval for results (ex. ‘month’). defaults to nil

Returns:

Raises:

See Also:

Since:

  • v0.1.0



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/rescuetime/query_buildable.rb', line 191

def order_by(order, interval: nil)
  # set order and intervals as symbols
  order    = order.to_s
  interval = interval ? interval.to_s : nil

  # guards against invalid order or interval
  unless valid_order? order
    raise Errors::InvalidQueryError, "#{order} is not a valid order"
  end

  unless valid_interval? interval
    raise Errors::InvalidQueryError, "#{interval} is not a valid interval"
  end

  add_to_query perspective: (order == 'time' ? 'interval' : order),
               resolution_time: interval
end

#overview ⇒ Rescuetime::Collection

Returns a Rescuetime overview report, grouping activities into their top-level categories

Defaults:

  • order: rank

  • date range: current day

Examples:

Basic Use

client = Rescuetime::Client.new
client.overview
#=> #<Rescuetime::Collection:0x007f93841681a8>

Returns:

See Also:

Since:

  • v0.1.0



45
46
47
 
# File 'lib/rescuetime/query_buildable.rb', line 45

def overview
  add_to_query restrict_kind: 'overview'
end

#productivity ⇒ Rescuetime::Collection

Returns a Rescuetime productivity report, featuring productivity calculations

Defaults:

  • order: rank

  • date range: current day

Examples:

Basic Use

client = Rescuetime::Client.new
client.productivity
#=> #<Rescuetime::Collection:0x007f93841681a8>

Returns:

See Also:

Since:

  • v0.1.0



120
121
122
 
# File 'lib/rescuetime/query_buildable.rb', line 120

def productivity
  add_to_query restrict_kind: 'productivity'
end

#to(date) ⇒ Rescuetime::Collection

Limits the Rescuetime report to a specific end date. Requires #from to be set before the query is sent, but it doesn’t matter if that happens before or after the call to #to.

Examples:

Basic Use

client = Rescuetime::Client.new
client.from(3.days.ago).to(1.day.ago)
#=> #<Rescuetime::Collection:0x007f93841681a8>

Requires a specified start date

client.from(2.weeks.ago).to(1.week.ago).all # valid
#=> [ ... ]

client.to(1.week.ago).from(2.weeks.ago).all # valid
#=> [ ... ]

client.to(1.week.ago).all                   # invalid!
#=> Rescuetime::Errors::InvalidQueryError

Parameters:

  • date (#strftime, String) —

    a valid date-like object

Returns:

Raises:

See Also:

Since:

  • v0.3.0



306
307
308
 
# File 'lib/rescuetime/query_buildable.rb', line 306

def to(date)
  add_to_query restrict_end: to_formatted_s(date)
end

#where(name: nil, document: nil) ⇒ Rescuetime::Collection

Limits the Rescuetime report to specific activities and documents. The name option limits the results to those where name is an exact match; this can be used on the overview, activity, and category report. The document option limits the specific document title; this is only available on the activity report.

If a value is passed for an unsupported report, it will be ignored.

To see the category and document names for your account, please look at your rescuetime dashboard or generated rescuetime report.

:name can be used on:

  • Overview report

  • Category report

  • Activity report

:document can be used on:

  • Activity report when :name is set

Examples:

Basic Use

client = Rescuetime::Client.new
client.activities.where name: 'github.com',
                        document: 'leesharma/rescuetime'
#=> #<Rescuetime::Collection:0x007f93841681a8>

Valid reports

client.overview.where name: 'Utilities'
client.categories.where name: 'Intelligence'
client.activities.where name: 'github.com'
client.activities.where name: 'github.com', document: 'rails/rails'

Invalid reports

client.productivity.where name: 'Intelligence'  # Invalid!
client.efficiency.where name: 'Intelligence'    # Invalid!
client.activities.where document: 'rails/rails' # Invalid!

Parameters:

  • name (String) (defaults to: nil) —

    Rescuetime category name, valid on overview, category, and activity reports

  • document (String) (defaults to: nil) —

    Specific document name, valid on activity reports when :name is set

Returns:

Raises:

  • (ArgumentError) —

    if name is not set

See Also:

Since:

  • v0.3.0



362
363
364
365
366
367
368
 
# File 'lib/rescuetime/query_buildable.rb', line 362

def where(name: nil, document: nil)
  # Stand-in for required keyword arguments
  name || raise(ArgumentError, 'missing keyword: name')

  add_to_query restrict_thing:  name,
               restrict_thingy: document
end