NAME
PITA::XML::Report - A PITA report on the results of zero or more installs
SYNOPSIS
# Create a new empty report file
$report = PITA::XML::Report->new;
# Load an existing report
$report = PITA::XML::Report->read('filename.pita');DESCRIPTION
The Perl Image Testing Architecture (PITA) is designed to provide a highly modular and flexible set of components for doing testing of Perl distributions.
Within PITA, the PITA::XML::Report module provides the primary method of reporting the results of installation attempts.
The PITA::XML::Report class itself provides a way to create a set of testing results, and then store (and later recover) these results as you wish to a file.
A single PITA report file consists of structured XML that can be validated against a known schema, while storing a large amount of testing data without any ambiguity or the edge cases you may find in a YAML, email or text-file file.
The ability to take testing results from another arbitrary user and validate them also makes implementing a parser very simple, and thus allows the creation of aggregators and processing systems without undue thoughts about the report files themselves.
METHODS
validate
# Validate a file without loading it
PITA::XML::Report->validate( 'filename.pita' );
PITA::XML::Report->validate( $filehandle );The validate static method provides standalone validation of a file or file handle, without creating a PITA::XML::Report object.
Returns true, or dies if it fails to validate the file or file handle.
new
# Create a new (empty) report file
$empty = PITA::XML::Report->new;The new constructor creates a new, empty, report.
Returns a new PITA::XML::Report object, or undef on error.
read
# Load an existing file
$report = PITA::XML::Report->read( 'filename.pita' );
$report = PITA::XML::Report->read( $filehandle );The read constructor takes a file name or handle and parses it to create a new PITA::XML::Report object.
If passed a file handle object, it must be seekable (an IO::Seekable subclass) as the file will need to be read twice. The first pass validates the file against the schema, and the second populates the object with PITA::XML::Install reports.
Returns a new PITA::XML::Report object, or dies on error (most often due to problems validating an incorrect file).
add_install
# Add a new install object to the report
$report->add_install( $install );All PITA::XML files can contain more than one install report.
The add_install method takes a single PITA::XML::Install object as a parameter and adds it to the PITA::XML object.
installs
The installs method returns all of the PITA::XML::Install objects from the PITA::XML as a list.
write
my $output = '';
$report->write( \$output );
$report->write( 'filename.pita' );The write method is used to save the report out to a named file, or to a string by passing it by reference.
It takes a single parameter, which can be either an XML SAX Handler (any object that isa XML::SAX::Base) or any value that is legal to pass as the Output parameter to XML::SAX::Writer's new constructor.
Returns true when the file is written, or dies on error.
SUPPORT
Bugs should be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PITA-XML
For other issues, contact the author.
AUTHOR
Adam Kennedy <adamk@cpan.org>, http://ali.as/
SEE ALSO
The Perl Image-based Testing Architecture (http://ali.as/pita/)
COPYRIGHT
Copyright 2005 - 2009 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.