Module: Rtasklib::Controller

Extended by:
Controller
Included in:
Controller, TaskWarrior
Defined in:
lib/rtasklib/controller.rb

Overview

Accessed through the main TW, which includes this module, e.g. `tw.all`

This module contains the public, user-facing methods.

By convention bang methods modify the task database, and non-bang read from the database, e.g. `Controller#all` vs `Controller#modify!`

Most methods accept filtering in the form of ids, tags, and dom

taskwarrior.org/docs/tags.html

Changes to the config are not effected by #undo!

XXX: depends on TaskWarrior#override_a currently, which isn't great.

Examples:

ids: can be a single id as a String or Fixnum or Range

tw.some(ids: 1)
tw.some(ids: "1")
tw.some(ids: 1..4)  # 1,2,3,4
tw.some(ids: 1...4) # 1,2,3

ids: can be an array of mixed types

tw.some(ids: [1,2,4...10,"12"])

ids: can be a TaskWarrior formatted string

tw.some(ids: "1-3,10")

tags: can be a single string

tw.some(tags: "work") # converted to +work
tw.some(tags: "-work")

tags: can be an array and include relational operators

tw.some(tags: ["work", "and", "-fun"])

tags: work with TaskWarrior built-in virtual tags

tw.some(tags: "+TODAY")

dom: work as hashes

require "date"
today = DateTime.now
tw.some(dom: {project: "Work", "due.before" => today})

You can also pass in a TW style string if you prefer

tw.some(dom: "project:Work due.before:#{today}")

Instance Method Summary (collapse)

Instance Method Details

- (Process::Status) add!(description, tags: nil, dom: nil)

Add a single task to the database w/required description and optional tags and dom queries (e.g. project:Work)

Parameters:

Returns:

  • (Process::Status) —

    the exit status of the thread



211
212
213
214
215
216
217
 
# File 'lib/rtasklib/controller.rb', line 211

def add! description, tags: nil, dom: nil
  f = Helpers.filter(tags: tags, dom: dom)
  d = Helpers.wrap_string(description)
  Execute.task_popen3(*override_a, "add", d, f) do |i, o, e, t|
    return t.value
  end
end

- (Array<Models::TaskModel>) all(active: true)

Retrieves the current task list from the TaskWarrior database. Defaults to just show active (waiting & pending) tasks, which is usually what is exposed to the end user through the default reports. To see everything including completed, deleted, and parent recurring tasks, set `active: false`. For more granular control see Controller#some.

Examples:

tw.all.count #=> 200
tw.all(active: true) #=> 200
tw.all(active: false) #=> 578

Parameters:

  • active (Boolean) —

    return only pending & waiting tasks

Returns:



71
72
73
74
75
76
77
78
79
80
 
# File 'lib/rtasklib/controller.rb', line 71

def all active: true
  all = []
  f = Helpers.pending_or_waiting(active)
  Execute.task_popen3(*override_a, f, "export") do |i, o, e, t|
    all = MultiJson.load(o.read).map do |x|
      Rtasklib::Models::TaskModel.new(x)
    end
  end
  return all
end

- (Object) count(ids: nil, tags: nil, dom: nil, active: true) Also known as: size, length

Count the number of tasks that match a given filter. Faster than counting an array returned by Controller#all or Controller#some.

Parameters:



125
126
127
128
129
130
131
 
# File 'lib/rtasklib/controller.rb', line 125

def count ids: nil, tags: nil, dom: nil, active: true
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  Execute.task_popen3(*@override_a, f, a, "count") do |i, o, e, t|
    return Integer(o.read)
  end
end

- (Boolean) create_uda!(name, type: "string", label: nil, values: nil, default: nil, urgency: nil)

Add a UDA to the users config/database

Parameters:

Returns:

  • (Boolean) —

    success



369
370
371
372
373
374
375
376
377
378
 
# File 'lib/rtasklib/controller.rb', line 369

