XML::AutoWriter(3pm)

✨ XML::AutoWriter ✨

okay bestie, welcome to the XML::AutoWriter page from the User Contributed Perl Documentation, and honestly? this one is a whole vibe. it's the module that writes your XML for you based on your DOCTYPE, so you can just sit there being the main character while it handles the tags. 💅

---

🌸 NAME 🌸

XML::AutoWriter — DOCTYPE based XML output. yes that's the whole name. short, iconic, to the point. periodt.

---

🦋 SYNOPSIS 🦋

okay so here's the tea, look at this:

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 ;

like. it literally just knows to open <a> and <b1> for you. no cap. it read the DTD, it did the homework, it's carrying the group project fr fr. 📚✨

---

💀 STATUS 💀

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

ngl bestie that is a big yikes for production. it's giving "works on my machine". many methods supplied by XML::Writer are not yet supplied here, so don't expect the full menu, okay? 🫶

---

🎀 DESCRIPTION 🎀

This module subclasses XML::ValidWriter and provides automatic start and end tag generation, allowing you to emit only the 'important' tags.

the way that it just... handles the boring tags for you? obsessed. 😭

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.

so like, it's aiming for drop-in replacement energy but it's not there yet. think of it as the understudy who knows most of the lines. 💜

✨ 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.

(yes, that capital-A "All" is in the original. we respect the source material here. 💅) basically: it opens the bare minimum of wrapper tags, no attributes, no drama, just vibes.

🔥 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.

(sic — "suceeds" is exactly how it's spelled up in here, we don't gatekeep spelling mistakes, we simply notice them. 🙈)

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.

heads up: those warnings/errors? future feature. right now it just does the automatic thing. lowkey ominous but okay.

---

👑 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.

so it's like the module adopts a package as its home and then every function call knows where to send the output. found family trope but for perl namespaces. 🫶

🌟 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.

so anything you'd normally hand to the parent class? just yeet it in here, it'll get forwarded. 🚀

🍓 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.

okay this one is genuinely wild — even an empty list triggers tag autogeneration. the module is eager. it's giving overachiever energy and we love that for it. 💖

⭐ 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.

so like, if you ask it to close something that was never opened? it will be messy about it. errors happen. be careful bestie. 😭

🧚 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.

okay so real talk: no <?xml?> declaration? it warns you. once. (perfectionist but polite.) no <!DOCTYPE...>? it literally does not care. but try to sneak in a second root element? it dies. absolutely not. one root. that's the rule. 👑✨

---

💖 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.

---

and that's the whole page, bestie!! you ate. go forth and let the module write your tags for you, you've earned it. 🫶🌈✨

signing off with the classic footer tea: this page ships with perl v5.34.0, dated 2022-06-28, and it lives at XML::AutoWriter(3pm) — mwah, iconic, no notes. 💅