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

FreeBSD Manual Pages

  
 
  

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

NAME
       XML::ValidWriter	- DOCTYPE driven valid XML output

SYNOPSIS
	  ## As	a normal perl object:
	  $writer = XML::ValidWriter->new(
	     DOCTYPE =>	$xml_doc_type,
	     OUTPUT => \*FH
	  ) ;
	  $writer->startTag( 'b1' ) ;
	  $writer->startTag( 'c2' ) ;
	  $writer->end ;

	  ## Writing to	a scalar:
	  $writer = XML::ValidWriter->new(
	     DOCTYPE =>	$xml_doc_type,
	     OUTPUT => \$buf
	  ) ;

	  ## Or, in scripting mode:
	  use XML::Doctype	   NAME	=> a, SYSTEM_ID	=> 'a.dtd' ;
	  use XML::ValidWriter qw( :all	:dtd_tags ) ;
	  b1 ;		      #	Emits <a><b1>
	  c2( attr=>"val" ) ; #	Emits </b1><b2><c2 attr="val">
	  endAllTags ;	      #	Emits </c2></b2></a>

	  ## If	you've got an XML::Doctype object handy:
	  use XML::ValidWriter qw( :dtd_tags ),	DOCTYPE	=> $doctype ;

	  ## If	you've saved a preparsed DTD as	a perl module
	  use FooML::Doctype::v1_0001 ;
	  use XML::ValidWriter qw( :dtd_tags ) ;

	  #
	  # This all assumes that the DTD contains:
	  #
	  #   <!ELEMENT	a ( b1,	b2?, b3* ) >
	  #	 <!ATTLIST   a aa1 CDATA       #REQUIRED >
	  #   <!ELEMENT	b1 ( c1	) >
	  #   <!ELEMENT	b2 ( c2	) >
	  #

STATUS
       Alpha.  Use and patch, don't depend on things not changing drastically.

       Many methods supplied by	XML::Writer are	not yet	supplied here.

