GLL Combinators 技术文档

本文档旨在帮助用户安装和使用 GLL Combinators，并详细解释其项目API。以下是项目的技术文档，包括安装指南、使用说明以及API使用文档。

1. 安装指南

GLL Combinators 的编译构件已推送到 Maven Central，groupId 为 com.codecommit，artifactId 为 gll-combinators。最新稳定版本为 2.3。此构件为 Scala 2.10、2.11 和 2.12 跨发布。如果您使用 SBT，只需将以下构件描述复制并粘贴到您的 build.sbt 文件中：

libraryDependencies += "com.codecommit" %% "gll-combinators" % "2.3"

安装完成后，以下包可供使用：

• com.codecommit.gll —— 框架的完整公共接口。
• com.codecommit.util —— 内部使用的许多有用的工具类。不应将其视为稳定API的一部分。

2. 项目使用说明

GLL Combinators 是一个用于以函数式方式实现 GLL 解析算法的框架。该框架使用原子解析组合子来构造语法，然后使用 GLL 算法进行评估。以下是使用 GLL Combinators 的基本示例：

lazy val expr: Parser[Any] = (
    "(" ~ expr ~ ")"
  | ""
)

您可以调用此解析器，如下所示：

expr("((()))")

返回值类型为 Stream[Result[Any]]。Result[A] ADT 定义为以下类型之一：

• Success[A] —— 表示解析成功并包含结果值。
• Failure —— 表示解析失败并包含相关错误消息以及解析流中未被消耗的部分。

如果任一结果是成功的（即 Success[A] 实例），则不会返回失败。因此，返回的 Stream 将完全同质，只包含 Success 或 Failure 中的一个。

3. 项目API使用文档

GLL Combinators 提供了用于构造语法的解析器组合子。以下是组合子的一些基本用法：

• ~ —— 用于连接两个解析器。
• ^^ —— 用于在解析成功后执行语义动作。

例如，以下是使用 ^^ 组合子的一个表达式解析器：

lazy val expr: Parser[Int] = (
    expr ~ "*" ~ expr     ^^ { (e1, _, e2) => e1 * e2 }
  | expr ~ "/" ~ expr     ^^ { (e1, _, e2) => e1 / e2 }
  | expr ~ "+" ~ expr     ^^ { (e1, _, e2) => e1 + e2 }
  | expr ~ "-" ~ expr     ^^ { (e1, _, e2) => e1 - e2 }
  | "(" ~> expr <~ ")"
  | "-" ~> expr           ^^ { -_ }
  | """\d+""".r           ^^ { _.toInt }
)

此解析器支持包括左递归和模糊性在内的复杂语法。

4. 项目安装方式

如前所述，您可以通过 SBT 添加 GLL Combinators 依赖项：

libraryDependencies += "com.codecommit" %% "gll-combinators" % "2.3"

然后，您可以编译并运行您的 Scala 项目，使用 GLL Combinators 提供的功能。

通过本文档，用户应能够成功安装和运行 GLL Combinators，并了解如何使用其API进行解析器开发。