Rust语言解释器库lead_lang_interpreter使用指南

概述

lead_lang_interpreter是一个高效的Rust脚本解释器库，提供动态脚本解析和执行能力。它适用于需要嵌入脚本功能的应用程序，如游戏脚本、自动化工具或配置系统。

主要特性

• 轻量级解释器实现
• 高效的解析和执行性能
• 支持变量、函数和控制结构
• 易于与Rust主程序集成
• 安全执行沙箱环境

安装

在Cargo.toml中添加依赖：

[dependencies]
lead_lang_interpreter = "0.3.0"

基本使用方法

1. 创建解释器实例

use lead_lang_interpreter::{Interpreter, RuntimeError};

fn main() -> Result<(), RuntimeError> {
    let mut interpreter = Interpreter::new();
    
    // 执行简单脚本
    let result = interpreter.execute("let x = 5 + 3; x * 2")?;
    println!("Result: {:?}", result); // 输出: Result: Value::Number(16.0)
    
    Ok(())
}

2. 注册自定义函数

use lead_lang_interpreter::{Interpreter, Value, RuntimeError};

fn main() -> Result<(), RuntimeError> {
    let mut interpreter = Interpreter::new();
    
    // 注册Rust函数到解释器
    interpreter.add_function("double", |args| {
        if let Value::Number(n) = args[0] {
            Ok(Value::Number(n * 2.0))
        } else {
            Err(RuntimeError::TypeError)
        }
    });
    
    let result = interpreter.execute("double(5)")?;
    println!("Result: {:?}", result); // 输出: Result: Value::Number(10.0)
    
    Ok(())
}

3. 脚本变量交互

use lead_lang_interpreter::{Interpreter, Value, RuntimeError};

fn main() -> Result<(), RuntimeError> {
    let mut interpreter = Interpreter::new();
    
    // 从Rust设置变量
    interpreter.set_variable("app_version", Value::String("1.0.0".to_string()));
    
    // 执行脚本获取变量
    interpreter.execute("let greeting = 'Hello from version ' + app_version")?;
    
    if let Some(Value::String(greeting)) = interpreter.get_variable("greeting") {
        println!("{}", greeting); // 输出: Hello from version 1.0.0
    }
    
    Ok(())
}

高级功能

1. 控制流支持

use lead_lang_interpreter::{Interpreter, RuntimeError};

fn main() -> Result<(), RuntimeError> {
    let script = r#"
        let x = 10;
        let result = 0;
        
        if x > 5 {
            for i in 0..x {
                result = result + i;
            }
        } else {
            result = -1;
        }
        
        result
    "#;
    
    let mut interpreter = Interpreter::new();
    let result = interpreter.execute(script)?;
    println!("Sum: {:?}", result); // 输出: Sum: Value::Number(45.0)
    
    Ok(())
}

2. 模块化脚本执行

use lead_lang_interpreter::{Interpreter, RuntimeError};

fn main() -> Result<(), RuntimeError> {
    let mut interpreter = Interpreter::new();
    
    // 加载并执行多个脚本
    interpreter.execute("fn square(x) { x * x }")?;
    interpreter.execute("let base = 4")?;
    let result = interpreter.execute("square(base + 1)")?;
    
    println!("Result: {:?}", result); // 输出: Result: Value::Number(25.0)
    
    Ok(())
}

性能优化建议

1. 对于重复执行的脚本，考虑先编译再执行：

let compiled = interpreter.compile("expensive_computation()")?;
for _ in 0..100 {
    interpreter.execute_compiled(&compiled)?;
}

1. 限制脚本执行资源：

let mut interpreter = Interpreter::with_limits(1000, 1024); // 1000步操作，1KB内存

错误处理

use lead_lang_interpreter::{Interpreter, RuntimeError};

fn main() {
    let mut interpreter = Interpreter::new();
    
    match interpreter.execute("5 + 'text'") {
        Ok(result) => println!("Success: {:?}", result),
        Err(e) => match e {
            RuntimeError::TypeError => println!("Type mismatch in operation"),
            RuntimeError::SyntaxError(msg) => println!("Syntax error: {}", msg),
            RuntimeError::RuntimeError(msg) => println!("Runtime error: {}", msg),
            _ => println!("Other error occurred"),
        },
    }
}

安全注意事项

1. 默认情况下，解释器运行在沙箱环境中，无法访问系统资源
2. 如果暴露敏感API，确保进行适当验证
3. 考虑设置执行超时限制长时间运行的脚本

lead_lang_interpreter为Rust应用程序提供了灵活的脚本功能，通过合理使用可以显著增强应用程序的可扩展性和动态性。

完整示例

下面是一个结合了多种功能的完整示例：

use lead_lang_interpreter::{Interpreter, Value, RuntimeError};

fn main() -> Result<(), RuntimeError> {
    // 1. 创建带有限制的解释器实例
    let mut interpreter = Interpreter::with_limits(5000, 2048); // 5000步操作，2KB内存
    
    // 2. 注册自定义函数
    interpreter.add_function("greet", |args| {
        if let Value::String(name) = &args[0] {
            Ok(Value::String(format!("Hello, {}!", name)))
        } else {
            Err(RuntimeError::TypeError)
        }
    });
    
    // 3. 设置应用程序变量
    interpreter.set_variable("app_name", Value::String("ScriptDemo".to_string()));
    
    // 4. 执行多个脚本片段
    interpreter.execute(r#"
        fn calculate(x) {
            if x > 100 {
                x / 2
            } else {
                x * 2
            }
        }
    "#)?;
    
    // 5. 获取脚本执行结果
    let result = interpreter.execute(r#"
        let user = "Alice";
        let greeting = greet(user);
        let score = calculate(150);
        
        app_name + ": " + greeting + " Your score is: " + score
    "#)?;
    
    // 6. 处理结果
    if let Value::String(output) = result {
        println!("{}", output); // 输出: ScriptDemo: Hello, Alice! Your score is: 75
    }
    
    // 7. 错误处理示例
    match interpreter.execute("5 + true") {
        Ok(_) => println!("Operation succeeded"),
        Err(e) => println!("Error occurred: {:?}", e), // 将输出类型错误
    }
    
    Ok(())
}

这个完整示例展示了：

1. 创建带有限制的解释器实例
2. 注册自定义函数
3. 设置和获取变量
4. 执行多个脚本片段
5. 处理控制流和函数调用
6. 错误处理机制