Crate eml_nl 

EML (Election Markup Language) library written by the Kiesraad (the Dutch Electoral Council) for parsing and writing EML_NL documents written in safe Rust code only.

This library sometimes uses EML and EML_NL interchangeably, but only EML_NL is supported. For details of the EML_NL standard, see the Kiesraad EML_NL repository.

This crate only parses and writes EML documents in memory, it does not support streaming parsing or writing. This was a design decision to keep the code simple and maintainable, and it is expected that EML documents will generally not be extremely large. Up to a few megabytes were expected, but larger documents will work fine as long as enough memory is available. Expect somewhere between 1.2 and 2.0 times the original document size depending on the contents of the file.

Getting started

The main entrypoints for this crate are the EML enum for parsing any EML document. You can also use the specific structs for specific EML_NL documents, such as ElectionDefinition for a 110a EML document. The best reference for which documents are supported are the variants in the EML enum.

Reading of EML documents is done through the EMLRead trait, while writing is done through the EMLWrite trait. So to read an EML document and directly write it back to XML you could do this:

use eml_nl::{documents::EML, io::{EMLRead, EMLWrite}};
let xml = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/test-emls/polling_stations/eml110b_polling_stations_construction_output.eml.xml"));
let eml_doc = EML::parse_eml(xml, eml_nl::io::EMLParsingMode::Strict).unwrap();
let xml_output = eml_doc.write_eml_root_str(true, true).unwrap();
assert_eq!(xml_output, xml);

In this example we also see EMLParsingMode being used. This enum defines how strict parsing of several values and elements should be. Take a look at the documenation for the enum for more information.

Many times when parsing specific values from EML documents, such as dates or identifiers, depending on the parsing mode, the values may be stored as the raw string or the parsed value. To handle this, we use the StringValue type, which can contain either the raw string or the parsed value. Take a look at the documentation for that type for more information.

In general it should not be necessary to use the string values directly unless you are doing something with values that cannot be parsed or where you don’t really care about the actual value. In most cases you should let the library handle the parsing of raw strings.

Error handling

During parsing and writing of EML documents, various errors can occur. These are represented by the EMLError type, which contains an EMLErrorKind indicating the actual error type.

When parsing, the library will attempt to provide location information whenever possible for errors. This is done through the use of the Span type, which indicates the byte range in the original XML document where the error occurred. Other operations (including writing documents) generally will not have this location information available.

Modules

common

Element definitions common to multiple EML_NL document variants.

documents

Document variants and related types for the all the specific EML_NL documents.

io

Reading and writing EML_NL documents.

utils

Utility function and types used within EML_NL documents.

Structs

MultipleEMLErrors

An error containing multiple EMLErrors

Enums

EMLError

An error encountered during EML_NL processing.

EMLErrorKind

Different kinds of errors that can occur during EML_NL processing.

Traits

CustomError

Custom error type that can be used in EMLErrorKind::Custom