view release on metacpan or  search on metacpan

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

  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
   music
   political
   religion
   science
   sport
   travel

The first line is output via C<STDERR>, so you don't have to filter it out
if you wanted to do something wacky, like printing out 1 random quote for
each currently supported category:

  shell>cnq categories | xargs -I% cnq random --category %

=item C<random [--category STRING]>

The command that returns the random Chuch Noris quote. It is the default
command if none is specified:

  shell> cnq random
  Chuck Norris dunks onion rings in his morning coffee.
  shell> nq random
  Chuck Norris savors the sweet taste of ax-murder.
  shell> cnq random
  Chuck Norris puts the "hurt" in yoghurt.
  shell> cnq
  Chuck Norris' leg kicks hit hard enough to knock the polio vaccine out of your body
  shell>

There's an optional named a parameter, C<category>, that will narrow down
the quote to a category supported by the SaaS. To see what catagories are
available, use the C<categories> command. Only one C<--category> at a time
is supported.

The following command does what you expect,