NAME

PICA::Writer - Write and count PICA+ records and fields

DESCRIPTION

This module contains a simple class to write PICA+ records and fields. Several output targets (file, GLOB, IO:Handle, string, null) and formats (XML, plain, normalized) are supported. The number of written records and fields is counted so you can also use the class as a simple counter. Additional statistics of fields and subfields can also be enabled.

SYNOPSIS

  $writer = PICA::Writer->new( \*STDOUT );
  $writer = PICA::Writer->new( "output.pica" );
  $writer = PICA::Writer->new( \$string, format => 'xml' );
  $writer = PICA::Writer->new( ); # no output

  $writer->start();  # called implicitely by default

  $writer->write( $record );
  $writer->write( @records );
  $writer->write( $field1, $field2, $field3 );
  $writer->write( $comment, $record );

  $writer->output( "output.xml" );  
  $writer->output( \*STDOUT, format => 'plain' );  
  print "Failed to open writer" unless $writer; # PICA::Writer::ERROR == 0

  print $writer->counter() . " records written\n";
  print $writer->fields()  . " fields written\n";

  $writer->reset();  # reset counters

  print $writer->status() == PICA::Writer::ENDED ? "open" : "ended";
 
  $writer->end(); # essential to close end tags in XML and such

  use PICA::Record qw(writerecord);
  writerecord( $record, $file );

METHODS

new ( [ $output ] [ format => $format ] [ %options ] )

Create a new writer. See the output method for possible parameters. The status of the new writer is set to PICA::Writer::NEW (1) or PICA::Writer::ERROR (0). Boolean conversion is overloaded to return the status so you can easily check whether a writer is in error status.

The writer can also be used for statistics if you set the 'stats' option. With stats = 1 statistics is created on field level and with stats = 2 also on subfield level.

output ( [ $output ] [ format => $format ] [ %options ] )

Define the output handler for this writer. Record and field counters are not reset but the writer is ended with the end method if it had been started before. The output handler can be a filename, a GLOB, an IO:Handle object, a string reference, or undef. In addition you can specify the output format with the format parameter (plain or xml) and some options depending on the format, for instance 'pretty => 1' and 'stats => 0|1|2'.

The status of the writer is set to PICA::Writer::NEW or PICA::Writer::ERROR. This methods returns the writer itself which boolean conversion is overloaded to return the status so you can easily check the return value whether an error occurred.

reset ( [ $output ] )

Reset the writer by setting record and field counters to zero and returning the writer object. Optionally you can define a new output handler, so the following two lines are equal:

  $writer->output( $output )->reset();
  $writer->reset( $output );

The status of the writer will only be changed if you specify a new output handler.

write ( [ $comment | $record | $field ]* )

Write PICA::Field, PICA::Record objects, and comments (as strings) and record the writer object. The number of written records and fields is counted and can be queried with methods counter and fields.

  $writer->write( $record );
  $writer->write( @records );
  $writer->write( "record number " . $writer->counter(), $record );
  $writer->write( $field1, $field2 );

Writing single fields or mixing records and fields may not be possible depending on the output format and output handler.

Returns the writer object so you can chain calls:

  $writer->write( $r1 )->write( $r2 )->end;

start ( [ %options ] )

Start writing and return the writer object. Depending on the format and output handler a header is written. Afterwards the status is set to PICA::Writer::STARTED. You can pass optional parameters depending on the format.

  $writer->start( ); # default
  $writer->start( xslt => 'mystylesheet.xsl' );
  $writer->start( nsprefix => 'pica' );

This method is implicitely called the first time you write to a PICA::Writer that is not in status PICA::Writer::STARTED..

end ( )

Finish writing. Depending on the format and output handler a footer is written (for instance an XML end tag) and the output handler is closed. Afterwards the status is set to PICA::Writer::ENDED. If the writer had not been started before, the start method is called first.

Ending or writing to an already ended writer will throw an error. You can restart an ended writer with the output method or with the start method.

status ( )

Return the status which can be PICA::Writer::NEW, PICA::Writer::STARTED, PICA::Writer::ENDED, or PICA::Writer::ERROR.

records ( )

Returns the number of written records.

counter ( )

Alias for records().

fields ( )

Returns the number of written fields.

statlines ( )

Return a list of lines with statistics (if stats option had been set).

FUNCTIONS

xmlwriter ( %params )

Create a new XML::Writer instance and optionally write XML header and processing instruction. Relevant parameters include 'header' (boolean), 'xslt', NAMESPACES, PREFIX_MAP.

PRIVATE METHDOS

addfieldstat ( $field )

Add a field to the statistics.

addrecordstat ( $record )

Add a record to the statistics.

AUTHOR

Jakob Voss <jakob.voss@gbv.de>

LICENSE

Copyright (C) 2007-2009 by Verbundzentrale Goettingen (VZG) and Jakob Voss

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm PICA::Record

perl -MCPAN -e shell
install PICA::Record