Format

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

```javascript
// 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 |
|---|---|---|
| `https://developers.google.com/apps-script/reference/xml-service/format#format(Document)` | `String` | Outputs the given `https://developers.google.com/apps-script/reference/xml-service/document` as a formatted string. |
| `https://developers.google.com/apps-script/reference/xml-service/format#format(Element)` | `String` | Outputs the given `https://developers.google.com/apps-script/reference/xml-service/element` node as a formatted string. |
| `https://developers.google.com/apps-script/reference/xml-service/format#setEncoding(String)` | `https://developers.google.com/apps-script/reference/xml-service/format#` | Sets the character encoding that the formatter should use. |
| `https://developers.google.com/apps-script/reference/xml-service/format#setIndent(String)` | `https://developers.google.com/apps-script/reference/xml-service/format#` | Sets the string used to indent child nodes relative to their parents. |
| `https://developers.google.com/apps-script/reference/xml-service/format#setLineSeparator(String)` | `https://developers.google.com/apps-script/reference/xml-service/format#` | Sets the string to insert whenever the formatter would normally insert a line break. |
| `https://developers.google.com/apps-script/reference/xml-service/format#setOmitDeclaration(Boolean)` | `https://developers.google.com/apps-script/reference/xml-service/format#` | Sets whether the formatter should omit the XML declaration, such as `<?xml version="1.0" encoding="UTF-8"?>`. |
| `https://developers.google.com/apps-script/reference/xml-service/format#setOmitEncoding(Boolean)` | `https://developers.google.com/apps-script/reference/xml-service/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 `https://developers.google.com/apps-script/reference/xml-service/document` as a formatted string.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `document` | `https://developers.google.com/apps-script/reference/xml-service/document` | The document to format. |

#### Return


`String` --- The formatted document.

*** ** * ** ***

### `format(element)`

Outputs the given `https://developers.google.com/apps-script/reference/xml-service/element` node as a formatted string.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `element` | `https://developers.google.com/apps-script/reference/xml-service/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`.

```javascript
// 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


`https://developers.google.com/apps-script/reference/xml-service/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.

```javascript
// 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


`https://developers.google.com/apps-script/reference/xml-service/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`.

```javascript
// 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


`https://developers.google.com/apps-script/reference/xml-service/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


`https://developers.google.com/apps-script/reference/xml-service/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


`https://developers.google.com/apps-script/reference/xml-service/format#` --- The formatter, for chaining.