/ 
App-Toodledo-2.01
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( user_id => 'rudolph', app_id => 'MyAppID' );
$todo->login( password => 'secret', app_token => 'api2729372' )

$todo = App::Toodledo->new( app_id => 'MyAppID' );
$todo->login_from_rc;

my @folders = $todo->get( 'folders' );
my @tasks   = $todo->get_tasks_with_cache;
my $time = time;

# Tasks due in next day
my @wanted  = $todo->select( \@tasks,
              "duedate < $time + $ONEDAY && duedate  > $time" );
my @privates = $todo->select( \@folders, "private > 0" );

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.

THIS MODULE IS NOT BACKWARDS COMPATIBLE WITH ANY PREVIOUS VERSIONS.

This version is a minimal port to version 2 of the Toodledo API. It is not at all backwards compatible with version 0.07 or earlier of this module. Toodledo now frowns upon using version 1 of the API; not using an application token makes it almost impossible to get anything useful done.

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( %option );

Construct a new Toodledo handle. No connection to the service is made. Options are:

app_id

Application ID. See the Toodledo API documentation for details.

app_token

Application token.

user_id

User ID.

The app_id entry in the option hash is mandatory. The others may be left out and supplied elsewhere.

$todo->get_session_token( user_id => $user_id, app_token => $app_token )

This call creates a session token and caches it in a file in your home directory called .toodledo_token, unless that file already exists and contains a token younger than three hours, in which case that one will be used. The published lifespan of a Toodledo token is four hours. The $app_token must be the token given to you by the Toodledo site when you registered the application that this code is running. The user_id is the long string on your Toodledo account's "Settings" page.

If the user_id is not supplied here it must have been given in the constructor. Ditto for the app_token.

$todo->get_session_token_from_rc( [ $user_id ] )

Same as get_session_token, only it obtains the arguments from a YAML file in your home directory called .toodledorc. See the FILES section below for instructions on how to format and populate that file. If no user_id is specified it will look for and use a default_user_id in the .toodledorc file.

$todo->login( %option )

The %option hash must include the entries for password and app_token. Optionally it can include user_id; if not specified here, it must have been sent in the constructor.

$todo->login_from_rc( [$user_id] )

Optionally specify the user_id, else the same rules apply as for get_session_token_from_rc. The password will be taken from the one associated with that user_id in the .toodledorc file.

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

Low-level Toodledo API access. You should not need to use this unless you're extending the App::Toodledo::Account functionality. (Please contribute patches.) $argref is a hashref of arguments to the call. Refer to the Toodledo API documentation for formatting and encoding.

$app_token = $todo->app_token_of( $app_id )

Convenience function for returning the application token of a given application id by reading it from the .toodledorc file.

$password = $todo->password_of( $user_id )

Convenience function for returning the password for a given user_id by reading it from the .toodledorc file.

$user_id = $todo->default_user_id

Convenience function for returning the default user_id by reading it from the .toodledorc file.

$token = $todo->new_session_token( $app_token )

Return the temporary session token given the application token. The user_id and app_id are read from the object.

@objects = $todo->get( $type )

Fetch and return a list of some kind of thing, the choices being the following strings:

tasks
folders
goals
contexts
notebooks

The returned list will be of the corresponding App::Toodledo::whatever objects. There are optional arguments for tasks:

@tasks = $todo->get( tasks => %param )

The optional named parameters correspond to the parameters that can be specified in the Toodledo tasks/get API call: modbefore, modafter, comp, start, num, fields. Note that this call will not cache the tasks returned, so it is safe to play with these parameters. This method will default fields to all available fields. It does not change comp, which the Toodledo API defaults to all uncompleted tasks only.

@tasks = $todo->get_tasks_with_cache( %param )

Same as get( tasks => %param ), except that the tasks are fetched from the cache file ~/.toodledo_task_cache if it is still valid (Toodledo reports no changes since cache update). If there is no cache file, it is populated after the tasks are fetched from Toodledo.

$id = $todo->add( $object )

The argument should be a new App::Toodledo::whatever object to be created. The result is the id of the new object. Any of the standard object types can be added.

$todo->delete( $object )

Delete the given object from Toodledo. The id attribute of the object must be correctly set. No other attributes will be used.

$todo->edit( $object )

The given object will be updated in Toodledo to match the one passed.

@objects = $todo->select( \@objects, $expr );

Select just the objects you need from the given array, based upon the expression. Any attribute of the givem objects specified in the exprssion will br turned into an object accessor for that attribute and the resulting expression must be syntactically correct. Any Perl code can be used; it will be passed through eval. Examples:

tag eq "garden" && status > 3

Must have the 'garden' tag (and only that tag) amd a status higher than the 'Planning' status. (Only makes sense for a task list.)

title =~ /deliver/i && comp == 1

Title must match regex and task must be completed.

The type of object is determined from the first one in the arrayref.

$todo->readable( $object, $attribute )

Currently just looks to see if the given $attribute of $object is a date and if so, returns the preferred_date_formst string from App::Toodledo::Util instead of the stored epoch second count.

ERRORS

Any API call may croak if it returns an error.

FILES

~/.toodledo_token

This file is in YAML format and caches the session token for one or more application ids. You should not need to edit it.

~/.toodledorc

This file is in YAML format and is where you keep information to save having to enter it in login calls. It is not written by App::Toodledo. It is of the following format:

---
app_tokens:
  <app_id>: <app_token>
default_user_id: <user_id>
passwords:
  <user_id>: <password>

The app_id line may be repeated for as many application ids that you have. It supplies the application token corresponding to each app_id. Since the app_id is a mnemonic string like 'cpantest' and the app_token is a hex identifier supplied by Toodledo like 'api4e49ce90e5c31', this saves the trouble of copying arcane strings into every program. The password line may be repeated for as many user ids that you want to manage. The default_user_id is optional and will be used if none is specified in a login call.

~/.toodledo_task_cache

This file is in YAML format and is used by App::Toodledo to store a cache of tasks. You should not need to edit it. If App::Toodledo is using this cache and you believe it to be invalid, delete this file.

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.

Realistically, I am not likely to have the time to respond to any bug reports that don't impact code I use personally unless they include complete fixes in the form of a patch file. New functionality should include documentation and test patches.

TODO

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

  • Improve task caching to not be all-or-nothing. Use SQLite and check only for which tasks need to be added or removed.

  • Bulk addition of tasks.

  • Flesh out the App::Toodledo::Account class with the methods for querying an account.

  • Addition of enumerated type for statuses.

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://api.toodledo.com/2/account/.

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

COPYRIGHT & LICENSE

Copyright 2009 - 2011 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.