Inca::Reporter - Module for creating Inca reporters
use Inca::Reporter;
my $reporter = new Inca::Reporter(
name => 'hack.version',
version => 0.1,
description => 'A really helpful reporter description',
url => 'http://url.to.more.reporter.info'
);
This module creates Inca reporters--objects that produce XML that follows the Inca Report schema. The constructor may be called with a number of reporter attributes that can later be set and queried with their corresponding get/set functions (described below). For example,
my $reporter = new Inca::Reporter();
$reporter->setUrl('http://url.to.more.reporter.info');
$reporter->setVersion(0.1);
Class constructor that returns a new Inca::Reporter object. The constructor may be called with any of the following named attributes as parameters.
the XML body of the report. See the Inca Report schema for format.
boolean (0 or 1) indicating whether or not the reporter has completed generating the information it is intended to produce
a verbose description of the reporter
a message describing why the reporter failed to complete its task
the name that identifies this reporter
URL to get more information about the reporter
the version of the reporter; defaults to 0
Adds a command line argument (invocation syntax -name=value) to the reporter. If supplied, the optional $description will be included in the reporter help XML and display. If supplied, $default indicates that the argument is optional; the argValue method will return $default if the command line does not include a value for the argument. The optional $pattern specifies a pattern for recognizing valid argument values; the default is '.*', which means that any text is acceptable for the argument value.
Add one or more dependencies to the list of modules on which this reporter depends. Dependencies are reported as part of reporter help output to assist reporter repository tools in their retrievals. NOTE: dependencies on the standard Inca reporter library modules are added by the modules themselves, so a reporter only needs to invoke this method to report external dependencies. The Inca Reporter Instance Manager presently only supports dependencies on Inca repository packages, not packages from, e.g., CPAN.
Called after the processArgv method, this returns the value of the position'th instance (starting with 1) of the $name command-line argument. Returns the value of the last instance if position is not supplied. Returns undef if $name is not a recognized argument. Returns the default value for $name if it has one and $name is included fewer than $position times on the command line.
Called after the processArgv method, this returns an array of all values specified for the $name command-line argument. Returns undef if $name is not a recognized argument. Returns a single-element array containing the default value for $name if it has one and $name does not appear on the command line.
A convenience; compiles and runs a program, removes the source and exec files, and returns the program's combined stderr/out output. Recognized params:
the code to compile; required
the compiler to invoke; defaults to cc
source file language--one of 'c', 'c++', 'fortran', or 'java'; defaults to 'c'.
the switch to use to specify the compiler output file; defaults to '-o '
additional switches to pass to the compiler; defaults to ''
max seconds compilation/execution may take; sets $? to a non-zero value and returns any partial program output on time-out
A convenience; calls setResult(0, $msg) and print( ) before exiting the reporter.
Returns the body of the report.
Returns the completion indicator of the reporter.
Returns the initial working directory of the reporter.
Returns the description of the reporter.
Returns the failure message of the reporter.
Returns the name that identifies this reporter.
Returns the url which describes the reporter in more detail.
Returns the version of the reporter.
Appends each element of @msgs to the list of $type log messages stored in the reporter. $type must be one of 'debug', 'error', 'info', 'system', or 'warn'.
A convenience; appends $cmd to the 'system'-type log messages stored in the reporter, then returns `$cmd 2>&1`. If $timeout is specified and the command doesn't complete within $timeout seconds, aborts the execution of $cmd, sets $! to POSIX::EINTR and $? to a non-zero value, and returns any partial output.
A convenience; prints report($verbose) to stdout.
Processes @ARGV which is a list of command-line arguments of the form:
-name1=value1 -name2=value2 ...
The following options are predefined:
Prints help information describing the reporter inputs, then forces the reporter to exit. If the verbose level is 0, the output will be text; otherwise, it will be Inca Report XML.
Normal reporter execution.
log no messages
log error messages
log error and warning messages
log error, warning, and system messages
log error, warning, system, and info messages
log error, warning, system, info, and debug messages
log only debug messages
log only error messages
log only info messages
log only system messages
log only warning messages
print will only produce "completed" or "failed".
print will produce Inca Report XML.
print will produce Inca Report XML that includes help information.
Prints the reporter version number and exits.
Normal reporter execution.
Returns report text or XML, depending on the value (0, 1, 2) of $verbose. Uses the value of the -verbose switch if $verbose is undef.
Constructs and returns the XML contents of the report body. Child classes should override the default implementation, which returns undef.
Sets the body of the report to $body.
Sets the completion indicator of the reporter to $completed.
Sets the initial working directory of the reporter to $cwd.
Sets the description of the reporter to $description.
Sets the failure message of the reporter to $msg.
Sets the name that identifies this reporter to $name.
A convenience; calls setCompleted($completed) and setFailMessage($msg).
Sets the url for the reporter to $url.
Sets the version of the reporter to $version. Recognizes and parses CVS revision strings.
A convenience. Adds each element of @paths to a list of temporary files that will be deleted automatically when the reporter is destroyed.
Returns the XML element $name surrounding @contents. $escape should be true only for leaf elements; in this case, each special XML character (<>&) in @contents is replaced by the equivalent XML entity.
use strict;
use warnings;
use Inca::Reporter;
my $reporter = new Inca::Reporter(
name => 'selfPathReporter',
version => '1.0.0',
description => 'Reports the path to the reporter',
url => 'http://mothership.ufo.edu'
);
$reporter->processArgv(@ARGV);
$reporter->setBody($reporter->xmlElement('path', 1, $0));
$reporter->print();
Running this reporter with -verbose=1 will produce output that looks something like this.
<?xml version='1.0'?>
<rep:report xmlns:rep='http://inca.sdsc.edu/dataModel/report_2.1'>
<gmt>Tue Jan 7 07:55:44 2005</gmt>
<hostname>blue.ufo.edu</hostname>
<name>selfPathReporter</name>
<version>1.0.0</version>
<workingDir>/home/inca</workingDir>
<reporterPath>reporters/bin/selfPathReporter</reporterPath>
<args>
<arg>
<name>help</name>
<value>no</value>
</arg>
<arg>
<name>log</name>
<value></value>
</arg>
<arg>
<name>verbose</name>
<value>1</value>
</arg>
<arg>
<name>version</name>
<value>no</value>
</arg>
</args>
<body>
<path>sr</body>
</body>
<exitStatus>
<completed>true</completed>
</exitStatus>
</rep:report>
Shava Smallen <ssmallen@sdsc.edu>