Haystack库

在Rust编程语言中实现Haystack 4规范。

该库涵盖了规范的大部分内容，并使用cargo功能来允许选择性地启用功能，例如 解码器、过滤器、单位、时区 以及 C FFI API。

此实现旨在构建高性能的Haystack应用程序，这些应用程序还可以在受限制的设备上高效运行。对于更通用的实现，J2 Innovations还提供了一个TypeScript实现。目前，该库需要分配器功能和标准库，但它可以编译为WASM作为非OS目标。

构建

使用 cargo cargo build 创建调试版本，cargo build --release 创建发布版本。

可以为每个功能集专门构建，可以编译为 cargo build --release --no-default-features --features "encoders, zinc"，这将仅编译核心类型和zinc编码模块，从而生成较小的二进制文件（Windows x86-64上为12KB）

测试

使用 cargo test 运行单元和集成测试

文档

通常，每当发布时，库的文档都会在docs.rs上生成。

特性

类型

库的基本类型是Value。它可以存储Haystack支持的任何数据类型。

标量类型

从字符串&str创建一个Str Value

use libhaystack::val::*;
// Creates a Str Value
let value = Value::from("Hello");

// Get a std::String from the value
assert!(String::try_form(value).expect("String"), "Hello");

使用一个单位创建一个Number Value

use libhaystack::val::*;
use libhaystack::units::*;

// Creates a Number Value using the Value helper function
let a = Value::make_number_unit(42, get_unit("m³"));

// Creates the Number scalar
let b = Number::make_with_unit(100.0, "m³".into());

// Add numbers with units
assert_eq!(Number::try_form(a).expect("Number") + b, Number::make_with_unit(142.0, get_unit("m³")));

复杂类型

创建一个Haystack Dict

use libhaystack::val::*;

// Create the Dict type
let dict = Value::from(dict! {
    "site" => Value::make_marker(),
    "name" => Value::make_str("Foo")
});

assert!(dict.has("site"));
assert_eq!(dict_value.get_str("name"), Some(&"Foo".into()));

// Wrap the type as a Value
let value: Value = dict.into();
assert!(value.is_dict());

过滤器

提供了一个遵守Haystack 4规范的过滤器解析器和评估器，它使用来自Project Haystack的本体定义。

use libhaystack::dict;
use libhaystack::val::*;
use libhaystack::filter::*;

// Parse the filter from a string
let filter = Filter::try_from(r#"site and dis=="Test""#).expect("Filter");

// Define a Dict to apply the filter against
let dict = dict!{"site" => Value::make_marker(), "dis" => Value::from("Test")};

// Verify that the filter matched the Dict
assert_eq!(dict.filter(&filter), true);

// Filter using advanced ontology query
let filter = Filter::try_from(r#"^geoPlace and dis=="Test""#).expect("Filter");

// Sites are [geoPlaces](https://project-haystack.org/doc/lib-phIoT/site)
let dict = dict!{"site" => Value::make_marker(), "dis" => Value::from("Test")};

// Verify that the filter matched the Dict
assert_eq!(dict.filter(&filter), true);

编码

库提供了对JSON和Zinc编码的支持。

JSON通过出色的Serde库提供，而Zinc则提供为手动调优的解码器和编码器，以及以性能为导向的流式懒Grid行解析器。

use libhaystack::val::*;
// Decode a `Str` haystack `Value` from JSON encoding
let value: Value = serde_json::from_str("'hello'").unwrap();

use libhaystack::val::*;
use libhaystack::encoding::zinc::*;
// Decode a `Number` haystack `Value` from Zinc encoding
let value: Value = decode::from_str("42s").unwrap();

C API

此库公开了一个基于C的API，允许其他编程语言通过C FFI使用它。头文件生成使用cbindgen完成。

构建头文件

cbindgen --lang c -q --crate libhaystack --output src/c_api/libhaystack.h

请参阅仓库中分发的预生成的头文件。

Webassembly支持

通过利用C API，可以调用浏览器、Node.js或Deno中公开的函数。

为此，使用wasm-pack生成wasm二进制文件、初始化的JS包装器以及API定义的类型脚本文件。

wasm-pack build --out-dir wasm --target web