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

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 taskwarrior.org/docs/tags.html

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

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

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

Parameters:

  • description (String) —

    the required desc of the task

  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)

Returns:

  • (Process::Status) —

    the exit status of the thread



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

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

#all(active: true) ⇒ Array<Models::TaskModel>

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) (defaults to: true) —

    return only pending & waiting tasks

Returns:



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

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

#count(ids: nil, tags: nil, dom: nil, active: true) ⇒ Object 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:

  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks



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

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

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

Add a UDA to the users config/database

Parameters:

  • name (String)
  • type (String) (defaults to: "string")
  • label (String) (defaults to: nil)
  • values (String) (defaults to: nil)
  • default (String) (defaults to: nil)
  • urgency (String) (defaults to: nil)

Returns:

  • (Boolean) —

    success



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

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

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

Returns false if filter is blank.

Parameters:

  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks

Returns:

  • (Process::Status) —

    the exit status of the thread



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

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

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

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

Parameters:

  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks

Returns:

  • (Process::Status) —

    the exit status of the thread



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

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

#get_rc ⇒ Rtasklib::Taskrc

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

Returns:



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

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

#get_uda_names ⇒ Array<String>

Retrieve an array of the uda names

Returns:



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

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

#get_udas ⇒ Hash{Symbol=>Hash}

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

Returns:

  • (Hash{Symbol=>Hash}) 


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

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

#get_version ⇒ String

Calls ‘task _version` and returns the result

Returns:



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

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

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

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:

  • attr (String)
  • val (String)
  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks

Returns:

  • (Process::Status) —

    the exit status of the thread



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

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

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

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:

  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks

Returns:



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

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

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

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

Examples:

tw.start!(ids: 1)

Parameters:

  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks

Returns:

  • (Process::Status, False) —

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



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

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

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

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

Parameters:

  • ids (Array<Range, Fixnum, String>, String, Range, Fixnum) (defaults to: nil)
  • tags (Array<String>, String) (defaults to: nil)
  • dom (Array<String>, String) (defaults to: nil)
  • active (Boolean) (defaults to: true) —

    return only pending & waiting tasks

Returns:

  • (Process::Status, False) —

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



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

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

#sync! ⇒ Process::Status

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



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

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

#uda_exists?(uda_name) ⇒ Boolean

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



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

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

#undo! ⇒ Object

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



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

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

#update_config!(attr, val) ⇒ Process::Status

Update a configuration variable in the .taskrc

Parameters:

Returns:

  • (Process::Status) —

    the exit status of the thread



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

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