29 releases (15 breaking)

new 0.16.0 Jul 12, 2024
0.14.0 Jul 11, 2024
0.9.0 Jan 24, 2024
0.8.1 Nov 3, 2023
0.1.7 Mar 5, 2021

#245 in Parser implementations

Download history 45/week @ 2024-03-28 276/week @ 2024-04-04 69/week @ 2024-04-11 89/week @ 2024-04-18 1868/week @ 2024-04-25 1063/week @ 2024-05-02 894/week @ 2024-05-09 171/week @ 2024-05-16 516/week @ 2024-05-23 92/week @ 2024-05-30 46/week @ 2024-06-06 64/week @ 2024-06-13 85/week @ 2024-06-20 224/week @ 2024-06-27 129/week @ 2024-07-04 397/week @ 2024-07-11

845 downloads per month
Used in sysrepo

MIT license

6.5MB
142K SLoC

C 109K SLoC // 0.2% comments Rust 31K SLoC // 0.0% comments Forge Config 835 SLoC // 0.7% comments Shell 415 SLoC // 0.2% comments TCL 320 SLoC // 0.3% comments RPM Specfile 102 SLoC Bitbake 3 SLoC

yang2-rs

Crates.io Documentation MIT licensed Build Status codecov

Rust bindings for the libyang2 library.

For raw FFI bindings for libyang2, see libyang2-sys.

Cargo.toml

[dependencies]
yang2 = "0.16"

Design Goals

  • Provide high-level bindings for libyang2 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, yang2-rs uses pre-generated FFI bindings and uses dynamic linking to load libyang2. The following feature flags, however, can be used to change that behavior:

  • bundled: instructs cargo to download and build libyang2 from the sources. The resulting objects are grouped into a static archive linked to this crate. This feature can be used when having a libyang2 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 libyang2 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::sync::Arc;
use std::fs::File;
use yang2::context::{Context, ContextFlags};
use yang2::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");
    }
    let ctx = Arc::new(ctx);

    // 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/yang2-rs.

Dependencies