#yaml-parser #low-level #pure #language #events #specification #memory-safety

yaml-rust-olidacombe

为 Rust 缺失的 YAML 1.2 解析器

1 个不稳定版本

0.6.0 2024年2月8日

#18 in #yaml-parser


用于 serde-yaml-olidacombe

MIT/Apache

150KB
4.5K SLoC

yaml-rust

为 Rust 提供缺失的 YAML 1.2 实现。

Build status crates.io docs.rs

yaml-rust 是一个纯 Rust YAML 1.2 实现,它享受 Rust 语言带来的内存安全特性和其他好处。解析器受到 libyamlyaml-cpp 的很大影响。

快速开始

将以下内容添加到您的项目的 Cargo.toml 中

[dependencies]
yaml-rust = { version = "0.6", package = "yaml-rust-davvid" }

使用 yaml::YamlLoader 来加载 YAML 文档并将其作为 Vec/HashMap 访问

use yaml_rust::{YamlLoader, YamlEmitter};

fn main() {
    let s =
"
foo:
    - list1
    - list2
bar:
    - 1
    - 2.0
";
    let docs = YamlLoader::load_from_str(s).unwrap();

    // Multi document support, doc is a yaml::Yaml
    let doc = &docs[0];

    // Debug support
    println!("{:?}", doc);

    // Index access for map & array
    assert_eq!(doc["foo"][0].as_str().unwrap(), "list1");
    assert_eq!(doc["bar"][1].as_f64().unwrap(), 2.0);

    // Chained key/array access is checked and won't panic,
    // returns BadValue if the key does not exist.
    assert!(doc["INVALID_KEY"][100].is_badvalue());

    // Dump the YAML object
    let mut out_str = String::new();
    {
        let mut emitter = YamlEmitter::new(&mut out_str);
        emitter.dump(doc).unwrap(); // dump the YAML object to a String
    }
    println!("{}", out_str);
}

请注意,yaml_rust::Yaml 实现了 Index<'a str> & Index<usize>

  • Index<usize> 假设容器是一个数组
  • Index<'a str> 假设容器是一个字符串到值的映射
  • 否则,将返回 Yaml::BadValue

如果您的文档不符合此约定(例如具有复杂类型键的映射),您可以使用 Yaml::as_XXX 系列API来访问您的文档。

功能

  • 纯 Rust
  • Ruby 风格的数组/哈希访问 API
  • 低级 YAML 事件发射

规范兼容性

此实现旨在提供与 YAML 1.2 规范完全兼容的 YAML 解析器。解析器可以正确解析规范中的几乎所有示例,除了以下已知错误

  • 某些上下文中的空普通标量

然而,广泛使用的库 libyaml 也无法解析这些示例,因此这可能不是大多数用户的大问题。

安全性

这个库不会尝试解释YAML文档中的任何类型说明符,因此,通过解析YAML文档就实例化套接字并与外部世界通信,例如,不会存在风险。

目标

  • 编码器
  • 标签指令
  • 反序列化时的别名

Rust最低版本策略

本crate的最低支持的rustc版本是1.31(随Rust 2018发布,在v0.4.3之后),因为这也是目前已知regex的最低版本。

许可证

许可协议为以下之一

任选其一。

贡献

在Github上Fork & PR。

除非你明确表示,否则根据Apache-2.0许可证定义的,你有意提交以包含在本工作中的任何贡献,将按上述方式双重许可,不附加任何额外条款或条件。

致谢

yaml-rust-davvid是原版、现在已不再维护的yaml-rust解析器chyh1990的分支。

依赖项

~4MB
~58K SLoC