view release on metacpan or  search on metacpan

lib/Acme/Free/API/ChuckNorris.pm  view on Meta::CPAN

    my $self  = shift;
    my $args  = d2o {@_};
    my $query = ( $args->category ) ? sprintf( "?category=%s", $args->category ) : "";
    my $URL   = sprintf "%s/%s%s", BASEURL, "random", $query;
    my $resp  = d2o $self->ua->get($URL);
    die sprintf( "fatal cnq: API did not a useful response (status: %d)\n", $resp->status ) if ( $resp->status != 200 );
    my $ret = d2o decode_json $resp->content;
    return $ret->value;
}

sub search {
    my $self  = shift;
    my $args  = h2o {@_};
    my $terms = $args->terms;
    my $URL   = sprintf "%s/%s?query=%s", BASEURL, "search", $terms;
    my $resp = d2o $self->ua->get($URL);
    my $ret  = d2o decode_json $resp->content;
    return scalar $ret;
}

1;

__END__

=head1 NAME

Acme::Free::API::ChuckNorris - Perl API client for the Chuck Norris Quote API service, L<https://api.chucknorris.io>.

This module provides the client, "cnq", that is available via C<PATH> after install.

=head1 SYNOPSIS

  #!/usr/bin/env perl
    
  use strict;
  use warnings;
  
  use Acme::Free::API::ChuckNorris qw//;
  
  my $cnq = Acme::Free::API::ChuckNorris->new;

  printf "%s\n", $cnq->random;

=head2 C<cnq> Commandline Client

After installing this module, simply run the command C<cnq> without any arguments,
and you will get a random quote.

  shell> cnq
  Calculator's refuse to work around Chuck Norris in fear of outsmarting him
  shell>

=head1 DESCRIPTION

Contributed as part of the B<FreePublicPerlAPIs> Project described at,
L<https://github.com/oodler577/FreePublicPerlAPIs>.

This fun module is to demonstrate how to use L<Util::H2O::More> and
L<Dispatch::Fu> to make creating easily make API SaaS modules and
clients in a clean and idiomatic way. These kind of APIs tracked at
L<https://www.freepublicapis.com/> are really nice for fun and practice
because they don't require dealing with API keys in the vast majority of cases.

=head1 METHODS

=over 4

=item C<new>

Instantiates object reference. No parameters are accepted.

=item C<categories>

Makes the SaaS API call to get the list of categories. It accepts no arguments.

=item C<< random([category => STRING]) >>

Returns a random quote. Accepts a single optional parameter that will select the
random quote from a specific category.

=item C<< search( terms => STRING ) >>

Requires a single named parameter to specify the search terms. The resulting quotes
are returned as a L<Util::H2O::More> object. The following example is pulled right
out of the C<cnq> utilitye,

  my $cnq    = Acme::Free::API::ChuckNorris->new;
  my $ret    = $cnq->search(terms => $terms);
  my $quotes = $ret->result;
  printf STDERR "Found %d quotes\n", $ret->total;
  if ($ret->total == 0) {
    warn "warning: cnq: no results for '$terms'\n";
    exit;
  }
  foreach my $quote ($quotes->all) {
    say $quote->value;
  }

=back

=head1 C<cnq> OPTIONS

=over 4

=item C<categories>

Lists categories supported by the Chuck Norris Quote SaaS, this is as the
SaaS reports it presently (it uses an API call).

  shell> cnq categories
  Found 16 categories
   animal
   career
   celebrity
   dev
   explicit
   fashion
   food
   history
   money
   movie