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"] }

no_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_communication_example
• ethernet_example
• ipv4_example
• tcp_example
• http_hashmap_example
• http_vec_example
• parse_example: 包含 Ethernet/IPv4/TCP/UDP

特性

ContainerAttrModifiers

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

枚举分支

• byte_count_disable
• branch_enum

FieldAttrModifiers

• 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

枚举分支

• branch=<int|variable>：例如：branch example
• branch_option=<variable>：例如：branch_option example.rs
• branch_default：例如：branch_default example
• branch_bits：例如：branch_bits example
• branch_range：例如：branch_range example
• branch_value：例如：branch_value example

DataType

• u8/u16/u32/u64/usize/u128
• i8/i16/i32/i64/isize/i128
• bool
• f32/f64
• String 和 &str
• array[T;N]
• Tuple
• Vec<T>
• &[u8]
• Option<T>
• Struct
• Enum
• PhantomData
• HashMap：支持 String/&str/&[u8]，例如：hashmap_example。
• HashSet<T>：必须指定 HashSet 类型，并使用 #[jppe(count=xxx)] 修饰符，仅支持解码函数，默认 count=0，例如：hashset_example。
• MacAddress：例如：mac_example。
• std::net::Ipv4Addr/Ipv6Addr/IpAddr：需要指定 length=<16|4> 修饰符，否则返回错误，例如：ip_address_example。
• PpeAddress：需要指定 length=<16|4|6|usize> 修饰符，否则返回错误，例如：ppe_address_example。
• HexString：例如：hex_example
• HexBytes：例如：hex_bytes_example
• DateTime
• Bit