Class Format

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.
var xml = '<root><a><b>Text!</b><b>More text!</b></a></root>';
var document = XmlService.parse(xml);
var output = XmlService.getCompactFormat()
    .setLineSeparator('\n')
    .setEncoding('UTF-8')
    .setIndent('   ')
    .format(document);
Logger.log(output);

Methods

MethodReturn typeBrief description
format(document)StringOutputs the given Document as a formatted string.
format(element)StringOutputs the given Element node as a formatted string.
setEncoding(encoding)FormatSets the character encoding that the formatter should use.
setIndent(indent)FormatSets the string used to indent child nodes relative to their parents.
setLineSeparator(separator)FormatSets the string to insert whenever the formatter would normally insert a line break.
setOmitDeclaration(omitDeclaration)FormatSets whether the formatter should omit the XML declaration, such as <?xml version="1.0" encoding="UTF-8"?>.
setOmitEncoding(omitEncoding)FormatSets 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

NameTypeDescription
documentDocumentthe document to format

Return

String — the formatted document


format(element)

Outputs the given Element node as a formatted string.

Parameters

NameTypeDescription
elementElementthe 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.
var xml = '<root><a><b>ಠ‿ಠ</b><b>ಠ‿ಠ</b></a></root>';
var document = XmlService.parse(xml);
var output = XmlService.getRawFormat()
    .setEncoding('ISO-8859-1')
    .format(document);
Logger.log(output);

Parameters

NameTypeDescription
encodingStringthe 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.
var xml = '<root><a><b>Text!</b><b>More text!</b></a></root>';
var document = XmlService.parse(xml);
var output = XmlService.getCompactFormat()
    .setIndent('    ')
    .format(document);
Logger.log(output);

Parameters

NameTypeDescription
indentStringthe 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.
var xml = '<root><a><b>Text!</b><b>More text!</b></a></root>';
var document = XmlService.parse(xml);
var output = XmlService.getRawFormat()
    .setLineSeparator(' | ')
    .format(document);
Logger.log(output);

Parameters

NameTypeDescription
separatorStringthe 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

NameTypeDescription
omitDeclarationBooleantrue 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

NameTypeDescription
omitEncodingBooleantrue to omit the encoding in the XML declaration; false to include it

Return

Format — the formatter, for chaining