Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Boulder::XML(3)	      User Contributed Perl Documentation      Boulder::XML(3)

       Boulder::XML - XML format input/output for Boulder streams

	  use Boulder::XML;

	  $stream = Boulder::XML->newFh;

	  while	($stone	= <$stream>) {
	       print $stream $stone;

       Boulder::XML generates BoulderIO	streams	from XML files and/or streams.
       It is also able to output Boulder Stones	in XML format.	Its semantics
       are similar to those of Boulder::Stream,	except that there is never any
       pass-through behavior.

       Because XML was not designed for	streaming, some	care must be taken
       when reading an XML document into a series of Stones.  Consider this
       XML document:

	<?xml version="1.0" standalone="yes"?>

	  <Author>Lincoln Stein</Author>
	  <Author>Jean Siao</Author>
	  <Date>September 29, 1999</Date>
	  <Copyright copyrighted="yes">1999 Lincoln Stein</Copright>
	      This is the abstract.  It	is not anything	very fancy,
	      but it will do.
	       <Author>Fitchberg J</Author>
	       <Journal>Journal	of Irreproducible Results</Journal>
	       <Author>Clemenson V</Author>
	       <Author>Ruggles M</Author>
	       <Journal>Journal	of Aesthetic Surgery</Journal>

       Ordinarily the document will be construed as a single Paper tag
       containing subtags Author, Date,	Copyright, Abstract, and so on.
       However it might	be desirable to	fetch out just the citation tags as a
       series of Stones.  In this case,	you can	declare	Citation to be the top
       level tag by passing the	-tag argument to new().	Now calling get() will
       return each of the three	Citation sections in turn.  If no tag is
       explicitly declared to be the top level tag, then Boulder::XML will
       take the	first tag it sees in the document.

       It is possible to stream	XML files.  You	can either separate them into
       separate	documents and use the automatic	ARGV processing	features of
       the BoulderIO library, or separate the XML documents using a delimiter
       string similar to the delimiters	used in	MIME multipart documents.  By
       default,	BoulderIO uses a delimiter of <!--Boulder::XML-->.

       This is not a general XML parsing engine! Instead, it is	a way to
       represent BoulderIO tag/value streams in	XML format.  The module	uses
       XML::Parser to parse the	XML streams, and therefore any syntactic error
       in the stream can cause the XML parser to quit with an error.  Another
       thing to	be aware of is that there are certain XML constructions	that
       will not	translate into BoulderIO format, specifically free text	that
       contains	embedded tags.	This is	OK:

	 <Author>Jean Siao</Author>

       but this	is not:

	 <Author>The <Emphatic>extremely illustrious</Emphatic>	Jean Siao</Author>

       In BoulderIO format, tags can contain other tags	or text, but cannot
       contain a mixture of tags and text.

       $stream = Boulder::XML->new(*IN,*OUT);
       $stream =
	   new() creates a new Boulder::XML stream that	can be read from or
	   written to.	All arguments are optional.

	    -in	   Filehandle to read from.
		   If a	file name is provided, will open the file.
		   Defaults to the magic <> filehandle.

	    -out   Filehandle to write to.
		   If a	file name is provided, will open the file for writing.
		   Defaults to STDOUT

	    -tag   The top-level XML tag to consider as	the Stone record.  Defaults
		   to the first	tag seen when reading from an XML file,	or to
		   E<lt>StoneE<gt> when	writing	to an output stream without
		   previously having read.

	    -delim Delimiter to	use for	delimiting multiple Stone objects in an
		   XML stream.

	    -strip If true, automatically strips leading and trailing whitespace
		   from	text contained within tags.

       $fh = Boulder::XML->newFh(*IN,*OUT);
       $fh =
	   The newFh() constructor creates a tied filehandle that can read and
	   write Boulder::XML streams.	Invoking <> on the filehandle will
	   perform a get(), returning a	Stone object.  Calling print() on the
	   filehandle will perform a put(), writing a Stone object to output
	   in XML format.

       $stone =	$stream->get()
       $done = $stream->done
	   All these methods have the same semantics as	the similar methods in
	   Boulder::Stream, except that	pass-through behavior doesn't apply.

       Lincoln D. Stein	<>, Cold	Spring Harbor Laboratory, Cold
       Spring Harbor, NY.  This	module can be used and distributed on the same
       terms as	Perl itself.

       Boulder,	Boulder::Stream, Stone

perl v5.32.1			  1999-11-30		       Boulder::XML(3)


Want to link to this manual page? Use this URL:

home | help