yang-rs

Rust bindings for the libyang library.

For raw FFI bindings for libyang, see libyang3-sys.

Cargo.toml

[dependencies]
yang3 = "0.10"

Design Goals

Provide high-level bindings for libyang using idiomatic Rust
Leverage Rust's ownership system to detect API misuse problems at compile time
Automatic resource management
Zero-cost abstractions

Feature flags

By default, yang-rs uses pre-generated FFI bindings and uses dynamic linking to load libyang. The following feature flags, however, can be used to change that behavior:

bundled: instructs cargo to download and build libyang from the sources. The resulting objects are grouped into a static archive linked to this crate. This feature can be used when having a libyang dynamic link dependency isn't desirable.
- Additional build requirements: cc 1.0, cmake 0.1, a C compiler and CMake.
use_bindgen: generate new C FFI bindings dynamically instead of using the pre-generated ones. Useful when updating this crate to use newer libyang versions.
- Additional build requirements: bindgen 0.68.0

Example

A basic example that parses and validates JSON instance data, and then converts it to the XML format:

use std::fs::File;
use yang3::context::{Context, ContextFlags};
use yang3::data::{
    Data, DataFormat, DataParserFlags, DataPrinterFlags, DataTree,
    DataValidationFlags,
};

static SEARCH_DIR: &str = "./assets/yang/";

fn main() -> std::io::Result<()> {
    // Initialize context.
    let mut ctx = Context::new(ContextFlags::NO_YANGLIBRARY)
        .expect("Failed to create context");
    ctx.set_searchdir(SEARCH_DIR)
        .expect("Failed to set YANG search directory");

    // Load YANG modules.
    for module_name in &["ietf-interfaces", "iana-if-type"] {
        ctx.load_module(module_name, None, &[])
            .expect("Failed to load module");
    }

    // Parse and validate data tree in the JSON format.
    let dtree = DataTree::parse_file(
        &ctx,
        File::open("./assets/data/interfaces.json")?,
        DataFormat::JSON,
        DataParserFlags::empty(),
        DataValidationFlags::NO_STATE,
    )
    .expect("Failed to parse data tree");

    // Print data tree in the XML format.
    dtree
        .print_file(
            std::io::stdout(),
            DataFormat::XML,
            DataPrinterFlags::WD_ALL | DataPrinterFlags::WITH_SIBLINGS,
        )
        .expect("Failed to print data tree");

    Ok(())
}

Note the NO_STATE flag passed to parse_file since the example json file does not contain state data. More examples can be found here.

License

This project is licensed under the MIT license.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/holo-routing/yang-rs.

holo-routing / yang-rs

readme