evalexpr

Evalexpr 是一个 Rust 中的表达式评估器和小型脚本语言。它具有小巧且易于使用的接口，可以轻松集成到任何应用程序中。它非常轻量级，不依赖任何其他库。Evalexpr 可在 crates.io 上获取，其 API 文档 可在 docs.rs 上获取。

最低支持的 Rust 版本 1.65.0

快速入门

将 evalexpr 作为依赖项添加到 Cargo.toml 中

[dependencies]
evalexpr = "<desired version>"

然后您可以使用 evalexpr 来 评估表达式 如此

use evalexpr::*;

assert_eq!(eval("1 + 2 + 3"), Ok(Value::from(6)));
// `eval` returns a variant of the `Value` enum,
// while `eval_[type]` returns the respective type directly.
// Both can be used interchangeably.
assert_eq!(eval_int("1 + 2 + 3"), Ok(6));
assert_eq!(eval("1 /* inline comments are supported */ - 2 * 3 // as are end-of-line comments"), Ok(Value::from(-5)));
assert_eq!(eval("1.0 + 2 * 3"), Ok(Value::from(7.0)));
assert_eq!(eval("true && 4 > 2"), Ok(Value::from(true)));

您也可以 链式 表达式并将 赋值 如此

use evalexpr::*;

let mut context = HashMapContext::new();
// Assign 5 to a like this
assert_eq!(eval_empty_with_context_mut("a = 5", &mut context), Ok(EMPTY_VALUE));
// The HashMapContext is type safe, so this will fail now
assert_eq!(eval_empty_with_context_mut("a = 5.0", &mut context),
           Err(EvalexprError::expected_int(Value::from(5.0))));
// We can check which value the context stores for a like this
assert_eq!(context.get_value("a"), Some(&Value::from(5)));
// And use the value in another expression like this
assert_eq!(eval_int_with_context_mut("a = a + 2; a", &mut context), Ok(7));
// It is also possible to save a bit of typing by using an operator-assignment operator
assert_eq!(eval_int_with_context_mut("a += 2; a", &mut context), Ok(9));

您还可以在表达式中使用 变量 和 函数 如此

use evalexpr::*;

let context = context_map! {
    "five" => 5,
    "twelve" => 12,
    "f" => Function::new(|argument| {
        if let Ok(int) = argument.as_int() {
            Ok(Value::Int(int / 2))
        } else if let Ok(float) = argument.as_float() {
            Ok(Value::Float(float / 2.0))
        } else {
            Err(EvalexprError::expected_number(argument.clone()))
        }
    }),
    "avg" => Function::new(|argument| {
        let arguments = argument.as_tuple()?;

        if let (Value::Int(a), Value::Int(b)) = (&arguments[0], &arguments[1]) {
            Ok(Value::Int((a + b) / 2))
        } else {
            Ok(Value::Float((arguments[0].as_number()? + arguments[1].as_number()?) / 2.0))
        }
    })
}.unwrap(); // Do proper error handling here

assert_eq!(eval_with_context("five + 8 > f(twelve)", &context), Ok(Value::from(true)));
// `eval_with_context` returns a variant of the `Value` enum,
// while `eval_[type]_with_context` returns the respective type directly.
// Both can be used interchangeably.
assert_eq!(eval_boolean_with_context("five + 8 > f(twelve)", &context), Ok(true));
assert_eq!(eval_with_context("avg(2, 4) == 3", &context), Ok(Value::from(true)));

您还可以 预编译 表达式如此

use evalexpr::*;

let precompiled = build_operator_tree("a * b - c > 5").unwrap(); // Do proper error handling here

let mut context = context_map! {
    "a" => 6,
    "b" => 2,
    "c" => 3
}.unwrap(); // Do proper error handling here
assert_eq!(precompiled.eval_with_context(&context), Ok(Value::from(true)));

context.set_value("c".into(), 8.into()).unwrap(); // Do proper error handling here
assert_eq!(precompiled.eval_with_context(&context), Ok(Value::from(false)));
// `Node::eval_with_context` returns a variant of the `Value` enum,
// while `Node::eval_[type]_with_context` returns the respective type directly.
// Both can be used interchangeably.
assert_eq!(precompiled.eval_boolean_with_context(&context), Ok(false));

