NAME

WebService::HabitRPG - Perl interface to the HabitRPG API

VERSION

version 0.08

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

new

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

Creates a new WebService::HabitRPG object. The api_token and user_id parameters are mandatory. You may also pass your own WWW::Mechanize compatible user-agent with agent, and should you need it your own HabitRPG API base URL with api_base (useful for testing, or if you're running your own server).

By default, the official API base of https://habitrpg.com/api/v1 is used.

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.

Tasks which are marked as completed are not considered by this search. This behaviour may change in future, where parameters may be passed to indicate what should happen with regards to completed tasks.

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/pjf/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.

cpanm WebService::HabitRPG

perl -MCPAN -e shell
install WebService::HabitRPG