Class Format

AI-generated Key Takeaways

• The XmlService provides a formatter to output XML documents with customizable formatting options like encoding, indentation, and line separators.

• Three predefined formats are available and can be accessed using XmlService.getPrettyFormat(), XmlService.getCompactFormat(), and XmlService.getRawFormat().

• The format() method outputs either a given Document or Element node as a formatted string based on the set formatting options.

• Developers can customize the output by setting the encoding, indent, line separator, and whether to omit the XML declaration or encoding using the respective methods on the Format object.

• The formatter allows for chaining methods to easily configure multiple formatting options in a single line of code.

Format

A formatter for outputting an XML document, with three pre-defined formats that can be further customized.

// Log an XML document with specified formatting options.
const xml = '<root><a><b>Text!</b><b>More text!</b></a></root>';
const document = XmlService.parse(xml);
const output = XmlService.getCompactFormat()
                   .setLineSeparator('\n')
                   .setEncoding('UTF-8')
                   .setIndent('   ')
                   .format(document);
Logger.log(output);

Methods

Method	Return type	Brief description
format(document)	String	Outputs the given Document as a formatted string.
format(element)	String	Outputs the given Element node as a formatted string.
setEncoding(encoding)	Format	Sets the character encoding that the formatter should use.
setIndent(indent)	Format	Sets the string used to indent child nodes relative to their parents.
setLineSeparator(separator)	Format	Sets the string to insert whenever the formatter would normally insert a line break.
setOmitDeclaration(omitDeclaration)	Format	Sets whether the formatter should omit the XML declaration, such as <?xml version="1.0" encoding="UTF-8"?>.
setOmitEncoding(omitEncoding)	Format	Sets whether the formatter should omit the encoding in the XML declaration, such as the encoding field in <?xml version="1.0" encoding="UTF-8"?>.

Detailed documentation

format(document)

Outputs the given Document as a formatted string.

Parameters

Name	Type	Description
document	Document	the document to format

Return

String — the formatted document

---

format(element)

Outputs the given Element node as a formatted string.

Parameters

Name	Type	Description
element	Element	the element to format

Return

String — the formatted element

---

setEncoding(encoding)

Sets the character encoding that the formatter should use. The encoding argument must be an accepted XML encoding like ISO-8859-1, US-ASCII, UTF-8, or UTF-16.

// Log an XML document with encoding that does not support certain special
// characters.
const xml = '<root><a><b>ಠ‿ಠ</b><b>ಠ‿ಠ</b></a></root>';
const document = XmlService.parse(xml);
const output =
    XmlService.getRawFormat().setEncoding('ISO-8859-1').format(document);
Logger.log(output);

Parameters

Name	Type	Description
encoding	String	the encoding to use

Return

Format — the formatter, for chaining

---

setIndent(indent)

Sets the string used to indent child nodes relative to their parents. Setting an indent other than null will cause the formatter to insert a line break after every node.

// Log an XML document with each child node indented four spaces.
const xml = '<root><a><b>Text!</b><b>More text!</b></a></root>';
const document = XmlService.parse(xml);
const output = XmlService.getCompactFormat().setIndent('    ').format(document);
Logger.log(output);

Parameters

Name	Type	Description
indent	String	the indent to use

Return

Format — the formatter, for chaining

---

setLineSeparator(separator)

Sets the string to insert whenever the formatter would normally insert a line break. The three pre-defined formatters have different conditions under which they insert a line break. The default line separator is \r\n.

// Log an XML document with several spaces and a pipe character in place of line
// breaks.
const xml = '<root><a><b>Text!</b><b>More text!</b></a></root>';
const document = XmlService.parse(xml);
const output =
    XmlService.getRawFormat().setLineSeparator(' | ').format(document);
Logger.log(output);

Parameters

Name	Type	Description
separator	String	the separator to use

Return

Format — the formatter, for chaining

---

setOmitDeclaration(omitDeclaration)

Sets whether the formatter should omit the XML declaration, such as <?xml version="1.0" encoding="UTF-8"?>.

Parameters

Name	Type	Description
omitDeclaration	Boolean	true to omit the XML declaration; false to include it

Return

Format — the formatter, for chaining

---

setOmitEncoding(omitEncoding)

Sets whether the formatter should omit the encoding in the XML declaration, such as the encoding field in <?xml version="1.0" encoding="UTF-8"?>.

Parameters

Name	Type	Description
omitEncoding	Boolean	true to omit the encoding in the XML declaration; false to include it

Return

Format — the formatter, for chaining