命令行界面

虽然主要设计为库使用，但 evalexpr 也可用作命令行工具。以下是如何安装和使用它的说明

cargo install evalexpr
evalexpr 2 + 3 # outputs `5` to stdout.

功能

运算符

此包提供了一组二元和一元运算符，用于构建表达式。运算符的优先级决定了它们的评估顺序，优先级较高的运算符先被评估。优先级应类似于大多数编程语言，特别是 Rust。变量和值的优先级为 200，函数字面量的优先级为 190。

支持的二元运算符

支持的单一操作符

接受数字作为参数的操作符可以接受整数或浮点数。如果其中一个参数是浮点数，其他所有参数也会转换为浮点数，并且结果也是浮点数。否则，结果是整数。这里有一个例外是指数操作符，它总是返回一个浮点数。示例

use evalexpr::*;

assert_eq!(eval("1 / 2"), Ok(Value::from(0)));
assert_eq!(eval("1.0 / 2"), Ok(Value::from(0.5)));
assert_eq!(eval("2^2"), Ok(Value::from(4.0)));

聚合操作符

聚合操作符将一组值聚合为一个元组。元组可以包含任意值，它不受单一类型的限制。操作符是n元的，因此它支持创建长度超过两个的元组。示例

use evalexpr::*;

assert_eq!(eval("1, \"b\", 3"),
           Ok(Value::from(vec![Value::from(1), Value::from("b"), Value::from(3)])));

要创建嵌套元组，请使用括号

use evalexpr::*;

assert_eq!(eval("1, 2, (true, \"b\")"), Ok(Value::from(vec![
    Value::from(1),
    Value::from(2),
    Value::from(vec![
        Value::from(true),
        Value::from("b")
    ])
])));

赋值操作符

此crate具有赋值操作符，允许表达式在表达式上下文中将它们的结果存储在变量中。如果一个表达式使用赋值操作符，则必须以可变上下文对其进行评估。

请注意，当使用HashMapContext时，赋值是类型安全的。这意味着一旦一个标识符被分配了一个类型的值，它就不能再分配另一个类型的值。

use evalexpr::*;

let mut context = HashMapContext::new();
assert_eq!(eval_with_context("a = 5", &context), Err(EvalexprError::ContextNotMutable));
assert_eq!(eval_empty_with_context_mut("a = 5", &mut context), Ok(EMPTY_VALUE));
assert_eq!(eval_empty_with_context_mut("a = 5.0", &mut context),
           Err(EvalexprError::expected_int(5.0.into())));
assert_eq!(eval_int_with_context("a", &context), Ok(5));
assert_eq!(context.get_value("a"), Some(5.into()).as_ref());

对于每个二元操作符，都存在一个等效的操作符赋值操作符。以下是一些示例

use evalexpr::*;

assert_eq!(eval_int("a = 2; a *= 2; a += 2; a"), Ok(6));
assert_eq!(eval_float("a = 2.2; a /= 2.0 / 4 + 1; a"), Ok(2.2 / (2.0 / 4.0 + 1.0)));
assert_eq!(eval_string("a = \"abc\"; a += \"def\"; a"), Ok("abcdef".to_string()));
assert_eq!(eval_boolean("a = true; a &&= false; a"), Ok(false));

表达式链操作符

表达式链操作符的作用类似于使用分号结束语句的编程语言，如Rust、C或Java。它有一个特殊的功能，即返回表达式链中最后一个表达式的值。如果最后一个表达式也被分号终止，则返回Value::Empty。表达式链与赋值结合使用时非常有用，可以创建小的脚本。

use evalexpr::*;

let mut context = HashMapContext::new();
assert_eq!(eval("1;2;3;4;"), Ok(Value::Empty));
assert_eq!(eval("1;2;3;4"), Ok(4.into()));

// Initialization of variables via script
assert_eq!(eval_empty_with_context_mut("hp = 1; max_hp = 5; heal_amount = 3;", &mut context),
           Ok(EMPTY_VALUE));
// Precompile healing script
let healing_script = build_operator_tree("hp = min(hp + heal_amount, max_hp); hp").unwrap(); // Do proper error handling here
// Execute precompiled healing script
assert_eq!(healing_script.eval_int_with_context_mut(&mut context), Ok(4));
assert_eq!(healing_script.eval_int_with_context_mut(&mut context), Ok(5));

