/ 
Lingua-AtD-1.160790
River stage zero No dependents
/ Lingua::AtD

NAME

Lingua::AtD - Provides an OO wrapper for After the Deadline grammar and spelling service.

VERSION

version 1.160790

SYNOPSIS

use Lingua::AtD;

# Create a new service proxy
my $atd = Lingua::AtD->new( {
    host     => 'service.afterthedeadline.com',
    port     => 80,
    throttle => 2,
});

# Run spelling and grammar checks. Returns a Lingua::AtD::Response object.
my $doc_check = $atd->check_document('Text to check.');
# Loop through reported document errors.
foreach my $atd_error ($doc_check->get_errors()) {
    # Do something with...
    print "Error string: ", $atd_error->get_string(), "\n";
}

# Run only grammar checks. Essentially the same as
# check_document(), sans spell-check.
my $grmr_check = $atd->check_grammar('Text to check.');
# Loop through reported document errors.
foreach my $atd_error ($grmr_check->get_errors()) {
    # Do something with...
    print "Error string: ", $atd_error->get_string(), "\n";
}

# Get statistics on a document. Returns a Lingua::AtD::Scores object.
my $atd_scores = $atd->stats('Text to check.');
# Loop through reported document errors.
foreach my $atd_metric ($atd_scores->get_metrics()) {
    # Do something with...
    print $atd_metric->get_type(), "/", $atd_metric->get_key(),
        " = ", $atd_metric->get_value(), "\n";
}

DESCRIPTION

Lingua::AtD provides an OO-style interface for After the Deadline's grammar and spell checking services.

METHODS

new

This constructor takes four arguments, all optional. The sample below shows the defaults.

$atd = Lingua::AtD->new({
    api_key  => 'Lingua-AtD',
    host     => 'service.afterthedeadline.com',
    port     => 80,
    throttle => 2,
});
api_key

API key used to access the service. Defaults to this package's name plus 32 hex digits (i.e. Lingua-AtD-7b8391f59fd9fa4246b2c69cd8793b88). See the API Documentation for requirements.

host

Host for the AtD service. Defaults to the public host: service.afterthedeadline.com. AtD's software is open source, and it's entirely possible to download and set up your own private AtD service. See the AtD Project website for details.

port

Port for the AtD service. Defaults to the standard http port: 80. AtD's software is open source, and it's entirely possible to download and set up your own private AtD service. See the AtD Project website for details.

throttle

There's no API documentation stating such, but testing has shown that AtD service throws a 503 error if called too quickly. This specifies the number of seconds to wait between calls. The default is 2 and seems to work fine. If you see 503 errors, consider bumping this up more.

get_api_key

$atd->get_api_key();

Returns the API Key used to access the AtD service.

get_host

$atd->get_host();

Returns the host of the AtD service.

get_port

$atd->get_port();

Returns the port of the AtD service.

get_service_url

$atd->get_service();

Returns a formatted URL for the AtD service.

get_throttle

$atd->get_throttle();

Returns the number of seconds that must pass between calls to the AtD service.

set_throttle

$atd->set_throttle(3);

Sets the number of seconds that must pass between calls to the AtD service.

check_document

$atd_results = $atd->check_document('Some text stringg in badd nneed of prufreding.');

Invokes the document check service for some string of text and return a Lingua::AtD::Results object.

From the API Documentation: Checks a document and returns errors and suggestions

check_grammar

$atd_results = $atd->check_grammar('Some text stringg in badd nneed of prufreding.');

Invokes the grammar check service for some string of text and return a Lingua::AtD::Results object. This differs from check_document in that it only checks grammar and style, not spelling.

From the API Documentation: Checks a document (sans spelling) returns errors and suggestions

stats

$atd_scores = $atd->stats('Some text stringg in badd nneed of prufreding.');

Invokes the stats service for some string of text and return a Lingua::AtD::Scores object. This differs from check_document in that it only checks grammar and style, not spelling.

From the API Documentation: Returns statistics about the writing quality of a document

BUGS

No known bugs.

IRONY

Wouldn't it be kind of funny if I had a ton of spelling/grammar/style errors in my documentation? Yeah, it would. And I bet there are. Shame on me for not running my documentation through my own module.

SEE ALSO

See the API Documentation at After the Deadline's website.

NB: In the API Documentation, there is a fourth service called /info.slp. I do not plan to implement this. Each Lingua::AtD::Error supplies an informative URL when one is available. I see no reason to call this independently, but feel free to submit a patch if you find a reason.

AUTHOR

David L. Day <dday376@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by David L. Day.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.