NAME
    WWW::PivotalTracker - Functional interface to Pivotal Tracker
    http://www.pivotaltracker.com/

INSTALLATION
    To install this module, run the following commands:

        perl Makefile.PL
        make
        make test
        make install

VERSION
    0.17

SYNOPSIS
    This module provides simple methods to interact with the Pivotal Tracker
    API.

        use WWW::PivotalTracker qw/
            add_note
            add_story
            all_stories
            delete_story
            project_details
            show_story
            stories_for_filter
            update_story
        /;

        my $details = project_details("API Token", "Project ID");

        ...

EXPORT
    Nothing is exported by default. See FUNCTIONS for the exportable
    functions.

FUNCTIONS
  project_details

    Returns a hashref with the project's name, point scale, number of weeks
    per iteration, and which day of the week the iterations start on.

        my $proj = project_details($token, $project_id);

        print "Project name: $proj->{'name'}\n"
            . "Point scale: $proj->{'point_scale'}\n"
            . "Weeks per Iteration: $proj->{'iteration_weeks'}\n"
            . "Iteration start day: $proj->{'start_day'}\n";

  show_story

    Return a hashref with the details of a specific story.

        my $story = show_story($token, $project_id, $story_id);

        # If the story doesn't have a particular attribute, then the hash key's
        # value will be undef. (Ex: description, deadline, labels, notes)
        $story->{'id'}
        $story->{'name'}
        $story->{'description'} # Possibly multi-line string.
        $story->{'estimate'}    # Possible values are results in point_scale
                                # returned by project_details, and -1 if not
                                # estimated, yet.
        $story->{'current_state'}
        $story->{'created_at'}
        $story->{'deadline'}    # undef, unless story type is 'release'
        $story->{'story_type'}  # 'feature', 'bug', 'chore', or 'release'
        $story->{'labels'}      # [ 'foo', 'bar', 'baz', ]
        $story->{'notes'}       # [
                                #     { id => 1, author => 'alice', date => 'Dec 20, 2008', text => 'comment', },
                                #     { id => 2, author => 'bob', date => 'Dec 20, 2008', text => 'commenting on your comment', },
                                # ]
        $story->{'url'}

  all_stories

    Return an arrayref of story hashrefs (see show_story for story hashref
    details).

  add_story

    Create a new story, given a hashref of the story's details, and return a
    story hashref of the same format as show_story.

    Possible story details hash keys are: created_at current_state deadline
    description estimate labels name requested_by story_type

    The bare minimum to create a new story are "requested_by", and "name".
    New stories will default to be "feature" stories, unless a "story_type"
    ("feature", "bug", "chore", or "release") is specified.

    To add labels, include a comma separated list as the "labels" value.

        my $story_details = {
            requested_by => "Bob",
            name         => "Users can request stories.",
            labels       => "label 1, label 2, another label",
        };

        my $story_details_2 = {
            requested_by => "Alice",
            name         => "Release #1",
            deadline     => "Dec 31, 2008",
        };

        my $story = add_story($token, $project_id, $story_details);
        my $story_2 = add_story($token, $project_id, $story_details_2);

  delete_story

    Delete an existing story.

        my $result = delete_story($token, $project_id, $story_id);

        print $result->{'success'};
        print $result->{'name'};

  stories_for_filter

    Find all stories given search parameters.

        my $result = stories_for_filter($token, $project_id, $search_filter);

        my @stories;
        if($result->{'success'} eq 'true') {
            print $result->{'message'} . "\n";

            @stories = @{$result->{'stories'}};
        }

    In the example above `@stories' will be an array of story hashrefs. See
    the description of `show_story' for the details of the hashrefs.

    Any multi-word terms in the search filter must be enclosed by double
    quotes. (See http://www.pivotaltracker.com/help: Search)

        Example:
            requester:"Jacob Helwig"
            owner:"Jacob Helwig"
            mywork:"Jacob Helwig"
            state:unstarted
            type:Feature

  update_story

    Update aspects of a given story.

        my $result = update_story($token, $project_id, $story_id, { current_state => 'started' });

    See the description of `show_story' for the details of `$result'.

  add_note

    Add a note to an existing story.

        my $result = add_comment($token, $project_id, $story_id, $note);

    See the description of `show_story' for the details of `$result'.

AUTHOR
    Jacob Helwig, `<jhelwig at cpan.org>'

BUGS
    Please report any bugs or feature requests to `bug-www-pivotaltracker at
    rt.cpan.org', or through the web interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-PivotalTracker. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc WWW::PivotalTracker

    You can also look for information at:

    * RT: CPAN's request tracker
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-PivotalTracker

    * AnnoCPAN: Annotated CPAN documentation
        http://annocpan.org/dist/WWW-PivotalTracker

    * CPAN Ratings
        http://cpanratings.perl.org/d/WWW-PivotalTracker

    * Search CPAN
        http://search.cpan.org/dist/WWW-PivotalTracker/

    * Source code
        git:

    * Webpage
        http://github.com/jhelwig/www-pivotaltracker

ACKNOWLEDGEMENTS
    Chris Hellmuth

COPYRIGHT & LICENSE
    Copyright 2008-2010 Jacob Helwig.

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