This is a Ruby client library for Gina Trapani's todo.txt. It allows for easy management of task lists and tasks in the todo.txt format.

Find the project on GitHub: http://github.com/samwho/todo-txt-gem.

Find the full API docs on Rubydoc.info: http://www.rubydoc.info/gems/todo-txt.

Installation is very simple. The project is packaged as a Ruby gem and can be installed by running:

gem install todo-txt

A Todo::List object encapsulates your todo.txt file. You initialise it by passing the path to your todo.txt to the constructor:

require 'todo-txt'

list = Todo::List.new "path/to/todo.txt"

Todo::List subclasses Array so it has all of the standard methods that are available on an array. It is, basically, an array of Todo::Task items.

You can filter your todo list by priority, project, context or a combination of all three with ease.

require 'todo-txt'

list = Todo::List.new "path/to/todo.txt"

list.by_priority "A"
# => Contains a Todo::List object with only priority A tasks.

list.by_context "@code"
# => Returns a new Todo::List with only tasks that have a @code context.

list.by_project "+manhattan"
# => Returns a new Todo::List with only tasks that are part of the
#    +manhattan project (see what I did there?)

# And you can combine these, like so
list.by_project("+manhattan").by_priority("B")

A Todo::Task object can be created from a standard task string if you don't want to use the Todo::List approach (though using Todo::List is recommended).

require 'todo-txt'

task = Todo::Task.new "(A) This task is top priority! +project @context"

task.priority
# => "A"

task.contexts
# => ["@context"]

task.projects
# => ["+project"]

task.text
# => "This task is top priority!"

task.orig
# => "(A) This task is top priority! +project @context"

The Todo::Task object includes the Comparable mixin. It compares with other tasks and sorts by priority in descending order.

task1 = Todo::Task.new "(A) Priority A."
task2 = Todo::Task.new "(B) Priority B."

task1 > task2
# => true

task1 == task2
# => false

task2 > task1
# => false

Tasks without a priority will always be less than a task with a priority.

The todo-txt gem requires Ruby 2.0 or higher.