xmlwrite.3am - Man Page

Provides facilities for writing XML fragments. A whole XML document can be composed this way. The composed document may be indented if desired.

Synopsis

@include "xmlwrite"

xwopen(filename[, options])
xwclose()

xwdeclaration(version, encoding, standalone)
xwstartdoct(root, pubid, sysid)
xwenddoct()

xwprocinst(name, string)
xwcomment(comment)

xwstarttag(name)
xwattrib(name, value)
xwendtag(name)

xwtext(string)
xwstartcdata()
xwendcdata()

xwunparsed(string)

xwdoctype(root, pubid, sysid, declarations)
xwstyle(type, uri)
xwelement(name, content)
xwcdata(string)
xwcopy()

The xmlwrite library facilitates writing a XML document serially, piece by piece. It takes care of some peculiarities of the XML standard, like metacharacters escaping, whitespace handling, markup indentation, etc.

Output file and mode

xwopen(filename[, options])

Initializes output to the given file. The optional argument is an array of named options:

options["INDENT"]: Indent step (-1 = no indent), default = 2.
options["QUOTE"]: Preferred quote character (', "), default = (").

xwclose()

Closes the current opened output file.

XML prologue

xwdeclaration(version, encoding, standalone): Writes an XML declaration (<?xml ... ?>). All the arguments are optional.
xwstartdoct(root, pubid, sysid): Writes the starting part of a DOCTYPE declaration (<!DOCTYPE ...). All the arguments are optional.Internal DOCTYPE declarations, if any, may be inserted by subsequent xwunparsed() calls.
xwenddoct(): Writes the closing mark of the DOCTYPE declaration (]>).

Processing Instructions and Comments

xwprocinst(name, string): Prints a Processing Instruction with the given name and contents (<?name string?>).
xwcomment(comment): Prints a XML comment ().

Elements and attributes

xwstarttag(name): Prints the opening mark of an element start tag (<name ...>).
xwattrib(name, value): Prints an attribute markup fragment (name="value"). Must be invoked immediately after the xwstartag() call.
xwendtag(name): Prints an element closing tag (</name>). If the element is empty, just closes its collapsed markup (/>).

Character data

xwtext(string): Writes the escaped text. If it is invoked inside a CDATA section, the text is written unescaped.
xwstartcdata(): Writes the opening mark of a CDATA section (<![CDATA[).
xwendcdata(): Writes the closing mark of a CDATA section (]]>).

Unparsed markup

xwunparsed(string): Writes a text fragment literally. Can be used to directly insert special markup fragments.

Higher level convenience functions

xwdoctype(root, pubid, sysid, declarations): Writes a complete DOCTYPE declaration with a single call. All the arguments are optional.
xwstyle(type, uri): Writes a stylesheet processing instruction (<?xsl-stylesheet type="text/type" href="uri"?>).
xwelement(name, content): Writes a complete simple element markup with a single call. Attributes are not supported. Nested child elements are not supported.
xwcdata(string): Writes a complete CDATA section with a single call.

Integration with the XML extension

If the xmlwrite library and the gawk-xml extension are used together, then it is possible to directly copy XML input markup.

xwcopy(): Writes the markup fragment equivalent to the current XML input token. Should be used instead of the XmlCopy() function provided by the xmlcopy library.

Notes

xmlwrite is a standalone library that can be used independently of the gawk-xml extension.

Bugs

Improper use of the provided functions may produce non-wellformed markup.

The whole output document must be written with the provided functions. Mixing xmlwrite calls and direct print commands may produce corrupted markup.

It is not possible to write several output documents concurrently.

Author

Manuel Collado, m-collado@users.sourceforge.net.

Copying Permissions

Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual page under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual page into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

Info

January 2017 GAWK Extension Library (gawkextlib) GNU Awk Extension Modules