Skip to content

Latest commit

 

History

History
261 lines (205 loc) · 10.8 KB

README-zh_CN.md

File metadata and controls

261 lines (205 loc) · 10.8 KB

jbytes

Crates.io Crates.io License

这是一个基于Rust实现的字节流结构化序列化/反序列化通用库，可以应用于网络数据包解析、网络数据包组包、网络通信、文件内容解析等，觉得不错的小伙伴们请点个赞👍~

安装

Cargo.toml

[dependencies]
jbytes = { version="0.2.0", features = ["derive"] }

no_std:

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

例子

Bytes例子

use jbytes::prelude::*;


fn main() {
    let bytes = Bytes::new(b"\x01\x02\x03");
    assert_eq!(bytes.take_be_u16(), Ok(0x0102));
    assert_eq!(bytes.take_be_u16().is_err(), true);
}

Buffer例子

use jbytes::prelude::*;


fn buffer_example(buffer: &mut Buffer) -> JResult<()>  {
    buffer.push_be_u16(1)?;
    buffer.push(b"\x01\x02\x03")?;

    Ok(())
}


fn main() {
    let mut buffer = Buffer::new();
    if buffer_example(&mut buffer).is_ok() {
        assert_eq!(*buffer, b"\x00\x01\x01\x02\x03");
    }
}

简单例子

use jbytes::{ByteEncode, ByteDecode};
use jbytes::prelude::*;


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode)]
pub struct SimpleExample {
    pub length: u16,
    // 这里是指定动态长度，也可以指定固定数值，比如：`#[jbytes(length=3)]`
    // 还可以不指定`length`, 指定`byte_count=<1..8>`表示提前取走几个字节根据字节序转为长度数值
    #[jbytes(length="length")]
    pub value: String,
    pub cmd: u8,
    // 这里指定了branch, 表示根据cmd的值进行枚举类型(enum)模式匹配, 同样也可以不指定branch, 指定`byte_count=<1..8>`修饰符
    #[jbytes(branch="cmd")]
    pub body: SimpleExampleBody,
}


#[derive(Debug, PartialEq, Eq, ByteEncode, ByteDecode)]
pub enum SimpleExampleBody {
    #[jbytes(branch_value=1)]
    Read {
        address: u8,
    },                        // 这里表示当前面的`cmd`字段为1，则会进入该分支解析
    Write {
        address: u8,
        value: [u8; 3],
    },                        // 这里如果不指定，默认是递增的关系为2
    #[jbytes(branch_default)]
    Unknown,                  // 这里由于指定了默认分支，所以会被映射为`_ => { ... }`, 如果没有指定，Unknown序号为3，其他则会返回解析错误
}


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

默认值例子

[dependencies]
jbytes = { version="0.2.0", features = ["derive", "jdefault"] }
use jbytes::{ByteEncode, ByteDecode, Jdefault};
use jbytes::prelude::*;


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


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


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

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

    let value: SimpleExample = jbytes::decode(b"\x03\x31\x32\x33\x03\x0a")?;
    assert_eq!(value, SimpleExample {
        value: "123".to_string(),
        body: SimpleExampleBody::Unknown { value: 10 },
    });
}

其他例子

数据类型

  • u8/u16/u32/u64/usize/u128
  • i8/i16/i32/i64/isize/i128
  • bool
  • char
  • f32/f64
  • String
  • &str
  • &[u8]
  • array[T; N]
  • tuple
  • Vec<T>
  • Option<T>
  • Struct
  • Enum
  • PhantomData
  • HashMap
  • HashSet
  • MacAddress
  • std::net::Ipv4Addr
  • std::net::Ipv6Addr
  • std::net::IpAddr
  • NetAddress
  • HexString
  • DateTime
  • Bit

宏修饰属性

ContainerAttrModifiers

主要用于修饰某个struct/enum全局定义，表示struct/enum里面的字段都遵循，也可以通过FieldAttrModifiers修饰单个内容。

