things-rb 0.3.0

data/.gitignore

@@ -0,0 +1,4 @@
+pkg
+doc
+Manifest
+test/fixures/Backups

data/CHANGELOG

@@ -0,0 +1,8 @@
+*0.2.0* (August 29, 2009)
+
+* Added support for due dates, scheduled items & notes
+
+
+*0.1.0* (March 23, 2009)
+
+* Initial public release.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Martin Str�m
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,110 @@
+things-rb
+=========
+
+things-rb is a Ruby library and a command line tool for accessing the backend of the GTD app [Things.app](http://culturedcode.com/things/)
+
+## Why?
+There are many reasons why you would use a command line version of Things, including: 
+
+![GeekTools](http://img.skitch.com/20090323-xacfsghrsi7p6yjt1x2fnse8ek.jpg)
+
+- Keep a list of your ToDos on the desktop using an app like [GeekTool](http://projects.tynsoe.org/en/geektool/)
+- Access your ToDos remotely by SSH:ing into your machine (even from a Windows or Linux box)
+- You don't need to have Things.app running all the time
+- You like the Terminal and command line
+
+## Install
+
+    $ sudo gem install haraldmartin-things-rb --source http://gems.github.com
+
+If you're on default Mac OS X Leopard and haven't upgraded your RubyGem installation you'll need to to this first:
+
+    $ sudo gem update --system
+
+When the upgrade is done, just runt the `gem install ...` command above and you're set.
+
+
+## Usage
+
+things-rb can be used either as a Ruby library or with the included command line tool. 
+
+### Ruby Library
+
+Example usage:
+
+    things = Things.new # will use Things' default database location. 
+    # things = Things.new(:database => '/path/to/Database.xml')
+    
+    tasks = things.today.map do |task|
+      tags    = "(#{task.tags.join(' ')})" if task.tags?
+      project = "[#{task.parent}]" if task.parent?
+      bullet  = task.completed? ? "✓" : task.canceled? ? "×" : "-"
+      [bullet, task.title, tags, project].compact.join(" ")
+    end
+    
+    puts tasks.compact.sort.join("\n")
+    
+### Command Line Use
+
+    $ things
+    $ things --help
+    
+Shows all the options available. 
+
+The most common use I assume would be:
+    
+    $ things today
+  
+which lists all tasks in "Today" which are not already completed.
+    
+If you like to show completed and canceled tasks, just pass the `--all` option
+        
+    $ things --all today
+
+Be default, things-rb will use the default location of the Things' database but if you keep it somewhere else you can
+set a custom path using the `-d` or `--database` switch
+
+    $ things --database /path/to/Database.xml
+
+Replace `today` with other focus to list the task
+
+    $ things --all next
+    $ things logbook
+
+
+## Testing
+
+To view test document (`test/fixtures/Database.xml`) in Things, just launch Things.app with ⌥ (option/alt) down and click "Choose Library" and point it to `things-rb/test/fixtures`. 
+Be sure to disable automatic logging of completed tasks in the Things.app preferences so they won't be moved around in the document.
+
+
+## TODO
+- Support "Projects" focus
+- Optimize test and XML queries
+- Add tag support to binary
+- Organize the classes, make internal methods private
+
+
+## Credits and license
+
+By [Martin Ström](http://my-domain.se) under the MIT license:
+
+>  Copyright (c) 2009 Martin Ström
+>
+>  Permission is hereby granted, free of charge, to any person obtaining a copy
+>  of this software and associated documentation files (the "Software"), to deal
+>  in the Software without restriction, including without limitation the rights
+>  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+>  copies of the Software, and to permit persons to whom the Software is
+>  furnished to do so, subject to the following conditions:
+>
+>  The above copyright notice and this permission notice shall be included in
+>  all copies or substantial portions of the Software.
+>
+>  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+>  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+>  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+>  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+>  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+>  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+>  THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,26 @@
+require "rubygems"
+require "rake/testtask"
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/test_*.rb"]
+  t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name        = "things-rb"
+    gemspec.summary     = "Library and command-line tool for accessing Things.app databases"
+    gemspec.description = "Library and command-line tool for accessing Things.app databases"
+    gemspec.email       = "name@my-domain.se"
+    gemspec.homepage    = "http://github.com/haraldmartin/things-rb"
+    gemspec.authors     = ["Martin Ström"]
+    gemspec.add_dependency 'hpricot'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/bin/things

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require 'things'
+
+options = { :tasks => { :completed => false } }
+opts = OptionParser.new do |opts|
+  opts.separator ''
+  opts.separator 'Options:'
+  
+  opts.banner = "Usage: things [options] today|next|inbox|logbook|trash"
+  
+  def opts.show_usage
+    puts self
+    exit  
+  end
+  
+  opts.on("-d FILENAME", "--database FILENAME", "Use the specified Things database") do |database|    
+    options[:database] = database
+  end
+  
+  opts.on("-c", "--completed", 'Shows only completed tasks') { options[:tasks] = { :completed => true } }
+  opts.on("-a", "--all", 'Shows all tasks in the focus') { |f| options[:tasks] = { } }
+
+  opts.on_tail("-h", "--help", "Shows this help message") { opts.show_usage }
+  opts.on_tail("-v", "--version", "Shows version") do
+    puts Things::Version::STRING
+    exit
+  end
+
+  opts.show_usage if ARGV.empty?
+  
+  begin
+    opts.order(ARGV) { |focus| options[:focus] = focus }
+  rescue OptionParser::ParseError => e
+    opts.warn e.message
+    opts.show_usage
+  end
+end
+
+opts.parse!
+opts.show_usage unless options.key?(:focus)
+
+things = Things.new(:database => options.delete(:database))
+tasks = things.focus(options[:focus]).tasks(options[:tasks]).map do |task|
+  tags    = "(#{task.tags.join(' ')})" if task.tags?
+  project = "[#{task.parent}]" if task.parent?
+  [task.bullet, task.title, tags, project].compact.join(" ")
+end
+
+puts tasks.compact.sort.join("\n")
+

data/lib/things/document.rb

@@ -0,0 +1,39 @@
+module Things
+  class Document
+    DEFAULT_DATABASE_PATH = "#{ENV['HOME']}/Library/Application Support/Cultured Code/Things/Database.xml" unless defined?(DEFAULT_DATABASE_PATH)
+    
+    attr_reader :database_file
+  
+    def initialize(options = {}, &block)
+      @database_file = options[:database] || DEFAULT_DATABASE_PATH
+      @focus_cache = {}
+      parse!
+      yield self if block_given?
+    end
+  
+    def database
+      @doc
+    end
+    
+    def focus(name)
+      @focus_cache[name] ||= Focus.new(name, @doc)
+    end
+  
+    [:today, :inbox, :trash, :logbook, :next, :scheduled].each do |name|
+      class_eval <<-EOF
+        def #{name}(options = {})               # def inbox(options = {})
+          focus(:#{name}).tasks(options)        #   focus(:inbox).tasks(options)
+        end                                     # end
+      EOF
+    end
+    
+    alias_method :nextactions, :next
+    alias_method :next_actions, :next
+  
+    private
+
+    def parse!
+      @doc = Hpricot(IO.read(database_file))
+    end
+  end
+end

data/lib/things/focus.rb

@@ -0,0 +1,63 @@
+module Things
+  class Focus
+    FOCUS_TYPES = %w[FocusInbox FocusLogbook FocusMaybe FocusNextActions FocusTickler FocusToday FocusTrash].freeze
+    
+    def initialize(name, doc)
+      @name     = name
+      @doc      = doc
+      @xml_node = @doc.at("//object[@type='FOCUS']/attribute[@name='identifier'][text()='#{type_name}']/..")
+    end
+    
+    def type_name
+      name = case @name.to_s
+        when /next/i            then "FocusNextActions"
+        when "someday", "later" then "FocusMaybe"
+        when "scheduled"        then "FocusTickler"
+        else "Focus" + @name.to_s.capitalize
+      end
+      raise Things::InvalidFocus, name unless FOCUS_TYPES.member?(name)
+      name
+    end
+
+    def id
+      @id ||= @xml_node.attributes['id']
+    end
+
+    def type_id
+      @type_id ||= @xml_node.at("/attribute[@name='focustype']").inner_text
+    end
+    
+    def tasks(options = {})
+      options ||= {} # when options == nil
+      
+      selector = "//object[@type='TODO']/attribute[@name='focustype'][text()='#{type_id}']/.."
+      @all_tasks ||= @doc.search(selector).map do |task_xml|
+        Task.new(task_xml, @doc)
+      end
+
+      filter_tasks!(options)
+      
+      @tasks.sort_by &:position
+    end
+    
+    alias_method :todos, :tasks
+    
+    private
+    
+    # TODO: Smarter task filtering
+    def filter_tasks!(options)
+      @tasks = @all_tasks.reject(&:children?)
+
+      [:completed, :canceled].each do |filter|
+        proc = Proc.new { |e| e.send("#{filter}?") }
+        if options.key?(filter)
+          if options[filter]
+            @tasks = @tasks.select(&proc)
+          else
+            @tasks = @tasks.reject(&proc)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/things/task.rb

@@ -0,0 +1,162 @@
+module Things
+  class Task
+    include Comparable
+    
+    INCOMPLETED = 0
+    CANCELED    = 2
+    COMPLETED   = 3
+
+    def initialize(task_xml, doc)
+      @doc      = doc
+      @xml_node = task_xml
+    end
+
+    def title
+      @xml_node.at("attribute[@name='title']").inner_text
+    end
+
+    alias_method :to_s, :title
+
+    def <=>(another)
+      if parent? && another.parent?
+        parent <=> another.parent
+      else
+        title <=> another.title
+      end
+    end
+
+    def to_xml
+      @xml_node.to_s
+    end
+  
+    def tag_ids
+      ids_from_relationship("tags")
+    end
+
+    def tags
+      @tags ||= tag_ids.map do |tag_id|
+        @doc.at("##{tag_id} attribute[@name=title]").inner_text
+      end
+    end
+
+    def tags?
+      tags.any?
+    end
+    
+    def tag?(name)
+      tags.include?(name)
+    end
+    
+    def parent_id
+      id_from_relationship('parent')
+    end
+
+    def parent
+      @parent ||= task_from_id(parent_id)
+    end
+
+    def parent?
+      !!parent
+    end
+
+    def completed?
+      status == COMPLETED
+    end
+
+    alias_method :complete?, :completed?
+    alias_method :done?, :completed?
+
+    def incompleted?
+      status == INCOMPLETED
+    end
+
+    alias_method :incomplete?, :incompleted?
+    
+    def canceled?
+      status == CANCELED
+    end
+    
+    def notes
+      @notes ||= (node = @xml_node.at("attribute[@name='content']")) &&
+        Hpricot.parse(node.inner_text.gsub(/\\u3c00/, "<").gsub(/\\u3e00/, ">")).inner_text
+    end
+    
+    def notes?
+      !!notes
+    end
+    
+    def status
+      @status ||= (node = @xml_node.at("attribute[@name='status']")) && node.inner_text.to_i
+    end
+    
+    def position
+      @position ||= @xml_node.at("attribute[@name='index']").inner_text.to_i
+    end
+    
+    alias_method :index, :position
+    alias_method :order, :position
+    
+    def due_date
+      @due_date ||= date_attribute("datedue")
+    end
+
+    def due?
+      due_date && Time.now > due_date
+    end
+
+    def scheduled_date
+      @scheduled_date ||= date_attribute('tickledate')
+    end
+    
+    def scheduled?
+      !!scheduled_date
+    end
+
+    def bullet
+      completed? ? "✓" : canceled? ? "×" : "-"
+    end
+
+    def children_ids
+      ids_from_relationship('children')
+    end
+    
+    def children
+      @children ||= tasks_from_ids(children_ids)
+    end
+    
+    def children?
+      children.any?
+    end
+    
+    private
+    
+    def tasks_from_ids(ids)
+      ids.map { |id| task_from_id(id) }.compact
+    end
+    
+    def task_from_id(id)
+      if (node = @doc.at("##{id}")) && node.inner_text.strip != ''
+        Task.new(node, @doc)
+      else
+        nil
+      end
+    end
+  
+    # TODO rename id_from_relationship
+    def id_from_relationship(name)
+      ids_from_relationship(name)[0]
+    end
+    
+    def ids_from_relationship(name)
+      if node = @xml_node.at("relationship[@name='#{name}'][@idrefs]")
+        node.attributes['idrefs'].split
+      else
+        []
+      end
+    end
+  
+    def date_attribute(name)
+      (node = @xml_node.at("attribute[@name='#{name}']")) && node.inner_text.to_f.to_cocoa_date
+    end
+  end
+end

data/lib/things/version.rb

@@ -0,0 +1,9 @@
+module Things
+  module Version
+    MAJOR  = 0
+    MINOR  = 3
+    TINY   = 0
+
+    STRING = [MAJOR, MINOR, TINY].join(".")
+  end
+end

data/lib/things.rb

@@ -0,0 +1,34 @@
+begin
+  require 'hpricot'
+rescue LoadError => e
+  puts "Hpricot is missing. Run `gem install hpricot` to install"
+end
+require "time"
+
+class Symbol
+  def to_proc
+    Proc.new { |obj, *args| obj.send(self, *args) }
+  end
+end
+
+class Float
+  EPOCH = Time.at(978307200.0)
+
+  def to_cocoa_date
+    EPOCH + self
+  end
+end
+
+require 'things/version'
+require 'things/document'
+require 'things/focus'
+require 'things/task'
+
+module Things
+  class FocusNotFound < StandardError; end
+  class InvalidFocus < StandardError; end
+  
+  def Things.new(*options, &block)
+    Document.new(*options, &block)
+  end
+end