Rust协议处理库nu-protocol的使用指南

概述

nu-protocol是Nushell生态系统的核心协议处理库，为Nushell提供基础数据类型、协议支持和数据处理功能。它定义了Nushell中使用的核心数据结构、值类型以及与shell交互的基本协议。

主要功能

1. 提供Nushell的核心数据类型(Value, Span等)
2. 定义插件协议和序列化格式
3. 处理管道数据流
4. 支持错误处理和诊断信息

基本使用方法

添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
nu-protocol = "0.85"  # 使用最新版本

核心数据类型

nu-protocol定义了Nushell的核心Value类型：

use nu_protocol::{Value, Span};

fn create_value() -> Value {
    // 创建一个简单的整数值
    Value::int(42, Span::unknown())
}

fn create_list() -> Value {
    // 创建一个列表值
    Value::list(
        vec![
            Value::int(1, Span::unknown()),
            Value::string("hello", Span::unknown()),
            Value::bool(true, Span::unknown()),
        ],
        Span::unknown(),
    )
}

处理插件协议

nu-protocol提供了与Nushell插件系统交互的功能：

use nu_protocol::{
    PluginSignature, Plugin, EngineInterface, 
    EvaluatedCall, LabeledError, Value
};

struct MyPlugin;

impl Plugin for MyPlugin {
    fn signature(&self) -> Vec<PluginSignature> {
        vec![PluginSignature::build("my-command")
            .desc("A custom command for Nushell")
            .required("input", SyntaxShape::Any, "input value")
        ]
    }

    fn run(
        &mut self,
        name: &str,
        call: &EvaluatedCall,
        input: &Value,
        engine: &EngineInterface,
    ) -> Result<Value, LabeledError> {
        // 处理命令逻辑
        Ok(input.clone())
    }
}

错误处理

use nu_protocol::{LabeledError, Span};

fn might_fail(input: &str) -> Result<Value, LabeledError> {
    if input.is_empty() {
        Err(LabeledError {
            msg: "Input cannot be empty".into(),
            span: Some(Span::unknown()),
            labels: vec![],
            help: Some("Please provide a non-empty string".into()),
        })
    } else {
        Ok(Value::string(input.to_owned(), Span::unknown()))
    }
}

自定义值类型

use nu_protocol::{CustomValue, ShellError, Span, Value};

#[derive(Debug, Clone)]
struct MyCustomValue {
    data: String,
}

impl CustomValue for MyCustomValue {
    fn type_name(&self) -> String {
        "MyCustomValue".into()
    }

    fn to_base_value(&self, span: Span) -> Result<Value, ShellError> {
        Ok(Value::string(self.data.clone(), span))
    }

    fn as_any(&self) &dyn std::any::Any {
        self
    }
}

高级用法

实现自定义命令

use nu_protocol::{
    engine::{Command, EngineState, Stack},
    Category, Example, PipelineData, ShellError, Signature, SyntaxShape, Type, Value,
};

pub struct MyCommand;

impl Command for MyCommand {
    fn name(&self) -> &str {
        "my-command"
    }

    fn signature(&self) -> Signature {
        Signature::build("my-command")
            .input_output_types(vec![(Type::Any, Type::Any)])
            .required("arg", SyntaxShape::Any, "argument description")
            .category(Category::Custom("my-category".into()))
    }

    fn usage(&self) -> &str {
        "Description of what my-command does"
    }

    fn examples(&self) -> Vec<Example> {
        vec![Example {
            description: "Example usage",
            example: "my-command 42",
            result: Some(Value::test_int(42)),
        }]
    }

    fn run(
        &self,
        engine_state: &EngineState,
        stack: &mut Stack,
        call: &Call,
        input: PipelineData,
    ) -> Result<PipelineData, ShellError> {
        // 命令实现逻辑
        Ok(input)
    }
}

处理管道数据

use nu_protocol::{PipelineData, Value, ShellError};

fn process_pipeline(input: PipelineData) -> Result<PipelineData, ShellError> {
    input.map(move |value| {
        // 对管道中的每个值进行处理
        match value {
            Value::Int { val, span } => Value::int(val * 2, span),
            _ => value,
        }
    })
}

完整示例代码

下面是一个完整的Nushell插件示例，展示了如何使用nu-protocol创建一个自定义命令：

use nu_protocol::{
    ast::Call,
    engine::{Command, EngineState, Stack},
    Category, Example, PipelineData, ShellError, Signature, Span, Type, Value,
};

// 定义一个平方命令
pub struct SquareCommand;

impl Command for SquareCommand {
    fn name(&self) -> &str {
        "square"  // 命令名称
    }

    fn signature(&self) -> Signature {
        Signature::build(self.name())
            .input_output_types(vec![(Type::Int, Type::Int)])  // 输入输出类型
            .category(Category::Math)  // 命令分类
    }

    fn usage(&self) -> &str {
        "计算输入整数的平方"  // 命令描述
    }

    fn examples(&self) -> Vec<Example> {
        vec![
            Example {
                description: "计算5的平方",
                example: "5 | square",
                result: Some(Value::test_int(25)),
            },
        ]
    }

    fn run(
        &self,
        _engine_state: &EngineState,
        _stack: &mut Stack,
        call: &Call,
        input: PipelineData,
    ) -> Result<PipelineData, ShellError> {
        // 处理输入数据
        input.map(
            move |value| match value {
                Value::Int { val, span } => {
                    // 计算平方值
                    Value::int(val * val, span)
                }
                other => Value::error(
                    ShellError::OnlySupportsThisInputType {
                        exp_input_type: "integer".into(),
                        wrong_type: other.get_type().to_string(),
                        dst_span: call.head,
                        src_span: other.span(),
                    },
                    call.head,
                ),
            },
        )
    }
}

总结

nu-protocol是开发Nushell插件和扩展的核心库，提供了与Nushell交互所需的所有基础类型和协议。通过它，开发者可以：

1. 创建自定义命令和插件
2. 处理Nushell管道数据
3. 定义自定义值类型
4. 与Nushell引擎进行深度集成

对于更复杂的用例，建议参考Nushell官方文档和nu-protocol的源代码。