def create_uda! name, type: "string", label: nil, values: nil,
               default: nil, urgency: nil
  label = name if label.nil?

  update_config("uda.#{name}.type",  type)
  update_config("uda.#{name}.label", label)
  update_config("uda.#{name}.values",  values)  unless values.nil?
  update_config("uda.#{name}.default", default) unless default.nil?
  update_config("uda.#{name}.urgency", urgency) unless urgency.nil?
end

- (Process::Status) delete!(ids: nil, tags: nil, dom: nil, active: true)

Returns false if filter is blank.

Parameters:

Returns:

  • (Process::Status) —

    the exit status of the thread



269
270
271
272
273
274
275
276
277
 
# File 'lib/rtasklib/controller.rb', line 269

def delete! ids: nil, tags: nil, dom: nil, active: true
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  return false if f.blank?

  Execute.task_popen3(*override_a, f, a, "delete") do |i, o, e, t|
    return t.value
  end
end

- (Process::Status) done!(ids: nil, tags: nil, dom: nil, active: true)

Finishes the filtered tasks. Returns false if filter (ids:, tags:, dom:) is blank.

Parameters:

Returns:

  • (Process::Status) —

    the exit status of the thread



251
252
253
254
255
256
257
258
259
 
# File 'lib/rtasklib/controller.rb', line 251

def done! ids: nil, tags: nil, dom: nil, active: true
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  return false if f.blank?

  Execute.task_popen3(*override_a, f, a, "done") do |i, o, e, t|
    return t.value
  end
end

- (Rtasklib::Taskrc) get_rc

Calls `task _show` with initial overrides returns a Taskrc object of the result

Returns:



140
141
142
143
144
145
146
 
# File 'lib/rtasklib/controller.rb', line 140

def get_rc
  res = []
  Execute.task_popen3(*@override_a, "_show") do |i, o, e, t|
    res = o.read.each_line.map { |l| l.chomp }
  end
  Taskrc.new(res, :array)
end

- (Array<String>) get_uda_names

Retrieve an array of the uda names

Returns:



340
341
342
343
344
 
# File 'lib/rtasklib/controller.rb', line 340

def get_uda_names
  Execute.task_popen3(*@override_a, "_udas") do |i, o, e, t|
    return o.read.each_line.map { |l| l.chomp }
  end
end

- (Hash{Symbol=>Hash}) get_udas

Retrieves a hash of hashes with info about the UDAs currently available

Returns:

  • (Hash{Symbol=>Hash}) 


293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/rtasklib/controller.rb', line 293

def get_udas
  udas = {}
  taskrc.config.attributes
    .select { |attr, val| Helpers.uda_attr? attr }
    .sort
    .chunk  { |attr, val| Helpers.arbitrary_attr attr }
    .each do |attr, arr|
      uda = arr.map do |pair|
        [Helpers.deep_attr(pair[0]), pair[1]]
      end
      udas[attr.to_sym] = Hash[uda]
    end
    return udas
end

- (String) get_version

Calls `task _version` and returns the result

Returns:



152
153
154
155
156
157
158
 
# File 'lib/rtasklib/controller.rb', line 152

def get_version
  version = nil
  Execute.task_popen3("_version") do |i, o, e, t|
    version = Helpers.to_gem_version(o.read.chomp)
  end
  version
end

- (Process::Status) modify!(attr, val, ids: nil, tags: nil, dom: nil, active: true)

Modify a set of task the match the input filter with a single attr/value pair. Returns false if filter (ids:, tags:, dom:) is blank.

Parameters:

Returns:

  • (Process::Status) —

    the exit status of the thread



231
232
233
234
235
236
237
238
239
240
 
# File 'lib/rtasklib/controller.rb', line 231

def modify! attr, val, ids: nil, tags: nil, dom: nil, active: true
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  return false if f.blank?

  query = "#{f} #{a} modify #{attr}:#{val}"
  Execute.task_popen3(*override_a, query) do |i, o, e, t|
    return t.value
  end
end

- (Array<Models::TaskModel>) some(ids: nil, tags: nil, dom: nil, active: true)