通用修饰符

  • byteorder=<"BE"|"LE">: 表示字节序，BE(大端字节序)/LE(小端字节序)，eg: byteorder example。
  • encode_with=<func>: 自定义encode函数，eg: encode_with example。
  • decode_with=<func>: 自定义decode函数，eg: decode_with example。
  • with=<mod>: 自定义encode/decode函数，eg: with example。
  • get_variable_name=<variable>: 获取缓存变量, 必须配合variable_name使用，可以用于不同struct或enum类型传递, eg: variable_name_example。

枚举(Enum)类型修饰符

  • byte_count_disable: 禁用默认读取1个字节，实现match匹配枚举分支。
  • branch_enum

FieldAttrModifiers

主要用于修饰struct/enum里面某个字段内容

  • byteorder=<"BE"|"LE"|variable(BE=0,LE=1)>: 表示字节序，BE(大端字节序)/LE(小端字节序)，eg: byteorder example。
  • length=<num|variable>: 表示读取数据的长度，支持int/&str/String/&[u8]/Vec类型，eg: length example。
  • offset=<num|variable>: 表示从当前位置向前前进n个位置，实现数据流的位置偏移，eg: offset example。
  • full=<int>: 表示用于encode编码填充值, 默认为0, 常常用于offset偏移之后进行encode编码填充, eg: full example。
  • byte_count=<1..8>: 表示取几个字节转成整型，代表后续需要读取的字节流长度，eg：byte_count example。
  • remaining: 表示取走剩余所有字节，eg：remaining example。
  • untake: 表示读取数据不移动位置，后续可以继续从该位置读取数据，eg: untake example。
  • encode_value=<expr>: value处理表达式，eg: encode_value example。
  • decode_value=<expr>: value处理表达式，eg: decode_value example。
  • variable_name=<variable>: 指定整型类型缓存变量，并通过get_variable_name修饰符在其他Struct/Enum使用，eg: variable_name example。
  • skip: 表示跳过该字段的encode/decode函数，类型需要实现Defaulttrait，eg：skip example。
  • skip_encode: 表示跳过该字段的encode函数，eg：skip_encode example。
  • skip_decode: 表示跳过该字段的decode函数，类型需要实现Defaulttrait，eg：skip_decode example。
  • if_expr=<bool expr>: 指定if条件表达式，支持Option<T>类型，eg: if_expr example。
  • encode_with=<func>: 自定义encode函数，eg: encode_with example。
  • decode_with=<func>: 自定义decode函数，eg: decode_with example。
  • with=<mod>: 自定义encode/decode函数，eg: with example。
  • with_args=<variable>: 自定义encode/decode函数参数，eg: with_args example。
  • linend|end_with=<string|bytes>：指定结束位置，支持String/&str/&[u8]/HashMap等类型，eg：linend。
  • key|starts_with：指定精准匹配关键字，必须配合linend使用，支持string/&str/&[u8]等类型，eg：key example。
  • split: 指定分隔符, 常常用于Key: Value这种内容, 支持HashMap类型, eg: split example
  • from_str: 表示通过FromStr类型进行转换，eg：from_str example。
  • from_str=<type>：表示通过Type::FromStr类型进行转换，eg：from_str example。
  • check_value：主要用于检查结果是否正常，如果异常会返回错误，eg：check_value example。

容器类型修饰符，比如：Vec/HashMap/HashSet等

  • count=<num|variable>: 表示容器元素数量，支持Vec/HashMap/HashSet类型，eg：count example。
  • try_count=<num|variable>: 表示容器元素数量, 如果不足，不会返回解析错误，支持Vec/HashMap/HashSet类型，eg：try_count example。
  • byte_count_outside=<1..8>：表示容器元素数量，类似byte_count，该修饰符应用Vec/HashMap/HashSet等类型，eg：byte_count_outside example。

enum branch