NAME PITA::Report - Create, load, save and manipulate PITA-XML reports STATUS This is an experimental release for demonstration purposes only. Please note the .xsd schema file may not install correctly as yet. SYNOPSIS # Create a new empty report file my $report = PITA::Report->new; # Load an existing report my $report = PITA::Report->new('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::Report module provides the primary method of reporting the results of installation attempts. The PITA::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 new # Create a new (empty) report file $empty = PITA::Report->new; # Load an existing file $report = PITA::Report->new( 'filename.pita' ); $report = PITA::Report->new( $filehandle ); The "new" constructor takes a file name or handle and parses it to create a new "PITA::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::Report::Install reports. If passed no param, it creates a new empty report, ready for you to fill with PITA::Report::Install objects you will generate yourself. Returns a new "PITA::Report" object, or dies on error (most often due to problems validating an incorrect file). validate # Validate a file without loading it PITA::Report->validate( 'filename.pita' ); PITA::Report->validate( $filehandle ); The "validate" static method provides standalone validation of a file or file handle, without creating a "PITA::Report" object. Returns true, or dies if it fails to validate the file or file handle. add_install # Add a new install object to the report $report->add_install( $install ); All "PITA::Report" files can contain more than one install report. The "add_install" method takes a single PITA::Report::Install object as a parameter and adds it to the "PITA::Report" object. installs The "installs" method returns all of the PITA::Report::Install objects from the "PITA::Report" 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. 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 For other issues, contact the author. AUTHOR Adam Kennedy , SEE ALSO The Perl Image-based Testing Architecture () COPYRIGHT Copyright 2005 Adam Kennedy. All rights reserved. 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.