# @acuminous/bitsyntax 中文文档

规范地址：https://npmcn.com/package/%40acuminous/bitsyntax/

版本：0\.1\.2
npm 元数据更新时间：2022-09-01T06:42:09.130Z
中文译文更新时间：2026-11-05T17:04:34.087Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40acuminous/bitsyntax
原文对照：https://npmcn.com/package/%40acuminous/bitsyntax/?lang=original
项目主页：https://github.com/acuminous/bitsyntax-js#readme
源码仓库：https://github.com/acuminous/bitsyntax-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：78.8 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=0\.8
- 运行依赖：3 个
- 首次发布：2022-09-01T06:27:26.867Z
- 最新版本发布：2022-09-01T06:42:09.042Z
- 近 30 天下载量：1427519（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

字节缓冲图案匹配

## 安装

```sh
npm install @acuminous/bitsyntax
```

也可以使用：`pnpm add @acuminous/bitsyntax`、`yarn add @acuminous/bitsyntax`、`bun add @acuminous/bitsyntax`

## README

# 节点的字节匹配 。 联合来文

[![Node.js CI](https://github.com/acuminous/bitsyntax-js/workflows/Node.js%20CI/badge.svg)](https://github.com/acuminous/bitsyntax-js/actions?query=workflow%3A%22Node.js+CI%22) [![NPM version](https://img.shields.io/npm/v/bitsyntax.svg?style=flat-square)](https://www.npmjs.com/package/@acuminous/bitsyntax) [![NPM downloads](https://img.shields.io/npm/dm/bitsyntax.svg?style=flat-square)](https://www.npmjs.com/package/@acuminous/bitsyntax)

给出一个用于解析和构建字节缓冲的紧凑语法, 来源于 [Erlang的一点 语法](http://www.erlang.org/doc/programming_examples/bit_syntax.html#id64858)。 。 。 .

```js
var bitsyntax = require('bitsyntax');
var pattern = bitsyntax.matcher('len:8/integer, str:len/binary');
var bound = pattern(new Buffer([4, 0x41, 0x42, 0x43, 0x44]));
bound.str
// => <Buffer 41 42 43 44>
```

一个典型的用法是解析插座的字节流 。 对于 示例,大小前缀框架 :

```js
var framePattern = bitsyntax.matcher('len:32/integer, frame:len/binary, rest/binary');
socket.on('data', function process(data) {
  var m;
  if (m = framePattern(data)) {
    emit('frame', m.frame);
    process(m.rest);
  }
  else {
    stashForNextData(data);
  }
});
```

模式也可以用来从供应中构建字节缓冲 值 :

```js
var spdyDataFrame = require('bitsyntax')
  .builder('streamId:32, flags:8, length:24, data/binary');

spdyDataFrame({streamId:5, flags:0, length:bin.length, data:bin});
```

一种模式的一个或多个部分也可以多种形式提供 参数,如果这样做更方便的话;这样就更容易拆分 长线图案 :

```js
var p = bitsyntax.matcher('size:8, payload:size/binary',
                          'rest/binary');
```

## API 密码

### `matcher`

将图案编译为字符串( 或字符串), 到一个会 返回装订地图,或 `false`,以缓冲和 可选择的环境。 环境包含约束值 图案中的变量(如果有的话).

```js
var p = bitsyntax.matcher('header:headerSize/binary, rest/binary');
var b = p(new Buffer([1, 2, 3, 4, 5]), {headerSize: 3});
b.header
// => <Buffer 01 02 03>
```

火柴会回来的 `false` 如果提供的缓冲不匹配 模式;例如,如果字节太少,或字节不是 现相.

```js
var p = bitsyntax.matcher('"foo=", str/binary');
p(new Buffer("bar=humbug"));
// => false
```

### `parse` 财务报告和审定财务报表 `match`

组成时,相当于 `matcher`; 如果想要, 可能有用 考察图案的内部结构.

`parse` 字符串为 `matcher`,然后返回内部 说明模式. `match` 接受这一代表,a 缓冲和可选的环境,并返回绑定值或 `false` (如: `matcher`) (中文(简体) ).

```js
var p = bitsyntax.parse('header:headerSize/binary',
                        'rest/binary');
var b = bitsyntax.match(p, new Buffer([1, 2, 3, 4, 5]),
                          {headerSize: 3});
b.header
// => <Buffer 01 02 03>
```

### `builder`

使用模式并返回将构建字节的函数 缓冲,为模式中提及的变量设定值.

```js
var cons = bitsyntax.builder('size:8, bin/binary');
cons({size:6, bin:new Buffer('foobar')});
// => <Buffer 06 66 6f 6f 62 61 72>
```

提供给构建者的模式与模式略有不同 为匹配而提供,见下文.

### `build`

使用解析的图案和可变值地图,然后返回 a 缓冲。 一样 `match`,可能对调试模式有用.

```js
var pattern = bitsyntax.parse('size:8, bin:size/binary');
bitsyntax.build(pattern, {size:6, bin: new Buffer('foobar')});
// => <Buffer 06 66 6f 6f 62 61 72>
```

### `write`

根据 给出解析模式 。 返回完成偏移, 即已提供 页:1.

```js
var pattern = bitsyntax.parse('size:8, bin/binary');
var buf = new Buffer(7);
bitsyntax.write(buf, 0, pattern,
                {size:6, bin: new Buffer('foobar')});
// => 7
buf
// => <Buffer 06 66 6f 6f 62 61 72>
```

## 模式

图案是片段的序列,每个片段匹配一个值. 部分 有一般形式

```
 value:size/type_specifier_list
```

大小和类型规格列表可省略,另加三个 变量 :

```
value
value:size
value/type_specifier_list
```

类型区分符列表是一个关键词列表,由 连字. 类型描述如下.

图案一般作为字符串提供,以逗号分隔 系列片段.

### 变量或数值

片段的第一部分给出了可变名称或文字 数值。 如果给出了一个可变名称, 与段匹配的值 将被绑定在图案的其余部分的可变名称上。 如果有的话 给出字面值,匹配值必须等同该值。 如果有的话 变量的值在环境中给出,匹配的值必须 等于所提供的价值.

当在构建器中使用时,字面值将被复制到 缓冲按它给出的类型。 变量名称表示 用于复制向构建器提供的值的槽.

特殊可变名称 `_` 丢弃匹配的值; 即它 仅跳过输入中的适当位数。“ ”是 不允许在构建者模式中.

### 大小和单位

片段的大小按照数值或变量给出, 以冒号分隔 :

```
foo:32
```

该单位在规格清单中列为\`单位'和\`单位' 以冒号分隔的整数:

```
foo:4/integer-unit:8
```

大小为值中单位数;单位作为 位数。 单位可以使用,例如当您想要 匹配数个字节的整数,而不是数个比特.

对于整数和浮点,默认单位为 1 位;以保留事物 对齐字节边界, `unit * size` 在当前必须是多个 8. 对于二进制单位,默认单位为8,单位必须是 倍数八分.

如果大小被省略而类型是整数,大小默认为 8. 如果省去大小而类型为二进制,则段会 匹配输入中所有剩余字节; 此段可能只是 当匹配时,在图案结尾处使用.

大小也可以作为较早时匹配的整数变量 模式,如上方给出的例子。 当建造时, a 大小可能是指所提供环境的变量.

在建造者中,数字会被四舍五入、蒙上面具或加上以适应大小 单位;例如, `'256:8'` 给出二进制 `Buffer<00>` 因为最低的8位是0; `'255:16` 给出二进制 `Buffer<00 ff>`。 。 。 .

### 类型名称描述符

一个 `integer`, (中文(简体) ), `binary`, (中文(简体) ), `string`, (中文(简体) ), `float`未给出时 默认为 `integer`。 。 。 .

整数是大或小的,签名或未签名 整数。 最多32位的整数被支持. 已签名的整数为 2 的补充格式。 在JavaScript中,只有-(2^53)之间的整数 和 2^53 可显示,且位元运算符仅定义于 32位签名整数.

二进制只是字节缓冲;通常这会导致切片 输入缓冲器被返回时,请注意突变.

字符串是一个由给定字节数组成的UTF8字符串.

浮点是32位或64位 IEEE754 浮点值(这是 标准JavaScript与Java和Erlang一样使用.

### 强度描述符

整数可能是大-或小-endian;这是指哪个"end" of 构成整数的字节最为显著。 在网络中 协议整数通常是大后端的,意思是第一个 (左-最)字节是最重要的,但这并不总是 案例.

说明 `big` 表示整数将被解析(或写入) (结果)作为大endian,和 `little` 表示整数将是 解说或写作小-endian。 默认为大德.

### 签名规格

整数片段可包括下列规格: `signed` 或者说 `unsigned`A级 签名整数被解析为两个补充格式。 默认是 未签名.

签名在构建者中被忽略.

### 字串

在图案中出现的引用字符串是字节的快取 其UTF8编码. 譬如说,

```
"foobar", _/binary
```

匹配任何以字节开头的缓冲 `0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72`。 。 。 .

在构建器中使用时,引用的字符串会被复制到结果中,原因是 其UTF8编码的字节.

## 实例

以下对应的字节以数组表示: 方便所缘. 记住 `match()` 需要缓冲器 对应的字节。 “返回X为Y”或“输入X为Y” Y"表示返回值是一个有X值映射到密钥的对象 对.

```
54
```

匹配单字节 `54`。 。 。 .

```
54:32
```

匹配字节 \[0,0,54\].

```
54:32/little
```

匹配字节 \[54,0, 0\].

```
54:4/unit:8
```

匹配字节 \[0,0,54\].

```
int:32/signed
```

匹配四个字节的二进制,返回一个签名的32位整数为 `int`。 。 。 .

```
len:16, str:len/binary
```

匹配二进制 `2 + len` 字节,返回未签名的 16 位 整数为 `len` 和长度缓冲 `len` 作为 `str`。 。 。 .

```
len:16, _:len/binary, rest/binary
```

匹配至少一个二进制 `2 + len` 字节,绑定一个未签名的 16 位 整数为 `len`,忽略下一个 `len` 字节,并绑定 剩余(可能为零长)二进制为 `rest`。 。 。 .

```
s:8, key:s/binary, value/binary
```

环境 `{s:6, key: "foobar"}`,将匹配二进制 从 \[6, 0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72,.\]开始.

## 常见问题

### @acuminous/bitsyntax 是什么？

字节缓冲图案匹配

### 如何安装 @acuminous/bitsyntax？

在项目目录运行 npm install @acuminous/bitsyntax，或使用 pnpm add / yarn add / bun add。

### @acuminous/bitsyntax 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/acuminous\_\_bitsyntax 是否存在。

### @acuminous/bitsyntax 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @acuminous/bitsyntax 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=0\.8。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @acuminous/bitsyntax 可以商用吗？

@acuminous/bitsyntax 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @acuminous/bitsyntax 的下载量有多少？

根据 npm 官方下载统计，@acuminous/bitsyntax 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,427,519 次，日均约 47,584 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @acuminous/bitsyntax 还在维护吗？

最新版本 0\.1\.2 发布于 2022/09/01（4 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/09/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。