= 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.