jppe-rs

这是一个基于Rust的字节流结构化序列化/反序列化通用库，可用于网络包解析、网络包分组、网络通信、文件内容解析等，感觉好的小伙伴们请点赞👍~

安装

$ rustup install nightly
$ cargo +nightly build release

用法

Cargo.toml

[dependencies]
jppe = { version="1.1.0", features = ["derive"] }

或

[dependencies]
jppe = { version="1.1.0", features = ["derive", "serde"] }

无std

[dependencies]
jppe = { version="1.1.0", default-features = false, features = ["derive"] } # default use alloc.

简单示例

use jppe::{ByteEncode, ByteDecode};


// If the value size is less than 0xff, byte_count does not need to be specified,otherwise, byte_count=<2|4|8>


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode)]
pub struct SimpleExample {
    pub version: u8,
    // #[jppe(byte_count=1)]
    pub value: String,
    // #[jppe(byte_count=1)]
    pub body: SimpleExampleBody,
}


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode)]
#[repr(u8)]
pub enum SimpleExampleBody {
    Read {
        address: u8,
    } = 1,
    Write {
        address: u8,
        value: [u8; 3],
    },
    #[jppe(enum_default)]
    Unknown, 
}


fn main() {
    let input = b"\x01\x03\x31\x32\x33\x01\x05";
    let (input_remain, value) = jppe::decode::<SimpleExample>(input).unwrap();
    assert_eq!(value, SimpleExample { version: 1, value: "123".to_string(), body: SimpleExampleBody::Read { address: 5 } });
    assert_eq!(input_remain.is_empty(), true);
    assert_eq!(jppe::encode(value), input);
}

简单示例2

use jppe::{ByteEncode, ByteDecode};


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode)]
pub struct SimpleExample {
    pub length: u16,
    #[jppe(length="length")]
    pub value: String,
    pub cmd: u8,
    #[jppe(branch="cmd")]
    pub body: SimpleExampleBody,
}


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode)]
#[repr(u8)]
pub enum SimpleExampleBody {
    Read {
        address: u8,
    } = 1,
    Write {
        address: u8,
        value: [u8; 3],
    },
    #[jppe(enum_default)]
    Unknown, 
}


fn main() {
    let input = b"\x00\x03\x31\x32\x33\x01\x05";
    let (input_remain, value) = jppe::decode::<SimpleExample>(input).unwrap();
    assert_eq!(value, SimpleExample { length: 3, value: "123".to_string(), cmd: 1, body: SimpleExampleBody::Read { address: 5 } });
    assert_eq!(input_remain.is_empty(), true);
    assert_eq!(jppe::encode(value), input);
}

默认示例

[dependencies]
jppe = { version="1.1.0", features = ["derive", "jdefault"] }

use jppe::{ByteEncode, ByteDecode, Jdefault};


// If the value size is less than 0xff, byte_count does not need to be specified,otherwise, byte_count=<2|4|8>


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode, Jdefault)]
pub struct SimpleExample {
    #[jppe(byte_count=1, default="\"123\".to_string()")]
    pub value: String,
    #[jppe(byte_count=1)]
    pub body: SimpleExampleBody,
}


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode, Jdefault)]
#[repr(u8)]
pub enum SimpleExampleBody {
    Read {
        address: u8,
    } = 1,
    Write {
        address: u8,
        value: [u8; 3],
    },
    #[jppe(branch_default)]
    Unknown {
        #[jppe(default=10)]
        value: u8,
    },
}


fn main() {
    let value = SimpleExample::default();
    assert_eq!(value, SimpleExample {
        value: "123".to_string(),
        body: SimpleExampleBody::Unknown { value: 10 },
    });

    assert_eq!(jppe::encode(value), b"\x03\x31\x32\x33\x03\x0a");

    let (input_remain, value) = jppe::decode::<SimpleExample>(b"\x03\x31\x32\x33\x03\x0a").unwrap();
    assert_eq!(value, SimpleExample {
        value: "123".to_string(),
        body: SimpleExampleBody::Unknown { value: 10 },
    });
    assert_eq!(input_remain.is_empty(), true);
}

其他示例

• tcp通信示例
• 以太网示例
• IPv4示例
• tcp示例
• http散列表示例
• http向量示例
• 解析示例：包括以太网/IPv4/TCP/UDP

特性

容器属性修改器

• byteorder=<"BE"|"LE">：结构和枚举的全局字节顺序，例如：#[jppe(byteorder="LE")]。
• encode_with：自定义编码函数。
• decode_with：自定义解码函数。
• with：自定义编码/解码函数。
• get_variable_name：获取缓存变量，必须与 variable_name 一起使用，例如：变量名示例。

枚举分支

• 禁用字节计数
• 枚举分支

字段属性修改器

• byteorder=<"BE"|"LE">：局部性字段的数据字节顺序，例如：#[jppe(byteorder="LE")]
• length=<num|variable>：数据长度，支持 int/&str/String/&[u8] 类型，例如：length_example。
• offset=<num|variable>：字节流偏移。
• count==<num|variable>：数据计数，支持 Vec/HashMap 类型。
• try_count==<num|variable>：数据计数，支持 Vec/HashMap 类型。
• full=<int>：编码完整值。
• untake：不取字节。
• linend|end_with=<string|bytes>：支持 String/&str/&[u8] 类型。
• key|starts_with：适用于对键/值结构数据的精确解析，支持 string/&str/&[u8] 类型。
• split：支持 HashMap 类型，例如：split_example。
• if_expr：支持 Option<T> 类型，例如：if_expr_example。
• encode_with：自定义编码函数，例如：with_example。
• decode_with：自定义解码函数，例如：with_example。
• with：自定义编码/解码函数，例如：with_example。
• with_args：自定义编码/解码函数参数，例如：with_args_example。
• encode_value：值处理表达式，例如：#[jppe(encode_value="length * 2")]。
• decode_value：值处理表达式，例如：#[jppe(decode_value="length / 2")]。
• variable_name：设置整数缓存变量，例如：variable_name_example。
• byte_count=<1|2|4|8>：指定字节数，自动解码/编码长度或其他。
  • String/&str/&[u8]：提前获取n个字节的映射长度，例如：byte_count。
  • HexString/HexBytes：提前获取n个字节的映射长度，例如：byte_count。
  • Enum：提前获取byte_count字节的枚举映射并编码通过枚举索引，例如：enum_byte_count
  • Vec<T>
• skip：要求数据类型实现Default特质。
• skip_encode：跳过编码函数。
• skip_decode：要求数据类型实现Default特质。
• check_value
• default：例如：default example
• from_str