上下文

一个仅评估表达式的表达式评估器已经很有用，但此crate可以做得更多。它允许在表达式中使用变量、赋值、语句链和用户定义的函数。在将变量赋值时，赋值会存储在上下文中。稍后读取变量时，它将从中读取上下文。可以通过自己创建上下文来在多个对eval的调用之间保留上下文。以下是一个简单的示例，以展示在评估之间保留和不保留上下文之间的差异

use evalexpr::*;

assert_eq!(eval("a = 5;"), Ok(Value::from(())));
// The context is not preserved between eval calls
assert_eq!(eval("a"), Err(EvalexprError::VariableIdentifierNotFound("a".to_string())));

let mut context = HashMapContext::new();
assert_eq!(eval_with_context_mut("a = 5;", &mut context), Ok(Value::from(())));
// Assignments require mutable contexts
assert_eq!(eval_with_context("a = 6", &context), Err(EvalexprError::ContextNotMutable));
// The HashMapContext is type safe
assert_eq!(eval_with_context_mut("a = 5.5", &mut context),
           Err(EvalexprError::ExpectedInt { actual: Value::from(5.5) }));
// Reading a variable does not require a mutable context
assert_eq!(eval_with_context("a", &context), Ok(Value::from(5)));

请注意，第一个示例中的两次eval调用之间忘记了赋值。在第二部分中，赋值被正确地保留了。请注意，要将变量赋值，上下文需要作为可变引用传递。当以不可变引用传递时，将返回错误。

此外，HashMapContext也是类型安全的。这意味着将a再次分配为不同类型的值会导致错误。如果需要，可以实现类型不安全的上下文。对于读取a，只需要传递一个不可变引用。

也可以在代码中操作上下文。请看以下示例

use evalexpr::*;

let mut context = HashMapContext::new();
// We can set variables in code like this...
context.set_value("a".into(), 5.into());
// ...and read from them in expressions
assert_eq!(eval_int_with_context("a", &context), Ok(5));
// We can write or overwrite variables in expressions...
assert_eq!(eval_with_context_mut("a = 10; b = 1.0;", &mut context), Ok(().into()));
// ...and read the value in code like this
assert_eq!(context.get_value("a"), Some(&Value::from(10)));
assert_eq!(context.get_value("b"), Some(&Value::from(1.0)));

上下文对于用户定义的函数也是必需的。这些可以通过set_function方法逐个传递，但使用context_map!宏可能更方便

use evalexpr::*;

let context = context_map!{
    "f" => Function::new(|args| Ok(Value::from(args.as_int()? + 5))),
}.unwrap_or_else(|error| panic!("Error creating context: {}", error));
assert_eq!(eval_int_with_context("f 5", &context), Ok(10));

有关用户定义函数的更多信息，请参阅相应的部分。

内建函数

这个包提供了一组内置函数（请参阅下文以获取完整列表）。如果需要，可以通过以下方式禁用它们

use evalexpr::*;
let mut context = HashMapContext::new();
assert_eq!(eval_with_context("max(1,3)",&context),Ok(Value::from(3)));
context.set_builtin_functions_disabled(true).unwrap(); // Do proper error handling here
assert_eq!(eval_with_context("max(1,3)",&context),Err(EvalexprError::FunctionIdentifierNotFound(String::from("max"))));

并非所有上下文都支持启用或禁用内置函数。具体来说，EmptyContext 默认禁用内置函数，并且无法启用。对称地，EmptyContextWithBuiltinFunctions 默认启用内置函数，并且无法禁用。

min 和 max 函数可以处理整数和浮点数的混合。如果最大值或最小值是整数，则返回整数。否则，返回浮点数。

正则表达式函数需要 regex_support 功能标志。

值

运算符接受值作为参数并产生值作为结果。值可以是布尔值、整数或浮点数、字符串、元组或空类型。值表示如下表所示。

整数在内部表示为i64，浮点数表示为f64。

元组、整数、浮点数、类型别名

整数、浮点数、类型别名

表达式、元组、整数、浮点数、类型别名

类型别名

