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

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.

$error = $reader->error

Returns the error, if one occurred.

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' } )

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 )
unsubscribe( @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 )

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 )
unshare_tag( @tags )
share_state( @states )
unshare_state( @states )

Associate / unassociate the 'broadcast' state with the given tags / states.

delete_tag( @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 )
mark_read_state( @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 )
unshare_entry( @entries )

Marks all the given entries as "broadcast".

star
star_entry
unstar
unstar_entry

Marks / unmarks all the given entries as "starred".

mark_read_entry( @entries )

Marks all the given entries as "read".

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 SID cookie.

_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").

NOTES

If Compress::Zlib is found, then requests will accept compressed responses.

SEE ALSO

XML::Atom::Feed

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

REQUESTS AND BUGS

Please report any bugs or feature requests to http://rt.cpan.org/NoAuth/ReportBug.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 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>