# @atomist/microgrammar 中文文档

规范地址：https://npmcn.com/package/%40atomist/microgrammar/

版本：1\.2\.1
npm 元数据更新时间：2023-02-23T17:59:18.387Z
中文译文更新时间：2026-11-07T03:37:26.668Z
软件包许可：SEE LICENSE IN LICENSE

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

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

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

- 包体积（解压后）：369 kB，172 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=8\.0\.0
- 运行依赖：3 个
- 首次发布：2017-06-21T03:43:43.515Z
- 最新版本发布：2019-07-20T16:04:27.432Z
- 近 30 天下载量：3661（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：94（近 12 个月 0 个）

## 中文简介

解析库以填补正则表达式和完整语法之间的空白

## 安装

```sh
npm install @atomist/microgrammar
```

也可以使用：`pnpm add @atomist/microgrammar`、`yarn add @atomist/microgrammar`、`bun add @atomist/microgrammar`

## README

# @atomist/微缩图

[![atomist sdm goals](http://badge.atomist.com/T29E48P34/atomist/microgrammar/92d2035b-575e-41c4-9088-996dc70d69c2)](https://app.atomist.com/workspace/T29E48P34) [![npm version](https://img.shields.io/npm/v/@atomist/microgrammar.svg)](https://www.npmjs.com/package/@atomist/microgrammar)

正在解析库中 [类型脚本](https://www.typescriptlang.org/ "TypeScript"),填补巨大的空白 介于正则表达式的甜点和全响之间 [银行](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form "Backus–Naur Form") 或等同的语法. 它可以分析 和干净地更新 结构化内容.

## 概念

**微语法** 是分析结构化内容的有力方式 如源代码,在此描述 [斯坦福论文](http://web.stanford.edu/~mlfbrown/paper.pdf "How to build static checking systems using orders of magnitude less code Brown et al., ASPLOS 2016")。 。 。 . 微语法旨在识别字符串中的结构或 流并提取其内容: 例如, 要识别 Java 具有特定注释和提取特定 参数。 他们更强大 [比较一般 可读](https://stackoverflow.com/questions/1732348/regex-match-open-tags-except-xhtml-self-contained-tags#answer-1732454) 比起来 [正则表达式](https://en.wikipedia.org/wiki/Regular_expression) 用于复合体 例,尽管可以使用正则表达式构建.

原子学家的微语法超越了斯坦福的论文例子 他们允许 _更新_ 以及匹配,保留位置。 他们 也从其他经验和来源,例如: 旧 [SNOBOL 编程语言](https://en.wikipedia.org/wiki/SNOBOL "SNOBOL Programming Language")。 。 。 .

## 实例

有两种使用方式:

-   从 _定义_: 在 JavaScript 中定义代表子组件的语法对象( 低等出品)
-   从字符串:在类似输入的字符串中定义语法 将匹配

微语法有一个由定义定义的回回类型. 每个匹配执行此接口以及 `PatternMatch` 界面,它暴露出输入和匹配值中的偏移值,可能与被输入值不同。 (例如,a `Person` 可能有一个 `forename` 财务报告和审定财务报表 `surname`,但其 `$matched` 值可能包括整个匹配的有白空间的字符串。 ) 田园 `PatternMatch` 界面从一个 `$` 以确保他们脱离乐队.

当定义了微语法时,可以使用它来匹配输入:通常是字符串.

发电机式的迭代通常效率最高,看起来是这样:

```typescript
const matches = myMicrogrammar.matchIterator(inputString);
for (const match of matches) {
    // Do with match. You can jump out of the generator here.
}
```

你也可以得到所有匹配 在一个通行证,像这样:

```typescript
const matches = myMicrogrammar.findMatches(inputString);
for (const match of matches) {
    // Do with match
}
```

如果您只想要一个匹配, 您可以使用返回匹配的方法 `undefined`,内容如下:

```typescript
const match = myMicrogrammar.firstMatch(inputString);
if (match) {
    // Do with match
}
```

### 定义样式

这里有一个简单的例子:

```typescript
const mg = microgrammar<{name: string, age: number}>({
    name: /[a-zA-Z0-9]+/,
    _col: ":",
    age: Integer
});

const results = mg.findMatches("-celine:61 greg*^ tom::: mandy:11");
assert(result.length === 2);
const first = results[0];
assert(first.$matched === "celine:61");
// The offset of this match was the 1st character, as the 0th was discarded
assert(first.$offset === 1);
assert(first.name === "celine");
assert(first.age === 61);
```

一些说明:

-   微语法定义一般为对象字面,带有 属性依次匹配。 这就像 **协和** 在一个BNF语法.
-   匹配属性值可以是正则表达式( 如 `/[a-zA-Z0-9]+/` 这里),字符串正文(如 `:`),或习惯 匹配者( 如 `Integer`) (中文(简体) ). 很容易定义自定义匹配者 用于构成.
-   所有属性都需要匹配整个微语法才能匹配.
-   匹配的属性与结果相接, 除非它们的名字开始于 `_`时 复数.
-   带值中的某些值, 首先 `$`,添加到 结果,显示匹配的准确文本、相抵等.
-   在使用TypeScript时,微语法返回可以被强烈地打入. 在这种情况下,我们已经 使用匿名类型, 但我们也可以使用接口 。 我们 也可以使用未打字的JavaScript样式.
-   匹配跳过垃圾, 如 `greg*^ tom:::`在这种情况下, `greg` 财务报告和审定财务报表 `tom:` 看起来像是有效匹配的开始,但 当它不能匹配时,首先会失败 `:` 和第二个何时 结肠后面没有数字.
-   我们可以比对一串或一串流。 在这种情况下,我们用 一个字符串。 在水流匹配中,我们更可能使用一个a API 提供回调而不是建立阵列, 所以我们不 需要我们所有的火柴 立即在记忆中.

当然,这样一个简单的例子可以很容易地由经常人员处理 表达和捕捉组。 但力量变得明显 筑巢出产并更精细相配.

一个更复杂的例子,显示构成:

```typescript
export const CLASS_NAME = /[a-zA-Z_$][a-zA-Z0-9_$]+/;

// Any annotation we're not interested in
const DiscardedAnnotation = {
    _at: "@",
    _annotationName: CLASS_NAME,
    _content: optional(JavaParenthesizedExpression),
};

const SpringBootApp = microgrammar<{ name: string }>({
    _app: "@SpringBootApplication",
    _content: optional(JavaParenthesizedExpression),
    _otherAnnotations: zeroOrMore(DiscardedAnnotation),
    _visibility: optional("public"),
    _class: "class",
    name: CLASS_NAME,
});
```

这符合这样的内容:

```java
@SpringBootApplication
@Foo
@Bar(name = "Baz", magicParam = 31754)
public class MySpringBootApplication
```

注释:

-   `JavaParenthesizedExpression` 是一个内置匹配器常数 匹配任何有效的 Java 内容 `(...)`它使用状态 机器。 机器。 。 写这种习俗相配者很容易.
-   默认情况下,微语法对白空间是宽容的,对待它 作为符号分隔符. 这是我们在分析时想要的行为 大多数语言或配置格式.
-   因为其他的属性 名字从 `_`,仅限 类名( e)`MySpringBootApplication` (以我们为例) 对结果。 我们关心其余部分的结构 类声明,但我们不需要在 这个案子.

### 字符串样式

这是一个更高水平的使用模式,其中的字符串类似于 需要输入但有可变占位符用于定义 语法.

这种风格最适合更简单的语法. 例如:

```typescript
const ValuePredicateGrammar = microgrammar<Predicate>({
    phrase: "@${name}='${value}'"});
```

它可以通过提供定义样式结合 指定字段的可选定义。 例如,限制 使用正则表达式进行上述示例中名称上的匹配 :

```typescript
const ValuePredicateGrammar = microgrammar<Predicate>({
    phrase: "@${name}='${value}'", 
    terms: {
        name: /[a-z]+/
    }
});
```

与对象定义样式一样,白空间默认被忽略.

进一步的文件可在以下网址查阅: [参考文献](https://npmcn.com/package/%40atomist/microgrammar/docs/reference.md)。也可以检查测试 在此仓库中.

## 替代品和何时使用微语法

微语法与 [BNF 语法](https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form "Backus–Naur Form")不过 一些重要方面有所不同:

-   它们是为了匹配和解释 _组件_ 输入,而不是 而不是整个输入
-   他们很擅长跳过他们不感兴趣的内容
-   他们不一定自由的背景
-   它们不需要建造一个完整的AST,尽管它们建造 匹配结构的AST. 因此,他们很容易应付 部分结构化数据, 愉快地跳过无法理解的内容

相似之处有:

-   设想 **生产**
-   可编织性,包括再利用生产的能力 不同的语法
-   业务,例如 _备选案文_, (中文(简体) ), _选项_ 财务报告和审定财务报表 _代表_,那个 能够建立复杂的结构.

相较于正则表达式,微语法为:

-   能够提出更复杂的问题
-   更可调和
-   更高级别, 能够使用正则表达式作为构件
-   能够表达嵌入式结构
-   通过类型脚本函数上游和 自定义 **匹配点**

虽然使用一个微语法来做一些 可以用简单的regex表示,微语法往往更清晰 对于复杂的案件.

## 使用量

这个 [`@atomist/microgrammar` 软件包](https://www.npmjs.com/package/@atomist/microgrammar "@atomist/microgrammar Node.js Package") 包含两个 TypeScript打字并编译了JavaScript. 您可以使用此项目 通过在您的 `package.json`。 。 。 .

```
$ npm install --save @atomist/microgrammar
```

## 解决问题

如果你努力使你的微语法吻合 请参考 [排除出错的页面](https://npmcn.com/package/%40atomist/microgrammar/docs/trouble.md "Troubleshooting microgrammars")。 。 。 .

## 业绩考虑

见 [写入高效的微语法](https://npmcn.com/package/%40atomist/microgrammar/docs/performance.md "Writing efficient microgrammars")。 。 。 .

## 支助

一般性支持问题应在缔约方会议 `#support` 频道 [原子主义社区](https://join.atomist.com/ "Atomist Community Slack")。 。 。 .

如果你发现问题,请创建 [问题](https://github.com/atomist/microgrammar/issues)。 。 。 .

## 发展

您需要安装 [节点.js](https://nodejs.org/ "Node.js") 来建立和测试这个 项目.

### 构建和测试

安装依赖关系 .

```
$ npm install
```

使用 `build` 用于编译、测试、嵌入和构建 文档.

```
$ npm run build
```

### 释放

释放是通过 [原子学家SDM](https://github.com/atomist/atomist-sdm "Atomist Software Delivery Machine")按钮 在原子仪表板或Slack上的“证明”按钮.

* * *

创建于 [原子学家](https://atomist.com/ "Atomist - How Teams Deliver Software")。 。 。 . 需要帮忙吗? [加入我们的黑工作区](https://join.atomist.com/ "Atomist Community Slack")。 。 。 .

## 常见问题

### @atomist/microgrammar 是什么？

解析库以填补正则表达式和完整语法之间的空白

### 如何安装 @atomist/microgrammar？

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

### @atomist/microgrammar 支持 TypeScript 吗？

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

### @atomist/microgrammar 支持 ESM 还是 CommonJS？

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

### @atomist/microgrammar 需要什么版本的 Node\.js？

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

### @atomist/microgrammar 可以商用吗？

@atomist/microgrammar 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @atomist/microgrammar 的下载量有多少？

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

### @atomist/microgrammar 还在维护吗？

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