类型别名

类型别名

类型别名

类型别名

类型别名

变量具有优先级200。

用户定义函数

此crate允许定义任意函数以在解析表达式中使用。函数被定义为包装一个 fn(&Value) -> EvalexprResult<Value> 实例的 Function。定义需要包含在用于评估的 Context 中。目前，函数不能在表达式中定义，但这可能会在未来改变。

函数传递给它直接后面的任何值，无论是元组还是单个值。如果没有值在函数后面，则将其解释为变量。更具体地说，函数后面必须跟一个开括号 (、另一个字面量或一个值。虽然没有特别支持多值函数，但可以通过要求单个元组参数来实现。

请注意，函数需要验证传递给它们的值的类型。错误模块包含一些用于验证的快捷方式，以及用于传递错误值类型的错误类型。此外，大多数数值函数需要区分整数或浮点数被调用，并相应地操作。

以下是一些关于解释为函数调用的表达式的示例和反例

函数具有优先级190。

Serde

要使用此crate与serde一起使用，必须在 Cargo.toml 中设置 serde_support 功能标志。可以这样完成

[dependencies]
evalexpr = {version = "<desired version>", features = ["serde_support"]}

此crate为表示解析表达式树的类型 Node 实现了 serde::de::Deserialize。实现期望一个 serde string 作为输入。以下是一个使用 ron格式 的示例解析

注释

Evalexpr支持C风格的内联注释和行尾注释。内联注释以 /* 开头，并以 */ 结尾。行尾注释以 // 开头，并以换行符结尾。例如

use evalexpr::*;

assert_eq!(
    eval(
        "
        // input
        a = 1;  // assignment
        // output
        2 * a /* first double a */ + 2 // then add 2"
    ),
    Ok(Value::Int(4))
);

extern crate ron;
use evalexpr::*;

let mut context = context_map!{
    "five" => 5
}.unwrap(); // Do proper error handling here

// In ron format, strings are surrounded by "
let serialized_free = "\"five * five\"";
match ron::de::from_str::<Node>(serialized_free) {
    Ok(free) => assert_eq!(free.eval_with_context(&context), Ok(Value::from(25))),
    Err(error) => {
        () // Handle error
    }
}

使用 serde，可以将表达式集成到任意复杂的数据中。

此crate还为 HashMapContext 实现了 Serialize 和 Deserialize，但请注意，只有变量被（反）序列化，而不是函数。

许可证

该软件包主要在MIT许可证的条款下分发。有关详细信息，请参阅LICENSE。

无恐慌

该软件包广泛使用了Result模式，旨在永不引发恐慌。唯一例外是因失败的分配而引发的恐慌。但是不幸的是，Rust没有提供任何功能来证明这种行为。该软件包的开发者尚未找到任何确保无恐慌行为的好方法。请立即在github上报告此软件包中的恐慌。

即使该软件包本身无恐慌，但它允许用户定义由软件包执行的自定义函数。用户需要确保他们提供给软件包的函数永远不会引发恐慌。

不可信的输入

该软件包没有考虑到不可信的输入，但由于其简单性和无恐慌的自由，它可能是安全的，以下注意事项请牢记：

• 限制不可信输入的长度。
• 如果在评估不可信输入之间保持可变上下文，不可信输入可能会逐渐填满它，直到应用程序耗尽内存。
• 如果没有提供上下文，则隐式提供一个临时可变上下文。这将在评估每个字符串后释放，因此不会发生渐进填充。
• 如果没有提供上下文或可变上下文，并且激活了regex_support功能，则可以使用regex_replace内置函数构建一个指数级大小的字符串。

贡献

如果您有任何功能想法或看到代码、架构、接口、算法或文档中的任何问题，请在github上创建一个问题。如果有问题描述了您想说的内容，请为该问题添加点赞或其他合适的表情符号，以便我知道哪些应该优先处理。

贡献者注意事项

• 该软件包使用sync-readme cargo子命令来保持src/lib.rs和README.md中的文档同步。子命令仅从src/lib.rs中的文档同步到README.md。因此，请修改src/lib.rs中的文档，而不是在README.md中的以下内容之间进行修改：<!-- cargo-sync-readme start -->和<!-- cargo-sync-readme end -->。