Crate libyaml_safer 

libyaml-safer

This library is a fork of unsafe-libyaml translated to safe and idiomatic Rust.

unsafe-libyaml is libyaml translated from C to unsafe Rust with the assistance of c2rust.

[dependencies]
libyaml-safer = "0.1"

Compiler support: requires rustc 1.70

Notes

This library uses the same test suite as unsafe-libyaml, which is also the “official” test suite for libyaml. The library was ported line by line, function by function, from unsafe-libyaml, with the aim of precisely matching its behavior, including performance and allocation patterns. Any observable difference in behavior, outside of API differences due to Rust conventions, is considered a bug.

One notable exception to the above is that this library uses the Rust standard library in place of custom routines where possible. For example, most UTF-8 and UTF-16 encoding and decoding is handled by the standard library, and input/output callbacks are replaced with the applicable std::io::* traits. Due to the use of std::io, this library cannot currently be no_std.

Memory allocation patterns are generally preserved, except that standard library containers may overallocate buffers using different heuristics.

In places where libyaml routines are replaced by the standard library, certain errors may be reported with reduced fidelity compared with libyaml (e.g., error messages may look slightly different), but the same inputs should generate the same general errors.

Compatibility and interoperability

While this library matches the behavior of libyaml, it is not intended as a drop-in replacement. The shape of the API is idiomatic Rust, and while it is possible to emulate the C API using this library, supporting this use case is not a priority. Use unsafe-libyaml if that is what you need.

Performance

Performance is largely on par with unsafe-libyaml. No significant effort has been put into optimizing this library, beyond just choosing the most straightforward ways to reasonably port concepts from the C-like code.

See benches/bench.rs for a very simple benchmark dealing with a very large (~700 KiB) YAML document. On my machine (Ryzen 9 3950X) the parser from this library is slightly slower and the emitter is slightly faster, but both within about ~1ms of their unsafe counterparts. Run cargo bench to test on your machine.

If there is demand, there are clear paths forward to optimize the parser. For example, due to it being ported directly from unsafe C-like code doing pointer arithmetic, it performs a completely unreasonable number of bounds checks for each input byte.

License

MIT license, same as unsafe-libyaml and libyaml.

Structs

AliasData

This structure holds aliases data.

Document

The document structure.

Emitter

The emitter structure.

Error

Event

The event structure.

Mark

The pointer position.

Node

The node structure.

NodePair

An element of a mapping node.

Parser

The parser structure.

Scanner

Given an input stream of bytes, produce a stream of Tokens.

SimpleKey

This structure holds information about a potential simple key.

TagDirective

The tag directive data.

Token

The token structure.

VersionDirective

The version directive data.

Enums

Break

Line break type.

EmitterState

The emitter states.

Encoding

The stream encoding.

ErrorKind

EventData

MappingStyle

Mapping styles.

NodeData

Node types.

ParserState

The states of the parser.

ScalarStyle

Scalar styles.

SequenceStyle

Sequence styles.

TokenData

Constants

BOOL_TAG

The tag !!bool with the values: true and false.

DEFAULT_MAPPING_TAG

The default mapping tag is !!map.

DEFAULT_SCALAR_TAG

The default scalar tag is !!str.

DEFAULT_SEQUENCE_TAG

The default sequence tag is !!seq.

FLOAT_TAG

The tag !!float for float values.

INT_TAG

The tag !!int for integer values.

MAP_TAG

The tag !!map is used to denote mapping.

NULL_TAG

The tag !!null with the only possible value: null.

SEQ_TAG

The tag !!seq is used to denote sequences.

STR_TAG

The tag !!str for string values.

TIMESTAMP_TAG

The tag !!timestamp for date and time values.

Type Aliases

NodeItem

An element of a sequence node.

Result