/ 
App-Toodledo-0.06
River stage zero No dependents
/ App::Toodledo

NAME

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

SYNOPSIS

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 );
}

DESCRIPTION

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.

METHODS

$todo = App::Toodledo->new;

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

$todo->login( $userid, $password )

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

$todo->login_from_rc

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

$todo->call_func( $function, $argref )

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.

$todo->foreach_task( \&callback, [ \%search_opts ] )

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.

@folders = $todo->get_folders

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

$id = $todo->add_task( $task )

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

$id = $todo->add_context( $title )

Add a context with the given title.

$id = $todo->add_folder( $title_or_folder, [ $private ] )

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.

$id = $todo->add_goal( $title, [ $level, [ $contributes ] ] )

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.

$success = $todo->delete_task( $id )

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

$success = $todo->delete_goal( $id )

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

$success = $todo->delete_context( $id )

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

$success = $todo->delete_folder( $id )

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

ERRORS

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.

ENVIRONMENT

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

AUTHOR

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

BUGS

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.

TODO

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.

SUPPORT

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

perldoc App::Toodledo

You can also look for information at:

SEE ALSO

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

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

COPYRIGHT & LICENSE

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.