package WebService::Google::Reader;
use strict;
use warnings;
use Carp qw(croak);
use HTTP::Request::Common qw(GET POST);
use LWP::UserAgent;
use JSON::MaybeXS;
use URI;
use URI::Escape;
use URI::QueryParam;
use WebService::Google::Reader::Constants;
use WebService::Google::Reader::Feed;
use WebService::Google::Reader::ListElement;
our $VERSION = '0.24';
$VERSION = eval $VERSION;
use Class::Tiny qw(
appid appkey auth compress error host password response _scheme token ua
username
);
sub BUILD {
my ($self, $params) = @_;
croak q('host' is required) unless $self->host;
my $host = $self->host;
$host = "http://$host" unless $host =~ m[^https?://];
$host =~ s[/+$][];
$self->host($host);
if ($host =~ /(^|\.)inoreader\.com$/i) {
croak q('appid' and 'appkey' are required by inoreader)
unless defined $self->appid and defined $self->appkey;
}
unless (ref $self->ua and $self->ua->isa(q(LWP::UserAgent))) {
$self->ua(LWP::UserAgent->new(agent => __PACKAGE__.'/'.$VERSION));
}
$self->compress(exists $params->{compress} ? $params->{compress} : 1);
$self->debug(exists $params->{debug} ? $params->{debug} : 0);
$self->ua->default_header(accept_encoding => 'gzip,deflate')
if $self->compress;
$self->_scheme($params->{secure} || $params->{https} ? 'https' : 'http');
return $self;
}
sub debug {
my ($self, $val) = @_;
return $self->{debug} unless 2 == @_;
my $ua = $self->ua;
if ($val) {
my $dump_sub = sub { $_[0]->dump(maxlength => 0); return };
$ua->set_my_handler(request_send => $dump_sub);
$ua->set_my_handler(response_done => $dump_sub);
}
else {
$ua->set_my_handler(request_send => undef);
$ua->set_my_handler(response_done => undef);
}
return $self->{debug} = $val;
}
## Feeds
sub feed { shift->_feed(feed => shift, @_) }
sub tag { shift->_feed(tag => shift, @_) }
sub state { shift->_feed(state => shift, @_) }
sub shared { shift->state(broadcast => @_) }
sub starred { shift->state(starred => @_) }
sub liked { shift->state(like => @_) }
sub unread {
shift->state(
'reading-list', exclude => { state => 'read' }, @_
);
}
sub search {
my ($self, $query, %params) = @_;
$self->_login or return;
$self->_token or return;
my $uri = URI->new($self->host . SEARCH_ITEM_IDS_PATH);
my %fields = (num => $params{results} || 1000);
my @types = grep { exists $params{$_} } qw(feed state tag);
for my $type (@types) {
push @{$fields{s}}, _encode_type($type, $params{$type});
}
$uri->query_form({ q => $query, %fields, output => 'json' });
my $req = HTTP::Request->new(GET => $uri);
my $res = $self->_request($req) or return;
my @ids = do {
my $ref = eval { JSON->new->decode($res->decoded_content) } or do {
$self->error("Failed to parse JSON response: $@");
return;
};
map { $_->{id} } @{$ref->{results}};
};
return unless @ids;
if (my $order = $params{order} || $params{sort}) {
@ids = reverse @ids if 'asc' eq $order;
}
my $feed = (__PACKAGE__.'::Feed')->new(_request => $req, _ids => \@ids);
return $self->more($feed);
}
sub more {
my ($self, $feed) = @_;
my $req;
if (defined $feed->_ids) {
my @ids = splice @{$feed->_ids}, 0, $feed->count;
return unless @ids;
my $uri = URI->new($self->host . STREAM_ITEMS_CONTENTS_PATH);
$req = POST $uri, [ output => 'atom', map { (i => $_) } @ids ];
}
elsif ($feed->elem) {
return unless defined $feed->continuation;
return if $feed->entries < $feed->count;
$req = $feed->_request;
my $prev_continuation = $req->uri->query_param('c') || '';
return if $feed->continuation eq $prev_continuation;
$req->uri->query_param(c => $feed->continuation);
}
elsif ($req = $feed->_request) {
# Initial request.
}
else { return }
my $res = $self->_request($req) or return;
$feed->init(Stream => $res->decoded_content(ref => 1)) or return;
return $feed;
}
*previous = *previous = *next = *next = \&more;
## Lists
sub tags { $_[0]->_list($_[0]->host . LIST_TAGS_PATH) }
sub feeds { $_[0]->_list($_[0]->host . LIST_SUBS_PATH) }
sub preferences { $_[0]->_list($_[0]->host . LIST_PREFS_PATH) }
sub counts { $_[0]->_list($_[0]->host . LIST_COUNTS_PATH) }
sub userinfo { $_[0]->_list($_[0]->host . LIST_USER_INFO_PATH) }
## Edit tags
sub edit_tag { shift->_edit_tag(tag => @_) }
sub edit_state { shift->_edit_tag(state => @_) }
sub share_tag { shift->edit_tag(_listify(\@_), share => 1) }
sub unshare_tag { shift->edit_tag(_listify(\@_), unshare => 1) }
sub share_state { shift->edit_state(_listify(\@_), share => 1) }
sub unshare_state { shift->edit_state(_listify(\@_), unshare => 1) }
sub delete_tag { shift->edit_tag(_listify(\@_), delete => 1) }
sub mark_read_tag { shift->mark_read(tag => _listify(\@_)) }
sub mark_read_state { shift->mark_read(state => _listify(\@_)) }
sub rename_feed_tag {
my ($self, $old, $new) = @_;
my @tagged;
my @feeds = $self->feeds or return;
# Get the list of subs which are associated with the tag to be renamed.
FEED:
for my $feed (@feeds) {
for my $cat ($self->categories) {
for my $o ('ARRAY' eq ref $old ? @$old : ($old)) {
if ($o eq $cat->label or $o eq $cat->id) {
push @tagged, $feed->id;
next FEED;
}
}
}
}
$_ = [ _encode_type(tag => $_) ] for ($old, $new);
return $self->edit_feed(\@tagged, tag => $new, untag => $old);
}
sub rename_entry_tag {
my ($self, $old, $new) = @_;
for my $o ('ARRAY' eq ref $old ? @$old : ($old)) {
my $feed = $self->tag($o) or return;
do {
$self->edit_entry(
[ $feed->entries ], tag => $new, untag => $old
) or return;
} while ($self->feed($feed));
}
return 1;
}
sub rename_tag {
my $self = shift;
return unless $self->rename_feed_tag(@_);
return unless $self->rename_entry_tag(@_);
return $self->delete_tag(shift);
}
## Edit feeds
sub edit_feed {
my ($self, $sub, %params) = @_;
$self->_login or return;
$self->_token or return;
my $url = $self->host . EDIT_SUB_PATH;
my %fields;
for my $s ('ARRAY' eq ref $sub ? @$sub : ($sub)) {
if (__PACKAGE__.'::Feed' eq ref $s) {
my $id = $s->id or next;
$id =~ s[^(?:user|webfeed|tag:google\.com,2005:reader/)][];
$id =~ s[\?.*][];
push @{$fields{s}}, $id;
}
else {
push @{$fields{s}}, _encode_type(feed => $s);
}
}
return 1 unless @{$fields{s} || []};
if (defined(my $title = $params{title})) {
$fields{t} = $title;
}
if (grep { exists $params{$_} } qw(subscribe add)) {
$fields{ac} = 'subscribe';
}
elsif (grep { exists $params{$_} } qw(unsubscribe remove)) {
$fields{ac} = 'unsubscribe';
}
else {
$fields{ac} = 'edit';
}
# Add a tag or state.
for my $t (qw(tag state)) {
next unless exists $params{$t};
defined(my $p = $params{$t}) or next;
for my $a ('ARRAY' eq ref $p ? @$p : ($p)) {
push @{$fields{a}}, _encode_type($t => $a);
}
}
# Remove a tag or state.
for my $t (qw(untag unstate)) {
next unless exists $params{$t};
defined(my $p = $params{$t}) or next;
for my $d ('ARRAY' eq ref $p ? @$p : ($p)) {
push @{$fields{r}}, _encode_type(substr($t, 2) => $d);
}
}
return $self->_edit($url, %fields);
}
sub tag_feed { shift->edit_feed(shift, tag => \@_) }
sub untag_feed { shift->edit_feed(shift, untag => \@_) }
sub state_feed { shift->edit_feed(shift, state => \@_) }
sub unstate_feed { shift->edit_feed(shift, unstate => \@_) }
sub subscribe { shift->edit_feed(_listify(\@_), subscribe => 1) }
sub unsubscribe { shift->edit_feed(_listify(\@_), unsubscribe => 1) }
sub mark_read_feed { shift->mark_read(feed => _listify(\@_)) }
sub rename_feed { $_[0]->edit_feed($_[1], title => $_[2]) }
## Edit entries
sub edit_entry {
my ($self, $entry, %params) = @_;
return unless $entry;
$self->_login or return;
$self->_token or return;
my %fields = (ac => 'edit');
for my $e ('ARRAY' eq ref $entry ? @$entry : ($entry)) {
my $source = $e->source or next;
my $stream_id = $source->get_attr('gr:stream-id') or next;
push @{$fields{i}}, $e->id;
push @{$fields{s}}, $stream_id;
}
return 1 unless @{$fields{i} || []};
my $url = $self->host . EDIT_ENTRY_TAG_PATH;
# Add a tag or state.
for my $t (qw(tag state)) {
next unless exists $params{$t};
defined(my $p = $params{$t}) or next;
for my $a ('ARRAY' eq ref $p ? @$p : ($p)) {
push @{$fields{a}}, _encode_type($t => $a);
}
}
# Remove a tag or state.
for my $t (qw(untag unstate)) {
next unless exists $params{$t};
defined(my $p = $params{$t}) or next;
for my $d ('ARRAY' eq ref $p ? @$p : ($p)) {
push @{$fields{r}}, _encode_type(substr($t, 2) => $d);
}
}
return $self->_edit($url, %fields);
}
sub tag_entry { shift->edit_entry(shift, tag => \@_) }
sub untag_entry { shift->edit_entry(shift, untag => \@_) }
sub state_entry { shift->edit_entry(shift, state => \@_) }
sub unstate_entry { shift->edit_entry(shift, unstate => \@_) }
sub share_entry { shift->edit_entry(_listify(\@_), state => 'broadcast') }
sub unshare_entry { shift->edit_entry(_listify(\@_), unstate => 'broadcast') }
sub star_entry { shift->edit_entry(_listify(\@_), state => 'starred') }
sub unstar_entry { shift->edit_entry(_listify(\@_), unstate => 'starred') }
sub mark_read_entry { shift->edit_entry(_listify(\@_), state => 'read') }
sub like_entry { shift->edit_entry(_listify(\@_), state => 'like') }
sub unlike_entry { shift->edit_entry(_listify(\@_), unstate => 'like') }
# Create some aliases.
for (qw(star unstar like unlike)) {
no strict 'refs';
*$_ = \&{$_.'_entry'};
}
## Miscellaneous
sub mark_read {
my ($self, %params) = @_;
$self->_login or return;
$self->_token or return;
my %fields;
my @types = grep { exists $params{$_} } qw(feed state tag);
for my $type (@types) {
push @{$fields{s}}, _encode_type($type, $params{$type});
}
return $self->_edit($self->host . EDIT_MARK_READ_PATH, %fields);
}
sub edit_preference {
my ($self, $key, $val) = @_;
$self->_login or return;
$self->_token or return;
return $self->_edit($self->host . EDIT_PREF_PATH, k => $key, v => $val);
}
sub opml {
my ($self) = @_;
$self->_login or return;
my $res = $self->_request(GET($self->host . EXPORT_SUBS_PATH)) or return;
return $res->decoded_content;
}
sub ping {
my ($self) = @_;
my $res = $self->_request(GET($self->host . PING_PATH)) or return;
return 1 if 'OK' eq $res->decoded_content;
$self->error('Ping failed: '. $res->decoded_content);
return;
}
## Private interface
sub _request {
my ($self, $req, $count) = @_;
return if $count and 3 <= $count;
# Assume all POST requests are secure.
if ('POST' eq $req->method) {
$req->uri->scheme('https');
}
elsif ('GET' eq $req->method and 'https' ne $req->uri->scheme) {
$req->uri->scheme($self->_scheme);
}
$req->uri->query_param(ck => time * 1000);
$req->uri->query_param(client => $self->ua->agent);
$req->header(AppId => $self->appid, AppKey => $self->appkey)
if defined $self->appid and defined $self->appkey;
$req->header(authorization => 'GoogleLogin auth=' . $self->auth)
if $self->auth;
my $res = $self->ua->request($req);
$self->response($res);
if ($res->is_error) {
# Need fresh tokens.
if (401 == $res->code and $res->message =~ /^Token /) {
print "Stale Auth token- retrying\n" if $self->debug;
$self->_login(1) or return;
return $self->_request($req, ++$count);
}
elsif ($res->header('X-Reader-Google-Bad-Token')) {
print "Stale T token- retrying\n" if $self->debug;
$self->_token(1) or return;
# Replace the T token in the url-encoded content.
my $uri = URI->new;
$uri->query($req->content);
$uri->query_param(T => $self->token);
$req->content($uri->query);
return $self->_request($req, ++$count);
}
$self->error(join ' - ',
'Request failed', $res->status_line, $res->header('title')
);
return;
}
# Reset the error from previous requests.
$self->error(undef);
return $res;
}
sub _login {
my ($self, $force) = @_;
return 1 if $self->_public;
return 1 if $self->auth and not $force;
my $uri = URI->new($self->host . LOGIN_PATH);
$uri->query_form(
service => 'reader',
Email => $self->username,
Passwd => $self->password,
source => $self->ua->agent,
);
my $res = $self->_request(POST($uri)) or return;
my $content = $res->decoded_content;
my ($auth) = $content =~ m[ ^Auth=(.*)$ ]mx;
unless ($auth) {
$self->error('Failed to find Auth token');
return;
}
$self->auth($auth);
return 1;
}
sub _token {
my ($self, $force) = @_;
return 1 if $self->token and not $force;
$self->_login($force) or return;
my $uri = URI->new($self->host . TOKEN_PATH);
$uri->scheme('https');
my $res = $self->_request(GET($uri)) or return;
return $self->token($res->decoded_content);
}
sub _public {
return ! ($_[0]->username and $_[0]->password);
}
sub _encode_type {
my ($type, $val, $escape) = @_;
my @paths;
if ('feed' eq $type) { @paths = _encode_feed($val, $escape) }
elsif ('tag' eq $type) { @paths = _encode_tag($val) }
elsif ('state' eq $type) { @paths = _encode_state($val) }
elsif ('entry' eq $type) { @paths = _encode_entry($val) }
else { return }
return wantarray ? @paths : shift @paths;
}
sub _encode_feed {
my ($feed, $escape) = @_;
my @paths;
for my $f ('ARRAY' eq ref $feed ? @$feed : ($feed)) {
my $path = ($escape ? uri_escape($f) : $f);
$path = "feed/$path"
if 'user/' ne substr $f, 0, 5 and 'feed/' ne substr $f, 0, 5;
push @paths, $path;
}
return @paths;
}
sub _encode_tag {
my ($tag) = @_;
my @paths;
for my $t ('ARRAY' eq ref $tag ? @$tag : ($tag)) {
my $path = $t;
if ($t !~ m[ ^user/(?:-|\d{20})/ ]x) {
$path = "user/-/label/$t"
}
push @paths, $path;
}
return @paths;
}
sub _encode_state {
my ($state) = @_;
my @paths;
for my $s ('ARRAY' eq ref $state ? @$state : ($state)) {
my $path = $s;
if ($s !~ m[ ^user/(?:-|\d{20})/ ]x) {
$path = "user/-/state/com.google/$s";
}
push @paths, $path;
}
return @paths;
}
sub _encode_entry {
my ($entry) = @_;
my @paths;
for my $e ('ARRAY' eq ref $entry ? @$entry : ($entry)) {
my $path = $e;
if ('tag:google.com,2005:reader/item/' ne substr $e, 0, 32) {
$path = "tag:google.com,2005:reader/item/$e";
}
push @paths, $path;
}
return @paths;
}
sub _feed {
my ($self, $type, $val, %params) = @_;
return unless $val;
$self->_login or return;
my $path = $self->host . ($self->_public ? ATOM_PUBLIC_PATH : ATOM_PATH);
my $uri = URI->new($path . '/' . _encode_type($type, $val, 1));
my %fields;
if (my $start_time = $params{start_time}) {
$fields{ot} = $start_time;
}
if (my $order = $params{order} || $params{sort} || 'desc') {
# m = magic/auto; not really sure what that is
$fields{r} = 'desc' eq $order ? 'n' :
'asc' eq $order ? 'o' : $order;
}
if (defined(my $continuation = $params{continuation})) {
$fields{c} = $continuation;
}
if (my $ex = $params{exclude}) {
for my $x ('ARRAY' eq ref $ex ? @$ex : ($ex)) {
while (my ($xtype, $exclude) = each %$x) {
push @{$fields{xt}}, _encode_type($xtype, $exclude);
}
}
}
$uri->query_form(\%fields);
my $feed = (__PACKAGE__.'::Feed')->new(_request => GET($uri), %params);
return $self->more($feed);
}
sub _list {
my ($self, $url) = @_;
$self->_login or return;
my $uri = URI->new($url);
$uri->query_form({ $uri->query_form, output => 'json' });
my $res = $self->_request(GET($uri)) or return;
my $ref = eval { JSON->new->decode($res->decoded_content) } or do {
$self->error("Failed to parse JSON response: $@");
return;
};
# Remove an unecessary level of indirection.
my $aref = (grep { 'ARRAY' eq ref } values %$ref)[0] || [];
for my $ref (@$aref) {
$ref = (__PACKAGE__.'::ListElement')->new($ref)
}
return @$aref
}
sub _edit {
my ($self, $url, %fields) = @_;
my $uri = URI->new($url);
my $req = POST($uri, [ %fields, T => $self->token ]);
my $res = $self->_request($req) or return;
return 1 if 'OK' eq $res->decoded_content;
# TODO: is there a standard error format which can be reliably parsed?
$self->error('Edit failed: '. $res->decoded_content);
return;
}
sub _edit_tag {
my ($self, $type, $tag, %params) = @_;
return unless $tag;
$self->_login or return;
$self->_token or return;
my %fields = (s => [ _encode_type($type => $tag) ]);
return 1 unless @{$fields{s}};
my $url;
if (grep { exists $params{$_} } qw(share public)) {
$url = $self->host . EDIT_TAG_SHARE_PATH;
$fields{pub} = 'true';
}
elsif (grep { exists $params{$_} } qw(unshare private)) {
$url = $self->host . EDIT_TAG_SHARE_PATH;
$fields{pub} = 'false';
}
elsif (grep { exists $params{$_} } qw(disable delete)) {
$url = $self->host . EDIT_TAG_DISABLE_PATH;
$fields{ac} = 'disable-tags';
}
else {
$self->error('Unknown action');
return;
}
return $self->_edit($url, %fields);
}
sub _states {
return qw(
read kept-unread fresh starred broadcast reading-list
tracking-body-link-used tracking-emailed tracking-item-link-used
tracking-kept-unread like
);
}
sub _listify {
my ($aref) = @_;
return (1 == @$aref and 'ARRAY' eq ref $aref->[0]) ? @$aref : $aref;
}
1;
__END__
=head1 NAME
WebService::Google::Reader - Perl interface to the Google Reader API
=head1 SYNOPSIS
use WebService::Google::Reader;
my $reader = WebService::Google::Reader->new(
host => 'www.inoreader.com',
appid => $appid,
appkey => $appey,
username => $username,
password => $password,
);
my $feed = $reader->unread(count => 100);
my @entries = $feed->entries;
# Fetch past entries.
while ($reader->more($feed)) {
my @entries = $feed->entries;
}
=head1 DESCRIPTION
The C<WebService::Google::Reader> module provides an interface to webservices
using the Google Reader API. The only tested webservice at this time is
L<www.inoreader.com>.
=head1 METHODS
=over
=item $reader = WebService::Google::Reader->B<new>
Creates a new WebService::Google::Reader object. The following named
parameters are accepted:
=over
=item B<host>
The hostname of the service.
=item B<username> and B<password>
Required for accessing any personalized or account-related functionality
(reading-list, editing, etc.).
=item B<appid> and B<appkey>
Inoreader requires users to also obtain an appid and appkey.
See L<http://www.inoreader.com/developers/register-app>
=item B<https> / B<secure>
Use https scheme for all requests, even when not required.
=item B<ua>
An optional useragent object.
=item B<debug>
Enable debugging. Default: 0. This will dump the headers and content for
both requests and responses.
=item B<compress>
Disable compression. Default: 1. This is useful when debugging is enabled
and you want to read the response content.
=back
=item $error = $reader->B<error>
Returns the error string, if any.
=item $response = $reader->B<response>
Returns an L<HTTP::Response> object for the last submitted request. Can be
used to determine the details of an error.
=back
=head2 Feed generators
The following methods request an ATOM feed and return a subclass of
C<XML::Atom::Feed>. These methods accept the following optional named
parameters:
=over
=over
=item B<order> / B<sort>
The sort order of the entries: B<desc> (default) or B<asc> in time. When
ordering by B<asc>, Google only returns entries within 30 days, whereas the
default order has no limitation.
=item B<start_time>
Request entries only newer than this time (represented as a unix
timestamp).
=item B<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.
=back
=back
=over
=item B<feed>($feed)
Accepts a single feed url.
=item B<tag>($tag)
Accepts a single tag name. See L</TAGS>
=item B<state>($state)
Accepts a single state name. See L</STATES>.
=item B<shared>
Shortcut for B<state>('broadcast').
=item B<starred>
Shortcut for B<state>('starred').
=item B<unread>
Shortcut for B<state>('reading-list', exclude => { state => 'read' })
=item B<liked>
Shortcut for B<state>('like').
=back
=over
=item B<search>($query, %params)
Accepts a query string and the following named parameters:
=over
=item B<feed> / B<state> / B<tag>
One or more (as a array reference) feed / state / tag to search. The
default is to search all feed subscriptions.
=item B<results>
The total number of search results: defaults to 1000.
=item B<count>
The number of entries per fetch: defaults to 40.
=item B<order> / B<sort>
The sort order of the entries: B<desc> (default) or B<asc> in time.
=back
=item B<more> / B<previous> / B<next>
A feed generator only returns B<count> entries. If more are available,
calling this method will return a feed with the next B<count> entries.
=back
=head2 List generators
The following methods return an object of type
C<WebService::Google::Reader::ListElement>.
=over
=item B<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.
=item B<feeds>
Returns the list of user subscriptions. The following accessors are
provided: id, title, categories, firstitemmsec. categories is a reference
to a list of C<ListElement>s providing accessors: id, label.
=item B<preferences>
Returns the list of preference settings. The following accessors are
provided: id, value.
=item B<tags>
Returns the list of user-created tags. The following accessors are
provided: id, shared.
=item B<userinfo>
Returns the list of user information. The following accessors are provided:
isBloggerUser, userId, userEmail.
=back
=head2 Edit feeds
The following methods are used to edit feed subscriptions.
=over
=item B<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:
=over
=item B<subscribe> / B<unsubscribe>
Flag indicating whether the target feeds should be added or removed from
the user's subscriptions.
=item B<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).
=item B<tag> / B<state> / B<untag> / B<unstate>
Accepts a tag / state or a reference to a list of tags / states for which
to associate / unassociate the target feeds.
=back
=item B<tag_feed>($feed|[@feeds], @tags)
=item B<untag_feed>($feed|[@feeds], @tags)
=item B<state_feed>($feed|[@feeds], @states)
=item B<unstate_feed>($feed|[@feeds], @states)
Associate / unassociate a list of tags / states from a feed / feeds.
=item B<subscribe>(@feeds|[@feeds])
=item B<unsubscribe>(@feeds|[@feeds])
Subscribe or unsubscribe from a list of feeds.
=item B<rename_feed>($feed|[@feeds], $title)
Renames a feed to the given title.
=item B<mark_read_feed>(@feeds|[@feeds])
Marks the feeds as read.
=back
=head2 Edit tags / states
The following methods are used to edit tags and states.
=over
=item B<edit_tag>($tag|[@tags], %params)
=item B<edit_state>($state|[@states], %params)
Accepts the following parameters.
=over
=item B<share> / B<public>
Make the given tags / states public.
=item B<unshare> / B<private>
Make the given tags / states private.
=item B<disable> / B<delete>
Only tags (and not states) can be disabled.
=back
=item B<share_tag>(@tags|[@tags])
=item B<unshare_tag>(@tags|[@tags])
=item B<share_state>(@states|[@states])
=item B<unshare_state>(@states|[@states])
Associate / unassociate the 'broadcast' state with the given tags / states.
=item B<delete_tag>(@tags|[@tags])
Delete the given tags.
=item B<rename_feed_tag>($oldtag|[@oldtags], $newtag|[@newtags]
Renames the tags associated with any feeds.
=item B<rename_entry_tag>($oldtag|[@oldtags], $newtag|[@newtags]
Renames the tags associated with any individual entries.
=item B<rename_tag>($oldtag|[@oldtags], $newtag|[@newtags]
Calls B<rename_feed_tag> and B<rename_entry_tag>, and finally
B<delete_tag>.
=item B<mark_read_tag>(@tags|[@tags])
=item B<mark_read_state>(@states|[@states])
Marks all entries as read for the given tags / states.
=back
=head2 Edit entries
The following methods are used to edit individual entries.
=over
=item B<edit_entry>($entry|[@entries], %params)
=over
=item B<tag> / B<state> / B<untag> / B<unstate>
Associate / unassociate the entries with the given tags / states.
=back
=item B<tag_entry>($entry|[@entries], @tags)
=item B<untag_entry>($entry|[@entries], @tags)
=item B<state_entry>($entry|[@entries], @tags)
=item B<unstate_entry>($entry|[@entries], @tags)
Associate / unassociate the entries with the given tags / states.
=item B<share_entry>(@entries|[@entries])
=item B<unshare_entry>(@entries|[@entries])
Marks all the given entries as "broadcast".
=item B<star>(@entries|[@entries])
=item B<star_entry>(@entries|[@entries])
=item B<unstar>(@entries|[@entries])
=item B<unstar_entry>(@entries|[@entries])
Marks / unmarks all the given entries as "starred".
=item B<mark_read_entry>(@entries|[@entries])
Marks all the given entries as "read".
=item B<like>(@entries|[@entries])
=item B<like_entry>(@entries|[@entries])
=item B<unlike>(@entries|[@entries])
=item B<unlike_entry>(@entries|[@entries])
Marks / unmarks all the given entries as "liked".
=back
=head2 Miscellaneous
These are a list of other useful methods.
=over
=item B<edit_preference>($key, $value)
Sets the given preference name to the given value.
=item B<mark_read>(feed => $feed|[@feeds], state => $state|[@states],
tag => $tag|[@tags])
=item B<opml>
Exports feed subscriptions as OPML.
=item B<ping>
Returns true / false on success / failure. Unsure of when this needs to be
used.
=back
=head2 Private methods
The following private methods may be of use to others.
=over
=item B<_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 B<auth> token.
=item B<_request>
Given an C<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 C<HTTP::Response> on success, false
on failure (check B<error>).
=item B<_states>
Returns a list of all the known states. See L</STATES>.
=item B<_token>
This is automatically called from within methods that require a user token. It
fetches a new token when it becomes stale.
=item B<auth>
Accessor for the auth token, which is set after a successful B<_login>.
=item B<token>
Accessor for the user token, which is set by B<_token>.
=back
=head1 TAGS
The following characters are not allowed: "E<lt>E<gt>?&/\^
=head1 STATES
These are tags in a Google-specific namespace. The following are all the
known used states.
=over
=item read
Entries which have been read.
=item kept-unread
Entries which have been read, but marked unread.
=item fresh
New entries from reading-list.
=item starred
Entries which have been starred.
=item broadcast
Entries which have been shared and made publicly available.
=item reading-list
Entries from all subscriptions.
=item tracking-body-link-used
Entries for which a link in the body has been clicked.
=item tracking-emailed
Entries which have been mailed.
=item tracking-item-link-used
Entries for which the title link has been clicked.
=item tracking-kept-unread
Entries which have been kept unread.
(Not sure how this differs from "kept-unread").
=back
=head1 SEE ALSO
L<XML::Atom::Feed>
L<https://groups.google.com/group/fougrapi/>
L<http://code.google.com/p/pyrfeed/wiki/GoogleReaderAPI>
L<http://www.inoreader.com/developers/>
=head1 REQUESTS AND BUGS
Please report any bugs or feature requests to
L<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.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WebService::Google::Reader
You can also look for information at:
=over
=item * GitHub Source Repository
L<http://github.com/gray/webservice-google-reader>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/WebService-Google-Reader>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/WebService-Google-Reader>
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/Public/Dist/Display.html?Dist=WebService-Google-Reader>
=item * Search CPAN
L<http://search.cpan.org/dist/WebService-Google-Reader/>
=back
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2007-2017 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.
=head1 AUTHOR
gray, <gray at cpan.org>
=cut