WebService::Google::Reader(3)

NAME
WebService::Google::Reader - Perl interface to Google Reader

SYNOPSIS
    use WebService::Google::Reader;

    my $reader = WebService::Google::Reader->new(
        username => $user,
        password => $pass,
    );

    my $feed = $reader->unread(count => 100);
    my @entries = $feed->entries;

    # Fetch past entries.
    while ($reader->more($feed)) {
        my @entries = $feed->entries;
    }

DESCRIPTION
The "WebService::Google::Reader" module provides an interface to the Google Reader service through the unofficial (as-yet unpublished) API.

METHODS

$reader = WebService::Google::Reader->new
    Creates a new WebService::Google::Reader object. The following named parameters are accepted:

    username and password
        Required for accessing any personalized or account-related functionality (reading-list, editing, etc.).

    https / secure
        Use https scheme for all requests, even when not required.

    ua  An optional useragent object.

    debug
        Enable debugging. Default: 0. This will dump the headers and content for both requests and responses.

    compress
        Disable compression. Default: 1. This is useful when debugging is enabled and you want to read the response content.

$error = $reader->error
    Returns the error string, if any.

$response = $reader->response
    Returns an HTTP::Response object for the last submitted request. Can be used to determine the details of an error.

  Feed generators
The following methods request an ATOM feed and return a subclass of "XML::Atom::Feed". These methods accept the following optional named parameters:

    order / sort
        The sort order of the entries: desc (default) or asc in time. When ordering by asc, Google only returns entries within 30 days, whereas the default order has no limitation.

    start_time
        Request entries only newer than this time (represented as a unix timestamp).

    exclude(feed => $feed|[@feeds], tag => $tag|[@tags])
        Accepts a hash reference to one or more of feed / tag / state. Each of which is a scalar or array reference.

feed($feed)
    Accepts a single feed url.

tag($tag)
    Accepts a single tag name. See "TAGS"

state($state)
    Accepts a single state name. See "STATES".

shared
    Shortcut for state('broadcast').

starred
    Shortcut for state('starred').

unread
    Shortcut for state('reading-list', exclude => { state => 'read' })

liked
    Shortcut for state('like').

search($query, %params)
    Accepts a query string and the following named parameters:

    feed / state / tag
        One or more (as a array reference) feed / state / tag to search. The default is to search all feed subscriptions.

    results
        The total number of search results: defaults to 1000.

    count
        The number of entries per fetch: defaults to 40.

    order / sort
        The sort order of the entries: desc (default) or asc in time.

more / previous / next
    A feed generator only returns $count entries. If more are available, calling this method will return a feed with the next $count entries.

  List generators
The following methods return an object of type "WebService::Google::Reader::ListElement".

counts
    Returns a list of subscriptions and a count of unread entries. Also listed are any tags or states which have positive unread counts. The following accessors are provided: id, count. The maximum count reported is 1000.

feeds
    Returns the list of user subscriptions. The following accessors are provided: id, title, categories, firstitemmsec. categories is a reference to a list of "ListElement"s providing accessors: id, label.

preferences
    Returns the list of preference settings. The following accessors are provided: id, value.

tags
    Returns the list of user-created tags. The following accessors are provided: id, shared.

userinfo
    Returns the list of user information. The following accessors are provided: isBloggerUser, userId, userEmail.

  Edit feeds
The following methods are used to edit feed subscriptions.

edit_feed($feed|[@feeds], %params)
    Requires a feed url or Feed object, or a reference to a list of them. The following named parameters are accepted:

    subscribe / unsubscribe
        Flag indicating whether the target feeds should be added or removed from the user's subscriptions.

    title
        Accepts a title to associate with the feed. This probaby wouldn't make sense to use when there are multiple feeds. (Maybe later will consider allowing a list here and zipping the feed and title lists).

    tag / state / untag / unstate
        Accepts a tag / state or a reference to a list of tags / states for which to associate / unassociate the target feeds.

tag_feed($feed|[@feeds], @tags)
untag_feed($feed|[@feeds], @tags)
state_feed($feed|[@feeds], @states)
unstate_feed($feed|[@feeds], @states)
    Associate / unassociate a list of tags / states from a feed / feeds.

subscribe(@feeds|[@feeds])
unsubscribe(@feeds|[@feeds])
    Subscribe or unsubscribe from a list of feeds.

rename_feed($feed|[@feeds], $title)
    Renames a feed to the given title.

mark_read_feed(@feeds|[@feeds])
    Marks the feeds as read.

  Edit tags / states
The following methods are used to edit tags and states.

