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

FreeBSD Manual Pages

  
 
  

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

NAME
       XML::AutoWriter - DOCTYPE based XML output

SYNOPSIS
	  use XML::Doctype	   NAME	=> a, SYSTEM_ID	=> 'a.dtd' ;
	  use XML::AutoWriter qw( :all :dtd_tags ) ;
	  #
	  # a.dtd contains:
	  #
	  #   <!ELEMENT	a ( b1,	b2?, b3* ) >
	  #	 <!ATTLIST   a aa1 CDATA       #REQUIRED >
	  #   <!ELEMENT	b1 ( c1	) >
	  #   <!ELEMENT	b2 ( c2	) >
	  #
	  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::AutoWriter qw( :dtd_tags ), DOCTYPE => $doctype ;

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

	  ## Or	as a normal perl object:
	  $writer = XML::AutoWriter->new( ... )	;
	  $writer->startTag( 'b1' ) ;
	  $writer->startTag( 'c2' ) ;
	  $writer->end ;

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 subclasses XML::ValidWriter and provides automatic start
       and end tag generation, allowing	you to emit only the 'important' tags.

       See XML::ValidWriter for	the details on all functions not documented
       here.

   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.

   Automatic start tags
       Automatic start tag creation is done when emitting a start tag that is
       not allowed to be a child of the	currently open tag but is allowed to
       be contained in the currently open tag's	subset.	 In this case, the
       minimal number of start tags necessary to allow All start tags between
       the current tag and the desired tag are automatically emitted with no
       attributes.

   Automatic end tags
       If start	tag autogeneration fails, then end tag autogeneration is
       attempted.  startTag() scans the	stack of currently open	tags trying to
       close as	few as possible	before start tag autogeneration	suceeds.

       Explicit	end tags may be	emitted	to prevent unwanted automatic start
       tags, and, in the future, warnings or errors will be available in place
       of automatic start and end tag creation.

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::AutoWriter DOCTYPE => XML::Doctype->new( ...	) ;
	  use XML::AutoWriter qw( :dtd_tags ) ;

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

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

	   Creates an XML::AutoWriter.

	   All other parameters	are passed to the XML::ValidWriter base	class
	   constructor.

       characters
	      characters( 'yabba dabba dooo' ) ;
	      $writer->characters( 'yabba dabba	dooo' )	;

	   If the currently open tag cannot contain #PCDATA, then start	tag
	   autogeneration will be attempted, followed by end tag
	   autogeneration.

	   Start tag autogeneration takes place	even if	you pass in only '',
	   or even (), the empty list.

       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.

       startTag
	      startTag(	'a', attr => val ) ;  #	use default XML::AutoWriter 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.

AUTHOR
       Barrie Slaymaker	<barries@slaysys.com>

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

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

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 331:
	   You forgot a	'=back'	before '=head1'

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

NAME | SYNOPSIS | STATUS | DESCRIPTION | METHODS AND FUNCTIONS | AUTHOR | COPYRIGHT | POD ERRORS

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

home | help