From 38f8b09aa59b7da47e8597b17a91be5f177bec74 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Sun, 10 May 2015 21:40:55 -0400 Subject: documentation --- bin/pocket | 95 +++++++++++++++++++++++++++++++ dist.ini | 3 + lib/WWW/Pocket.pm | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 264 insertions(+) diff --git a/bin/pocket b/bin/pocket index a73633c..b335ae1 100644 --- a/bin/pocket +++ b/bin/pocket @@ -1,6 +1,101 @@ #!/usr/bin/env perl use strict; use warnings; +# PODNAME: pocket +# ABSTRACT: interact with the Pocket API from the command line + +=head1 SYNOPSIS + + $ pocket list + Enter your consumer key: ... + Visit https://getpocket.com/auth/authorize?request_token=...&redirect_uri=https://getpocket.com/ and log in. When you're done, press enter to continue. + + http://the-toast.net/2015/04/27/looking-back-fragments-from-womens-shelters-1981-1996/view-all/ + https://modelviewculture.com/pieces/dreaming-holding-onto-the-hope-of-justice-in-technology-and-america + [...] + $ pocket words --archive + 2233913 + +=head1 DESCRIPTION + +This program provides several subcommands to allow you to interact with your +Pocket list from the command line. It will automatically authenticate as +needed, prompting you for your consumer key, and will store the returned +credentials in C<~/.pocket>. + +=head1 COMMANDS + +=head2 authenticate + +Authenticates you with the Pocket API and does nothing else. Not usually +necessary, since all of the following commands will automatically authenticate +as necessary. + +=head2 list + +Prints the URLs in your list. By default, prints unread URLs, but also takes options to adjust the list that is returned: + +=over 4 + +=item --unread + +Return only unread links. This is the default, but can be provided for +explicitness. + +=item --archive + +Return only archived links. + +=item --all + +Return both unread and archived links. + +=item --tag= + +Return links with the given tag. This option can be passed multiple times, and +may be combined with the above options. + +=back + +=head2 words + +Takes the same options as C, but instead of printing the URLs of the +articles, prints the number of words in all of those articles combined. + +=head2 search + +Returns a list of URLs whose title or URL contains C. Takes the same +options as C to limit the search. + +=head2 favorites + +Returns a list of favorited URLs. Takes the same options as C. + +=head2 add [title] + +Adds C to your list, optionally with the given C. + +=head2 archive <url> + +Moves C<url> from your list to your archive. + +=head2 readd <url> + +Moves C<url> from your archive to your list. + +=head2 favorite <url> + +Marks C<url> as a favorite. + +=head2 unfavorite <url> + +Unmarks C<url> as a favorite. + +=head2 delete <url> + +Deletes C<url> from your list and/or archive entirely. + +=cut use WWW::Pocket::Script; WWW::Pocket::Script->new->run(@ARGV); diff --git a/dist.ini b/dist.ini index ae31fcf..7d3c026 100644 --- a/dist.ini +++ b/dist.ini @@ -8,4 +8,7 @@ copyright_holder = Jesse Luehrs dist = WWW-Pocket repository = github +[MetaNoIndex] +package = WWW::Pocket::Script + [AutoPrereqs] diff --git a/lib/WWW/Pocket.pm b/lib/WWW/Pocket.pm index 2b032f0..645f30c 100644 --- a/lib/WWW/Pocket.pm +++ b/lib/WWW/Pocket.pm @@ -1,15 +1,63 @@ package WWW::Pocket; use Moose; +# ABSTRACT: Wrapper for the Pocket v3 API use HTTP::Tiny; use JSON::PP; +=head1 SYNOPSIS + + use WWW::Pocket; + + my $pocket = WWW::Pocket->new( + # get a consumer key at https://getpocket.com/developer/ + consumer_key => '...', + ); + + my ($url, $code) = $pocket->start_authentication('https://example.com/'); + # visit $url, log in + $pocket->finish_authentication($code); + + say for map { $_->{resolved_url} } values %{ $pocket->retrieve->{list} }; + +=head1 DESCRIPTION + +This module wraps the L<Pocket|https://getpocket.com/> v3 API. To use, you +must first authenticate via OAuth by providing a valid consumer key, and then +visiting the OAuth endpoint (handled by the C<start_authentication> and +C<finish_authentication> methods). Once logged in, you can interact with the +API via the C<add>, C<modify>, and C<retrieve> methods, which correspond to +the endpoints documented at L<https://getpocket.com/developer/docs/overview>. + +This module also ships with a command line scripts called C<pocket>, for +interacting with the API from the command line. See the documentation for that +script for more details. + +=cut + +=attr consumer_key + +The consumer key for your application. You can generate a consumer key at +L<https://getpocket.com/developer/apps/>. Required. + +=cut + has consumer_key => ( is => 'ro', isa => 'Str', required => 1, ); +=attr access_token + +The token returned when you successfully authenticate. This can be used to +reauthenticate with the server without having to log in every time. It is set +automatically by C<finish_authentication>, but can also be provided directly +to avoid having to reauthenticate. It is required to be set before any API +methods are called. + +=cut + has access_token => ( is => 'ro', isa => 'Str', @@ -19,6 +67,14 @@ has access_token => ( writer => '_set_access_token', ); +=attr username + +The username that you have authenticated as. It is set automatically by +C<finish_authentication>, and can also be provided directly. It is +informational only. + +=cut + has username => ( is => 'ro', isa => 'Str', @@ -26,12 +82,25 @@ has username => ( writer => '_set_username', ); +=attr base_uri + +The base URI for the Pocket service. Defaults to C<https://getpocket.com/>. + +=cut + has base_uri => ( is => 'ro', isa => 'Str', default => 'https://getpocket.com/', ); +=attr api_base_uri + +The base URI for the API endpoints. Defaults to appending C</v3/> to the +C<base_uri>. + +=cut + has api_base_uri => ( is => 'ro', isa => 'Str', @@ -43,6 +112,13 @@ has api_base_uri => ( }, ); +=attr auth_base_uri + +The base URI for the authentication endpoints. Defaults to appending C</auth/> +to the C<base_uri>. + +=cut + has auth_base_uri => ( is => 'ro', isa => 'Str', @@ -54,6 +130,12 @@ has auth_base_uri => ( }, ); +=attr ua + +The L<HTTP::Tiny> instance used to access the api. + +=cut + has ua => ( is => 'ro', isa => 'HTTP::Tiny', @@ -61,6 +143,17 @@ has ua => ( default => sub { HTTP::Tiny->new }, ); +=method start_authentication($redirect_uri) + +Call this method to begin the authentication process. You must provide the +C<$redirect_uri>, which is where the user will be redirected to after +authenticating. This method returns a URL and an authentication code. The user +must visit the URL to log into Pocket and approve the application, and then +you should call C<finish_authentication> with the authentication code after +that is done. + +=cut + sub start_authentication { my $self = shift; my ($redirect_uri) = @_; @@ -80,6 +173,16 @@ sub start_authentication { ); } +=method finish_authentication($code) + +Finishes the authentication process. Call this method with the code returned +by C<start_authentication> after the user has visited the URL which was also +returned by C<start_authentication>. Once this method returns, the +C<access_key> and C<username> attributes will be set, and other API methods +can be successfully called. + +=cut + sub finish_authentication { my $self = shift; my ($code) = @_; @@ -98,18 +201,40 @@ sub finish_authentication { return; } +=method add(%params) + +Wraps the L<add|https://getpocket.com/developer/docs/v3/add> endpoint. +C<%params> can include any parameters documented in the API documentation. + +=cut + sub add { my $self = shift; my (%params) = @_; return $self->_endpoint_request('add', \%params); } +=method modify + +Wraps the L<modify|https://getpocket.com/developer/docs/v3/modify> endpoint. +C<%params> can include any parameters documented in the API documentation. + +=cut + sub modify { my $self = shift; my (%params) = @_; return $self->_endpoint_request('send', \%params); } +=method retrieve + +Wraps the L<retrieve|https://getpocket.com/developer/docs/v3/retrieve> +endpoint. C<%params> can include any parameters documented in the API +documentation. + +=cut + sub retrieve { my $self = shift; my (%params) = @_; @@ -147,4 +272,45 @@ sub _request { __PACKAGE__->meta->make_immutable; no Moose; +=head1 BUGS + +No known bugs. + +Please report any bugs to GitHub Issues at +L<https://github.com/doy/www-pocket/issues>. + +=head1 SEE ALSO + +L<Webservice::Pocket> for the v2 API + +=head1 SUPPORT + +You can find this documentation for this module with the perldoc command. + + perldoc WWW::Pocket + +You can also look for information at: + +=over 4 + +=item * MetaCPAN + +L<https://metacpan.org/release/WWW-Pocket> + +=item * Github + +L<https://github.com/doy/www-pocket> + +=item * RT: CPAN's request tracker + +L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Pocket> + +=item * CPAN Ratings + +L<http://cpanratings.perl.org/d/WWW-Pocket> + +=back + +=cut + 1; -- cgit v1.2.3