Struct EmitterConfig

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,
    pub pad_self_closing: 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: <!-- something --> instead of <!--something-->.

pad_self_closing: bool

Whether or not to automatically insert spaces before the trailing /> in self-closing elements. Default is true.

This option is only meaningful if normalize_empty_elements is true. For example, the element <a></a> would be unaffected. When normalize_empty_elements is true, then when this option is also true, the same element would appear <a />. If this option is false, then the same element would appear <a/>.

Implementations

impl EmitterConfig

pub fn new() -> Self

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);

pub 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.

impl EmitterConfig

pub fn line_separator<T: Into<Cow<'static, str>>>(self, value: T) -> Self

See ParserConfig fields docs for details

pub fn indent_string<T: Into<Cow<'static, str>>>(self, value: T) -> Self

See ParserConfig fields docs for details

pub const fn perform_indent(self, value: bool) -> Self

See ParserConfig fields docs for details

pub const fn write_document_declaration(self, value: bool) -> Self

See ParserConfig fields docs for details

pub const fn normalize_empty_elements(self, value: bool) -> Self

See ParserConfig fields docs for details

pub const fn cdata_to_characters(self, value: bool) -> Self

See ParserConfig fields docs for details

pub const fn keep_element_names_stack(self, value: bool) -> Self

See ParserConfig fields docs for details

pub const fn autopad_comments(self, value: bool) -> Self

See ParserConfig fields docs for details

pub const fn pad_self_closing(self, value: bool) -> Self

See ParserConfig fields docs for details

Trait Implementations

impl Clone for EmitterConfig

fn clone(&self) -> EmitterConfig

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EmitterConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for EmitterConfig

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for EmitterConfig

fn eq(&self, other: &EmitterConfig) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for EmitterConfig

impl StructuralPartialEq for EmitterConfig