/ 
WebService-HabitRPG-0.02
River stage one • 1 direct dependent • 1 total dependent
/ WebService::HabitRPG

NAME

WebService::HabitRPG - Perl interface to the HabitRPG API

VERSION

version 0.02

SYNOPSIS

use WebService::HabitRPG;

# The API Token and User ID are obained through the
# Setting -> API link on http://habitrpg.com/

my $hrpg = WebService::HabitRPG->new(
    api_token => 'your-token-goes-here',
    user_id   => 'your-user-id-goes-here',
);

# Get everyting about the user
my $user = $hrpg->user;

# Get all tasks.
my $tasks = $hrpg->tasks;

# Get all tasks of a particular type (eg: 'daily')
my $daily = $hrpg->tasks('daily');

# Increment/decrement a task
$hrpg->up($task_id);
$hrpg->down($task_id);

# Make a new task
$hrpg->new_task(
    type => 'daily',
    text => 'floss teeth',
    up   => 1,
    down => 0,
);

DESCRIPTION

Interface to API provided by HabitRPG.

At the time of release, the HabitRPG API is still under construction. This module may change as a result.

Note that when data structures are returned, they are almost always straight conversions from the JSON returned by the HabitRPG API.

METHODS

user

my $user = $hrpg->user();

Returns everything from the /user route in the HabitRPG API. This is practically everything about the user, their tasks, scores, and other information.

The Perl data structure that is returned is a straight conversion from the JSON provided by the HabitRPG API.

tasks

my $tasks  = $hrpg->tasks();            # All tasks
my $habits = $hrpg->tasks('habit');     # Only habits

Return a reference to an array of tasks. With no arguments, all tasks (habits, dailies, todos and rewards) are returned. With an argument, only tasks of the given type are returned. The argument must be one of habit, daily, todo or reward.

The data returned for each task is defined by the HabitRPG API, but at the time of writing is:

{
    text    => 'floss', # Text shown in web interface. Task name.
    type    => 'habit', # One of: habit, todo, daily, reward
    id      => '...',   # Internal task ID. Extensively used by API.
    value   => 0,       # Either cost in GP, or how well one is doing
    notes   => '',      # Extended, human-readable note field
    repeat  => {...},   # Daily tasks only. 
    up      => 1,       # Can this task be incremented?
    down    => 0,       # Can this task be decremented?
    history => [...],   # History data for this task.
}

Not all tasks will have all fields. Using the hrpg command-line tool with hrpg dump tasks is a convenient way to see the data structures returned by this method.

get_task

my $task = $hrpg->get_task('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e');

Given a task ID, returns information on that task in the same format at "tasks" above.

new_task

$hrpg->new_task(
    type      => 'daily',           # Required
    text      => 'floss teeth',     # Required
    up        => 1,                 # Suggested, defaults true
    down      => 0,                 # Suggested, defaults true
    value     => 0,
    note      => "Floss every tooth for great justice",
    completed => 0,
);

Creates a new task. Only the type and text arguments are required, all other tasks are optional. The up and down options default to true (ie, tasks can be both incremented and decremented).

The type parameter must be one of: habit, daily, todo or reward.

Returns a task data structure of the task created, identical to the "tasks" method above.

Creating tasks that can be neither incremented nor decremented is of dubious usefulness.

updown

$hrpg->updown('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e', 'up'  );
$hrpg->updown('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e', 'down');

Moves the habit in the direction specified. Returns a data structure of character status:

{
    exp   => 11,
    gp    => 15.5,
    hp    => 50,
    lv    => 2,
    delta => 1,
}

up

$hrpg->up($task);

Convenience method. Equivalent to $hrpg-updown($task, 'up')>;

down

$hrpg->down($task);

Convenience method. Equivalent to $hrpg-updown($task, 'down')>;

search_tasks

my @tasks = $hrpg->search_tasks($search_term);

# Eg:
my @tasks = $hrpg->search_tasks('floss');

Search for tasks which match the provided search term. If the search term exactly matches a task ID, then the task ID is returned. Otherwise, returns a list of tasks which contain the search term in their names (the text field returned by the API). This list is in the same format as the as the "tasks" method call.

The search term is treated in a literal, case-insensitive fashion.

This is useful for providing a human-friendly way to refer to tasks. For example:

# Search for a user-provided term
my @tasks = $hrpg->search_tasks($term);

# Increment task if found
if (@tasks == 1) {
    $hrpg->up($tasks[0]{id});
}
else {
    say "Too few or too many tasks found.";
}

BUGS

I'm sure there are plenty! Please view and/or record them at https://github.com/pfenwick/WebService-HabitRPG/issues .

SEE ALSO

The HabitRPG API spec.

The hrpg command-line client. It's freakin' awesome.

AUTHOR

Paul Fenwick <pjf@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Paul Fenwick.

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