Retrieves the current task list filtered by id, tag, or a dom query

Examples:

filter by an array of ids

tw.some(ids: [1..2, 5])

filter by tags

tw.some(tags: ["+school", "or", "-work"]
# You can also pass in a TW style string if you prefer
tw.some(tags: "+school or -work"]

filter by a dom query

require "date"
today = DateTime.now
# note that queries with dots need to be Strings, as they would be
# invalid Symbols
tw.some(dom: {project: "Work", "due.before" => today})
# You can also pass in a TW style string if you prefer
tw.some(dom: "project:Work due.before:#{today}")

Parameters:

Returns:



105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/rtasklib/controller.rb', line 105

def some ids: nil, tags: nil, dom: nil, active: true
  some = []
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  Execute.task_popen3(*@override_a, f, a, "export") do |i, o, e, t|
    some = MultiJson.load(o.read).map do |x|
      Rtasklib::Models::TaskModel.new(x)
    end
  end
  return some
end

- (Process::Status, False) start!(ids: nil, tags: nil, dom: nil, active: true)

Mark the filter of tasks as started Returns false if filter (ids:, tags:, dom:) is blank.

Examples:

tw.start!(ids: 1)

Parameters:

Returns:

  • (Process::Status, False) —

    the exit status of the thread or false if it exited early because filter was blank.



173
174
175
176
177
178
179
180
181
 
# File 'lib/rtasklib/controller.rb', line 173

def start! ids: nil, tags: nil, dom: nil, active: true
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  return false if f.blank?

  Execute.task_popen3(*@override_a, f, a, "start") do |i, o, e, t|
    return t.value
  end
end

- (Process::Status, False) stop!(ids: nil, tags: nil, dom: nil, active: true)

Mark the filter of tasks as stopped Returns false if filter (ids:, tags:, dom:) is blank.

Parameters:

Returns:

  • (Process::Status, False) —

    the exit status of the thread or false if it exited early because filter was blank.



193
194
195
196
197
198
199
200
201
 
# File 'lib/rtasklib/controller.rb', line 193

def stop! ids: nil, tags: nil, dom: nil, active: true
  f = Helpers.filter(ids: ids, tags: tags, dom: dom)
  a = Helpers.pending_or_waiting(active)
  return false if f.blank?

  Execute.task_popen3(*@override_a, f, a, "stop") do |i, o, e, t|
    return t.value
  end
end

- (Process::Status) sync!

Sync the local TaskWarrior database changes to the remote databases. Remotes need to be configured in the .taskrc.

Examples:

# make some local changes with add!, modify!, or the like
tw.sync!

Returns:

  • (Process::Status) —

    the exit status of the thread



389
390
391
392
393
 
# File 'lib/rtasklib/controller.rb', line 389

def sync!
  Execute.task_popen3(*override_a, "sync") do |i, o, e, t|
    return t.value
  end
end

- (Boolean) uda_exists?(uda_name)

Checks if a given uda exists in the current task database

Parameters:

  • uda_name (String) —

    the uda name to check for

Returns:

  • (Boolean) —

    whether it matches or not



351
352
353
354
355
356
357
 
# File 'lib/rtasklib/controller.rb', line 351

def uda_exists? uda_name
  if get_udas.any? { |uda| uda == uda_name }
    true
  else
    false
  end
end

- (Object) undo!

Directly call `task undo`, which only applies to edits to the task db not configuration changes



283
284
285
286
287
 
# File 'lib/rtasklib/controller.rb', line 283

def undo!
  Execute.task_popen3(*override_a, "undo") do |i, o, e, t|
    return t.value
  end
end

- (Process::Status) update_config!(attr, val)

Update a configuration variable in the .taskrc

Parameters:

Returns:

  • (Process::Status) —

    the exit status of the thread



314
315
316
317
318
 
# File 'lib/rtasklib/controller.rb', line 314

def update_config! attr, val
  Execute.task_popen3(*override_a, "config #{attr} #{val}") do |i, o, e, t|
    return t.value
  end
end