DESCRIPTION
       This module uses	the DTD	contained in an	XML::Doctype to	enable
       compile-	and run-time checks of XML output validity.  It	also provides
       methods and functions named after the elements mentioned	in the DTD.
       If an XML::ValidWriter uses a DTD that mentions the element type	TABLE,
       that instance will provide the methods

	  $writer->TABLE( $content, ...attrs...	) ;
	  $writer->start_TABLE(	...attrs... ) ;
	  $writer->end_TABLE() ;
	  $writer->empty_TABLE(	...attrs... ) ;

       .  These	are created for	undeclared elements--those elements not
       explicitly declared with	an <!ELEMENT ..> declaration--as well.	If an
       element type name conflicts with	a method, it will not override the
       internal	method.

       When an XML::Doctype is parsed, the name	of the doctype defines the
       root node of the	document.  This	name can be changed, though, see
       XML::Doctype for	details.

       In addition to the object-oriented API, a function API is also
       provided.  This allows you to import most of the	methods	of
       XML::ValidWriter	as functions using standard import specifications:

	  use XML::ValidWriter qw( :all	) ; ## Could list function names instead

       ":all" does not import the functions named after	elements mentioned in
       the DTD,	you need to import those tags using ":dtd_tags":

	  use XML::Doctype NAME	=> 'foo', SYSTEM_ID => 'fooml.dtd' ;
	  use XML::ValidWriter qw( :all	:dtd_tags ) ;

       or

	  BEGIN	{
	     $doctype =	XML::Doctype->new( ... ) ;
	  }

	  use XML::ValidWriter DOCTYPE => $doctype, qw(	:all :dtd_tags ) ;

   XML::Writer API compatibility
       Much of the interface is	patterned after	XML::Writer so that it can
       possibly	be used	as a drop-in replacement.  It will take	awhile before
       this module emulates enough of XML::Writer to be	a drop-in replacement
       in situations where the more advanced XML::Writer methods are used.  If
       you find	you need a method not suported here, write it and send it in!

       This was	not derived from XML::Writer because XML::Writer does not
       expose it's stack.  Even	if it did, it's	might be difficult to store
       enough state in it's stack.

       Unlike XML::Writer, this	does not call in all of	the IO::* family, and
       method dispatch should be faster.  DTD-specific methods are also
       supported (see "AUTOLOAD").

   Quick and Easy Unix Filter Apps
       For quick applications that provide Unix	filter application
       functionality, XML::ValidWriter and XML::Doctype	cooperate to allow you
       to

       1.  Parse a DTD at compile-time and set that as the default DTD for the
	   current package.  This is done using	the

	      use XML::Doctype NAME => 'FooML, SYSTEM_ID => 'fooml.dtd'	;

	   syntax.

       2.  Define and export a set of functions	corresponding to start and end
	   tags	for all	declared and undeclared	ELEMENTs in the	DTD.  This is
	   done	by using the ":dtd_tags" export	symbol like so:

	      use XML::Doctype	   NAME	=> 'FooML, SYSTEM_ID =>	'fooml.dtd' ;
	      use XML::ValidWriter qw(:dtd_tags) ;

	   If the elements a, b_c, and d-e are referred	to in the DTD, the
	   following functions will be exported:

	      a()	 end_a()       # like startTag(	'a', ... ) and endTag( 'a' )
	      b_c()	 end_b_c()
	      d_e()	 end_d_e()     {'d-e'}()     {'end_d-e'}()

	   These functions emit	only tags, unlike the similar functions	found
	   in CGI.pm and XML::Generator, which also allow you to pass content
	   in as parameters.

	   See below for details on conflict resolution	in the mapping of
	   entity names	containing /\W/	to Perl	subroutine names.

	   If the elements declared in the DTD might conflict with functions
	   in your package namespace, simple put them in some safe namespace:

	      package FooML ;
	      use XML::Doctype	       NAME => 'FooML',	SYSTEM_ID => 'fooml.dtd' ;
	      use XML::ValidWriter qw(:dtd_tags) ;

	      package Whatever ;

	   The advantage of importing these subroutine names is	that perl can
	   then	detect use of unknown tags at compile time.

	   If you don't	want to	use the	default	DTD, use the "-dtd" option:

	      BEGIN { $dtd = XML::Doctype->new(	.... ) }
	      use XML::ValidWriter qw(:dtd_tags), -dtd => \$dtd	;

       3.  Use the default DTD to validate emitted XML.	 startTag() and
	   endTag() will check the tag being emitted against the list of
	   currently open tags and either emit a minimal set of	missing	end
	   and start tags necessary to achieve document	validity or produce
	   errors or warnings.

	   Since the functions created by the ":dtd_tags" export symbol	are
	   wrappers around startTag() and endTag(), they provide this
	   functionality as well.

	   So, if you have a DTD like

	      <!ELEMENT	a ( b1,	b2?, b3* ) >

		  <!ATTLIST   a	aa1 CDATA	#REQUIRED >

	      <!ELEMENT	b1 ( c1	) >
	      <!ELEMENT	b2 ( c2	) >
	      <!ELEMENT	b3 ( c3	) >

	   you can do this:

	      use XML::Doctype	   NAME	=> 'a',	SYSTEM_ID => 'a.dtd' ;
	      use XML::ValidWriter ':dtd_tags' ;

	      getDoctype->element_decl('a')->attdef('aa1')->default_on_write('foo') ;

	      a	;
		 b1 ;
		    c1 ;
		    end_c1 ;
		 end_b1	;
		 b3 ;
		    c3(	-attr => val ) ;
		    end_c3 ;
		 end_b3	;
	      end_a ;

	   and emit a document like

	      <a aa1="foo">
		 <b1>
		    <c1	/>
		 </b1>
		 <b3>
		    <c3	attr =>	"val" />
		 </b3>
	      </a>

	   .

OUTPUT OPTIMIZATION
       XML is a	very simple langauge and does not offer	a lot of room for
       optimization.  As the spec says "Terseness in XML markup	is of minimal
       importance."  XML::ValidWriter does optimize the	following on output:

       "<a...></a>"   becomes '<a... />'

       Spurious	emissions of "]]><![CDATA[" are	supressed.

       XML::ValidWriter	chooses	whether	or not to use a	<![CDATA[...]]>
       section or simply escape	'<' and	'&'.  If you are emitting content for
       an element in multiple calls to "characters", the first call decides
       whether or not to use CDATA, so it's to your advantage to emit as much
       in the first call as possible.  You can do

	  characters( @lots_of_segments	) ;

       if it helps.

