Struct ParserConfig 

#[non_exhaustive]
pub struct ParserConfig {

    pub trim_whitespace: bool,
    pub whitespace_to_characters: bool,
    pub cdata_to_characters: bool,
    pub ignore_comments: bool,
    pub coalesce_characters: bool,
    pub extra_entities: HashMap<String, String>,
    pub ignore_end_of_stream: bool,
    pub replace_unknown_entity_references: bool,
    pub ignore_root_level_whitespace: bool,
    pub override_encoding: Option<Encoding>,
    pub ignore_invalid_encoding_declarations: bool,
    pub allow_multiple_root_elements: bool,
    pub max_entity_expansion_length: usize,
    pub max_entity_expansion_depth: u8,
    pub max_name_length: usize,
    pub max_attributes: usize,
    pub max_attribute_length: usize,
    pub max_data_length: usize,
}

Parser configuration structure. There are more config methods than public fileds — see methods below.

This structure contains various configuration options which affect behavior of the parser.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

trim_whitespace: bool

Whether or not should whitespace in textual events be removed. Default is false.

When true, all standalone whitespace will be removed (this means no Whitespace events will be emitted), and leading and trailing whitespace from Character events will be deleted. If after trimming Characters event will be empty, it will also be omitted from output stream. This is possible, however, only if whitespace_to_characters or cdata_to_characters options are set.

This option does not affect CDATA events, unless cdata_to_characters option is also set. In that case CDATA content will also be trimmed.

whitespace_to_characters: bool

Whether or not should whitespace be converted to characters. Default is false.

If true, instead of Whitespace events Characters events with the same content will be emitted. If trim_whitespace is also true, these events will be trimmed to nothing and, consequently, not emitted.

cdata_to_characters: bool

Whether or not should CDATA be converted to characters. Default is false.

If true, instead of CData events Characters events with the same content will be emitted. If trim_whitespace is also true, these events will be trimmed. If corresponding CDATA contained nothing but whitespace, this event will be omitted from the stream.

ignore_comments: bool

Whether or not should comments be omitted. Default is true.

If true, Comment events will not be emitted at all.

coalesce_characters: bool

Whether or not should sequential Characters events be merged. Default is true.

If true, multiple sequential Characters events will be merged into a single event, that is, their data will be concatenated.

Multiple sequential Characters events are only possible if either cdata_to_characters or ignore_comments are set. Otherwise character events will always be separated by other events.

extra_entities: HashMap<String, String>

A map of extra entities recognized by the parser. Default is an empty map.

By default the XML parser recognizes the entities defined in the XML spec. Sometimes, however, it is convenient to make the parser recognize additional entities which are also not available through the DTD definitions (especially given that at the moment DTD parsing is not supported).

ignore_end_of_stream: bool

Whether or not the parser should ignore the end of stream. Default is false.

By default the parser will either error out when it encounters a premature end of stream or complete normally if the end of stream was expected. If you want to continue reading from a stream whose input is supplied progressively, you can set this option to true. In this case the parser will allow you to invoke the next() method even if a supposed end of stream has happened.

Note that support for this functionality is incomplete; for example, the parser will fail if the premature end of stream happens inside PCDATA. Therefore, use this option at your own risk.

replace_unknown_entity_references: bool

Whether or not non-unicode entity references get replaced with the replacement character

When true, any decimal or hexadecimal character reference that cannot be converted from a u32 to a char using std::char::from_u32 will be converted into the unicode REPLACEMENT CHARACTER (U+FFFD).

ignore_root_level_whitespace: bool

Whether or not whitespace at the root level of the document is ignored. Default is true.

By default any whitespace that is not enclosed within at least one level of elements will be ignored. Setting this value to false will cause root level whitespace events to be emitted.

override_encoding: Option<Encoding>

Use this encoding as the default. Necessary for UTF-16 files without BOM.

ignore_invalid_encoding_declarations: bool

Allow <?xml encoding="…"> to contain unsupported encoding names, and interpret them as Latin1 instead. This will mangle non-ASCII characters, but usually it won’t fail parsing.

allow_multiple_root_elements: bool

Documents with multiple root elements are ill-formed

max_entity_expansion_length: usize

Abort if custom entities create a string longer than this

max_entity_expansion_depth: u8

Entities can expand into other entities this many times (be careful about exponential cost!)

max_name_length: usize

Maximum length of tag name or attribute name

max_attributes: usize

Max number of attributes per element

