todo-txt 0.1

data/README.md

@@ -0,0 +1,95 @@
+# Todo.txt
+
+This is a Ruby client library for Gina Trapani's [todo.txt](https://github.com/ginatrapani/todo.txt-cli/). It allows for easy parsing of task lists and tasks in the todo.txt format.
+
+# Installation
+
+Installation is very simple. The project is packaged as a Ruby gem and can be installed by running:
+
+    gem install todo-txt
+
+# Usage
+
+## Todo::List
+
+A `Todo::List` object encapsulates your todo.txt file. You initialise it by passing the path to your todo.txt to the constructor:
+
+``` ruby
+    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.
+
+### Filtering
+
+You can filter your todo list by priority, project, context or a combination of all three with ease.
+
+``` ruby
+    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 "+manhatten"
+    # => Returns a new Todo::List with only tasks that are part of the
+         +manhatten project (see what I did there?)
+
+    # And you can combine these, like so
+    list.by_project("+manhatten").by_priority("B")
+```
+
+## Todo::Task
+
+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).
+
+``` ruby
+    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"
+```
+
+### Comparable
+
+The `Todo::Task` object includes the `Comparable` mixin. It compares with other tasks and sorts by priority in descending order.
+
+``` ruby
+    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.
+
+# Requirements
+
+The todo-txt gem requires Ruby 1.9.2 or higher. It doesn't currently run on 1.8.7.

data/lib/todo-txt.rb

@@ -0,0 +1,5 @@
+# Require all files in the main lib directory
+Dir[File.dirname(__FILE__) + '/todo-txt/*.rb'].each do |file|
+  require file
+end
+

data/lib/todo-txt/list.rb

@@ -0,0 +1,87 @@
+module Todo
+  class List < Array
+    # Initializes a Todo List object with a path to the corresponding todo.txt
+    # file. For example, if your todo.txt file is located at:
+    #
+    #   /home/sam/Dropbox/todo/todo.txt
+    #
+    # You would initialize this object like do:
+    #
+    #   list = Todo::List.new "/home/sam/Dropbox/todo/todo-txt"
+    #
+    # Alternately, you can initialize this object with an array of strings or
+    # tasks. If the array is of strings, the strings will be converted into
+    # tasks. You can supply a mixed list of string and tasks if you wish.
+    #
+    # Example:
+    #
+    #   array = Array.new
+    #   array.push "(A) A string task!"
+    #   array.push Todo::Task.new("(A) An actual task!")
+    #
+    #   list = Todo::List.new array
+    def initialize list
+      if list.is_a? Array
+        # No file path was given.
+        @path = nil
+
+        # If path is an array, loop over it, adding to self.
+        list.each do |task|
+          # If it's a string, make a new task out of it.
+          if task.is_a? String
+            self.push Todo::Task.new task
+          # If it's a task, just add it.
+          elsif task.is_a? Todo::Task
+            self.push task
+          end
+        end
+      elsif list.is_a? String
+        @path = list
+
+        # Read in lines from file, create Todo::Tasks out of them and push them
+        # onto self.
+        File.open(list) do |file|
+          file.each_line { |line| self.push Todo::Task.new line }
+        end
+      end
+    end
+
+    # The path to the todo.txt file that you supplied when you created the
+    # Todo::List object.
+    def path
+      @path
+    end
+
+    # Filters the list by priority and returns a new list.
+    #
+    # Example:
+    #
+    #   list = Todo::List.new "/path/to/list"
+    #   list.by_priority "A" #=> Will be a new list with only priority A tasks
+    def by_priority priority
+      Todo::List.new self.select { |task| task.priority == priority }
+    end
+
+    # Filters the list by context and returns a new list.
+    #
+    # Example:
+    #
+    #   list = Todo::List.new "/path/to/list"
+    #   list.by_context "@context" #=> Will be a new list with only tasks
+    #                                  containing "@context"
+    def by_context context
+      Todo::List.new self.select { |task| task.contexts.include? context }
+    end
+
+    # Filters the list by project and returns a new list.
+    #
+    # Example:
+    #
+    #   list = Todo::List.new "/path/to/list"
+    #   list.by_project "+project" #=> Will be a new list with only tasks
+    #                                  containing "+project"
+    def by_project project
+      Todo::List.new self.select { |task| task.projects.include? project }
+    end
+  end
+end

data/lib/todo-txt/task.rb

