Struct xml::writer::EmitterConfig

source ·
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,
}
Expand description

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§

source§

impl EmitterConfig

source

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

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.

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

source§

impl EmitterConfig

source

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

See ParserConfig fields docs for details

Trait Implementations§

source§

impl Clone for EmitterConfig

source§

fn clone(&self) -> EmitterConfig

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for EmitterConfig

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for EmitterConfig

source§

fn default() -> EmitterConfig

Returns the “default value” for a type. Read more
source§

impl PartialEq<EmitterConfig> for EmitterConfig

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for EmitterConfig

source§

impl StructuralEq for EmitterConfig

source§

impl StructuralPartialEq for EmitterConfig

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.