NAME
    System::Wrapper - Class-wrapped system calls and qx operator

VERSION
    This document describes System::Wrapper version 0.0.1

SYNOPSIS
        use System::Wrapper;

        my $command = System::Wrapper->new();

        $command->interpreter( 'perl');
        $command->executable( 'program.pl');
        $command->arguments( [ 'first', {second_a => 2, second_b => 2}, {third => [1,2,3]} ] );
        $command->input( \@ARGV );
        $command->output( { '--output' => 'file'}, q{>} => 'file2' );
        $command->path( [$command->path, q{.}] );
        $command->capture = 1;
        $command->verbose = 1;
        print $command->command;
        $command->run;

DESCRIPTION
     This module wraps perl's C<system> call and c<qx> operator in an object-oriented
     interface. It provides utility methods for accomplishing things that are not very
     simple in C<system> and C<qx>. This includes in-situ I/O and call success via
     temporary filenames, C<system> call progress estimation, finding whether the
     executable and-or interpreter are on the path, validating filenames, cross-platform
     output operators and argument type specification.

     This module can be used as a generic wrapper around C<system> and C<qx>, or as
     a base class for building interfaces to utilities not available to C<perl> itself.

INTERFACE
  CLASS METHODS
    new(%args)
            my %args = (
                interpreter => undef, # optional: string
                executable  => undef, # required: string
                arguments   => undef, # optional: any nested structure of hashes,
                                      # arrays or scalar references
                input       => undef, # optional: scalar or array reference
                output      => undef, # optional: hash reference of form { spec => file }
                                      # eg:   { '>' => 'out' } or { '--output' => 'out' }
                capture     => undef, # optional: return stdout, instead of exit code,
                                      # via $self->run
                path        => [ grep $_, File::Spec->path, q{.} ]
                                      # required: path of directories on which to look for
                                      # interpreter and executable programs
            );

            my $command = System::Wrapper->new(%args);

  SELECTOR METHODS
    new interpreter executable arguments input output path capture command
    run _program_in_path _canonical _flatten DESTROY

    server_uri()
    server_uri($uri)
        Default $uri: <http://api.wordnik.com/api-v3>

    api_key()
    api_key($key)
        Required $key: Your API key, which can be requested at
        <http://api.wordnik.com/signup/>.

    version()
    version($version)
        Default $version: *3*. Only API version 3 (the latest) is currently
        supported.

    format()
    format($format)
        Default $format: *json*. Other accepted formats are *xml* and
        *perl*.

    cache()
    cache($cache)
        Default $cache: *10*. Number of requests to cache. Deletes the
        oldest request if cache fills up.

    debug()
    debug($debug)
        Default $debug: *0*. Don't sent GET requests to Wordnik. Return the
        actual request as a string.

  OBJECT METHODS
    word($word, %args)
        This returns the word you requested, assuming it is found in our
        corpus. See <http://docs.wordnik.com/api/methods#words>.

        $word is the word to look up. %args accepts:

        Default "useSuggest": *false*. Return an array of suggestions, if
        available.

        Default "literal": *true*. Return non-literal matches.

        If the suggester is enabled, you can tell it to return the best
        match with "useSuggest=true" and "literal=false".

    phrases($word, %args)
        You can fetch interesting bi-gram phrases containing a word. The
        "mi" and "wlmi" elements refer to "mutual information" and "weighted
        mutual information" and will be explained in detail via future blog
        post. See <http://docs.wordnik.com/api/methods#phrases>.

        $word is the word to look up. %args accepts:

        Default "count": *5*. Specify the number of results returned.

    definitions($word, %args)
        Definitions for words are available from Wordnik's keying of the
        Century Dictionary and parse of the Webster GCIDE. The Dictionary
        Model XSD is available in
        <http://github.com/wordnik/api-examples/blob/master/docs/dictionary.
        xsd> in GitHub. See
        <http://docs.wordnik.com/api/methods#definitions>.

        $word is the word to look up. %args accepts:

        Default "count": *5*. Specify the number of results returned.

        Default "partOfSpeech": *empty*. Specify one or many part-of-speech
        types for which to return definitions. Pass multiple types as an
        array reference.

        The available partOfSpeech values are:

            [noun, verb, adjective, adverb, idiom, article, abbreviation, preposition, prefix, interjection, suffix]

    examples($word)
        You can retrieve 5 example sentences for a words in Wordnik's alpha
        corpus. Each example contains the source document and a source URL,
        if it exists. See <http://docs.wordnik.com/api/methods#examples>.

        $word is the word to look up.

    related($word, %args)
        You retrieve related words for a particular word. See
        <http://docs.wordnik.com/api/methods#relateds>.

        $word is the word to look up. %args accepts:

        Default "type": *empty*. Return one or many relationship types. Pass
        multiple types as an array reference.

        The available type values are:

            [synonym, antonym, form, equivalent, hyponym, variant]

    frequency($word)
        You can see how common particular words occur in Wordnik's alpha
        corpus, ordered by year. See
        <http://docs.wordnik.com/api/methods#freq>.

        $word is the word to look up.

    punctuationFactor($word)
        You can see how common particular words are used with punctuation.
        See <http://docs.wordnik.com/api/methods#punc>.

        $word is the word to look up.

    suggest($word, %args)
        The autocomplete service gives you the opportunity to take a word
        fragment (start of a word) and show what other words start with the
        same letters. The results are based on corpus frequency, not static
        word lists, so you have access to more dynamic words in the
        language. See <http://docs.wordnik.com/api/methods#auto>.

        $word is the word to look up. %args accepts:

        Default "count": *5*. Specify the number of results returned.

        Default "startAt": *0*. You can also specify the starting index for
        the results returned. This allows you to paginate through the
        matching values.

    wordoftheday
        You can fetch Wordnik's word-of-the day which contains definitions
        and example sentences. See
        <http://docs.wordnik.com/api/methods#wotd>.

    randomWord(%args)
        You can fetch a random word from the Alpha Corpus. See
        <http://docs.wordnik.com/api/methods#random>.

        %args accepts:

        Default "hasDictionaryDef": *true*. You can ask the API to return
        only words where there is a definition available.

