PITA::XML::Report - A PITA report on the results of zero or more installs

  # Create a new empty report file
  $report = PITA::XML::Report->new;

  # Load an existing report
  $report = PITA::XML::Report->read('filename.pita');

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.

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

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

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

The installs method returns all of the PITA::XML::Install objects from the PITA::XML as a list.

  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.

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.

Adam Kennedy <adamk@cpan.org>, http://ali.as/

The Perl Image-based Testing Architecture (http://ali.as/pita/)

Copyright 2005 - 2011 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.