App::Toodledo - Interacting with the Toodledo task management service.

    use App::Toodledo;

    my $todo = App::Toodledo->new();
    $todo->login_from_rc;
    my %search_opts = ( notcomp => 1, before => time );  # Already expired
    $todo->foreach_task( \&per_task, \%search_opts );

    sub per_task {
        my ($self, $task) = @_;
        print $task->title, ": due on " . localtime( $task->duedate );
    }

Toodledo (http://www.toodledo.com/) is a web-based capability for managing to-do lists along Getting Things Done (GTD) lines. This module provides a Perl-based access to its API.

What do you need the API for? Doesn't the web interface do everything you want? Not always. See the examples included with this distribution. For instance, Toodledo has only one level of notification and it's either on or off. With the API you can customize the heck out of notification.

This is a very basic, preliminary Toodledo module. I wrote it to do the few things I wanted out of an API and when I feel a need for some additional capability, I'll add it. In the mean time, if there's something you want it to do, feel free to submit a patch. Or, heck, if you're sufficiently motivated, I'll let you take over the whole thing.

Construct a new Toodledo handle. This call does not contact the service.

"Login" to Toodledo. The userid is the long string on your Toodledo account's "Settings" page.

Same as login, only obtains the userid and password from a YAML file in your home directory called .toodledorc. The attributes userid and password must be set, like this:

  ---
  userid: td94d4b473d171f
  password: secret

Call an arbitrary Toodledo API function $function. Use this for any function not wrapped in a more convenient method below. Arguments are supplied via a hashref. Examples:

  $context = $todo->call_func( 'getAccountInfo'  );
  $context = $todo->call_func( getUserid => { email => $email, pass => $pass })

The result is an XML::LibXML::Element. See the CPAN documentation for that class and its superclass, XML::LibXML::Node. The findnodes and getChildrenByTagName methods are particularly useful.

Run the subroutine callback for every task that matches the search criteria in %search_opts. The callback will be called with two arguments: the $todo object and a App::Toodledo::Task object. The search options are as described in the Toodledo API documentation for the getTasks call, with the following modifications:

• The title and tag arguments will be encoded for you;
• The before, after, startbefore, modbefore, compbefore, startafter, modafter, and compafter arguments should be integer epoch times such as returned by time. They will be converted to the required format for you.

Return a list of App::Toodledo::Folder objects, ordered by their order attribute.

The argument should be a new App::Toodledo::Task object to be created. The result is the id of the new task.

Add a context with the given title.

Add a folder with the given title. $private if supplied must be either 0 (default) or 1, which signifies that the folder is to be private. If the first argument is an App::Toodledo::Folder object, the title and private attributes will be taken from it.

Add a goal with the given title. The $level if supplied should be 0 (default), 1, or 2, signifying goal span (0=lifetime, 1=long-term, 2=short-term). If $contributes is supplied, it should be the id of a higher-level goal that this goal contributes to.

Delete the task with the given $id. The result is a boolean for the success of the operation.

Delete the goal with the given $id. The result is a boolean for the success of the operation.

Delete the context with the given $id. The result is a boolean for the success of the operation.

Delete the folder with the given $id. The result is a boolean for the success of the operation.

Any API call may croak if it returns an error. A common cause of this would be making too many API calls within an hour. The limit seems to be reached much faster than you would think based on Toodledo's claims for what that limit is. Just wait an hour if you hit this limit.

Setting the environment variable APP_TOODLEDO_DEBUG will cause debugging-type information to be output to STDERR.

Peter J. Scott, <cpan at psdt.com>

Please report any bugs or feature requests to bug-app-toodledo at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Toodledo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Help improve App::Toodledo! Some low-hanging fruit you might want to submit a patch for:

• Use the new unix parameter to getTasks to simplify date fetching.
• Implement the getContexts call to an App::Toodledo::Context object.
• Ditto for goals.
• Implement the editTask and editFolder calls.
• Implement task caching to avoid hitting API limits.

You can find documentation for this module with the perldoc command:

    perldoc App::Toodledo

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Toodledo

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-Toodledo

* CPAN Ratings

http://cpanratings.perl.org/d/App-Toodledo

* Search CPAN

http://search.cpan.org/dist/App-Toodledo/

Toodledo API documentation: http://www.toodledo.com/info/api_doc.php.

Getting Things Done, David Allen, ISBN 978-0142000281.

Copyright 2009 Peter J. Scott, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.