The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-Toodledo-0.04
River stage zero No dependents
1 ++
/ App::Toodledo

NAME

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

SYNOPSIS

    use App::Toodledo;

    my $todo = App::Toodledo->new();
    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. 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, \%ssearch_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.

$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, [$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.

$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:

  • Implement the getFolders call to a App::Toodledo::Folder object.

  • Ditto for contexts and 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.