Struct xml::EmitterConfig [−] [src]

pub struct EmitterConfig {
    pub line_separator: Cow<'static, str>,
    pub indent_string: Cow<'static, str>,
    pub perform_indent: bool,
    pub perform_escaping: bool,
    pub write_document_declaration: bool,
    pub normalize_empty_elements: bool,
    pub cdata_to_characters: bool,
    pub keep_element_names_stack: bool,
    pub autopad_comments: bool,
}

Emitter configuration structure.

This structure contains various options which control XML document emitter behavior.

Fields

line_separator: Cow<'static, str>

Line separator used to separate lines in formatted output. Default is "\n".

indent_string: Cow<'static, str>

A string which will be used for a single level of indentation. Default is " " (two spaces).

perform_indent: bool

Whether or not the emitted document should be indented. Default is false.

The emitter is capable to perform automatic indentation of the emitted XML document. It is done in stream-like fashion and does not require the knowledge of the whole document in advance.

Sometimes, however, automatic indentation is undesirable, e.g. when you want to keep existing layout when processing an existing XML document. Also the indentiation algorithm is not thoroughly tested. Hence by default it is disabled.

perform_escaping: bool

Whether or not characters in output events will be escaped. Default is true.

The emitter can automatically escape characters which can't appear in PCDATA sections or element attributes of an XML document, like < or " (in attributes). This may introduce some overhead because then every corresponding piece of character data should be scanned for invalid characters.

If this option is disabled, the XML writer may produce non-well-formed documents, so use false value for this option with care.

write_document_declaration: bool

Whether or not to write XML document declaration at the beginning of a document. Default is true.

This option controls whether the document declaration should be emitted automatically before a root element is written if it was not emitted explicitly by the user.

normalize_empty_elements: bool

Whether or not to convert elements with empty content to empty elements. Default is true.

This option allows turning elements like <a></a> (an element with empty content) into <a /> (an empty element).

cdata_to_characters: bool

Whether or not to emit CDATA events as plain characters. Default is false.

This option forces the emitter to convert CDATA events into regular character events, performing all the necessary escaping beforehand. This may be occasionally useful for feeding the document into incorrect parsers which do not support CDATA.

keep_element_names_stack: bool

Whether or not to keep element names to support EndElement events without explicit names. Default is true.

This option makes the emitter to keep names of written elements in order to allow omitting names when writing closing element tags. This could incur some memory overhead.

autopad_comments: bool

Whether or not to automatically insert leading and trailing spaces in emitted comments, if necessary. Default is true.

This is a convenience option in order for the user not to append spaces before and after comments text in order to get more pretty comments:  instead of .

Methods

`impl EmitterConfig`
[src]

`fn new() -> EmitterConfig`

Creates an emitter configuration with default values.

You can tweak default options with builder-like pattern:

use xml::writer::EmitterConfig;

let config = EmitterConfig::new()
    .line_separator("\r\n")
    .perform_indent(true)
    .normalize_empty_elements(false);

`fn create_writer<W: Write>(self, sink: W) -> EventWriter<W>`

Creates an XML writer with this configuration.

This is a convenience method for configuring and creating a writer at the same time:

use xml::writer::EmitterConfig;

let mut target: Vec<u8> = Vec::new();

let writer = EmitterConfig::new()
    .line_separator("\r\n")
    .perform_indent(true)
    .normalize_empty_elements(false)
    .create_writer(&mut target);

This method is exactly equivalent to calling EventWriter::new_with_config() with this configuration object.