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 auto
matic 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 autogener
ation is attempted. startTag() scans the stack of cur rently open tags trying to close as few as possible before
start tag autogeneration suceeds.

Explicit end tags may be emitted to prevent unwanted auto
matic 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 state
ment:

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

=> H ) ;

Creates an XML::AutoWriter.

All other parameters are passed to the XML::Valid
Writer 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 docu
ment.

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 start_
Tag() 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, Barrie Slaymaker. All
rights reserved.

This module is licensed under the GPL, version 2. Please
contact me if this does not suit your needs.

perl v5.8.0 2000-08-09 XML::AutoWriter(3)