INSTALLATION
    To install this module type the following:

       perl Build.PL
       Build
       Build test
       Build install

    or

       perl Makefile.PL
       make
       make test
       make install

DIAGNOSTICS
    "Can't access '$key' field in class $class"
        Private or inexistent member variable.

    "Invalid argument key or value: '$type'"
        Inexistent query parameter, or wrong value passed to existing
        parameter.

    "Parameter 'partOfSpeech' requires a reference to an array"
        partOfSpeech => [qw/.../].

    "Parameter 'type' requires a reference to an array"
        type => [qw/.../].

    "The operation you requested requires JSON to be installed"
        perl -MCPAN -e 'install JSON'.

    "Unsupported api format: '$format'"
        Supported formats are 'perl', 'json', 'xml'.

    "Unsupported api version: '$version'"
        The only API version supported by this module is 3.

CONFIGURATION AND ENVIRONMENT
    System::Wrapper requires no configuration files or environment
    variables.

DEPENDENCIES
    This module requires the core modules "Test::More", "version" and
    "Carp", and "LWP::UserAgent" from "CPAN". Additionally, it
    recommends-requires "JSON" from "CPAN" for getting data in Perl data
    structures.

INCOMPATIBILITIES
    None reported.

BUGS AND LIMITATIONS
    No bugs have been reported.

    Response headers are not checked for 404s, etc. Likewise, response data
    is not post-processed in any way, other than optionally being parsed
    from "JSON" to "Perl" data structures. Data::Dumper should be of help
    there.

    Please report any bugs or feature requests to
    "bug-www-wordnik-api@rt.cpan.org", or through the web interface at
    <http://rt.cpan.org>.

TODO
    Error checking
        Implement basic HTTP error checking on response headers.

    Post-processing
        Add filtering methods on response data.

AUTHOR
    Pedro Silva "<pedros@berkeley.edu>"

LICENCE AND COPYRIGHT
    Copyright (c) 2010, Pedro Silva "<pedros@berkeley.edu>". All rights
    reserved.

    This program is free software: you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program. If not, see <http://www.gnu.org/licenses/>. 880:
    final indentation level: 1

    Final nesting depth of '('s is 1 The most recent un-matched '(' is on
    line 409 409: _err( "%s: $spec", _this_sub_name(2), @args; ^ 880: To
    save a full .LOG file rerun with -g