@@ -0,0 +1,114 @@
+module Todo
+  class Task
+    include Comparable
+
+    # The regular expression used to match contexts.
+    def self.contexts_regex
+       /(?:\s+|^)@\w+/
+    end
+
+    # The regex used to match projects.
+    def self.projects_regex
+       /(?:\s+|^)\+\w+/
+    end
+
+    # The regex used to match priorities.
+    def self.priotity_regex
+      /^\([A-Za-z]\)\s+/
+    end
+
+    # Creates a new task. The argument that you pass in must be a string.
+    def initialize task
+      @orig = task
+    end
+
+    # Returns the original content of the task.
+    #
+    # Example:
+    #
+    #   task = Todo::Task.new "(A) @context +project Hello!"
+    #   task.orig #=> "(A) @context +project Hello!"
+    def orig
+      @orig
+    end
+
+    # Returns the priority, if any.
+    #
+    # Example:
+    #
+    #   task = Todo::Task.new "(A) Some task."
+    #   task.priority #=> "A"
+    #
+    #   task = Todo::Task.new "Some task."
+    #   task.priority #=> nil
+    def priority
+      @priority ||= if orig =~ self.class.priotity_regex
+        orig[1]
+      else
+        nil
+      end
+    end
+
+    # Retrieves an array of all the @context annotations.
+    #
+    # Example:
+    #
+    #   task = Todo:Task.new "(A) @context Testing!"
+    #   task.context #=> ["@context"]
+    def contexts
+      @contexts ||= orig.scan(self.class.contexts_regex).map { |item| item.strip }
+    end
+
+    # Retrieves an array of all the +project annotations.
+    #
+    # Example:
+    #
+    #   task = Todo:Task.new "(A) +test Testing!"
+    #   task.projects #=> ["+test"]
+    def projects
+      @projects ||= orig.scan(self.class.projects_regex).map { |item| item.strip }
+    end
+
+    # Gets just the text content of the todo, without the priority, contexts
+    # and projects annotations.
+    #
+    # Example:
+    #
+    #   task = Todo::Task.new "(A) @test Testing!"
+    #   task.text #=> "Testing!"
+    def text
+      @text ||= orig.
+        gsub(self.class.priotity_regex, '').
+        gsub(self.class.contexts_regex, '').
+        gsub(self.class.projects_regex, '').
+        strip
+    end
+
+    # Compares the priorities of two tasks.
+    #
+    # Example:
+    #
+    #   task1 = Todo::Task.new "(A) Priority A."
+    #   task2 = Todo::Task.new "(B) Priority B."
+    #
+    #   task1 > task2
+    #   # => true
+    #
+    #   task1 == task2
+    #   # => false
+    #
+    #   task2 > task1
+    #   # => false
+    def <=> other_task
+      if self.priority.nil? and other_task.priority.nil?
+        0
+      elsif other_task.priority.nil?
+        1
+      elsif self.priority.nil?
+        -1
+      else
+        other_task.priority <=> self.priority
+      end
+    end
+  end
+end

data/spec/data/todo.txt

@@ -0,0 +1,5 @@
+(A) Crack the Da Vinci Code.
+(B) +winning Win.
+@context Give it some context.
+Just a POD: Plain old task.
+(C) +project @context This one has it all!

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require_relative '../lib/todo-txt'

data/spec/todo-txt/list_spec.rb

@@ -0,0 +1,71 @@
+require_relative '../spec_helper'
+
+describe Todo::List do
+  # A helper method to grab the test data list.
+  def list
+    Todo::List.new(File.dirname(__FILE__) + '/../data/todo.txt')
+  end
+
+  it 'should grab a list of Todo::Tasks' do
+    list.each do |task|
+      task.class.should == Todo::Task
+    end
+
+    # This is a little bit fragile but it helps me sleep at night.
+    list[0].priority.should == "A"
+  end
+
+  it 'should be able to filter by priority' do
+    list.by_priority("A").each do |task|
+      task.priority.should == "A"
+    end
+
+    # Make sure some data was actually checked
+    list.by_priority("A").length.should be > 0
+  end
+
+  it 'should be able to filter by context' do
+    list.by_context("@context").each do |task|
+      task.contexts.should include "@context"
+    end
+
+    # Make sure some data was actually checked
+    list.by_context("@context").length.should be > 0
+  end
+
+  it 'should be able to filter by project' do
+    list.by_project("+project").each do |task|
+      task.projects.should include "+project"
+    end
+
+    # Make sure some data was actually checked
+    list.by_project("+project").length.should be > 0
+  end
+
+  it 'should be able to filter by project, context and priority' do
+    filtered = list.by_project("+project").
+                    by_context("@context").
+                    by_priority("C")
+
+    filtered.each do |task|
+      task.projects.should include "+project"
+      task.contexts.should include "@context"
+      task.priority.should == "C"
+    end
+
+    # Make sure some data was actually checked
+    filtered.length.should be > 0
+  end
+
+  it 'should be sortable' do
+    list.sort.each_cons(2) do |task_a, task_b|
+      task_a.should be <= task_b
+    end
+
+    # Make sure some data was actually checked
+    list.sort.length.should be > 0
+
+    # Class should still be Todo::List
+    list.sort.class.should == Todo::List
+  end
+end

