# @gmb/bitmark-parser-generator 中文文档

规范地址：https://npmcn.com/package/%40gmb/bitmark-parser-generator/

版本：5\.44\.3
npm 元数据更新时间：2026-11-15T22:40:29.519Z
中文译文更新时间：2026-11-16T16:59:57.919Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：26.4 MB，36 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：4 个
- 首次发布：2023-07-24T08:31:44.375Z
- 最新版本发布：2026-11-15T22:40:28.473Z
- 近 30 天下载量：6012（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：227（近 12 个月 55 个）

## 中文简介

使用 Peggy.js 的比特马克解析器和生成器

## 安装

```sh
npm install @gmb/bitmark-parser-generator
```

也可以使用：`pnpm add @gmb/bitmark-parser-generator`、`yarn add @gmb/bitmark-parser-generator`、`bun add @gmb/bitmark-parser-generator`

## README

# @ gmb/ 比特马克- parser- 生成器

[![npm](https://img.shields.io/npm/v/@gmb/bitmark-parser-generator)](https://www.npmjs.com/package/@gmb/bitmark-parser-generator) [![Downloads](https://img.shields.io/npm/dm/@gmb/bitmark-parser-generator)](https://www.npmjs.com/package/@gmb/bitmark-parser-generator) [![Publish](https://github.com/getMoreBrain/bitmark-parser-generator/actions/workflows/publish.yml/badge.svg)](https://github.com/getMoreBrain/bitmark-parser-generator/actions/workflows/publish.yml) [![License](https://img.shields.io/npm/l/@gmb/bitmark-parser-generator)](https://npmcn.com/package/%40gmb/bitmark-parser-generator/LICENSE)

一个使用 Peggy.js 的比特马克分解器和生成器.

[尝试退出比特马克 - 访问比特马克游戏场](https://getmorebrain.github.io/bitmark-playground/)

特征 :

-   将比特马克转换为 JSON, 反之亦然 .
-   程序上创建或修改比特标记.
-   在NodeJS或浏览器中工作.
-   验证并预设比特马克.
-   快活,有小浏览器足迹,不足60kB.

[支持的位元列表](https://npmcn.com/package/%40gmb/bitmark-parser-generator/SUPPORTED_BITS.md)

## 安装

### 软件包管理器

使用线条 :

```sh
$ yarn add @gmb/bitmark-parser-generator
```

使用 npm :

```sh
$ npm install @gmb/bitmark-parser-generator
```

### 光盘N

使用jsDelivr CDN(ES6 UMD模块):

```html
<script src="https://cdn.jsdelivr.net/npm/@gmb/bitmark-parser-generator@latest/dist/browser/bitmark-parser-generator.min.js"></script>
```

使用unpkg CDN(ES6 UMD模块):

```html
<script src="https://unpkg.com/@gmb/bitmark-parser-generator@latest/dist/browser/bitmark-parser-generator.min.js"></script>
```

替换 `latest` 上面任一URL中有一个特定的版本,用于使用特定的版本.

## 基本用途

### 导入

```ts
// Modules
import { BitmarkParserGenerator } from '@gmb/bitmark-parser-generator';

// CommonJS
const { BitmarkParserGenerator } = require('@gmb/bitmark-parser-generator');

// Browser UMD
const { BitmarkParserGenerator } = window.bitmarkParserGenerator;
```

### 改划

```ts
const bpg = new BitmarkParserGenerator();

// Convert bitmark markup to bitmark JSON
const json = await bpg.convert("[.article] Hello World");

// Convert bitmark JSON to bitmark markup
const bitmark = await bpg.convert('[{"bitmark": "[.article] Hello World","bit": { "type": "article", "format": "bitmark++", "bitLevel": 1, "body": "Hello World" }}]');

// Convert bitmark markup file to bitmark JSON
await bpg.convert("./input.bitmark", { output: "./output.json" });

// Convert bitmark JSON to bitmark markup
await bpg.convert("./input.json", { output: "./output.bitmark" });
```

### 转换选项

```ts
// Convert bitmark JSON to bitmark markup with options
await bpg.convert("./input.json", {
  bitmarkParserType: 'peggy',      // The parser type to use. 'peggy' or 'antlr'. Default: 'peggy'
  outputFormat: 'ast',             // Output AST rather than the default output. Default: automatic
  outputFile: "./output.ast.json", // Output to file rather than <stdout>. Default: <stdout>
  fileOptions: {
    append: true,                  // Append to output file. Default: overwrite
    encoding: 'utf8',              // Specify a file encoding. Default: 'utf8'
  },
  jsonOptions: {
    prettify: 2,                   // Prettify the JSON output. Default: not prettified
    stringify: false,              // Return JSON as a string. Default: plain JS object
    includeExtraProperties: false, // Include extra (non-standard) properties from the markup in the JSON: Default: ignore
    debugGenerationInline: false,  // [development only] Include debugging tags in the generated output. Default: false
  },
  bitmarkOptions: {
    explicitTextFormat: false,     // Include bitmark text format even when it is the default (bitmark++). Default: false
    prettifyJson: 2,               // Prettify the body JSON output. Default: not prettified
    cardSetVersion: 1,             // Output markup using the specified cardSet format. Default: 1
    debugGenerationInline: false,  // [development only] Include debugging tags in the generated output. Default: false
  }
});
```

### 程序符号创建

```ts
import { BitmarkParserGenerator, Builder, Ast, BitType, TextFormat } from 'bitmark-parser-generator';

const bpg = new BitmarkParserGenerator();
const builder = new Builder();

// Create bitmark AST programatically
const ast = builder.bitmark({
  bits: [
    builder.bit({
      bitType: BitType.article,
      textFormat: TextFormat.bitmarkText,
      body: builder.body({
        bodyParts: [
          builder.bodyText({
            text: "Hello World!"
          })
        ]
      }),
    })
  ]
});

// Write the AST to bitmark markup
bpg.convert(ast, { output: "./output.bitmark" });

// Write the AST to bitmark JSON
bpg.convert(ast, { output: "./output.json", outputFormat: 'json' });
```

### 断头

一个文本可以在程序上被断开以位标记包含.

注:建议使用上文程序比特马克创建中记录的比特构建器,而不是 手编码比特马克的创建,因为它保证了比特马克是有效的,并且所有断面都是正确的.

当将文本拆解以比特马克形式包含时,应用的拆解取决于该文本出现在 比特马克。 下列四个文本位置需要不同的断面:

| 位格式 | 文本位置 |
| --- | --- |
| 比特马克++ | 机构 |
| 比特马克++ | 标签 |
| 文本( 不是比特马克++) | 机构 |
| 文本( 不是比特马克++) | 标签 |

另外,如果纯文本分隔符 `==== text ====` ,然后在分隔符后必须使用 `text:body` 纵然是 `bitmark++`。 。 。 .

```ts
import { BitmarkParserGenerator, BodyTextFormat, TextLocation, InputType } from 'bitmark-parser-generator';

const bpg = new BitmarkParserGenerator();


const breakscaped = bpg.breakscapeText("This is the [!text] to be breakscaped", {
  inputFormat: InputType.string, // or "string"
  textFormat: BodyTextFormat.bitmarkPlusPlus, // or "bitmark++"
  textLocation: TextLocation.body, // or "body"
});
// breakscaped = "This is the [^!text] to be breakscaped"


const breakscaped = bpg.breakscapeText("This is the [!text] to be breakscaped", {
  inputFormat: InputType.string, // or "string"
  textFormat: BodyTextFormat.bitmarkPlusPlus, // or "bitmark++"
  textLocation: TextLocation.tag, // or "tag"
});
// breakscaped = "This is the [!text^] to be breakscaped"
```

### 资讯

支持位的信息可以通过信息 API 重排

```ts
import { BitmarkParserGenerator } from 'bitmark-parser-generator';

const bpg = new BitmarkParserGenerator();

// Write supported bit info to the console
const info = bpg.info();
console.log(JSON.stringify(info, null, 2));
```

### 升级

比特马克-parser-生成器可以"升级"比特马克标记或JSON. 这将升级标记 / JSON 到最近 版本并删除任何无效代码或标记.

这种感觉应该用 与原因。 它会完全删除数据.

如果输入包含无效或无法识别的数据,则会从输出中删除. 因此,这是 建议使用此特性带有源代码控制或另一个数据备份系统.

```ts
const bpg = new BitmarkParserGenerator();

// Upgrade bitmark markup
const json = await bpg.convert("[.article] Hello World [$I will be removed as I am invalid]");

// Upgrade bitmark JSON
const bitmark = await bpg.convert('[{"bitmark": "[.article] Hello World","bit": { "type": "article", "format": "bitmark++",
"bitLevel": 1, "body": "Hello World", unknownProperty: "Will be removed" }}]');

// Upgrade bitmark markup file to another file
await bpg.convert("./input.bitmark", { output: "./output.bitmark" });

// Upgrade bitmark JSON file to another file
await bpg.convert("./input.json", { output: "./output.json" });
```

### 版本

```ts
// Get the bitmar-parser-generator version
const version = bpg.version();

```

## 高级使用

更先进的使用是可能的,例如实施自定义流式输出写法.

见 [API 文档](https://npmcn.com/package/%40gmb/bitmark-parser-generator/docs/API.md) 更多信息.

## 许可证

此开源软件根据 [ISC 许可证](https://opensource.org/license/isc-license-txt)。 。 。 .

## 常见问题

### @gmb/bitmark-parser-generator 是什么？

使用 Peggy\.js 的比特马克解析器和生成器

### 如何安装 @gmb/bitmark-parser-generator？

在项目目录运行 npm install @gmb/bitmark-parser-generator，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bitmark-parser，可以用 npx bitmark-parser 直接运行。

### @gmb/bitmark-parser-generator 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gmb/bitmark-parser-generator 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gmb/bitmark-parser-generator 需要什么版本的 Node\.js？

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

### @gmb/bitmark-parser-generator 可以商用吗？

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

### @gmb/bitmark-parser-generator 的下载量有多少？

根据 npm 官方下载统计，@gmb/bitmark-parser-generator 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,012 次，日均约 200 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gmb/bitmark-parser-generator 还在维护吗？

最新版本 5\.44\.3 发布于 2026/11/16（今天）；至今共发布 227 个版本，其中过去 12 个月发布了 55 个；首次发布于 2023/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

