# @gooddata/maql-antlr4ts 中文文档

规范地址：https://npmcn.com/package/%40gooddata/maql-antlr4ts/

版本：0\.7\.2
npm 元数据更新时间：2026-10-27T14:13:36.463Z
中文译文更新时间：2026-11-16T19:15:25.299Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：669 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2023-07-18T12:10:35.186Z
- 最新版本发布：2026-10-27T10:59:47.781Z
- 近 30 天下载量：41764（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：784（近 12 个月 158 个）

## 中文简介

MAQL 的脚本借记和解析器

## 安装

```sh
npm install @gooddata/maql-antlr4ts
```

也可以使用：`pnpm add @gooddata/maql-antlr4ts`、`yarn add @gooddata/maql-antlr4ts`、`bun add @gooddata/maql-antlr4ts`

## README

# MAQL ANTRR4TS npm 软件包

模块捆绑了 TypeScript MAQL lexer 从 MAQL 语法生成的解析器, 一个访问者创建MAQL AST, 一个抽象的AST访问者与MAQL AST合作.

语法和解析器由 [蚂蚁-ng](https://github.com/mike-lischke/antlr-ng) 运行在 [蚂蚁4纳克](https://github.com/mike-lischke/antlr4ng) 运行时间,它被宣布为此软件包的依赖. 运行时间本身没有依赖关系,并且Node.js内建要求,因此软件包在浏览器中工作 没有多填充.

> 说明: `antlr4ng` 必须在消耗性申请中解决一个副本。 如果申请取决于 `antlr4ng` 直接或通过另一个软件包(例如: `antlr4-c3`,它必须使用与 这个包,否则 `instanceof` 运行时间副本之间检查失败 .

软件包名称保存历史 `antlr4ts` 后缀 `antlr4ts` 不再使用运行时间 .

示例用法:

```typescript
import { CharStream, CommonTokenStream } from "antlr4ng";

import { MaqlLexer, MaqlParser, MaqlAstVisitor, AstNormalizer } from "@gooddata/maql-antlr4ts";

const maql =
    "parse metric SELECT SUM(0.81 * {fact/price} * {fact/quantity}) BY {attribute/country} WITHOUT PF";
const charStream = CharStream.fromString(maql);
const lexer = new MaqlLexer(charStream);
const tokenStream = new CommonTokenStream(lexer);
const parser = new MaqlParser(tokenStream);
const parseTree = parser.maql();
const astVisitor = new MaqlAstVisitor(workspace, tokenStream);
const ast = astVisitor.visit(parseTree);
const normalizer = new AstNormalizer();
const normalizedAst = normalizer.visit(ast);
```

语法宣布 `caseInsensitive` 选项,生成的 Lexer 将尊重它,所以 MAQL 关键词可能是 写在任何字母的平面 `CharStream`。 。 。 .

使用导出 `CaseInsensitiveCharStream` 改为 `CharStream.fromString` 当符号位置必须 匹配 JavaScript 字符串偏移或 LSP 范围。 以 Unicode 代码点表示的 antlr4ng 溪流索引, 因此是一个字符 基本多语言计划(例如emoji)之外 `start`, (中文(简体) ), `stop` 财务报告和审定财务报表 `column` 与源字符串相对. `CaseInsensitiveCharStream` 由UTF-16代码单位编制索引,因此其位置是 字符串对齐.

## 地方发展

> 所需经费: [`pnpm`](https://pnpm.io/)

| 命令 | 效果 |
| --- | --- |
| `pnpm install` | 安装所有依赖关系 |
| `pnpm build` | 生成源文件、 类型检查和编译 `esm/` |
| `pnpm codegen` | 从 MAQL 语法和函数定义生成源文件 |
| `pnpm antlr4` | 从 MAQL 语法生成 Lexer、 解析器、 听众和访客 |
| `pnpm funcdef` | 从 MAQL 函数定义生成源文件 |
| `pnpm build-check` | 类型检查所有来源,包括测试 |
| `pnpm build-ts` | 编译 `src/` 输入 `esm/` 不检查类型 |
| `pnpm clean` | 删除 `esm/` 产出 |
| `pnpm test` | 以监视模式运行所有测试 |
| `pnpm test-once` | 运行所有测试一次 |
| `pnpm test-ci` | 使用 junit.xml 输出文件运行所有测试 |
| `pnpm lint` | 运行牛林和 ESLint |
| `pnpm lint-fix` | 自动修正克林特和ESLint错误 |
| `pnpm format` | 检查使用oxfmt的格式 |
| `pnpm format-fix` | 用 oxfmt 自动修正格式 |
| `pnpm validate` | 运行 `pnpm lint` 财务报告和审定财务报表 `pnpm format` |

ANTLR语法生活在 `../maql-parser/src/main/antlr`创建源 `src/gen/` 却不是 实施; `pnpm build` 使他们再生。 发电机运行在Node.js上,不需要Java.

## 将软件包与其他模块链接

首先安装依赖,然后构建模块.

`pnpm install`

`pnpm build`

> 警告: 不使用 `pnpm link` 或者说 `npm link`。 。 。 .
> 
> 符号链接此软件包可以使耗用应用程序加载第二个副本 `antlr4ng` 运行时间, 中断 `instanceof` 在运行时间检查两份副本之间.

使用 [雅尔克语](https://github.com/wclr/yalc) 将软件包链接到其他寄存器.

1.  运行 `yalc publish` 在当前目录中.
2.  运行 `yalc add @gooddata/maql-antlr4ts` 在目标目录中
3.  一旦你完成了测试运行 `yalc remove @gooddata/maql-antlr4ts` 或者说 `yalc remove --all`

## 出版

要发布软件包,请运行 [发布 maql antlr4ts npm](https://github.com/gooddata/gdc-nas/actions/workflows/publish_maql_antlr4ts_npm.yml) GitHub 手动工作流程 .

工作流程发布预发版本 `<package.json version + 1 patch>-<commit sha>.0`,例如 `0.5.1-a5e4f136.0`。 。 。 . 它能移动npm `latest` 与这个版本相对应。 它不会使版本返回。 为了提高基础版本, 变动 `version` 内 `package.json` 在运行工作流程前使用公关.

工作流程发布为 npm [值得信赖的出版](https://docs.npmjs.com/trusted-publishers) (OIDC),所以它不需要npm令牌. 受信任的出版并不支持自备跑车,因此工作流程运行在由GitHub托管跑车上.

### 信任的出版商设置

软件包的可信赖的出版商在npm上设定一次. 本节记录了它是如何设置的,以便您可以修改或再次设置.

你可以用其中一种方式设置:

-   **在 npm 用户界面** https://www.npmjs.com/package/@gooddata/maql-antlr4ts/access. 互联网档案馆的存檔,存档日期2013-12-22.
    
-   **与npm CLI. (英语).** 使用 npm 11.1.0 或 更新的, 其有: `npm trust` 命令. 登录到 npm (`npm login`)作为用户 `gooddata-ci`。 。 。 . 用户必须发布访问权限 `@gooddata/maql-antlr4ts` 和两要素认证. 然后运行 :
    
    ```sh
    npm trust github @gooddata/maql-antlr4ts \
        --file publish_maql_antlr4ts_npm.yml \
        --repo gooddata/gdc-nas \
        --allow-publish
    ```
    

要查看当前配置, 请运行 `npm trust list @gooddata/maql-antlr4ts`。 。 。 .

## 常见问题

### @gooddata/maql-antlr4ts 是什么？

MAQL 的脚本借记和解析器

### 如何安装 @gooddata/maql-antlr4ts？

在项目目录运行 npm install @gooddata/maql-antlr4ts，或使用 pnpm add / yarn add / bun add。

### @gooddata/maql-antlr4ts 支持 TypeScript 吗？

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

### @gooddata/maql-antlr4ts 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gooddata/maql-antlr4ts 可以商用吗？

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

### @gooddata/maql-antlr4ts 的下载量有多少？

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

### @gooddata/maql-antlr4ts 还在维护吗？

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

