slime-xml

English | 简体中文

基于 subhuti 框架的高性能 XML 解析器

简介

slime-xml 是一个使用 subhuti 解析器框架构建的严格模式 XML 解析器。它提供了完整的 XML 解析能力，包括元素、属性、文本、字符引用等完整支持，并可作为 WXML（微信小程序标记语言）解析器的基础。

特性

• ✅ 完整的 XML 1.0 支持 - 元素、属性、文本、注释、CDATA
• ✅ 字符引用处理 - 支持十进制、十六进制字符引用和预定义实体
• ✅ CST → AST 转换 - 完整的具体语法树到抽象语法树转换
• ✅ AST 打印器 - 将 AST 重新输出为格式化的 XML 字符串
• ✅ 严格的错误处理 - 详细的错误位置和诊断信息
• ✅ TypeScript - 完整的类型定义
• ✅ 零依赖 - 除 subhuti 和 slime-ast 外无其他运行时依赖

安装

npm install slime-xml

快速开始

基础解析

import XmlParser from 'slime-xml'
import XmlCstToAst from 'slime-xml/XmlCstToAst'
import XmlPrinter from 'slime-xml/XmlPrinter'

// 1. 解析 XML 字符串
const xml = '<view class="container">Hello World</view>'
const parser = new XmlParser(xml)
const cst = parser.Document()

// 2. 转换为 AST
const ast = XmlCstToAst.createDocumentAst(cst)

// 3. 打印 AST（验证 round-trip）
const output = XmlPrinter.print(ast)
console.log(output) // <view class="container">Hello World</view>

处理自闭合标签

const xml = '<image src="test.png" alt="test"/>'
const parser = new XmlParser(xml)
const cst = parser.Document()
const ast = XmlCstToAst.createDocumentAst(cst)

// AST 结构
// {
//   type: 'XmlDocument',
//   children: [{
//     type: 'XmlElement',
//     name: 'image',
//     attributes: [
//       { name: 'src', value: 'test.png' },
//       { name: 'alt', value: 'test' }
//     ],
//     children: [],
//     selfClosing: true
//   }]
// }

嵌套元素

const xml = '<view><text>Hello</text><text>World</text></view>'
const parser = new XmlParser(xml)
const cst = parser.Document()
const ast = XmlCstToAst.createDocumentAst(cst)

字符引用处理

import XmlCharRef from 'slime-xml/XmlCharRef'

// 十进制字符引用
XmlCharRef.resolveDecCharRef('A')  // 'A'

// 十六进制字符引用
XmlCharRef.resolveHexCharRef('A') // 'A'

// 预定义实体
XmlCharRef.resolveEntityRef('&lt;')    // '<'
XmlCharRef.resolveEntityRef('&gt;')    // '>'
XmlCharRef.resolveEntityRef('&amp;')   // '&'
XmlCharRef.resolveEntityRef('&quot;')  // '"'
XmlCharRef.resolveEntityRef('&apos;')  // "'"

// 转义文本
XmlCharRef.escapeText('Hello & <World>') 
// 'Hello &amp; &lt;World&gt;'

API 文档

XmlParser

主解析器类，继承自 subhuti 的 SubhutiParser。

方法

• Document() - 解析完整的 XML 文档，返回 CST
• Element() - 解析单个元素
• StartTag() - 解析开始标签
• EndTag() - 解析结束标签
• Attribute() - 解析属性

XmlCstToAst

CST 到 AST 的转换器。

静态方法

• createDocumentAst(cst) - 将 Document CST 转换为 AST
• createElementAst(cst) - 将 Element CST 转换为 AST
• createAttributeAst(cst) - 将 Attribute CST 转换为 AST
• createTextAst(cst) - 将 Text CST 转换为 AST

XmlPrinter

AST 打印器，将 AST 重新序列化为 XML 字符串。

静态方法

• print(ast) - 打印完整的 XML 文档
• printElement(element) - 打印单个元素
• printAttribute(attr) - 打印属性

XmlCharRef

字符引用处理工具。

静态方法

• resolveDecCharRef(ref) - 解析十进制字符引用
• resolveHexCharRef(ref) - 解析十六进制字符引用
• resolveEntityRef(ref) - 解析预定义实体引用
• escapeText(text) - 转义文本中的特殊字符

XmlErrorHandler

错误处理器，提供详细的错误诊断。

AST 结构

XmlDocument

interface XmlDocument {
  type: 'XmlDocument'
  children: (XmlElement | XmlText | XmlComment | XmlCData)[]
}

XmlElement

interface XmlElement {
  type: 'XmlElement'
  name: string
  attributes: XmlAttribute[]
  children: (XmlElement | XmlText | XmlComment | XmlCData)[]
  selfClosing: boolean
}

XmlAttribute

interface XmlAttribute {
  type: 'XmlAttribute'
  name: string
  value: string | StringLiteral
}

XmlText

interface XmlText {
  type: 'XmlText'
  value: string
}

开发

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 运行测试
mono test/test-parser.ts

项目结构

slime-xml/
├── src/
│   ├── XmlParser.ts           # 主解析器
│   ├── XmlTokens.ts           # Token 定义
│   ├── XmlTokenType.ts        # Token 类型
│   ├── XmlTokenConsumer.ts    # Token 消费器
│   ├── XmlCharRef.ts          # 字符引用处理
│   ├── XmlErrorHandler.ts     # 错误处理
│   ├── XmlParseError.ts       # 错误类型定义
│   ├── XmlPrinter.ts          # AST 打印器
│   └── cstToAst/
│       ├── index.ts           # CST → AST 入口
│       └── XmlCstToAst.ts     # CST → AST 转换器
├── test/                      # 测试文件
├── xmlgrammar/                # XML 语法规范文档
├── index.ts                   # 包入口
└── package.json

技术栈

• 解析器框架: subhuti
• AST 基础: slime-ast
• 构建工具: tsdown
• 语言: TypeScript 5.x

应用场景

1. WXML 解析

作为微信小程序 WXML 解析器的基础：

// WXML 可以继承 XmlParser
class WxmlParser extends XmlParser {
  // 扩展对 {{}} 插值的支持
}

2. XML 验证

验证 XML 文档的结构：

try {
  const parser = new XmlParser(xmlString)
  const cst = parser.Document()
  console.log('XML 格式正确')
} catch (error) {
  console.error('XML 解析错误:', error.message)
}

3. XML 格式化

格式化或美化 XML：

const parser = new XmlParser(messyXml)
const cst = parser.Document()
const ast = XmlCstToAst.createDocumentAst(cst)
const formatted = XmlPrinter.print(ast) // 格式化的 XML

限制

• 严格模式: 仅支持 well-formed XML，不支持 HTML 的宽松解析
• DTD: 不支持 DTD 声明和验证
• 命名空间: 当前版本不支持 XML 命名空间
• 处理指令: 不支持 <?xml ?> 等处理指令

许可证

MIT License

相关项目

• subhuti - 解析器框架
• slime-ast - JavaScript AST 工具库

Made with ❤️ by alamhubb