edit_tag($tag|[@tags], %params)
edit_state($state|[@states], %params)
    Accepts the following parameters.

    share / public
        Make the given tags / states public.

    unshare / private
        Make the given tags / states private.

    disable / delete
        Only tags (and not states) can be disabled.

share_tag(@tags|[@tags])
unshare_tag(@tags|[@tags])
share_state(@states|[@states])
unshare_state(@states|[@states])
    Associate / unassociate the 'broadcast' state with the given tags / states.

delete_tag(@tags|[@tags])
    Delete the given tags.

rename_feed_tag($oldtag|[@oldtags], $newtag|[@newtags]
    Renames the tags associated with any feeds.

rename_entry_tag($oldtag|[@oldtags], $newtag|[@newtags]
    Renames the tags associated with any individual entries.

rename_tag($oldtag|[@oldtags], $newtag|[@newtags]
    Calls rename_feed_tag and rename_entry_tag, and finally delete_tag.

mark_read_tag(@tags|[@tags])
mark_read_state(@states|[@states])
    Marks all entries as read for the given tags / states.

  Edit entries
The following methods are used to edit individual entries.

edit_entry($entry|[@entries], %params)
    tag / state / untag / unstate
        Associate / unassociate the entries with the given tags / states.

tag_entry($entry|[@entries], @tags)
untag_entry($entry|[@entries], @tags)
state_entry($entry|[@entries], @tags)
unstate_entry($entry|[@entries], @tags)
    Associate / unassociate the entries with the given tags / states.

share_entry(@entries|[@entries])
unshare_entry(@entries|[@entries])
    Marks all the given entries as "broadcast".

star(@entries|[@entries])
star_entry(@entries|[@entries])
unstar(@entries|[@entries])
unstar_entry(@entries|[@entries])
    Marks / unmarks all the given entries as "starred".

mark_read_entry(@entries|[@entries])
    Marks all the given entries as "read".

like(@entries|[@entries])
like_entry(@entries|[@entries])
unlike(@entries|[@entries])
unlike_entry(@entries|[@entries])
    Marks / unmarks all the given entries as "liked".

  Miscellaneous
These are a list of other useful methods.

edit_preference($key, $value)
    Sets the given preference name to the given value.

mark_read(feed => $feed|[@feeds], state => $state|[@states], tag => $tag|[@tags])
opml
    Exports feed subscriptions as OPML.

ping
    Returns true / false on success / failure. Unsure of when this needs to be used.

  Private methods
The following private methods may be of use to others.

_login
    This is automatically called from within methods that require authorization. An optional parameter is accepted which when true, will force a login even if a previous login was successful. The end result of a successful login is to set the auth token.

_request
    Given an "HTTP::Request", this will perform the request and if the response indicates a bad (expired) token, it will request another token before performing the request again. Returns an "HTTP::Response" on success, false on failure (check error).

_token
    This is automatically called from within methods that require a user token. If successful, the token is available via the token accessor.

_states
    Returns a list of all the known states. See "STATES".

TAGS
The following characters are not allowed: "<>?&/\^

STATES
These are tags in a Google-specific namespace. The following are all the known used states.

read
    Entries which have been read.

kept-unread
    Entries which have been read, but marked unread.

fresh
    New entries from reading-list.

starred
    Entries which have been starred.

broadcast
    Entries which have been shared and made publicly available.

reading-list
    Entries from all subscriptions.

tracking-body-link-used
    Entries for which a link in the body has been clicked.

tracking-emailed
    Entries which have been mailed.

tracking-item-link-used
    Entries for which the title link has been clicked.

tracking-kept-unread
    Entries which have been kept unread. (Not sure how this differs from "kept-unread").

SEE ALSO
XML::Atom::Feed

<https://groups.google.com/group/fougrapi/>

<http://code.google.com/p/pyrfeed/wiki/GoogleReaderAPI>

REQUESTS AND BUGS
Please report any bugs or feature requests to <http://rt.cpan.org/Public/Bug/Report.html?Queue=WebService-Google-Reader>. 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 WebService::Google::Reader

You can also look for information at:

•   GitHub Source Repository

    <http://github.com/gray/webservice-google-reader>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/WebService-Google-Reader>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/WebService-Google-Reader>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/Public/Dist/Display.html?Dist=WebService-Google-Reader>

•   Search CPAN

    <http://search.cpan.org/dist/WebService-Google-Reader/>

COPYRIGHT AND LICENSE
Copyright (C) 2007-2011 gray <gray at cpan.org>, all rights reserved.

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

AUTHOR
gray, <gray at cpan.org>