The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Toodledo-2.19
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( 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" );

    $todo->foreach( \@tasks, \&manipulate );
    $todo->edit( @tasks );

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 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. Or suppose you want to find tasks where the due date has erroneously been set to before the start date. Toodledo lets you do this and the online search function can't find them. But with App::Toodledo it's as simple as:

  say $_->title for $todo->select( \@tasks => q{duedate && startdate > duedate} )

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.

This module uses MooseX::Method::Signatures to perform argument validation. If you violate the type checking you will quite probably get upwards of a hundred lines of error messages. That's the way it goes.

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. This fetches all tasks, including completed ones, so can take a while.

$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. Note: this method is overridden in App::Toodledo::Task.

$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. Note: this method is overridden in App::Toodledo::Task.

$todo->edit( $object )

The given object will be updated in Toodledo to match the one passed. Note: this method is overridden in App::Toodledo::Task. When the object is a task, the signature is:

$todo->edit( $task, [@tasks] )

All of the tasks will be edited. You are responsible for ensuring that you do not exceed Toodledo limits on the number of tasks passed (currently 50).

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

Select just the objects you need from the given array, based upon the expression. Any attribute of the given 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 greater than the index for the status value 'Planning'. (Only makes sense for a task list.) To access (or change) the status as a string, use status_str.

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.

@objects = $todo->grep_objects( \@objects, $coderef )

Run $coderef for each object in the list. Called by the select method but can be used by the user. Ones for which the $coderef returns true will be passed through to the result.

$todo->foreach( \@objects, $coderef, [@args] )

Run the coderef on each object in the arrayref. $coderef will be called with the object as the first argument and any @args as the rest.

$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. If the date is null, returns an empty string (rather than the Toodledo display of "no date").

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

App::Toodledo uses log4perl for error logging and debug messages. By default they will be outputted to STDOUT, and STDERR. A log4perl can be specified in the users application, if one is not set App::Toodledo will use Log::Log4perl::easy_init($ERROR); Setting the environment variable APP_TOODLEDO_DEBUG will cause debugging-type information to be output to log4perl logger. If a logger hasn't been set App::Toodledo will use Log::Log4perl::easy_init($DEBUG);

AUTHOR

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

CONTRIBUTORS

Thanks to Edward Ash for the Log4Perl integration!

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. (Bulk editing is enabled but currently undocumented - see App::Toodledo::Task::edit.)

  • Separate task cache age testing from loading the whole cache, takes too long.

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

  • Handling of the *date/*time attributes needs to be coordinated so it is useful.

EXAMPLES

To find all tasks with the 'Home' context and add a 'DIY' tag if not there:

  use App::Toodledo;
  my $todo = App::Toodledo->new( app_id => 'myregisteredappid' );
  $todo->login_from_rc;
  my @all_tasks = $todo->get_tasks_from_cache;
  for my $task ( $todo->select( \@tasks, 'context eq "Home" ) )
  {
    next if $task->has_tag( 'DIY' );
    $task->tag( $task->tag . ',DIY' );
    $todo->edit( $task );
  }

Feel free to contribute more examples as short and complete as that one via email!

OBJECT MODEL

App::Toodledo is Moose-based. Each of the object types (task, folder, context, goal, location, notebook, and the account singleton) is represented via an object class App::Toodledo::Task, App::Toodledo::Folder, etc. Each one of those classes contains each Toodledo attribute as a writable attribute, e.g. $task->context( 12345 ). Additional methods can be added (e.g., 'tags' is a simple convenience method for App::Toodledo::Task) in each of those classes; the Toodledo attributes are handled by being delegated to an internal object (e.g., App::Toodledo::TaskInternal) which implements a Role (e.g., App::Toodledo::TaskRole) that contains precisely and only the list of Toodledo attributes. (See App::Toodledo::Task for details on the context_name method for accessing contexts via their names instead of IDs.)

Therefore when Toodledo changes its attribute lists, change only the corresponding Role class and everything will continue working. You can add methods to the object class (e.g. App::Toodledo::Task) without the class being cluttered with native Toodledo attributes. You can override a Toodledo attribute if you ensure that the base functionality still works; just call the method in the delegated object directly. (This delegate is named 'object'.)

DISCLAIMER

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM 'AS IS' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

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 - 2012 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.