node-buffer-helper v1.0.10
一、简介
一个用于解析Buffer数据的简单封装,这个库的开发初衷是用于解析一些协议方面的数据,对Buffer的一个简单的封装,设计采用Stream数据流动的思想。
它提供了一个Reader类,包含readArray、readInt、readShort、readByte四个方法,用于从Buffer中读取指定长度的数据,并提供一些简单数据转换函数。
也有Writer类,向Buffer中写数据。
二、Reader
2.1 constructor(buff,data)
- 参数
{Buffer} buff:需要解析的Buffer对象
{Object} data
用法 初始化一个Reader实例,使用
new Reader(buff)
或者Reader(buff)
初始化一个Reader
。示例
var buff = Buffer.from([1,2,3,4,5,6,7]) Reader(buff) //或者 new Reader(buff)
以上语法都会返回一个Reader的实例,可以不用new的语法是希望提供一种函数式初始化语法。data是一个可选项,如果有data参数,那么Reader解析出来的结果会挂载在data对象上。
2.2 Reader.prototype.readByte(options)
- 参数
{String | Object} options:解析的选项
- 用法 从buffer中取出1个字节,并将其转换成数值。
2.3 Reader.prototype.readShort(options)
- 参数
{String | Object} options:解析的选项
- 用法 从buffer中取出2个字节,并将其转换成数值。
2.4 Reader.prototype.readInt(options)
- 参数
{String | Object} options:解析的选项
- 用法 从buffer中取出4个字节,并将其转换成数值。
2.5 Reader.prototype.readArray(options)
- 参数
{String | Object} options:解析的选项
- 用法 从buffer中取出非固定长度的字节,长度在options中给定默认为0,并将其转换成整数数组。
2.6 Reader.prototype.Value()
- 用法 获取Reader解析的结果,得到的结果是一个Object对象
2.7 Reader.prototype.Sum()
- 用法 获取已经读取的数据byte的和,buffer还未读到的部分不会参与计算。主要目的是为了求校验和。
- 示例
var buffer = Buffer.from([1,2,3,4,5])
Reader(buffer).readArray({
len:4
}).Sum() //=>10
2.8 Reader.prototype.check(len)
- 参数
{Number} len:检查长度
- 用法
检查buffer剩余长度是否超过len,每次读取数据的时候会自动被调用,如果读取长度超过当前buffer的剩余长度,会抛出一个异常
throw new Error("读取长度超过buffer!")
。
2.9 Reader.prototype.validate(validate_fn,data)
- 参数
-
{Function} validate_fn:验证函数,目前仅支持函数,不支持表达式
-{Object} data:read之后的数组
- 用法
对解析的结果进行验证,如果验证失败会抛出一个异常
throw new Error("验证失败")
,这个函数也是自动被调用的,当读取时options的选项中包含validate
参数时有效。这个函数的出现为了解析数据时验证数据包的头部 - 示例
var buffer = Buffer.from([0x68,0,0,0,0x68])
Reader(buffer).readByte({
key:'head',
validate:(data)=>{data==0x68}
}).Value() //=>{head:0x68}
2.10 Reader.prototype.map(fn)
参数 -
{Function} fn:对buffer的每一个元素都执行fn方法
用法 正常的对数组的map操作,不过它只会修改buffer还未被读取的部分。
示例
var buffer = Buffer.from([1,1,1,1,1])
Reader(buffer).readByte('head').map(x=>x+2).readByte('body').Sum() //=>4
补充
options
参数可以字符串或者object,如果传递参数为字符串,会被转换成{key:options}
。options
支持以下选项:
{String} key
:写入data的键值,如果为空则不会将解析结果放入到最后的data中{Function} validate
:验证解析结果,如果验证失败会抛出异常,目前暂不支持自定义异常提示{Function} callback
:对结果执行解析结果执行callback,并将callback的结果存放到data中,它在验证之后执行{Number} len
:如果是读取数组需要用到该选项,指定读取的长度,默认为0
三、Writer
2.1 constructor(data)
- 参数
{Object} data:预先给定一些可能需要用到的数据,后面可以通过key取到结果,暂不支持表达式
用法 初始化一个Writer实例,使用
new Writer()
或者Writer(data)
初始化一个Writer
。以上语法都会返回一个Writer的实例,可以不用new的语法是希望提供一种函数式初始化语法,data是一个可选项。
2.2 Writer.prototype.writerByte(options)
- 参数
{String | Object | Number | Array} options
- 用法 向Buffer中写入1个字节的数据。
2.3 Writer.prototype.writeShort(options)
- 参数
{String | Object | Number | Array} options:解析的选项
- 用法 向Buffer中写入2个字节的数据。
2.4 Writer.prototype.writeInt(options)
- 参数
{String | Object | Number| Array} options:解析的选项
- 用法 向Buffer中写入4个字节的数据。
2.5 Writer.prototype.writeArray(options)
- 参数
{String | Object | Number | Array} options:解析的选项
- 用法 向Buffer中写入指定字节的数据,长度在options中给定默认为0,并将其转换成整数数组。
2.6 Writer.prototype.Value()
- 用法 获取一个Buffer实例
2.7 Writer.prototype.Sum()
- 用法 获取已经写入部分的和,也是为了求校验和
2.8 补充
options
参数可以字符串或者object,如果传递参数为String
,则会从构造函数中传递的data中取值,options
对象变成如下的形式{value:this.data[options]}
,如果传递的参数为Number
或者Array
,options
则变成{value:options}
。options
支持以下选项:
{String} value
:即将要解析的值,会转换成对应的格式。如果超过长度会截断,不足会补0。{Number} len
:如果是写入数组需要用到该选项,指定读取的长度,默认为0{Function} callback
:对即将要写入的结果执行callback,并将callback的结果写入
四、后期添加功能
为了能用于更多的场景,后期应该添加一些功能拟定如下:
- 读取UTF-8串
- 写入UTF-8串
- 读取PNG图片
- 写入PNG图片