max_attribute_length: usize

Max number of bytes in each attribute

max_data_length: usize

Maximum length of strings reprsenting characters, comments, and processing instructions

Implementations

impl ParserConfig

pub fn new() -> ParserConfig

Returns a new config with default values.

You can tweak default values using builder-like pattern:

use xml::reader::ParserConfig;

let config = ParserConfig::new()
    .trim_whitespace(true)
    .ignore_comments(true)
    .coalesce_characters(false);

pub fn create_reader<R>(self, source: R) -> EventReader<R>

where R: Read,

Creates an XML reader with this configuration. The reader should be wrapped in a BufReader, otherwise parsing may be very slow.

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

use xml::reader::ParserConfig;

let mut source: &[u8] = b"...";

let reader = ParserConfig::new()
    .trim_whitespace(true)
    .ignore_comments(true)
    .coalesce_characters(false)
    .create_reader(&mut source);

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

pub fn add_entity<S, T>(self, entity: S, value: T) -> ParserConfig

where S: Into<String>, T: Into<String>,

Adds a new entity mapping and returns an updated config object.

This is a convenience method for adding external entities mappings to the XML parser. An example:

use xml::reader::ParserConfig;

let mut source: &[u8] = b"...";

let reader = ParserConfig::new()
    .add_entity("nbsp", " ")
    .add_entity("copy", "©")
    .add_entity("reg", "®")
    .create_reader(&mut source);

impl ParserConfig

pub const fn trim_whitespace(self, value: bool) -> ParserConfig

See ParserConfig fields docs for details

pub const fn whitespace_to_characters(self, value: bool) -> ParserConfig

See ParserConfig fields docs for details

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

See ParserConfig fields docs for details

pub const fn ignore_comments(self, value: bool) -> ParserConfig

See ParserConfig fields docs for details

pub const fn coalesce_characters(self, value: bool) -> ParserConfig

See ParserConfig fields docs for details

pub const fn ignore_end_of_stream(self, value: bool) -> ParserConfig

See ParserConfig fields docs for details

pub const fn replace_unknown_entity_references( self, value: bool, ) -> ParserConfig

See ParserConfig fields docs for details

pub const fn ignore_root_level_whitespace(self, value: bool) -> ParserConfig

Whether or not whitespace at the root level of the document is ignored. Default is true.

See ParserConfig fields docs for details

impl ParserConfig

pub fn content_type(self, mime_type: &str) -> ParserConfig

Read character encoding from Content-Type header. Set this when parsing XML documents fetched over HTTP.

text/* MIME types do not imply latin1. UTF-8 is always the default fallback.

impl ParserConfig

pub const fn override_encoding(self, value: Option<Encoding>) -> ParserConfig

Set if you got one in the HTTP header

See ParserConfig fields docs for details

pub const fn allow_multiple_root_elements(self, value: bool) -> ParserConfig

Allows invalid documents. There should be only a single root element in XML.

See ParserConfig fields docs for details

pub const fn max_entity_expansion_length(self, value: usize) -> ParserConfig

Abort if custom entities create a string longer than this

See ParserConfig fields docs for details

pub const fn max_entity_expansion_depth(self, value: u8) -> ParserConfig

Entities can expand into other entities this many times (be careful about exponential cost!)

See ParserConfig fields docs for details

pub const fn max_attributes(self, value: usize) -> ParserConfig

Max number of attributes per element

See ParserConfig fields docs for details

pub const fn max_name_length(self, value: usize) -> ParserConfig

Maximum length of tag name or attribute name

See ParserConfig fields docs for details

pub const fn max_attribute_length(self, value: usize) -> ParserConfig

Max number of bytes in each attribute

See ParserConfig fields docs for details

pub const fn max_data_length(self, value: usize) -> ParserConfig

Maximum length of strings reprsenting characters, comments, and processing instructions

See ParserConfig fields docs for details

pub const fn ignore_invalid_encoding_declarations( self, value: bool, ) -> ParserConfig

Allow <?xml encoding="bogus"?>

See ParserConfig fields docs for details

Trait Implementations

impl Clone for ParserConfig

fn clone(&self) -> ParserConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ParserConfig

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

Formats the value using the given formatter.

impl Default for ParserConfig

fn default() -> ParserConfig

Returns the “default value” for a type.

impl PartialEq for ParserConfig

fn eq(&self, other: &ParserConfig) -> 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 ParserConfig

impl StructuralPartialEq for ParserConfig