KPeg 使用与技术文档

1. 安装指南

KPeg 是一个为 Ruby 语言设计的简单 PEG（Parsing Expression Grammar）库。以下是安装 KPeg 的步骤：

1. 确保已经安装了 Ruby 环境。

2. 使用 RubyGems 安装 KPeg：

   gem install kpeg
   

3. 安装完成后，你可以在 Ruby 项目中引入 KPeg 库。

2. 项目使用说明

KPeg 允许用户通过定义一系列规则来构建语法。以下是构建语法的步骤：

设置语法

所有语法都以类/模块名称开始，这将作为解析器：

%% name = Example::Parser

接着可以定义一个 Ruby 代码块，该代码块将被添加到解析器的类体中。在这个代码块中定义的属性可以作为实例变量在解析器中使用。同时也可以定义方法，并在动作块中使用它们。

%% {
  attr_accessor :something_cool
  def something_awesome
    # 执行一些伟大的操作
  end
}

定义字面量

字面量是设计用于在语法中重用的字符或正则表达式的静态声明。可以是常量或变量。字面量可以接受字符串、正则表达式或字符范围。

ALPHA = /[A-Za-z]/
DIGIT = /[0-9]/
period = "."
string = "a string"
regex = /(regexs?)+/
char_range = [b-t]

字面量也可以接受多个定义：

vowel = "a" | "e" | "i" | "o" | "u"
alpha = /[A-Z]/ | /[a-z]/

定义规则

在使用字符串进行解析之前，需要定义规则来接受或拒绝该字符串。KPeg 中有多种不同类型的规则。

最基础的规则是字符串捕获：

alpha = < /[A-Za-z]/ > { text }

规则还可以像函数一样接受参数：

d(num) = <.> &{ text[0] == num }

规则支持一些正则表达式语法来匹配：

• 可选 ?
• 多个 +
• 克里尼 *
• 分组 ()

定义动作

如上所述，KPeg 允许基于匹配执行动作。动作可以定义在提供的块中或规则定义本身。

num = /[1-9][0-9]*/
sum = < num:n1 "+" num:n2 > { n1 + n2 }

引用外部语法

KPeg 允许运行在另一个语法中定义的规则。这对于希望在另一个解析器中重用定义好的规则集非常有用。创建语法并使用 kpeg 命令行工具生成解析器。

kpeg literals.kpeg

在新的语法中引入生成的解析器文件，并创建一个变量来持有外部语法的接口。

%{
  require "literals.kpeg.rb"
}

%foreign_grammar = Literal

然后在本地语法文件中使用外部语法中定义的规则。

注释

KPeg 允许使用 # 符号在语法文件中添加注释。

变量

变量如下所示：

%% name = value

KPeg 允许以下控制输出解析器的变量：

• name：生成的解析器的类名。
• custom_initialize：当生成独立的解析器时，默认的 initialize 方法不会被包含。

指令

指令如下所示：

%% header {
  ...
}

KPeg 允许以下指令：

• header：放在任何生成代码之前。
• pre-class：放在类定义之前，用于提供类注释。
• footer：放在类定义之后（用于要求依赖于解析器命名空间的文件）。

3. 项目 API 使用文档

KPeg 的 API 由一系列用于构建语法的规则和方法组成。以下是 API 的简要概述：

• < rule > { block }：定义一个规则，并执行一个动作块。
• &{ condition }：如果条件为真，则返回 true。
• !{ condition }：如果条件为真，则返回 false。
• ~method_name(args)：调用定义的方法。

4. 项目安装方式

KPeg 的安装方式如安装指南中所述，通过 RubyGems 进行安装。

确保已经安装了 Ruby 环境，然后使用以下命令安装 KPeg：

gem install kpeg

安装完成后，你可以开始使用 KPeg 来构建你的语法解析器。