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

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

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/.

To install System::Wrapper, copy and paste the appropriate command in to your terminal.

cpanm

cpanm System::Wrapper

CPAN shell

perl -MCPAN -e shell
install System::Wrapper

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

INTERFACE

CLASS METHODS

SELECTOR METHODS

OBJECT METHODS

INSTALLATION

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

TODO

AUTHOR

LICENCE AND COPYRIGHT

Module Install Instructions