data/spec/todo-txt/task_spec.rb

@@ -0,0 +1,67 @@
+require_relative '../spec_helper'
+
+describe Todo::Task do
+  it 'should recognise priorities' do
+    task = Todo::Task.new "(A) Hello world!"
+    task.priority.should == "A"
+  end
+
+  it 'should only recognise priorities at the start of a task' do
+    task = Todo::Task.new "Hello, world! (A)"
+    task.priority.should == nil
+  end
+
+  it 'should recognise contexts' do
+    task = Todo::Task.new "Hello, world! @test"
+    task.contexts.should == ["@test"]
+  end
+
+  it 'should recognise multiple contexts' do
+    task = Todo::Task.new "Hello, world! @test @test2"
+    task.contexts.should == ["@test", "@test2"]
+  end
+
+  it 'should recognise projects' do
+    task = Todo::Task.new "Hello, world! +test"
+    task.projects.should == ["+test"]
+  end
+
+  it 'should recognise multiple projects' do
+    task = Todo::Task.new "Hello, world! +test +test2"
+    task.projects.should == ["+test", "+test2"]
+  end
+
+  it 'should retain the original task' do
+    task = Todo::Task.new "(A) This is an awesome task, yo. +winning"
+    task.orig.should == "(A) This is an awesome task, yo. +winning"
+  end
+
+  it 'should be able to get just the text, no contexts etc.' do
+    task = Todo::Task.new "(B) This is a sweet task. @context +project"
+    task.text.should == "This is a sweet task."
+  end
+
+  it 'should be comparable' do
+    task1 = Todo::Task.new "(A) Top priority, y'all!"
+    task2 = Todo::Task.new "(B) Not quite so high."
+
+    assertion = task1 > task2
+    assertion.should == true
+  end
+
+  it 'should be comparable to task without priority' do
+    task1 = Todo::Task.new "Top priority, y'all!"
+    task2 = Todo::Task.new "(B) Not quite so high."
+
+    assertion = task1 < task2
+    assertion.should == true
+  end
+
+  it 'should be able to compare two tasks without priority' do
+    task1 = Todo::Task.new "Top priority, y'all!"
+    task2 = Todo::Task.new "Not quite so high."
+
+    assertion = task1 == task2
+    assertion.should == true
+  end
+end

data/todo-txt.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name = %q{todo-txt}
+  s.version = "0.1"
+  s.date = %q{2011-08-19}
+  s.authors = ["Sam Rose"]
+  s.email = %q{samwho@lbak.co.uk}
+  s.summary = %q{A client library for parsing todo.txt files.}
+  s.homepage = %q{http://lbak.co.uk}
+  s.description = %q{Allows for simple parsing of todo.txt files, as per Gina Trapani's todo.txt project.}
+  s.required_ruby_version = '>= 1.9.2'
+  s.license = 'GPL-2'
+
+  # Add all files to the files parameter.
+  s.files = []
+  Dir["**/*.*"].each { |path| s.files.push path }
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: todo-txt
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Sam Rose
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-19 00:00:00.000000000Z
+dependencies: []
+description: Allows for simple parsing of todo.txt files, as per Gina Trapani's todo.txt
+  project.
+email: samwho@lbak.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- spec/todo-txt/list_spec.rb
+- spec/todo-txt/task_spec.rb
+- spec/data/todo.txt
+- spec/spec_helper.rb
+- todo-txt.gemspec
+- lib/todo-txt/list.rb
+- lib/todo-txt/task.rb
+- lib/todo-txt.rb
+homepage: http://lbak.co.uk
+licenses:
+- GPL-2
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.8
+signing_key: 
+specification_version: 3
+summary: A client library for parsing todo.txt files.
+test_files: []