The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-Google-Reader-0.22
River stage zero No dependents
5 ++
/ WebService::Google::Reader

NAME

WebService::Google::Reader - Perl interface to the Google Reader API

SYNOPSIS

    use WebService::Google::Reader;

    my $reader = WebService::Google::Reader->new(
        host     => 'www.inoreader.com',
        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 webservices using the Google Reader API. The only tested webservice at this time is www.inoreader.com.

METHODS

$reader = WebService::Google::Reader->new

Creates a new WebService::Google::Reader object. The following named parameters are accepted:

host

The hostname of the service.

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

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

http://wiki.inoreader.com/doku.php?id=api

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:

COPYRIGHT AND LICENSE

Copyright (C) 2007-2013 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>