things-client 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+doc
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Marcin Bunsch
+
+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.rdoc

@@ -0,0 +1,114 @@
+= Things
+
+Things is a Ruby API for the popular GTD app Things, available on the Mac.
+
+== Installation
+
+Currently, because this is an alpha version and it's too early for a release, installation must be done manually, like this:
+
+  git clone http://github.com/marcinbunsch/things
+  cd things
+  rake check_dependencies:runtime
+  rake build
+  sudo gem install pkg/things-0.0.1.gem
+
+== Usage
+
+=== Application
+
+The Application can be accessed at all times by calling Things::App. It has a few useful methods which will be described below. If you want Things to gain focus and move to the front of the window stack, you can call the Things::App.activate method.
+
+=== Todos
+
+Todos are accessed via the Things::Todo class.
+
+==== Create
+
+If you want to create a new Todo, you simple create a new instance of the Things::Todo class, supplying the parameters:
+
+  Things::Todo.new(:name => 'Take out the garbage')
+
+When you're ready to send it to Things, simply call the save method on the instance:
+
+  todo = Things::Todo.new(:name => 'Take out the garbage')
+  todo.save # the Todo will appear in the Inbox
+  
+If you want to send the Todo to Things during the instantiation process, simply call create:
+
+  Things::Todo.create(:name => 'Take out the garbage') # the Todo will appear in the Inbox
+
+==== Read
+
+===== Collections
+
+If you want to fetch a list of todos, there is a set of collections you can use.
+
+The largest one is the collection of all Todos. You fetch it by calling:
+ 
+   Things::App.todos
+   
+It will return an array of Things::Todo instances.
+
+If you only want the active (so non-finished) Todos, you can fetch a collection by calling:
+
+  Things::App.todos.active
+  
+It will return an array of Things::Todo instances.
+
+As the gem will grow, more methods will follow.
+
+===== Single Todos
+
+Things::Todo has a few useful methods if you want to fetch a single Todo.
+
+The smartest is the Things::Todo.find method, which will accept either a name or an id.
+
+  Things::Todo.find('Take out the garbage') # => #<Things::Todo:0x115dd84>
+  Things::Todo.find('11111111-1111-1111-1111-111111111111') # => #<Things::Todo:0x115dd84>
+
+If you want a more targeted approach, you can use Things::Todo.find_by_name or Things::Todo.find_by_id
+
+==== Update
+
+To update a Todo, you need to fetch it, change the desired properties and save it. The following example illustrates this:
+
+  todo = Things::Todo.find('Take out the garbage') # => #<Things::Todo:0x115dd84>
+  todo.name = 'Take out the garbage and old boxes'  
+  todo.save
+
+When you open up a Things window, you'll notice that the name has changed.
+
+==== Delete
+
+To delete a todo, simply call the delete method. The Todo will bo moved to Trash.
+
+  todo = Things::Todo.find('Take out the garbage') # => #<Things::Todo:0x115dd84>
+  todo.delete
+
+== Roadmap
+
+Currently Todos are fully supported, which is the core functionality of Todos, but leaves a lot of room for improvement. The first step is to create a unified API for handling AppleScript objects which behave in a similar way.
+
+Planned features:
+
+* Support for Projects
+* Support for Areas
+* Support for Tags
+* Support for Scheduled Todos
+
+== Contribution
+
+You're more than welcome to fork and improve this gem. Usual rules:
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+  bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request.
+
+== Copyright
+
+Copyright (c) 2010 Marcin Bunsch. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "things-client"
+    gem.summary = %Q{A Ruby client for Things' Applescript API. Things is a GTD app for OS X.}
+    gem.email = "marcin@applicake.com"
+    gem.homepage = "http://github.com/marcinbunsch/things"
+    gem.authors = ["Marcin Bunsch"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_dependency "rb-appscript", ">=0.5.3"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "things-client #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/appscript/reference.rb

@@ -0,0 +1,9 @@
+# a small hack - Things references a collection of Todos as to_dos
+# here we make an alias so todos is also possible
+module Appscript #:nodoc:
+  class Reference #:nodoc:
+    def todos
+      to_dos
+    end
+  end
+end

data/lib/things/app.rb

@@ -0,0 +1,30 @@
+module Things
+  class App < Reference::Base
+    extend Appscript
+    # get the singleton Application instance
+    def self.instance
+      reference ||= app('Things')
+    end
+    
+    # refresh the Application instance
+    def self.instance!
+      reference = app('Things')
+    end
+    
+    # get a collection of Lists
+    def self.lists
+      List
+    end
+    
+    # get a collection of Todos
+    def self.todos
+      Collections::Todo
+    end
+    
+    # activate the app and bring it to front
+    def self.activate
+      instance!.activate
+    end
+    
+  end
+end

data/lib/things/area.rb

@@ -0,0 +1,12 @@
+module Things
+  # Things::Todo
+  class Area < Reference::Record
+    
+    properties :name
+    # identifier is required for creation
+    identifier :area
+    # collection is used for findings
+    collection :areas
+   
+  end
+end

data/lib/things/collections/todo.rb

@@ -0,0 +1,42 @@
+module Things
+  module Collections
+    class Todo
+    
+      class << self
+        
+        # Returns an Appscript Reference to the entire collection of todos
+        def reference
+          Things::App.instance.todos
+        end
+        
+        # these are references and should be stored somewhere else...
+        Things::List::DEFAULTS.each do |list|
+          class_eval <<-"eval"
+            def #{list}
+              Things::App.lists.#{list}.todos
+            end
+          eval
+        end
+        
+        # Returns an array of Things::Todo objects
+        def all
+          reference.get.collect { |todo| Things::Todo.build(todo) }
+        end
+
+        # Get all not completed Todos
+        # Note this returns an array of Todos, not references
+        # TODO: find a better way of filtering references
+        def active
+          result = (reference.get - Things::List.trash.todos.get).collect do |todo| 
+            Things::Todo.build(todo) if todo.completion_date.get.to_s == 'missing_value'
+          end
+          result.compact
+        end
+    
+
+
+      end
+      
+    end
+  end
+end

data/lib/things/list.rb

@@ -0,0 +1,18 @@
+module Things
+  class List
+    DEFAULTS = [:inbox, :today, :next, :scheduled, :someday, :projects, :logbook, :trash]
+      class << self
+        def all
+          Things::App.instance.lists
+        end
+
+        DEFAULTS.each do |list|
+          class_eval <<-"eval"
+            def #{list}
+              all['#{list.to_s.capitalize}']
+            end
+          eval
+        end
+      end
+  end
+end

data/lib/things/project.rb

@@ -0,0 +1,12 @@
+module Things
+  # Things::Todo
+  class Project < Reference::Record
+    
+    properties :name
+    # identifier is required for creation
+    identifier :project
+    # collection is used for findings
+    collection :projects
+   
+  end
+end

data/lib/things/reference/base.rb

@@ -0,0 +1,14 @@
+module Things
+  # Things::Reference
+  module Reference
+
+    class Base
+      
+      attr_accessor :reference
+      
+      
+    end
+    
+  end
+  
+end

data/lib/things/reference/inheritance.rb

@@ -0,0 +1,29 @@
+module Things
+  # Things::Reference
+  module Reference
+    
+    module Inheritance
+      
+      def inheritable_attributes(*args)
+        @inheritable_attributes ||= [:inheritable_attributes]
+        @inheritable_attributes += args
+        args.each do |arg|
+          class_eval %(
+            class << self; attr_accessor :#{arg} end
+          )
+        end
+        @inheritable_attributes
+      end
+
+      def inherited(subclass)
+        @inheritable_attributes.each do |inheritable_attribute|
+          instance_var = "@#{inheritable_attribute}"
+          subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
+        end
+      end
+      
+    end
+ 
+  end
+
+end

data/lib/things/reference/record.rb

@@ -0,0 +1,121 @@
+module Things
+  # Things::Reference
+  module Reference
+
+    class Record < Base
+
+      extend Inheritance
+  
+      inheritable_attributes :_properties, :identifier, :collection
+
+      def self.identifier(name = nil)
+        name ? @identifier = name : @identifier
+      end
+
+      def self.collection(name = nil)
+        name ? @collection = name : @collection
+      end
+
+      def self.properties(*args)
+        @_properties = [] if !@_properties
+        if args
+          @_properties += args
+          @_properties.each do |property|
+            attr_writer(property) if !instance_methods.include?(property.to_s)
+            if !instance_methods.include?(property.to_s )
+              class_eval <<-"eval"
+                def #{property}
+                  if !@#{property}
+                    fetched = @reference.#{property}.get rescue nil
+                    @#{property} = fetched if fetched and fetched != :missing_value
+                  else
+                    @#{property}
+                  end
+                end
+              eval
+            end
+          end
+        end
+      end
+      # :id_ is always present
+      properties :id_          
+
+      def initialize(props = {})
+        props.each_pair do |property, value|
+          self.send("#{property}=", value)
+        end
+      end
+
+      # Returns whether the instance if new or has already been saved
+      def new?
+        id_.nil?  
+      end
+
+      # Save a Todo
+      #
+      # If a todo is new, it will be created. If not, it will be updated
+      def save
+        if new?
+          properties = {}
+          (self.class.properties - [:id_]).each do |property|
+            properties[property] = self.send(property) if self.send(property)
+          end
+          self.reference = Things::App.instance.make(:new => self.class.identifier, :with_properties => properties)
+        else
+          (self.class.properties - [:id_]).each do |property|
+            self.reference.send(property).set(self.send(property)) if self.send(property)
+          end
+        end
+        self
+      end
+
+      # Delete a object
+      #
+      # This places the object in the trash
+      def delete
+        Things::App.instance.delete(self.reference) rescue false
+      end
+
+      # create a new object based on that supplied properties and saves it
+      def self.create(props)
+        new(props).save
+      end
+
+      # build a new instance and link it to the supplied reference
+      #
+      # Returns a object associated with a reference
+      def self.build(reference)
+        todo = self.new
+        todo.reference = reference
+        todo
+      end
+
+      # find a todo by a name or id
+      #
+      # Returns a Things::Todo object associated with a reference
+      def self.find(name_or_id)
+        find_by_name(name_or_id) || find_by_id(name_or_id)
+      end
+
+      # find a todo by a name
+      #
+      # Returns a Things::Todo object associated with a reference
+      def self.find_by_name(name)
+        reference = Things::App.instance.send(self.collection)[name].get rescue nil
+        build(reference) if reference
+      end
+
+      # find a todo by a id
+      # Returns a Things::Todo object associated with a reference
+      def self.find_by_id(id)
+        finder = Appscript.its.id_.eq(id)
+        reference = Things::App.instance.send(self.collection)[finder].get rescue nil
+        reference = reference.first if reference.is_a?(Array)
+        build(reference) if reference
+      end
+
+    end
+
+  end
+
+end

data/lib/things/status.rb

@@ -0,0 +1,8 @@
+module Things
+  module Status
+    # To do is open.
+    OPEN	    =	:open	 	 
+    # To do has been completed.
+    COMPLETED	=	:completed	 	 
+  end
+end

data/lib/things/tag.rb

@@ -0,0 +1,12 @@
+module Things
+  # Things::Todo
+  class Tag < Reference::Record
+    
+    properties :name
+    # identifier is required for creation
+    identifier :tag
+    # collection is used for findings
+    collection :tags
+   
+  end
+end

data/lib/things/todo.rb

@@ -0,0 +1,18 @@
+module Things
+  # Things::Todo
+  class Todo < Reference::Record
+    
+    properties :name, :notes, :completion_date
+    # identifier is required for creation
+    identifier :to_do
+    # collection is used for findings
+    collection :todos
+   
+    # Move a todo to a different list <br />
+    # Moving to Trash will delete the todo
+    def move(list)
+      Things::App.instance.move(reference, { :to => list })
+    end
+    
+  end
+end

data/lib/things.rb

@@ -0,0 +1,28 @@
+require 'appscript'
+require "#{File.dirname(__FILE__)}/appscript/reference"
+#
+# Things is a client for the Mac OS X GTD app Things
+#
+# It uses AppleScript to gain access to the Things scripting API
+#
+module Things
+  autoload :App, File.dirname(__FILE__) + '/things/app'
+  autoload :Todo, File.dirname(__FILE__) + '/things/todo'
+  autoload :List, File.dirname(__FILE__) + '/things/list'
+  autoload :Status, File.dirname(__FILE__) + '/things/status'
+  autoload :Area, File.dirname(__FILE__) + '/things/area'
+  autoload :Project, File.dirname(__FILE__) + '/things/project'
+  autoload :Tag, File.dirname(__FILE__) + '/things/tag'
+  
+  module Collections
+    autoload :Todo, File.dirname(__FILE__) + '/things/collections/todo'
+  end
+  
+  module Reference
+    autoload :Base, File.dirname(__FILE__) + '/things/reference/base'
+    autoload :Inheritance, File.dirname(__FILE__) + '/things/reference/inheritance'
+    autoload :Record, File.dirname(__FILE__) + '/things/reference/record'
+  end
+  
+end
+

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'rubygems'
+require 'things'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

data/spec/things/app_spec.rb

@@ -0,0 +1,43 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe "Things::App" do
+
+  describe '#instance' do
+    
+    it 'should return an instance of the Things app' do
+      Things::App.instance.class.should == Appscript::Application
+    end
+    
+  end
+  
+  describe '#activate' do
+  
+    it 'should start the app if it is not running' do
+      
+      # close if running
+      #Things::App.instance!.quit if `ps x | grep Things`.include?('Things.app')
+      #{}`ps x | grep Things`.should_not match('Things.app')
+      #Things::App.instance!.activate
+      #{}`ps x | grep Things`.should match('Things.app')
+    end
+    
+  end
+  
+  describe '#lists' do
+    
+    it "should return Things::Collections::List" do
+      Things::App.lists.should == Things::List
+    end
+
+  end
+  
+  describe '#todos' do
+    
+    it "should return Things::Collections::Todo" do
+      Things::App.todos.should == Things::Collections::Todo
+    end
+
+  end
+
+  
+end