NAME

FAQ::OMatic::API - a Perl API to manipulate FAQ-O-Matics

SYNOPSIS

 use FAQ::OMatic::API;
 my $fom_api = new FAQ::OMatic::API();

DESCRIPTION

"FAQ::OMatic::API" is a class that makes HTTP requests to a FAQ-O-Matic. It provides a way to manipulate a FAQ-O-Matic from Perl code. Operations are performed by making HTTP requests on the FAQ-O-Matic server; this ensures that any operation is performed in exactly the same environment as it would be if it were requested by a human using a web browser.

Setup

The following methods are used to set up an API object.

$fom_api = new FAQ::OMatic::API([$url, [$id, $pass]]);: Constructs a new "FAQ::OMatic::API" object that points at the FAQ whose CGI is at $url. Requests will be authenticated on behalf of FAQ user $id using password $pass.
$fom_api->setURL($url);: Sets the URL of the target FAQ's CGI. This is where requests will be sent.
$fom_api->setAuth($id, $pass);: Sets the ID and password that will be used to authenticate requests.
$fom_api->setAuth('query');: Passing in 'query' will cause the script to query the terminal for the "id" and "password" at runtime.

Queries

The following methods retrieve information about a FAQ-O-Matic.

$fom_api->getCategories()

Returns a list of the categories (by file name) in the FAQ.

$item = $fom_api->getItem($filename)

Returns a local FAQ::OMatic::Item object created by retrieving $filename from the FAQ. You can perform operations on the result such as:

 print $item->getTitle();

 $parentItem = $item->getParent();

 print $item->displayHTML({'render'=>'text'});

my ($rc, $result) = $fom_api->fuzzyMatch(['Parent Category','child cat'])

 my ($rc, $result) = $fom_api->fuzzyMatch(['Parent Category','child cat'])
 die $result if (not $rc);
 my $item = $fom_api->getItem($result->[0]);

"fuzzyMatch()" attempts to figure out which category the last string in its array argument represents. The category name is matched "fuzzily" against existing categories. If a unique match is found, it is returned (as an array ref "[$filename, $parent, $title]"). If the match is ambiguous, the previous array element is matched against the parents of the set of fuzzy matches. This is performed recursively until the child category is disambiguated.

Fuzzy matching means that

(a): You don't have to get the parent category names right if they're not needed to disambiguate the child category.
(b): Category names are matched without respect to case, spacing, or punctuation: only alphanumerics matter. Also, the name you supply only has to appear somewhere inside the one you want to match. (Exact matches are preferred; this allows you to match categories whose names are prefixes of other category names.)

Operations

The following methods perform operations on a FAQ-O-Matic.

$fom_api->newAnswer($parent, $title, $text): A new answer is created as a child of item $parent. The new answer has title $title and a single text part containing $text.

REQUIRES

LWP and its hierarchy of helper classes.