@gmb/bitmark-parser-generator

中文文档
5.44.3发布于 2026/11/16ISCTypeScriptESM + CJS构建来源已验证近 30 天下载 6012

A bitmark parser and generator using Peggy.js

原始使用文档
文档目录14 节
  1. Installation
  2. Package manager
  3. CDN
  4. Basic Usage
  5. Import
  6. Conversion
  7. Convertion Options
  8. Programmatic Bitmark Creation
  9. Breakscaping
  10. Info
  11. Upgrade
  12. Version
  13. Advanced Usage
  14. License

@gmb/bitmark-parser-generator

npm Downloads Publish License

A bitmark parser and generator using Peggy.js.

Try out bitmark - visit the bitmark Playground

Features:

  • Convert bitmark to JSON, and vice-versa.
  • Programmatically create or modify bitmark.
  • Works in NodeJS or the browser.
  • Validate and prettify bitmark.
  • Fast, with a small browser footprint, less than 60kB.

List of supported bits

Installation

Package manager

Using yarn:

$ yarn add @gmb/bitmark-parser-generator

Using npm:

$ npm install @gmb/bitmark-parser-generator

CDN

Using jsDelivr CDN (ES6 UMD module):

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

Using unpkg CDN (ES6 UMD module):

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

Replace latest with a specific version in either of the URLs above to use a specific version.

Basic Usage

Import

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

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

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

Conversion

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" });

Convertion Options

// 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
  }
});

Programmatic Bitmark Creation

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' });

Breakscaping

A text can be breakscaped programmatically for inclusion in bitmark.

NOTE: It is recommended the bit builder documented above in Programmatic Bitmark Creation is used rather than hand-coding bitmark creation, because it guarantees the bitmark will be valid, and all breakscaping will be correct.

When breakscaping a text for inclusion in bitmark, the breakscaping applied depends on where that text appears in the bitmark. The following four text locations require different breakscaping:

Bit FormatText Location
bitmark++body
bitmark++tag
text (not bitmark++)body
text (not bitmark++)tag

Also, if a plain text divider ==== text ==== is used, then text after the divider must be breakscaped using text:body even if the bit is bitmark++.

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"

Info

Information about the supported bits can be retreived via the info API

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));

Upgrade

The bitmark-parser-generator can 'upgrade' bitmark markup or JSON. This will upgrade the markup / JSON to the latest version and remove any invalid code or markup.

THIS FEATURE SHOULD BE USED WITH CAUTION. IT WILL POTENTIALLY DELETE DATA.

If the input contains data that is invalid or unrecognised, it will be removed from the output. Therefore it is recommended to use this feature with source code control or another system for data backup.

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" });

Version

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

Advanced Usage

More advanced usage is possible, such as implementing custom streaming output writers.

See the API Documentation for more information.

License

This open source software is licenced under the ISC licence.

版本与发布记录

@gmb/bitmark-parser-generator 共发布 227 个版本,首次发布于 2023/07/24;过去 12 个月发布了 55 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.44.3latest2026/11/16今天
5.44.22026/11/133 天前
5.44.02026/10/131 个月前
5.43.02026/10/121 个月前
5.42.02026/09/142 个月前
5.41.02026/09/072 个月前

关于 @gmb/bitmark-parser-generator 的常见问题

@gmb/bitmark-parser-generator 是什么?

A bitmark parser and generator using 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 和提交记录判断。