<<

NAME

Inca::Reporter - Module for creating Inca reporters

SYNOPSIS

  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'
  );

DESCRIPTION

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 METHODS

new(%attributes)

Class constructor that returns a new Inca::Reporter object. The constructor may be called with any of the following named attributes as parameters.

body

the XML body of the report. See the Inca Report schema for format.

completed

boolean (0 or 1) indicating whether or not the reporter has completed generating the information it is intended to produce

description

a verbose description of the reporter

fail_message

a message describing why the reporter failed to complete its task

name

the name that identifies this reporter

url

URL to get more information about the reporter

version

the version of the reporter; defaults to 0

addArg($name, $description, $default, $pattern)

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.

addDependency($dependency [, ...])

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.

argValue($name, $position)

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.

argValues($name)

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.

compiledProgramOutput(%params)

A convenience; compiles and runs a program, removes the source and exec files, and returns the program's combined stderr/out output. Recognized params:

code

the code to compile; required

compiler

the compiler to invoke; defaults to cc

language

source file language--one of 'c', 'c++', 'fortran', or 'java'; defaults to 'c'.

out_switch

the switch to use to specify the compiler output file; defaults to '-o '

switches

additional switches to pass to the compiler; defaults to ''

timeout

max seconds compilation/execution may take; sets $? to a non-zero value and returns any partial program output on time-out

failPrintAndExit($msg)

A convenience; calls setResult(0, $msg) and print( ) before exiting the reporter.

getBody( )

Returns the body of the report.

getCompleted( )

Returns the completion indicator of the reporter.

getCwd( )

Returns the initial working directory of the reporter.

getDescription( )

Returns the description of the reporter.

getFailMessage( )

Returns the failure message of the reporter.

getName( )

Returns the name that identifies this reporter.

getUrl( )

Returns the url which describes the reporter in more detail.

getVersion( )

Returns the version of the reporter.

log($type, @msgs)

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

loggedCommand($cmd, $timeout)

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.

print($verbose)

A convenience; prints report($verbose) to stdout.

processArgv(@ARGV)

Processes @ARGV which is a list of command-line arguments of the form:

-name1=value1 -name2=value2 ...

The following options are predefined:

help
yes

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.

no (default)

Normal reporter execution.

log
0 (default)

log no messages

1

log error messages

2

log error and warning messages

3

log error, warning, and system messages

4

log error, warning, system, and info messages

5

log error, warning, system, info, and debug messages

debug

log only debug messages

error

log only error messages

info

log only info messages

system

log only system messages

warn

log only warning messages

verbose
0

print will only produce "completed" or "failed".

1 (default)

print will produce Inca Report XML.

2

print will produce Inca Report XML that includes help information.

version
yes

Prints the reporter version number and exits.

no (default)

Normal reporter execution.

report($verbose)

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.

reportBody( )

Constructs and returns the XML contents of the report body. Child classes should override the default implementation, which returns undef.

setBody($body)

Sets the body of the report to $body.

setCompleted($completed)

Sets the completion indicator of the reporter to $completed.

setCwd($cwd)

Sets the initial working directory of the reporter to $cwd.

setDescription($description)

Sets the description of the reporter to $description.

setFailMessage($msg)

Sets the failure message of the reporter to $msg.

setName($name)

Sets the name that identifies this reporter to $name.

setResult($completed, $msg)

A convenience; calls setCompleted($completed) and setFailMessage($msg).

setUrl($url)

Sets the url for the reporter to $url.

setVersion($version)

Sets the version of the reporter to $version. Recognizes and parses CVS revision strings.

tempFile(@paths)

A convenience. Adds each element of @paths to a list of temporary files that will be deleted automatically when the reporter is destroyed.

xmlElement($name, $escape, @contents)

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.

EXAMPLE

  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>

AUTHOR

Shava Smallen <ssmallen@sdsc.edu>

<<