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

For other issues, contact the author.


Adam Kennedy <>,


The Perl Image-based Testing Architecture (


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