NAME

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

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

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;

cnq Commandline Client

After installing this module, simply run the command 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>

DESCRIPTION

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

This fun module is to demonstrate how to use Util::H2O::More and Dispatch::Fu to make creating easily make API SaaS modules and clients in a clean and idiomatic way. These kind of APIs tracked at 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.

METHODS

new

Instantiates object reference. No parameters are accepted.

categories

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

random([category => STRING])

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

search( terms => STRING )

Requires a single named parameter to specify the search terms. The resulting quotes are returned as a Util::H2O::More object. The following example is pulled right out of the 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;
  }

cnq OPTIONS

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 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 %

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, category, that will narrow down the quote to a category supported by the SaaS. To see what catagories are available, use the categories command. Only one --category at a time is supported.

The following command does what you expect,

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

search SEARCHTERMS

This allows you to get some set of Chuck Norris Quotes based on search terms, e.g.:

  shell> cnq search his computer
  Found 7 quotes
  Chuck Norris can gag you with a horrendous stinch simply by typing the word "fart" on his computer keyboard.
  Chuck Norris is so strong, he can roundhouse a bubbled paladin and blow his computer up.
  Whenever Chuck Norris watches pornography, his computer gets an erection.
  Chuck Norris drugged Bill Cosby. Cosby woke up nine hours later in front of his computer, where he realized he just told the net to meme him.
  When Chuck Norris switches on his computer, it skips the bootup process and goes straight to the desktop.
  Chuck Norris regularly smashes open his computer to eat the cookies within.
  a man once heard two guys talking about Chuck Norris.He went home and decided to look up who Chuck Norris is? He was suprised when it came to a blank screen, he tryed to click out of it untill a window popped up please wait. He waited a while a bar appeared saying now uploading Chuck Norris.He looked stuned when Chuck Norris crawled out of his computer to round house kick him in the face. this man now knows every fact about Chuck Norris.
  

Like categories, the first line is printed via STDERR.

Internal Methods

There are no internal methods to speak of.

ENVIRONMENT

Nothing special required.

AUTHOR

Brett Estrade <oodler@cpan.org>

BUGS

Please report.

LICENSE AND COPYRIGHT

Same as Perl/perl.