= Ruby Client for Remember The Milk

Author::   Dave Copeland (mailto:davetron5000 at g mail dot com)
Copyright:: Copyright (c) 2009 by Dave Copeland
License:: Distributes under the Apache License, see LICENSE.txt in the source distro

== Install

Note that the most up-to-date version of the gem is hosted at [http://www.gemcutter.org], so you'll need a one-time setup
if you aren't already using Gemcutter as your primary source for gems.

    # Only if you aren't using gemcutter yet
    sudo gem install gemcutter
    sudo gem tumble

    # Once Gemcutter is setup
    sudo gem install moocow

== Overview

This is a very lightweight and easy-to-use client for [http://www.rememberthemilk.com]

    require 'moocow'

    rtm = RTM::RTM.new(RTM::Endpoint.new(your_api_key,your_secret))
    rtm.token = user_token
    response = rtm.tasks.getList
    response.tasks.list.as_array.each do |list|
      # this is an RTM list of taskseries
    end

=== Authorization

Authorization is a bit tricky, but you only need to do it one time.  This example shows
command line/desktop usage

    rtm = RTM.new(Endpoint.new(your_api_key,your_secret))
    auth = rtm.auth
    url = auth.url
    frob = auth.frob
    # Send user to this URL
    # They will authorize your app's api_key via the RTM website.  
    # store the frob somewhere, you will need it
    #
    # When they return...
    auth.frob=frob
    rtm.token=auth.get_token
    # store the token for all time
    
    rtm.tasks.getList
    rtm.groups.delete
    rtm.tasks.notes.add

And so forth.  Basically, you can call the RTM methods as if they were real methods.

=== Responses

As shown above, you can simply navigate the XML returned by method names.  This uses Hash.method_missing and can be dicey, so you can also navigate a bit safer via

    response = rtm.tasks.getList
    response['tasks']['list'].as_array.each do |list|
      # this is an RTM list of taskseries
    end

Note that for any element that you want to treat as a list, you must call as_array on it, to ensure that it gets turned into a list.  The underlying HTTParty code doesn't know if an XML element is supposed to be a list or just a singular.

<i>Note that you can use Ruby-style conventions instead of camel-case, e.g. <tt>rtm.tasks.get_list</tt></i>

=== Timelines

Many methods require timelines; this is the way that RTM provides for undo-type features.  If you don't really care about this, or want it done for you, you can specify auto timeline creation:


    rtm.auto_timeline=true
    rtm.tasks.add(:name => 'My new task')
    timeline = rtm.last_timeline

This will create a timeline for you, and use it to create the task.  The list of methods that <b>do not</b> require timelines is used to determine if this is done, and is based on the RTM documentation at the time of this writing.

== Basic Command Line

To verify and play with the RTM API, there is a command-line tool called <tt>rtm</tt>.  It takes the following commands:

[any] executes any RTM method
[auth] Prints out the auth URL to authorize your api key/ruby client. Do not do this after getting a token
[chktoken] Checks that your token is valid
[help] Shows list of commands or help for one command
[ls] Lists incomplete tasks
[token] Gets your token; do this only once and put it in your api.yaml file

The easiest way to get started is to get your API Key and Secret from RTM and then:

   rtm ls

This will init your api.yaml file

   rtm auth

Go to this URL and authorize your API Key.  Save the frob that is printed out

    rtm token <<frob>>

This will authorize your app and print out your token.  Edit <tt>api.yaml</tt> and add your token.

    :token: <<your token>>

To verify:

    rtm ls

This should list your incomplete tasks if all is well.

    rtm any contacts.getList

Will print out a hashdump of what RTM returns for this method.
   
== Links

* http://github.com/davetron5000/rtm - Source code
* http://davetron5000.github.com/rtm - Rubydoc
* http://www.rememberthemilk.com/services/api/methods/ - RTM API documentation
