ANTLR4 Swift 目标完整指南从语法生成到 Xcode / SwiftPM 工程集成【免费下载链接】antlr4ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.项目地址: https://gitcode.com/gh_mirrors/an/antlr4本文以 ANTLR4 官方文档 doc/swift-target.md 为主体结合仓库中 Swift 运行时runtime/Swift与代码生成器tool/src/org/antlr/v4/codegen/target/SwiftTarget.java的源码实现系统讲解如何在 Swift 项目中使用 ANTLR4包括性能优化前提、用-DlanguageSwift生成词法/语法分析器、通过boot.py辅助脚本接入 Xcode 工程与 Swift Package Manager以及通过accessLevel选项控制生成代码的访问级别。读完本文你将掌握在 Swift 中从.g4语法文件到可运行解析器的完整落地流程。性能前提务必开启编译器优化release 模式ANTLR4 的 Swift 运行时在未开启编译器优化的调试构建下解析速度会明显偏低。因此只要用于生产环境就必须打开编译器优化。使用Swift Package Manager构建时请使用release构建配置即swift build -c release或swift run -c release该配置会预设全部优化项使用Xcode构建时生产构建默认使用release配置同样包含完整优化。结论很简单让 ANTLR4 Swift 运行时获得合理解析速度的前提就是始终以release模式构建。准备工作安装 ANTLR 工具开始之前请确认本机已安装 ANTLR 工具本身。安装与首次使用流程可参考 doc/getting-started.md其中涵盖 JDK 环境、ANTLR jar 的获取方式以及antlr4命令的配置方法。生成 Swift 词法分析器与语法分析器基本命令在 Swift 中生成解析器的流程与 Java 完全一致唯一区别是必须显式指定语言目标$ antlr4 -DlanguageSwift MyGrammar.g4执行后ANTLR 会依据MyGrammar.g4中的词法规则与语法规则在 Swift 运行时之上生成对应的MyGrammarLexer.swift、MyGrammarParser.swift以及监听器/访问器等文件。面向 Xcode 构建步骤的选项如果要把语法生成集成进 Xcode 的构建步骤建议使用gnu消息格式让 Xcode 能够正确解析工具输出的错误信息并在 IDE 中定位使用-o选项把自动生成的文件输出到独立子目录避免与手写源码混在一起。antlr4 -DlanguageSwift -message-format gnu -o Autogen MyGrammar.g4ANTLR 工具的全部选项请参见 doc/tool-options.md。源码层面的补充SwiftTarget 的实现细节从生成器源码 tool/src/org/antlr/v4/codegen/target/SwiftTarget.java 可以看到 Swift 目标的具体实现保留字处理维护了一份完整的 Swift 保留字表包括class、func、public、try、#selector、_等当语法中的标识符与保留字冲突时通过escapeWord()将其包裹为反引号形式如class保证生成代码可编译字符转义定义了\0、\\、\t、\n、\r、\、\等转义映射非 ASCII 字符则通过escapeChar()输出为\u{X}格式的 Unicode 转义。这些细节意味着即便你的语法文件里出现了与 Swift 关键字同名的规则或 token 名生成的代码依然能通过 Swift 编译器。boot.pySwift 运行时辅助脚本boot.py位于 runtime/Swift/boot.py是 Swift 目标特有的辅助脚本为 Xcode 工程与 SPM 工程两种接入方式提供支持。快速上手可先运行python boot.py --help从源码看它支持三个主要参数参数适用者作用--gen-xcodeproj开发者 / 用户为 ANTLR4 Swift 运行时生成 Xcode 工程Antlr4.xcodeproj并会先生成工程所依赖的全部测试语法解析器--gen-spm-module用户生成一个 Swift Package Manager 风格的本地模块便于以 SPM 依赖方式引入 ANTLR4--test开发者生成解析器并运行单元测试底层调用swift test需要注意的是boot.py会从~/.m2/repository/org/antlr/antlr4/*-SNAPSHOT目录查找antlr4-*-SNAPSHOT-complete.jar对应mvn install的产物并通过$JAVA_HOME定位java可执行文件。也就是说使用它之前需要先在 ANTLR4 项目根目录执行mvn install构建出完整 jar并正确配置 Java 环境。生成解析器时它实际执行的命令等价于java -jar antlr4-*-SNAPSHOT-complete.jar -DlanguageSwift grammar.g4 -visitor -o grammar目录/genXcode 工程集成为什么必须从源码编译 Swift 运行时即使你平时使用 ANTLR 的二进制发行版Swift 运行时也必须从源码自行编译——Swift 语言目前还没有稳定的 ABI。ANTLR 通过 Swift Package Manager 来生成 Xcode 工程文件从而得到与你的项目一致的编译配置。第一步下载 ANTLR 源码git clone https://github.com/antlr/antlr4第二步生成运行时 Xcode 工程在runtime/Swift目录下执行cd antlr4/runtime/Swift python boot.py --gen-xcodeprojboot.py内部是swift package generate-xcodeproj的封装。不建议直接手动执行swift package generate-xcodeproj因为该工程依赖boot.py先生成的一些解析器文件源码中generate_xcodeproj()会先调用generate_parser()再调用swift package generate-xcodeproj直接跳过会得到不完整的工程。第三步将运行时导入你的工程在 Xcode 中打开你自己的项目然后在 Finder 中打开runtime/Swift目录# 在 antlr4/runtime/Swift 目录下 open .把Antlr4.xcodeproj拖入你的 Xcode 工程。完成后工程导航器中会显示一个内嵌的子工程效果类似下图第四步按需修改构建设置Swift Package Manager 目前不支持 iOS、watchOS 或 tvOS。如果目标平台包含这些系统需要手动调整工程的构建设置。第五步把生成的解析器/词法分析器加入工程将第二步生成的解析器/词法分析器文件.swift从 Finder 拖入 Xcode IDE。拖入时务必勾选Copy items if needed确保文件被真正复制进工程目录而不是以符号链接形式引用见下图。移动完成后检查工程导航器中的文件列表并确认 Target Membership 设置与你的目标一致。第六步把运行时添加为依赖选中你自己的工程进入Build Phases面板在Target Dependencies中加入 ANTLR 运行时在Link Binary With Libraries中加入 ANTLR 运行时。第七步构建完成上述步骤后运行时与生成的语法文件应能一起正常编译。至此你的 Xcode 工程便具备了调用 Swift 解析器的能力。Swift Package Manager 工程集成SPM 工程的接入要简单得多只需在Package.swift中把 Antlr4 声明为依赖即可。.package(url: https://github.com/antlr/antlr4, from: 4.13.2)随后在 target 的dependencies中加入Antlr4产品即可引用。仓库根目录的 Package.swift 展示了官方为 Swift 运行时声明的模块形态swift-tools-version:5.6目标Antlr4源码路径为./runtime/Swift/Sources/Antlr4产品Antlr4默认动态链接、Antlr4Static.static静态库、Antlr4Dynamic.dynamic动态库三种库形态可供选择测试目标Antlr4Tests位于./runtime/Swift/Tests/Antlr4Tests并将若干.g4测试语法文件排除在编译之外它们只在测试前由工具生成对应 Swift 代码。当以 SPM 依赖方式使用且用于生产环境时同样务必使用release配置构建参见本文开头的性能说明。控制生成代码的访问级别accessLevel 选项两种指定方式accessLevel选项用于控制生成代码的访问级别可通过命令行或语法文件内声明两种方式指定# 命令行方式 antlr4 -DlanguageSwift -DaccessLevelvalue MyGrammar.g4# 语法文件内方式 options { accessLevel value; }默认访问级别不指定accessLevel时生成代码遵循如下分层约定访问级别适用对象open一切可被继承扩展的内容生成的解析器、词法分析器、上下文类监听器与访问器的基类以及它们的全部访问器和 setter 函数public不应被继承、但对客户端代码有用的内容协议、初始化器以及词法 token、符号名等静态定义internal/private不应被直接访问的内部实现细节支持的取值与行为Swift 代码生成器只支持以下取值accessLevel public把所有默认open的项降为public其余行为与默认一致accessLevel 或accessLevel internal把默认open或public的项全部改为 Swift 的默认internal访问级别。推荐做法与理由官方文档明确推荐使用accessLevel 。即使你是在编写一个库通常也会把解析器包裹在自己的 API 内部让 ANTLR 生成的解析器保持模块内部可见internal即可只有当需要把解析器作为自身模块 API 的一部分直接对外暴露时才需要使用更宽松的访问级别。从生成器源码看accessLevel会在模型层被读取并写入生成文件如 tool/src/org/antlr/v4/codegen/model/Recognizer.java 中通过g.getOptionString(accessLevel)获取该选项tool/src/org/antlr/v4/codegen/model/VisitorFile.java 同样将-DaccessLevel映射为模板模型字段最终由 StringTemplate 模板渲染进每个生成的.swift文件。运行时结构与测试验证Swift 运行时源码集中在 runtime/Swift/Sources/Antlr4覆盖了完整的运行时能力核心入口类Lexer.swift、Parser.swift、Recognizer.swift、LexerInterpreter.swift、ParserInterpreter.swift等输入与 token 流ANTLRInputStream.swift、ANTLRFileStream.swift、BufferedTokenStream.swift、UnbufferedTokenStream.swift、TokenStreamRewriter.swift等ATN 执行引擎atn/目录下的ATNDeserializer、ParserATNSimulator、LexerATNSimulator等错误处理DefaultErrorStrategy.swift、BailErrorStrategy.swift、DiagnosticErrorListener.swift等树遍历与模式匹配tree/目录下的监听器、访问器、ParseTreeWalker、ParseTreePatternMatcher等。测试用例位于 runtime/Swift/Tests/Antlr4Tests例如ANTLRInputStreamTests.swift验证 ASCII、BMP 字符、增补平面字符与字素簇的输入流处理InterpreterDataTests.swift基于LexerA.g4、LexerB.g4等测试语法验证解释器数据生成MurmurHashTests.swift验证运行时使用的 MurmurHash 实现TokenStreamRewriterTests.swift、TokenStreamTests.swift验证 token 流与重写器行为。在完成mvn install与boot.py准备后可执行python boot.py --test一键运行上述全部单元测试等价于swift test快速验证你的 Swift 运行时环境是否就绪。小结要在 Swift 中使用 ANTLR4关键路径可以概括为四步性能前提生产构建务必使用release模式SPM 用-c releaseXcode 用 Release 配置生成代码用antlr4 -DlanguageSwift生成解析器Xcode 构建步骤可追加-message-format gnu -o Autogen接入运行时Xcode 工程通过python boot.py --gen-xcodeproj生成子工程后拖入并配置依赖SPM 工程只需在Package.swift声明.package(url:from:)依赖控制可见性用accessLevel推荐将生成代码限定为模块内部实现保持自身 API 干净。按照上述流程你便能在 Swift 项目中稳定地使用 ANTLR4 完成词法、语法分析乃至翻译、求值等结构化文本处理任务。【免费下载链接】antlr4ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.项目地址: https://gitcode.com/gh_mirrors/an/antlr4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考