LibYML

LibYML is a Rust library for parsing and emitting YAML data in a safe and efficient manner. The library is designed to be easy to use and provides a comprehensive set of tools for working with YAML data.

• Website • Documentation • Report Bug • Request Feature • Contributing Guidelines

Credits and Acknowledgements

LibYML is a new library that draws inspiration from the excellent work done by David Tolnay and the maintainers of the unsafe-libyaml library. I would like to express my sincere gratitude to David and the unsafe-libyaml team for their valuable contributions to the Rust community.

While LibYML started as a fork of unsafe-libyaml, it has evolved into a separate library with its own goals and direction. The primary intent behind creating LibYML was to provide an actively maintained and enhanced library for working with YAML data in Rust, while also serving as a learning opportunity.

It's important to note that LibYML is not intended to replace unsafe-libyaml. If you are currently using unsafe-libyaml in your projects, we recommend carefully evaluating your requirements and considering the stability and maturity of the original library before migrating to LibYML.

We acknowledge and appreciate the significant work done by David Tolnay and the unsafe-libyaml maintainers. Their efforts have been instrumental in laying the foundation for LibYML and inspiring its development.

Overview

LibYML is a robust Rust library that provides a comprehensive set of tools for working with YAML data. The library offers a wide range of features, including serialization, deserialization, custom struct and enum support, error handling, and more.

Features

• Serialization and Deserialization: LibYML provides easy-to-use APIs for serializing Rust structs and enums into YAML format and deserializing YAML data into Rust types.
• Custom Struct and Enum Support: The library allows you to work with custom structs and enums, enabling seamless serialization and deserialization of your own data types.
• Error Handling: LibYML provides comprehensive error handling mechanisms, including detailed error messages and the ability to handle and recover from parsing and emission errors.
• Streaming Support: The library supports streaming of YAML data, allowing you to efficiently process large YAML documents incrementally.
• Alias and Anchor Support: LibYML handles YAML aliases and anchors, enabling you to work with complex YAML structures that involve references and duplicated data.
• Tag Handling: The library provides support for custom tags, allowing you to serialize and deserialize YAML data with specific type information.
• Configurable Emitter: LibYML allows you to customize the emitter settings, such as indentation, line width, and scalar style, to generate YAML output according to your preferences.
• Extensive Documentation: The library comes with detailed documentation and examples, making it easy to get started and understand how to use its various features effectively.
• Safety and Efficiency: LibYML is designed with safety and efficiency in mind. It minimizes the use of unsafe code and provides an interface that helps prevent common pitfalls and errors.

Rust Version Compatibility

This library is compatible with Rust 1.60 and above.

Usage

LibYML offers a straightforward and intuitive API for working with YAML data in Rust. To get started, add the following dependency to your Cargo.toml file:

[dependencies]
libyml = "0.0.1"

Examples

To get started with LibYML, you can use the examples provided in the examples directory of the project.

LibYML provides a set of comprehensive examples to demonstrate its usage and capabilities. The examples cover various aspects of the library, including initializing and deleting parsers, setting input strings, memory management, string manipulation, and more.

To run the examples, clone the repository and navigate to the examples directory. Each example is contained in a separate file, focusing on specific functionalities or use cases.

For instance, to run all the example demonstrating the usage of the LibYML APIs, you can execute the following command:

cargo run --example example

The command will execute all the examples code, demonstrating all the features and use cases of the LibYML library.

Here are a few notable examples you can also run individually:

1) The apis Example

The api.rs file provides a set of low-level API functions for working with YAML data in the LibYML library. The apis example showcases the usage of these low-level APIs covering functions such as:

• yaml_parser_initialize - Initialize a YAML parser,
• yaml_parser_delete - Delete a YAML parser,
• yaml_parser_set_input_string - Set the input string for the parser,
• yaml_malloc - Allocate memory,
• yaml_realloc - Reallocate memory,
• yaml_free - Free memory,
• yaml_strdup - Duplicate a string,
• yaml_string_extend - Extend a string,
• yaml_string_join - Join strings,

You can run the apis example using the following command:

cargo run --example apis

Installation

To use LibYML in your Rust project, add the following to your Cargo.toml file:

[dependencies]
libyml = "0.0.1"

Semantic Versioning Policy

For transparency into our release cycle and in striving to maintain backward compatibility, libyml follows semantic versioning.

License

The project is licensed under the terms of both the MIT license and the Apache License (Version 2.0).

• Apache License, Version 2.0
• MIT license

Contribution

We welcome all people who want to contribute. Please see the contributing instructions for more information.

Contributions in any form (issues, pull requests, etc.) to this project must adhere to the Rust's Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.