METHODS	AND FUNCTIONS
       All of the routines in this module can be called	as either functions or
       methods unless otherwise	noted.

       To call these routines as functions use either the DOCTYPE or :dtd_tags
       options in the parameters to the	use statement:

	  use XML::ValidWriter DOCTYPE => XML::Doctype->new( ... ) ;
	  use XML::ValidWriter qw( :dtd_tags ) ;

       This associates an XML::ValidWriter and an XML::Doctype with the
       package.	 These are used	by the routines	when called as functions.

       new
	      $writer =	XML::ValidWriter->new( DTD => $dtd, OUTPUT => \*FH ) ;

	   Creates an XML::ValidWriter.

	   The value passed for	OUTPUT may be:

	   a SCALAR ref
	       if you want to direct output to append to a scalar.  This
	       scalar is truncated whenever the	XML::ValidWriter object	is
	       reset() or DESTROY()ed

	   a file handle glob ref or a reference to an IO object
	       XML::ValidWriter	does not load IO.  This	is the only mode
	       compatible with XML::Writer.

	   a file name
	       A simple	scalar is taken	to be a	filename to be created or
	       truncated and emitted to.  This file will be closed when	the
	       XML::ValidWriter	object is reset	or deatroyed.

	   NOTE: if you	leave OUTPUT undefined,	then the currently select()ed
	   output is used at each emission (ie calling select()	can alter the
	   destination mid-stream).  This eases	writing	command	line filter
	   applications, the select() interaction is unintentional, and	please
	   don't depend	on it.	I reserve the right to cache the select()ed
	   filehandle at creation time or at time of first emission at some
	   point in the	future.

       import
	   Can't think of why you'd call this method directly, it gets called
	   when	you use	this module:

	      use XML::ValidWriter qw( :all ) ;

	   In addition to the normal functionality of exporting	functions like
	   startTag() and endTag(), XML::ValidWriter's import()	can create
	   functions corresponding to all elements in a	DTD.  This is done
	   using the special ":dtd_tags" export	symbol.	 For example,

	      use XML::Doctype	   NAME	=> 'FooML', SYSTEM_ID => 'fooml.dtd' ;
	      use XML::ValidWriter qw( :dtd_tags ) ;

	   where fooml.dtd referse to a	tag type of 'blurb' causes these
	   functions to	be imported:

	      blurb()	      #	calls defaultWriter->startTag( 'blurb',	@_ ) ;
	      blurb_element() #	calls defaultWriter->dataElement( 'blurb', @_ )	;
	      empty_blurb()   #	calls defaultWriter->emptyTag( 'blurb',	@_ ) ;
	      end_blurb()     #	calls defaultWriter->endTag( 'blurb' ) ;

	   The range of	characters for element types is	much larger than the
	   range of characters for bareword perl subroutine names, which are
	   limited to [a-zA-Z0-9_].  In	this case, XML::ValidWriter will
	   export an oddly named function that you can use a symbolic
	   reference to	call (you will need "no	strict 'refs' ;" if you	are
	   doing a "use	strict ;"):

	      &{"space-1999:moonbase"}(	...attributes ... ) ;

	   .  XML::ValidWriter will also try to	fold the name in to bareword
	   space by converting /\W/ symbols to '_'.  If	the resulting function
	   name,

	      space_1999_moonbase( ...attributes... ) ;

	   has not been	generated and is not the name of an element type, then
	   it will also	be exported.

	   If you are using a DTD that might introduce function	names that
	   conflict with existing ones,	simple export them in to their own
	   namespace:

	      package ML ;

	      use XML::Doctype	   NAME	=> 'foo', SYSTEM_ID => 'fooml.dtd' ;
	      use XML::ValidWriter qw( :dtd_tags ) ;

	      package main ;

	      use XML::ValidWriter qw( :all ) ;

	      ML::foo ;
	      ML::c2 ;
	      ML::c1 ;
	      ML::end_a	;

	   I gave serious thought to converting	':' in element names to	'::'
	   in function declarations, which might work well in the
	   functions-in-their-own- namespace case, but not in the default
	   case, since Perl does not (yet) have	relative namespaces. Another
	   alternative is to allow a mapping of	XML namespaces to Perl
	   namespaces to be done.

       characters
	      characters( "escaped text", "& more" ) ;
	      $writer->characters( "escaped text", "& more" ) ;

	   Emits character data.  Character data will be escaped before
	   output, by either transforming '<' and '&' to &lt; and &amp;, or by
	   enclosing in	a '"<![CDATA[...]]>"' bracket, depending on which will
	   be more human-readable, according to	the module.

       dataElement
	      $writer->dataElement( $tag ) ;
	      $writer->dataElement( $tag, $content ) ;
	      $writer->dataElement( $tag, $content, attr1 => $val1, ...	) ;
	      dataElement( $tag	) ;
	      dataElement( $tag, $content ) ;
	      dataElement( $tag, $content, attr1 => $val1, ... ) ;

	   Does	the equivalent to

	      ## Split the optional args in to attributes and elements arrays.
	      $writer->startTag( $tag, @attributes ) ;
	      $writer->characters( $content ) ;
	      $writer->endTag( $tag ) ;

	   This	function is exportable as dataElement(), and is	also exported
	   for each element 'foo' found	in the DTD as foo().

       defaultWriter
	      $writer =	defaultWriter ;	      ## Not a method!
	      $writer =	defaultWriter( 'Foo::Bar' ) ;

	   Returns the default XML::ValidWriter	for the	given package, or the
	   current package if none is specified.  This is useful for getting
	   at methods like "reset" that	are not	also functions.

	   Croaks if no	default	writer has been	defined	(see "import").

       doctype
	      #	Using the writer's associated DTD:
	      doctype ;

	      #	Ignoring the writer's associated DTD:
	      doctype( $type ) ;
	      doctype( $type, undef, $system ) ;
	      doctype( $type, $public, $system ) ;

	      $writer->doctype ;
	      ...etc

	   See "internalDoctype" to emit the entire DTD	in the document.

	   This	checks to make sure that no doctype or elements	have been
	   emitted.

	   A warning is	emitted	if standalone="yes" was	specified in the
	   <?xml..?> declaration and a system id is specified.	This is
	   extremely likely to be an error.  If	you need to silence the
	   warning, write me (see below).

	   Passing '' or '0' (zero) as a $public_id or as a $system_id also
	   generates a warning,	as these are extremely likely to be errors.

       emptyTag
	      emptyTag(	$tag[, attr1 =>	$val1... ] ) ;
	      $writer->emptyTag( $tag[,	attr1 => $val1... ] ) ;

	   Emits an empty tag like '<foo />'.  The extra space is for
	   compatibility with XHTML.

       endTag
	      endTag ;
	      endTag( 'a' ) ;
	      $writer->endTag ;
	      $writer->endTag( 'a' ) ;

	   Prints one or more end tags.	 The tag name is optional and defaults
	   to the most recently	emitted	start tag if not present.

	   This	will emit as many close	tags as	necessary to close the
	   supplied tag	name, or will emit an error if the tag name specified
	   is not open in the output document.

       end
	      $writer->end ;	  # Not	a function!!

	   Emits all necessary end tags	to close the document.	Available as a
	   method only,	since 'end' is a little	to generic to be exported as a
	   function name, IMHO.	 See 'endAllTags' for the plain	function
	   equivalent function.

       endAllTags
	      endAllTags ;
	      $writer->endAllTags ;

	   A plain function that emits all necessart end tags to close the
	   document.  Corresponds to the method	"end", but is exportable as a
	   function/

       exportDTDTags
	      $writer->exportDTDTags() ;
	      $writer->exportDTDTags( $to_pkg )	;

	   Exports the tags found in the DTD to	the caller's namespace.

       getDataMode
	      $m = getDataMode ;
	      $m = $writer->getDataMode	;

	   Returns TRUE	if the writer is in DATA_MODE.

       getDoctype
	      $dtd = getDoctype	;
	      $dtd = $writer->getDoctype ;

	   This	is used	to get the writer's XML::Doctype object.

       getOutput
	      $fh = getOutput ;
	      $fh = $writer->getOutput ;

	   Gets	the filehandle an XML::ValidWriter sends output	to.

       rawCharacters
	      rawCharacters( "<unescaped text>", "& more text" ) ;
	      $writer->rawCharacters( "<unescaped text>", "& more text"	) ;

	   This	allows you to emit raw text without any	escape processing.
	   The text is not examined for	tags, so you can invalidate your
	   document and	even corrupt it's well-formedness.

       reset
	      $writer->reset ;	      #	Not a function!

	   Resets a writer to be initialized, but not have emitted anything.

	   This	is useful if you need to abort output, but want	to reuse the
	   XML::ValidWriter.

       setDataMode
	      setDataMode( 1 ) ;
	      $writer->setDataMode( 1 )	;

	   Enable or disable data mode.

       setDoctype
	      setDoctype $doctype ;
	      $writer->setDoctype( $doctype ) ;

	   This	is used	to set the doctype object.

       select_xml
	      select_xml OUTHANDLE ;  #	Nnot a method!!

	   Selects a filehandle	to send	the XML	output to when not using the
	   object oriented interface.  This is similar to perl's builtin
	   select, but only affects startTag and endTag	functions, (not
	   methods).

	   This	is only	needed if you want to interleave output	to the
	   selected output files (usually STDOUT, see "select" in perlfunc and
	   to an XML file on another filehandle.

	   If you want to redirect all output (yours and XML::Writer's)	to the
	   same	file, just use Perl's built-in select(), since startTag	and
	   endTag emit to the currently	selected filehandle by default.

	   Like	select,	this returns the old value.

       setOutput
	      setOutput( \*FH )	;
	      $writer->setOutput( \*FH ) ;

	   Sets	the filehandle an XML::ValidWriter sends output	to.

       startTag
	      startTag(	'a', attr => val ) ;  #	use default XML::ValidWriter for
					      #	current	package.
	      $writer->startTag( 'a', attr => val ) ;

	   Emits a named start tag with	optional attributes.  If the named tag
	   cannot be a child of	the most recently started tag, then any	tags
	   that	need to	be opened between that one and the named tag are
	   opened.

	   If the named	tag cannot be enclosed within the most recently	opened
	   tag,	no matter how deep, then startTag() tries to end as few
	   started tags	as necessary to	allow the named	tag to be emitted
	   within a tag	already	on the stack.

	   This	warns (once) if	no <?xml?> declaration has been	emitted.  It
	   does	not check to see if a <!DOCTYPE...> has	been emitted.  It dies
	   if an attempt is made to emit a second root element.

       xmlDecl([[$encoding][, $standalone])
	      xmlDecl ;
	      xmlDecl( "UTF-8" ) ;
	      xmlDecl( "UTF-8",	"yes" )	;
	      $writer->xmlDecl(	... ) ;

	   Emits an XML	declaration.  Must be called before any	of the other
	   output routines.

	   If $encoding	is not defined,	it is not output.  This	is slightly
	   different than XML::Writer, which outputs 'UTF-8' if	you pass in
	   undef, 0, or	''.

	   If $encoding	is '' or 0, then it is output as "" or "0" and a
	   warning is generated.

	   If $standalone is defined and is not	'no', 0, or '',	it is output
	   as 'yes'.  If it is 'no', then it is	output as 'no'.	 If it's 0 or
	   '' it is not	output.

       AUTOLOAD
	   This	function is called whenever a function or method is not	found
	   in XML::ValidWriter.

	   If it was a method being called, and	the desired method name	is a
	   start or end	tag found in the DTD, then a method is cooked up on
	   the fly.

	   These methods are slower than normal	methods, but they are cached
	   so that they	don't need to be recompiled.  The speed	penalty	is
	   probably not	significant since they do I/O and are thus usually
	   orders of magnitude slower than normal Perl methods.

       DESTROY
	   DESTROY is called when an XML::ValidWriter is cleaned up.  This is
	   used	to automatically close all tags	that remain open.  This	will
	   not work if you have	closed the output filehandle that the
	   ValidWriter was using.

	   This	method will also warn if anything was emitted bit no root node
	   was emitted.	 This warning can be silenced by calling

	      $writer->reset() ;

	   when	you abandon output.

AUTHOR
       Barrie Slaymaker	<barries@slaysys.com>

COPYRIGHT
       This module is Copyright	2000, 2005 Barrie Slaymaker.  All rights
       reserved.

       This module is licensed under your choice of the	Artistic, BSD or
       General Public License.

perl v5.32.1			  2021-02-28		   XML::ValidWriter(3)

NAME | SYNOPSIS | STATUS | DESCRIPTION | OUTPUT OPTIMIZATION | METHODS AND FUNCTIONS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::ValidWriter&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help