011 《Boost.Spirit 权威指南 (Boost.Spirit: The Definitive Guide)》
🌟🌟🌟本文案由Gemini 2.0 Flash Thinking Experimental 01-21创作，用来辅助学习知识。🌟🌟🌟
书籍大纲
▮▮▮▮ 1. chapter 1： 走进 Boost.Spirit (走进 Boost.Spirit, Getting Started with Boost.Spirit)
▮▮▮▮▮▮▮ 1.1 什么是 Boost.Spirit？ (什么是 Boost.Spirit?, What is Boost.Spirit?)
▮▮▮▮▮▮▮ 1.2 Boost.Spirit 的优势与应用场景 (Boost.Spirit 的优势与应用场景, Advantages and Use Cases of Boost.Spirit)
▮▮▮▮▮▮▮ 1.3 开发环境搭建 (开发环境搭建, Setting up the Development Environment)
▮▮▮▮▮▮▮ 1.4 第一个 Spirit 解析器：Hello World (第一个 Spirit 解析器：Hello World, Your First Spirit Parser: Hello World)
▮▮▮▮▮▮▮▮▮▮▮ 1.4.1 使用 Spirit.Qi 解析 (使用 Spirit.Qi 解析, Parsing with Spirit.Qi)
▮▮▮▮▮▮▮▮▮▮▮ 1.4.2 使用 Spirit.Karma 生成 (使用 Spirit.Karma 生成, Generating with Spirit.Karma)
▮▮▮▮▮▮▮▮▮▮▮ 1.4.3 编译与运行 (编译与运行, Compilation and Execution)
▮▮▮▮ 2. chapter 2： Spirit.Qi 核心概念 (Spirit.Qi 核心概念, Core Concepts of Spirit.Qi)
▮▮▮▮▮▮▮ 2.1 Parser (解析器) 详解 (Parser (解析器) 详解, In-depth Explanation of Parsers)
▮▮▮▮▮▮▮ 2.2 Rule (规则) 的定义与使用 (Rule (规则) 的定义与使用, Defining and Using Rules)
▮▮▮▮▮▮▮ 2.3 Attribute (属性) 与语义动作 (Attribute (属性) 与语义动作, Attributes and Semantic Actions)
▮▮▮▮▮▮▮ 2.4 组合解析器 (组合解析器, Parser Combinators)
▮▮▮▮▮▮▮▮▮▮▮ 2.4.1 序列 (Sequence)
▮▮▮▮▮▮▮▮▮▮▮ 2.4.2 选择 (Alternative)
▮▮▮▮▮▮▮▮▮▮▮ 2.4.3 重复 (Repetition)
▮▮▮▮▮▮▮▮▮▮▮ 2.4.4 可选 (Optional)
▮▮▮▮▮▮▮ 2.5 预定义的 Parser (预定义的 Parser, Predefined Parsers)
▮▮▮▮ 3. chapter 3： Spirit.Karma 核心概念 (Spirit.Karma 核心概念, Core Concepts of Spirit.Karma)
▮▮▮▮▮▮▮ 3.1 Generator (生成器) 详解 (Generator (生成器) 详解, In-depth Explanation of Generators)
▮▮▮▮▮▮▮ 3.2 Rule (规则) 的定义与使用 (Rule (规则) 的定义与使用, Defining and Using Rules)
▮▮▮▮▮▮▮ 3.3 Attribute (属性) 与语义动作 (Attribute (属性) 与语义动作, Attributes and Semantic Actions)
▮▮▮▮▮▮▮ 3.4 组合生成器 (组合生成器, Generator Combinators)
▮▮▮▮▮▮▮▮▮▮▮ 3.4.1 序列 (Sequence)
▮▮▮▮▮▮▮▮▮▮▮ 3.4.2 选择 (Alternative)
▮▮▮▮▮▮▮▮▮▮▮ 3.4.3 重复 (Repetition)
▮▮▮▮▮▮▮▮▮▮▮ 3.4.4 可选 (Optional)
▮▮▮▮▮▮▮ 3.5 预定义的 Generator (预定义的 Generator, Predefined Generators)
▮▮▮▮ 4. chapter 4： 属性处理与转换 (属性处理与转换, Attribute Handling and Transformation)
▮▮▮▮▮▮▮ 4.1 属性语法 (属性语法, Attribute Grammar)
▮▮▮▮▮▮▮ 4.2 属性类型推导 (属性类型推导, Attribute Type Deduction)
▮▮▮▮▮▮▮ 4.3 使用 Boost.Fusion 处理复合属性 (使用 Boost.Fusion 处理复合属性, Handling Composite Attributes with Boost.Fusion)
▮▮▮▮▮▮▮ 4.4 属性转换与自定义属性 (属性转换与自定义属性, Attribute Transformation and Custom Attributes)
▮▮▮▮ 5. chapter 5： 语义动作 (语义动作, Semantic Actions)
▮▮▮▮▮▮▮ 5.1 Lambda 表达式与语义动作 (Lambda 表达式与语义动作, Lambda Expressions and Semantic Actions)
▮▮▮▮▮▮▮ 5.2 使用 Boost.Phoenix (使用 Boost.Phoenix, Using Boost.Phoenix)
▮▮▮▮▮▮▮ 5.3 语义动作的返回值与属性传递 (语义动作的返回值与属性传递, Return Values and Attribute Propagation in Semantic Actions)
▮▮▮▮▮▮▮ 5.4 副作用与纯语义动作 (副作用与纯语义动作, Side Effects and Pure Semantic Actions)
▮▮▮▮ 6. chapter 6： 错误处理 (错误处理, Error Handling)
▮▮▮▮▮▮▮ 6.1 Spirit 的错误报告机制 (Spirit 的错误报告机制, Spirit's Error Reporting Mechanism)
▮▮▮▮▮▮▮ 6.2 自定义错误处理 (自定义错误处理, Custom Error Handling)
▮▮▮▮▮▮▮ 6.3 错误恢复策略 (错误恢复策略, Error Recovery Strategies)
▮▮▮▮▮▮▮ 6.4 异常处理与 Spirit (异常处理与 Spirit, Exception Handling and Spirit)
▮▮▮▮ 7. chapter 7： 跳过符与空白符处理 (跳过符与空白符处理, Skipper and Whitespace Handling)
▮▮▮▮▮▮▮ 7.1 Skipper 的概念与使用 (Skipper 的概念与使用, Concept and Usage of Skipper)
▮▮▮▮▮▮▮ 7.2 自定义 Skipper (自定义 Skipper, Custom Skipper)
▮▮▮▮▮▮▮ 7.3 空白符策略 (空白符策略, Whitespace Policy)
▮▮▮▮ 8. chapter 8： 词法分析 (词法分析, Lexical Analysis)
▮▮▮▮▮▮▮ 8.1 Token (词元) 的概念 (Token (词元) 的概念, Concept of Tokens)
▮▮▮▮▮▮▮ 8.2 使用 Spirit.Lex (使用 Spirit.Lex, Using Spirit.Lex)
▮▮▮▮▮▮▮ 8.3 自定义 Tokenizer (自定义 Tokenizer, Custom Tokenizer)
▮▮▮▮▮▮▮ 8.4 整合 Lex 和 Qi (整合 Lex 和 Qi, Integrating Lex and Qi)
▮▮▮▮ 9. chapter 9： 实战案例：解析 CSV 文件 (实战案例：解析 CSV 文件, Practical Case: Parsing CSV Files)
▮▮▮▮▮▮▮ 9.1 CSV 文件格式详解 (CSV 文件格式详解, Detailed Explanation of CSV File Format)
▮▮▮▮▮▮▮ 9.2 设计 CSV 解析器 (设计 CSV 解析器, Designing a CSV Parser)
▮▮▮▮▮▮▮ 9.3 代码实现与测试 (代码实现与测试, Code Implementation and Testing)
▮▮▮▮ 10. chapter 10： 实战案例：解析 JSON 数据 (实战案例：解析 JSON 数据, Practical Case: Parsing JSON Data)
▮▮▮▮▮▮▮ 10.1 JSON 数据格式详解 (JSON 数据格式详解, Detailed Explanation of JSON Data Format)
▮▮▮▮▮▮▮ 10.2 设计 JSON 解析器 (设计 JSON 解析器, Designing a JSON Parser)
▮▮▮▮▮▮▮ 10.3 代码实现与测试 (代码实现与测试, Code Implementation and Testing)
▮▮▮▮ 11. chapter 11： 实战案例：配置文件解析 (实战案例：配置文件解析, Practical Case: Configuration File Parsing)
▮▮▮▮▮▮▮ 11.1 配置文件格式设计 (配置文件格式设计, Configuration File Format Design)
▮▮▮▮▮▮▮ 11.2 使用 Spirit 解析配置文件 (使用 Spirit 解析配置文件, Parsing Configuration Files with Spirit)
▮▮▮▮▮▮▮ 11.3 配置项的动态处理 (配置项的动态处理, Dynamic Handling of Configuration Items)
▮▮▮▮ 12. chapter 12： 高级主题：性能优化 (高级主题：性能优化, Advanced Topics: Performance Optimization)
▮▮▮▮▮▮▮ 12.1 Spirit 性能瓶颈分析 (Spirit 性能瓶颈分析, Performance Bottleneck Analysis in Spirit)
▮▮▮▮▮▮▮ 12.2 优化技巧与策略 (优化技巧与策略, Optimization Techniques and Strategies)
▮▮▮▮▮▮▮ 12.3 编译期优化与运行期优化 (编译期优化与运行期优化, Compile-time and Runtime Optimization)
▮▮▮▮ 13. chapter 13： 高级主题：自定义 Parser 组件 (高级主题：自定义 Parser 组件, Advanced Topics: Custom Parser Components)
▮▮▮▮▮▮▮ 13.1 Parser 组件的设计原则 (Parser 组件的设计原则, Design Principles of Parser Components)
▮▮▮▮▮▮▮ 13.2 实现自定义 Parser (实现自定义 Parser, Implementing Custom Parsers)
▮▮▮▮▮▮▮ 13.3 测试与调试自定义 Parser (测试与调试自定义 Parser, Testing and Debugging Custom Parsers)
▮▮▮▮ 14. chapter 14： Boost.Spirit 与其他 Boost 库的集成 (Boost.Spirit 与其他 Boost 库的集成, Integration of Boost.Spirit with Other Boost Libraries)
▮▮▮▮▮▮▮ 14.1 与 Boost.Phoenix 的集成 (与 Boost.Phoenix 的集成, Integration with Boost.Phoenix)
▮▮▮▮▮▮▮ 14.2 与 Boost.Variant 的集成 (与 Boost.Variant 的集成, Integration with Boost.Variant)
▮▮▮▮▮▮▮ 14.3 与 Boost.Fusion 的集成 (与 Boost.Fusion 的集成, Integration with Boost.Fusion)
▮▮▮▮ 15. chapter 15： API 参考 (API 参考, API Reference)
▮▮▮▮▮▮▮ 15.1 Spirit.Qi API 详解 (Spirit.Qi API 详解, Detailed Spirit.Qi API)
▮▮▮▮▮▮▮ 15.2 Spirit.Karma API 详解 (Spirit.Karma API 详解, Detailed Spirit.Karma API)
▮▮▮▮▮▮▮ 15.3 Spirit.Lex API 详解 (Spirit.Lex API 详解, Detailed Spirit.Lex API)
1. chapter 1： 走进 Boost.Spirit (走进 Boost.Spirit, Getting Started with Boost.Spirit)
1.1 什么是 Boost.Spirit？ (什么是 Boost.Spirit?, What is Boost.Spirit?)
Boost.Spirit 是一套强大的 C++ 库，它允许开发者直接在 C++ 代码中，以声明式的方式创建解析器（Parser）和生成器（Generator）。这意味着你可以使用 C++ 语法本身来描述你的语法规则，而无需借助外部工具或预处理器。Boost.Spirit 被设计为一个领域特定嵌入式语言（Domain Specific Embedded Language, DSEL），充分利用 C++ 的模板元编程（Template Metaprogramming, TMP）技术，将语法规则的描述转换为高效的 C++ 代码。
简单来说，Boost.Spirit 就像是 C++ 语言中的“乐高积木”，它提供了一系列预定义的解析器组件（Parser Components）和生成器组件（Generator Components），你可以像搭积木一样，将这些组件组合起来，构建出能够解析各种文本格式（如：配置文件、编程语言、网络协议等）或者生成各种文本输出的程序。
Boost.Spirit 主要由三个核心库组成，它们协同工作，为开发者提供了全面的文本处理能力：
① Spirit.Qi： 这是一个解析器框架（Parser Framework），专注于解析（Parsing）。你可以使用 Spirit.Qi 定义各种语法规则，将输入的文本数据解析成结构化的数据，方便程序后续处理。例如，你可以使用 Spirit.Qi 来解析 CSV 文件、JSON 数据、配置文件，甚至是编程语言的源代码。
② Spirit.Karma： 这是一个生成器框架（Generator Framework），专注于生成（Generating）。与 Spirit.Qi 相反，Spirit.Karma 用于将结构化的数据转换成文本输出。例如，你可以使用 Spirit.Karma 将内存中的数据结构格式化输出为 XML、JSON 或其他文本格式。
③ Spirit.Lex： 这是一个词法分析器生成器（Lexer Generator），专注于词法分析（Lexical Analysis）。词法分析是编译原理中的第一步，它将输入的字符流分解成一个个有意义的词元（Token）。Spirit.Lex 可以帮助你定义词法规则，例如：标识符、关键字、运算符、字面量等，为后续的语法分析（通常使用 Spirit.Qi）提供基础。
总而言之，Boost.Spirit 提供了一套完整且强大的工具，用于处理文本的解析、生成和词法分析，它以其独特的 DSEL 特性、高效的性能和高度的灵活性，在 C++ 文本处理领域占据着重要的地位。
1.2 Boost.Spirit 的优势与应用场景 (Boost.Spirit 的优势与应用场景, Advantages and Use Cases of Boost.Spirit)
Boost.Spirit 作为一款优秀的 C++ 库，在文本处理领域拥有诸多优势，并被广泛应用于各种场景。
Boost.Spirit 的主要优势：
① 嵌入式 DSL (Embedded DSL)：
Boost.Spirit 最显著的特点是它是一个嵌入在 C++ 中的领域特定语言。这意味着你无需学习新的语法或使用额外的工具，就可以直接在 C++ 代码中使用类似 EBNF (Extended Backus-Naur Form) 的语法来描述你的解析和生成规则。这种方式极大地提高了开发效率和代码的可读性，同时也避免了外部工具链带来的复杂性。
② 编译期解析器/生成器生成 (Compile-time Parser/Generator Generation)：
Boost.Spirit 利用 C++ 模板元编程技术，在编译时将你定义的语法规则转换成高效的 C++ 代码。这意味着解析和生成过程的性能非常高，接近手写解析器的效率。与传统的解释型解析器生成器相比，Boost.Spirit 在性能方面具有显著优势。
③ 类型安全 (Type Safety)：
Boost.Spirit 充分利用 C++ 的类型系统，在编译时进行类型检查，确保语法规则的正确性和数据处理的安全性。属性（Attribute）机制是 Boost.Spirit 类型安全的核心体现，它保证了解析和生成过程中数据的类型匹配，避免了运行时类型错误。
④ 高度的灵活性和可扩展性 (High Flexibility and Extensibility)：
Boost.Spirit 提供了丰富的预定义解析器（Predefined Parsers）和生成器（Predefined Generators），同时也允许用户自定义解析器和生成器组件。这种高度的灵活性和可扩展性使得 Boost.Spirit 能够应对各种复杂的文本处理需求。你可以根据具体的应用场景，灵活地组合和扩展 Boost.Spirit 的功能。
⑤ 良好的可读性 (Good Readability)：
虽然初次接触 Boost.Spirit 可能会觉得其语法较为抽象，但一旦熟悉其基本概念和语法规则，你会发现使用 Boost.Spirit 编写的解析器和生成器代码具有良好的可读性。声明式的语法风格使得代码更接近于语法规则的描述，易于理解和维护。
Boost.Spirit 的典型应用场景：
① 配置文件解析 (Configuration File Parsing)：
几乎所有的软件系统都需要处理配置文件。Boost.Spirit 可以用来解析各种格式的配置文件，例如：INI、XML、JSON、YAML 等。其高效性和灵活性使得解析过程快速且可靠。
② 网络协议解析 (Network Protocol Parsing)：
网络编程中，需要解析各种网络协议，例如：HTTP、SMTP、FTP 等。Boost.Spirit 可以用来构建高性能的网络协议解析器，处理网络数据包，提取关键信息。
③ 数据验证 (Data Validation)：
在数据处理过程中，经常需要对输入数据进行验证，确保数据的格式和内容符合规范。Boost.Spirit 可以用来定义数据验证规则，快速有效地验证数据的合法性。
④ 代码生成 (Code Generation)：
Boost.Karma 可以用于代码生成，例如：根据模型数据生成代码框架、根据配置文件生成代码片段等。其强大的生成能力和灵活性使得代码生成过程更加自动化和可控。
⑤ 文本处理 (Text Processing)：
Boost.Spirit 可以应用于各种文本处理任务，例如：日志分析、文本搜索、数据提取、文本转换等。其高效的解析和生成能力，以及丰富的文本处理组件，使得文本处理任务更加轻松高效。
总而言之，Boost.Spirit 以其独特的优势，在文本处理领域展现出强大的生命力，无论是简单的配置文件解析，还是复杂的网络协议分析，Boost.Spirit 都能提供优雅且高效的解决方案。
1.3 开发环境搭建 (开发环境搭建, Setting up the Development Environment)
在使用 Boost.Spirit 之前，你需要先搭建好 C++ 开发环境，并确保 Boost 库已经正确安装。本节将指导你完成 Boost.Spirit 的开发环境搭建。
① 准备 C++ 编译器 (Prepare C++ Compiler)
首先，你需要一个现代的 C++ 编译器。Boost.Spirit 支持多种主流的 C++ 编译器，包括：
⚝ GCC (GNU Compiler Collection)： Linux 和 macOS 系统上常用的编译器。
⚝ Clang (LLVM Compiler Infrastructure)： Linux、macOS 和 Windows 系统上流行的编译器，以其快速的编译速度和友好的错误提示而著称。
⚝ MSVC (Microsoft Visual C++)： Windows 系统上常用的编译器，Visual Studio 自带。
你可以根据自己的操作系统和偏好选择合适的编译器。如果你的系统中尚未安装 C++ 编译器，请参考以下步骤进行安装：
⚝ Linux (Debian/Ubuntu)：
1
sudo apt-get update
2
sudo apt-get install g++
⚝ Linux (Fedora/CentOS)：
1
sudo yum update
2
sudo yum install gcc-c++
⚝ macOS (使用 Homebrew)：
1
brew update
2
brew install gcc
1
或者安装 Clang (macOS 系统通常自带 Clang，但你可能需要安装 Command Line Tools)：
1
xcode-select --install
⚝ Windows：
▮▮▮▮⚝ 安装 Visual Studio Community： 访问 Visual Studio 官网 下载并安装免费的 Community 版本。安装过程中，请确保选择 “使用 C++ 的桌面开发” 工作负载。
安装完成后，你可以在终端或命令提示符中输入 g++ --version (GCC), clang++ --version (Clang) 或 cl (MSVC) 来检查编译器是否安装成功，并查看编译器版本信息。
② 安装 Boost 库 (Install Boost Library)
Boost.Spirit 是 Boost 库的一部分，因此你需要先安装 Boost 库。Boost 库的安装方式取决于你的操作系统和包管理器。
⚝ 使用包管理器安装 (推荐)： 大多数 Linux 发行版和 macOS 都提供了 Boost 库的软件包，你可以使用包管理器快速安装。
▮▮▮▮⚝ Linux (Debian/Ubuntu)：
1
sudo apt-get install libboost-all-dev
▮▮▮▮⚝ Linux (Fedora/CentOS)：
1
sudo yum install boost-devel
▮▮▮▮⚝ macOS (使用 Homebrew)：
1
brew install boost
1
使用包管理器安装 Boost 库是最简单快捷的方式，推荐初学者使用。
⚝ 从源码编译安装： 如果你需要安装特定版本的 Boost 库，或者你的操作系统没有提供 Boost 库的软件包，你可以从 Boost 官网下载源码，然后手动编译安装。
1
1. **下载 Boost 源码**： 访问 [Boost 官网](https://www.boost.org/) 下载最新版本的 Boost 源码包 (通常是 `.zip` 或 `.tar.gz` 格式)。
2
2. **解压源码包**： 将下载的源码包解压到你希望安装 Boost 的目录。例如，解压到 `/usr/local/boost_x_xx_x` (Linux/macOS) 或 `C:\boost_x_xx_x` (Windows)。
3
3. **编译 Boost.Build (b2)**： 进入解压后的 Boost 源码根目录，运行 `bootstrap.sh` (Linux/macOS) 或 `bootstrap.bat` (Windows) 脚本，生成 `b2` 编译工具。
4
4. **编译安装 Boost 库**： 在 Boost 源码根目录下，运行 `b2 install --prefix=/usr/local` (Linux/macOS) 或 `b2 install --prefix=C:\Boost` (Windows)。`--prefix` 参数指定 Boost 库的安装路径，你可以根据需要修改。
5
6
从源码编译安装 Boost 库的过程相对复杂，但可以更灵活地控制安装选项和版本。
③ 验证 Boost.Spirit 安装 (Verify Boost.Spirit Installation)
安装完成后，你需要验证 Boost.Spirit 是否安装成功。你可以编写一个简单的 C++ 程序，包含 Boost.Spirit 的头文件，并尝试编译运行。
创建一个名为 hello_spirit.cpp 的文件，内容如下：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
int main() {
5
std::cout << "Boost.Spirit is ready!" << std::endl;
6
return 0;
7
}
然后，使用你的 C++ 编译器编译该程序。假设你使用的是 g++，编译命令如下：
1
g++ hello_spirit.cpp -o hello_spirit
如果编译过程中没有报错，并且生成了可执行文件 hello_spirit (或 hello_spirit.exe 在 Windows 上)，则说明 Boost.Spirit 已经成功安装。
最后，运行可执行文件：
1
./hello_spirit
如果终端或命令提示符输出了 Boost.Spirit is ready!，则表示 Boost.Spirit 环境搭建成功，你可以开始学习和使用 Boost.Spirit 了。
1.4 第一个 Spirit 解析器：Hello World (第一个 Spirit Parser: Hello World)
“Hello World!” 程序是编程入门的经典示例。在本节中，我们将使用 Boost.Spirit 创建一个简单的 “Hello World!” 解析器和生成器，帮助你快速入门 Boost.Spirit，并体验其基本用法。
1.4.1 使用 Spirit.Qi 解析 (使用 Spirit.Qi 解析, Parsing with Spirit.Qi)
首先，我们使用 Spirit.Qi 来创建一个解析器，它可以解析字符串 "Hello Spirit"。
创建一个名为 hello_qi.cpp 的文件，内容如下：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/phoenix_core.hpp>
3
#include <iostream>
4
#include <string>
5
6
namespace qi = boost::spirit::qi;
7
namespace ascii = boost::spirit::ascii;
8
namespace phoenix = boost::phoenix;
9
10
int main() {
11
std::string input = "Hello Spirit";
12
std::string parsed_text;
13
bool success = qi::phrase_parse(
14
input.begin(), input.end(),
15
ascii::string("Hello Spirit"), // 解析规则：匹配 "Hello Spirit" 字符串
16
ascii::space, // 跳过符：忽略空格
17
parsed_text // 属性：解析结果存储到 parsed_text
18
);
19
20
if (success) {
21
std::cout << "Parsing succeeded!" << std::endl;
22
std::cout << "Parsed text: " << parsed_text << std::endl;
23
} else {
24
std::cout << "Parsing failed!" << std::endl;
25
}
26
27
return 0;
28
}
代码解释：
⚝ #include <boost/spirit/include/qi.hpp>： 包含 Spirit.Qi 的核心头文件。
⚝ #include <boost/spirit/include/phoenix_core.hpp>： 包含 Boost.Phoenix 核心头文件，用于语义动作（Semantic Actions），虽然这个例子中没有用到，但通常会一起包含。
⚝ namespace qi = boost::spirit::qi;， namespace ascii = boost::spirit::ascii;， namespace phoenix = boost::phoenix;： 为了方便使用，我们创建了命名空间别名。
⚝ std::string input = "Hello Spirit";： 定义输入字符串。
⚝ std::string parsed_text;： 定义用于存储解析结果的字符串变量。
⚝ qi::phrase_parse(...)： Spirit.Qi 的核心解析函数。
▮▮▮▮⚝ input.begin(), input.end()： 指定输入字符串的起始和结束迭代器。
▮▮▮▮⚝ ascii::string("Hello Spirit")： 解析规则（Parser Rule），使用 ascii::string("Hello Spirit") 创建一个解析器，用于匹配字符串 "Hello Spirit"。ascii::string 是一个预定义解析器，用于匹配 ASCII 字符串。
▮▮▮▮⚝ ascii::space： 跳过符（Skipper），使用 ascii::space 指定在解析过程中忽略的字符，这里忽略空格。
▮▮▮▮⚝ parsed_text： 属性（Attribute），用于接收解析结果。在这个例子中，由于我们只是简单地匹配字符串，没有实际的解析结果需要返回，所以 parsed_text 实际上不会被赋值。
⚝ if (success)： 判断解析是否成功。qi::phrase_parse 函数返回一个布尔值，表示解析是否成功。
⚝ std::cout << ...： 根据解析结果输出相应的提示信息。
1.4.2 使用 Spirit.Karma 生成 (使用 Spirit.Karma 生成, Generating with Spirit.Karma)
接下来，我们使用 Spirit.Karma 来创建一个生成器，它可以生成字符串 "Hello Karma"。
创建一个名为 hello_karma.cpp 的文件，内容如下：
1
#include <boost/spirit/include/karma.hpp>
2
#include <iostream>
3
#include <string>
4
#include <iterator>
5
6
namespace karma = boost::spirit::karma;
7
namespace ascii = boost::spirit::ascii;
8
9
int main() {
10
std::string generated_text;
11
std::back_insert_iterator<std::string> sink(generated_text); // 输出迭代器
12
13
bool success = karma::generate(
14
sink,
15
ascii::string("Hello Karma") // 生成规则：生成 "Hello Karma" 字符串
16
);
17
18
if (success) {
19
std::cout << "Generation succeeded!" << std::endl;
20
std::cout << "Generated text: " << generated_text << std::endl;
21
} else {
22
std::cout << "Generation failed!" << std::endl;
23
}
24
25
return 0;
26
}
代码解释：
⚝ #include <boost/spirit/include/karma.hpp>： 包含 Spirit.Karma 的核心头文件。
⚝ #include <iterator>： 包含迭代器头文件，用于输出迭代器。
⚝ namespace karma = boost::spirit::karma;， namespace ascii = boost::spirit::ascii;： 创建命名空间别名。
⚝ std::string generated_text;： 定义用于存储生成结果的字符串变量。
⚝ std::back_insert_iterator<std::string> sink(generated_text);： 创建一个输出迭代器（Output Iterator），用于将生成的字符写入 generated_text 字符串。std::back_insert_iterator 是一个插入迭代器，它可以自动扩展容器的大小。
⚝ karma::generate(...)： Spirit.Karma 的核心生成函数。
▮▮▮▮⚝ sink： 指定输出迭代器，生成的字符将写入到 sink 指向的容器中。
▮▮▮▮⚝ ascii::string("Hello Karma")： 生成规则（Generator Rule），使用 ascii::string("Hello Karma") 创建一个生成器，用于生成字符串 "Hello Karma"。
⚝ if (success)： 判断生成是否成功。karma::generate 函数返回一个布尔值，表示生成是否成功。
⚝ std::cout << ...： 根据生成结果输出相应的提示信息。
1.4.3 编译与运行 (编译与运行, Compilation and Execution)
现在，我们来编译并运行 hello_qi.cpp 和 hello_karma.cpp 这两个程序。
编译：
使用 g++ 编译器编译这两个程序 (如果使用其他编译器，请根据实际情况调整编译命令)：
1
g++ hello_qi.cpp -o hello_qi
2
g++ hello_karma.cpp -o hello_karma
运行：
分别运行编译生成的可执行文件：
1
./hello_qi
2
./hello_karma
预期输出：
hello_qi 的输出：
1
Parsing succeeded!
2
Parsed text:
hello_karma 的输出：
1
Generation succeeded!
2
Generated text: Hello Karma
如果你的输出结果与预期一致，恭喜你，你已经成功运行了你的第一个 Boost.Spirit 解析器和生成器程序！这标志着你已经迈出了学习 Boost.Spirit 的第一步。在接下来的章节中，我们将深入学习 Boost.Spirit 的核心概念和高级应用，带你领略 Boost.Spirit 的强大魅力。
END_OF_CHAPTER
2. chapter 2： Spirit.Qi 核心概念 (Spirit.Qi Core Concepts)
2.1 Parser (解析器) 详解 (Parser (解析器) In-depth Explanation)
在 Boost.Spirit 库中，Parser (解析器) 是最核心的概念之一。简单来说，Parser 的作用是识别输入流中的特定模式。可以将 Parser 视为一个函数，它接受输入流（通常是字符序列）作为输入，并尝试从输入流的起始位置匹配预定义的模式。如果匹配成功，Parser 会“消耗”已匹配的输入，并可能返回一个Attribute (属性)，属性是解析结果的表示。如果匹配失败，Parser 不会消耗任何输入，并指示解析失败。
更深入地理解 Parser，我们需要掌握以下几个关键点：
① Parser 的本质：函数对象
在 C++ 中，Boost.Spirit 的 Parser 本质上是函数对象 (Function Object)，也称为 Functor。这意味着 Parser 可以像函数一样被调用，并且可以作为参数传递给其他函数。这种设计使得 Parser 具有高度的灵活性和可组合性。
② 输入流的抽象
Parser 操作的是输入流 (Input Stream)，这可以是多种形式，例如：
⚝ 字符串 (std::string)
⚝ 字符数组 (char array)
⚝ 迭代器范围 (Iterator Range)
Boost.Spirit 通过迭代器来抽象输入流，使得 Parser 可以处理各种不同的输入源，而无需关心底层的输入表示。
③ 匹配与消耗
Parser 的核心操作是匹配 (Matching) 和 消耗 (Consuming)。当 Parser 成功匹配输入流中的模式时，它会：
⚝ 消耗：将已匹配的部分从输入流中“移除”，实际上是移动迭代器的位置。
⚝ 返回：可能返回一个 Attribute (属性)，表示解析得到的结果。
如果 Parser 匹配失败，它不会消耗任何输入，并且通常会返回一个表示失败的状态。
④ Attribute (属性)
Attribute (属性) 是 Parser 解析成功时产生的结果。它可以是各种 C++ 类型，例如：
⚝ 基本类型：int, float, std::string 等
⚝ 容器类型：std::vector, std::list 等
⚝ 自定义类型：结构体 (struct), 类 (class) 等
Attribute 是 Parser 的重要输出，它将解析的文本数据转换为程序可以处理的数据结构。
⑤ Parser 的组合
Boost.Spirit 强大之处在于其 Parser 的可组合性 (Composability)。通过Parser Combinators (组合解析器)，我们可以将简单的 Parser 组合成复杂的 Parser，从而解析复杂的语法结构。例如，可以使用序列 (Sequence) 组合器将多个 Parser 顺序连接起来，使用选择 (Alternative) 组合器在多个 Parser 之间进行选择。
代码示例：一个简单的整数 Parser
下面是一个使用 Spirit.Qi 解析整数的简单示例：
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "123";
9
int result;
10
11
bool success = qi::parse(input.begin(), input.end(), qi::int_, result);
12
13
if (success) {
14
std::cout << "解析成功，结果为: " << result << std::endl;
15
} else {
16
std::cout << "解析失败" << std::endl;
17
}
18
19
return 0;
20
}
代码解释：
⚝ qi::int_：这是一个预定义的 Parser，用于解析整数。
⚝ qi::parse(input.begin(), input.end(), qi::int_, result)：qi::parse 函数是 Spirit.Qi 提供的解析入口点。
⚝ input.begin(), input.end()：指定输入流的迭代器范围，这里是字符串 input 的起始和结束迭代器。
⚝ qi::int_：要使用的 Parser，这里是整数 Parser。
⚝ result：用于存储解析结果的变量，类型为 int。
这段代码使用 qi::int_ Parser 解析字符串 "123"，并将解析结果存储在 result 变量中。如果解析成功，输出 "解析成功，结果为: 123"，否则输出 "解析失败"。
总结：
Parser 是 Boost.Spirit 的核心组件，负责识别输入流中的模式并产生解析结果。理解 Parser 的本质、输入流抽象、匹配与消耗、属性以及可组合性是掌握 Boost.Spirit 的关键。在后续章节中，我们将深入探讨各种 Parser 的使用和组合技巧。
2.2 Rule (规则) 的定义与使用 (Rule (规则) Definition and Usage)
在 Boost.Spirit 中，Rule (规则) 是对 Parser (解析器) 的抽象和封装。Rule 可以被看作是具名的 Parser，它允许我们将复杂的解析逻辑分解成更小的、可重用的模块。Rule 的引入极大地提高了代码的可读性和可维护性，并支持递归语法 (Recursive Grammar) 的定义。
Rule 的主要作用和特点包括：
① 命名和重用
Rule 允许我们为 Parser 赋予一个名称，这样就可以在代码中通过名称来引用和重用这个 Parser。这对于构建复杂的语法解析器非常重要，可以将复杂的语法规则分解成多个小的、易于理解和管理的 Rule。
② 延迟定义
Rule 支持延迟定义 (Deferred Definition)。这意味着我们可以在定义 Rule 的时候，引用尚未定义的其他 Rule。这对于处理递归语法至关重要，例如，定义一个可以嵌套的表达式语法。
③ Attribute (属性) 传播
Rule 可以管理其内部 Parser 的 Attribute (属性) 传播。Rule 可以定义自身的 Attribute 类型，并控制如何将内部 Parser 的 Attribute 转换为 Rule 的 Attribute。这使得我们可以构建类型安全的解析器，并方便地处理解析结果。
④ 语义动作 (Semantic Actions)
Rule 可以关联 Semantic Actions (语义动作)。Semantic Actions 是在 Rule 成功匹配时执行的 C++ 代码，用于处理解析结果，例如，构建抽象语法树 (Abstract Syntax Tree, AST)，执行计算，或者进行其他自定义操作。
Rule 的定义方式
在 Spirit.Qi 中，Rule 通常使用 qi::rule<> 模板类来定义。qi::rule<> 的基本语法如下：
1
qi::rule<Iterator, Attribute, Skipper> rule_name;
⚝ Iterator：输入流的迭代器类型。
⚝ Attribute：Rule 的 Attribute 类型，即解析成功时 Rule 产生的属性类型。如果 Rule 不产生属性，可以使用 qi::unused_type。
⚝ Skipper：跳过符 Parser 类型，用于处理输入流中的空白符。可以省略，默认使用 qi::space_type。
⚝ rule_name：Rule 的名称，可以自定义。
Rule 的赋值和使用
定义 Rule 后，需要为其赋值一个 Parser 或 Parser 表达式。赋值操作符 = 可以用于将 Parser 或 Parser 表达式赋值给 Rule。赋值后，Rule 就可以像 Parser 一样被使用，例如，在 qi::parse 函数中调用，或者与其他 Rule 组合。
代码示例：使用 Rule 定义整数 Parser
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "456";
9
int result;
10
11
// 定义一个名为 integer_rule 的 Rule，用于解析整数
12
qi::rule<std::string::iterator, int()> integer_rule;
13
14
// 将预定义的整数 Parser qi::int_ 赋值给 integer_rule
15
integer_rule = qi::int_;
16
17
bool success = qi::parse(input.begin(), input.end(), integer_rule, result);
18
19
if (success) {
20
std::cout << "解析成功，结果为: " << result << std::endl;
21
} else {
22
std::cout << "解析失败" << std::endl;
23
}
24
25
return 0;
26
}
代码解释：
⚝ qi::rule<std::string::iterator, int()> integer_rule;：定义了一个名为 integer_rule 的 Rule。
⚝ std::string::iterator：指定输入流迭代器类型为 std::string::iterator。
⚝ int()：指定 Rule 的 Attribute 类型为 int。() 表示不使用 Skipper，默认使用 qi::space_type 作为 Skipper。
⚝ integer_rule = qi::int_;：将预定义的整数 Parser qi::int_ 赋值给 integer_rule。
⚝ qi::parse(input.begin(), input.end(), integer_rule, result)：使用 integer_rule 进行解析。
这个例子虽然简单，但展示了 Rule 的基本定义和使用方法。通过 Rule，我们将整数 Parser qi::int_ 封装到了 integer_rule 中，并在 qi::parse 函数中使用了 integer_rule。
代码示例：使用 Rule 定义更复杂的 Parser
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
#include <vector>
5
6
namespace qi = boost::spirit::qi;
7
8
int main() {
9
std::string input = "1,2,3,4";
10
std::vector<int> results;
11
12
// 定义一个 Rule 用于解析逗号分隔的整数列表
13
qi::rule<std::string::iterator, std::vector<int>()> csv_rule;
14
15
// 使用组合解析器定义 csv_rule：整数 + (',' + 整数) *
16
csv_rule = qi::int_ >> *(',' >> qi::int_);
17
18
bool success = qi::parse(input.begin(), input.end(), csv_rule, results);
19
20
if (success) {
21
std::cout << "解析成功，结果为: ";
22
for (int val : results) {
23
std::cout << val << " ";
24
}
25
std::cout << std::endl;
26
} else {
27
std::cout << "解析失败" << std::endl;
28
}
29
30
return 0;
31
}
代码解释：
⚝ qi::rule<std::string::iterator, std::vector<int>()> csv_rule;：定义了一个名为 csv_rule 的 Rule，其 Attribute 类型为 std::vector<int>，用于存储解析得到的整数列表。
⚝ csv_rule = qi::int_ >> *(',' >> qi::int_);：使用组合解析器定义 csv_rule。
⚝ qi::int_: 解析一个整数。
⚝ ',': 解析一个逗号字符。
⚝ >>: 序列组合器，表示顺序解析。
⚝ *: 重复组合器，表示重复零次或多次。
⚝ (',' >> qi::int_): 解析一个逗号后跟一个整数的序列。
⚝ *(',' >> qi::int_): 重复解析零次或多次逗号加整数的序列。
⚝ qi::int_ >> *(',' >> qi::int_): 先解析一个整数，然后解析零次或多次逗号加整数的序列，从而构成逗号分隔的整数列表。
这个例子展示了如何使用 Rule 和组合解析器定义更复杂的语法规则。通过 Rule，我们可以将复杂的解析逻辑分解成更小的、可管理的模块，并提高代码的可读性和可维护性。
总结：
Rule 是 Boost.Spirit 中重要的抽象概念，它为 Parser 提供了命名、重用、延迟定义和属性管理等功能。Rule 是构建复杂语法解析器的基础，通过合理地使用 Rule，可以有效地组织和管理解析逻辑，提高代码质量。
2.3 Attribute (属性) 与语义动作 (Attribute (属性) and Semantic Actions)
Attribute (属性) 和 Semantic Actions (语义动作) 是 Boost.Spirit 中处理解析结果的关键机制。Attribute 是 Parser 解析成功时产生的值，而 Semantic Actions 是在 Parser 成功匹配后执行的 C++ 代码，用于处理 Attribute。
Attribute (属性) 的作用
Attribute 的主要作用是将解析的文本数据转换为程序可以处理的数据结构。例如，解析数字字符串 "123" 可以得到整数属性 123，解析 JSON 字符串可以得到 JSON 对象属性。
Attribute 在 Spirit.Qi 中扮演着至关重要的角色：
① 数据传递
Attribute 是 Parser 之间传递数据的桥梁。当组合多个 Parser 时，每个 Parser 产生的 Attribute 可以传递给后续的 Parser 或 Semantic Actions 进行处理。
② 类型推导
Spirit.Qi 具有强大的 Attribute 类型推导 (Attribute Type Deduction) 能力。它可以根据 Parser 的定义和组合方式，自动推导出 Parser 和 Rule 的 Attribute 类型，从而减少了手动指定类型的繁琐工作，并提高了代码的类型安全性。
③ 语义动作的输入
Semantic Actions 接收 Parser 的 Attribute 作为输入，并根据 Attribute 的值执行相应的操作。
Semantic Actions (语义动作) 的作用
Semantic Actions 是在 Parser 成功匹配后执行的 C++ 代码，用于处理解析得到的 Attribute。Semantic Actions 的主要作用包括：
① 数据转换
Semantic Actions 可以将 Parser 产生的 Attribute 转换为其他形式的数据。例如，将字符串 Attribute 转换为自定义对象，或者对数值 Attribute 进行计算。
② 构建数据结构
Semantic Actions 可以用于构建复杂的数据结构，例如，抽象语法树 (AST)，配置文件对象，或者其他自定义的数据模型。
③ 执行自定义操作
Semantic Actions 可以执行任何 C++ 代码，例如，调用函数，访问外部资源，或者进行其他自定义操作。这使得 Spirit.Qi 具有高度的灵活性和可扩展性。
Semantic Actions 的定义方式
Semantic Actions 可以通过多种方式定义，最常用的方式是使用 Lambda 表达式 (Lambda Expressions) 和 Boost.Phoenix。
使用 Lambda 表达式
Lambda 表达式是 C++11 引入的特性，可以方便地定义匿名函数对象。在 Spirit.Qi 中，可以使用 Lambda 表达式作为 Semantic Actions，直接在 Parser 表达式中定义处理逻辑。
代码示例：使用 Lambda 表达式的 Semantic Action
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
namespace phx = boost::phoenix;
7
8
int main() {
9
std::string input = "10 + 20";
10
int result = 0;
11
12
// 定义一个 Rule 解析加法表达式，并使用 Lambda 表达式作为 Semantic Action
13
qi::rule<std::string::iterator, int(), qi::space_type> addition_rule;
14
addition_rule = qi::int_ >> qi::lit('+') >> qi::int_ [ qi::_val = qi::_1 + qi::_2 ];
15
16
bool success = qi::parse(input.begin(), input.end(), addition_rule, result);
17
18
if (success) {
19
std::cout << "解析成功，结果为: " << result << std::endl;
20
} else {
21
std::cout << "解析失败" << std::endl;
22
}
23
24
return 0;
25
}
代码解释：
⚝ qi::rule<std::string::iterator, int(), qi::space_type> addition_rule;：定义一个 Rule addition_rule，其 Attribute 类型为 int，使用 qi::space_type 作为 Skipper。
⚝ addition_rule = qi::int_ >> qi::lit('+') >> qi::int_ [ qi::_val = qi::_1 + qi::_2 ];：定义 addition_rule 的解析规则和 Semantic Action。
⚝ qi::int_ >> qi::lit('+') >> qi::int_: 解析一个整数，一个加号，再解析一个整数。
⚝ [ qi::_val = qi::_1 + qi::_2 ]: Semantic Action 部分，使用方括号 [] 包围。
⚝ qi::_val: 占位符，表示 Rule 的 Attribute，即 addition_rule 的 Attribute int。
⚝ qi::_1: 占位符，表示第一个 qi::int_ Parser 的 Attribute。
⚝ qi::_2: 占位符，表示第二个 qi::int_ Parser 的 Attribute。
⚝ qi::_val = qi::_1 + qi::_2: 将第一个 qi::int_ 和第二个 qi::int_ 的 Attribute 相加，并将结果赋值给 qi::_val，即 addition_rule 的 Attribute。
这段代码解析 "10 + 20"，并使用 Lambda 表达式 [ qi::_val = qi::_1 + qi::_2 ] 将两个整数 Attribute 相加，并将结果作为 addition_rule 的 Attribute 返回。
使用 Boost.Phoenix
Boost.Phoenix 是一个 C++ 库，用于创建函数对象和 Lambda 表达式。Phoenix 提供了更丰富的占位符和函数对象，可以用于定义更复杂的 Semantic Actions。
代码示例：使用 Boost.Phoenix 的 Semantic Action
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/phoenix/phoenix.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
namespace phx = boost::phoenix;
8
9
int main() {
10
std::string input = "10 * 5";
11
int result = 0;
12
13
// 定义一个 Rule 解析乘法表达式，并使用 Boost.Phoenix 作为 Semantic Action
14
qi::rule<std::string::iterator, int(), qi::space_type> multiplication_rule;
15
multiplication_rule = qi::int_ >> qi::lit('*') >> qi::int_ [ phx::ref(result) = qi::_1 * qi::_2 ];
16
17
bool success = qi::parse(input.begin(), input.end(), multiplication_rule, qi::unused, qi::space, multiplication_rule);
18
19
if (success) {
20
std::cout << "解析成功，结果为: " << result << std::endl;
21
} else {
22
std::cout << "解析失败" << std::endl;
23
}
24
25
return 0;
26
}
代码解释：
⚝ [ phx::ref(result) = qi::_1 * qi::_2 ]: Semantic Action 部分，使用 Boost.Phoenix 语法。
⚝ phx::ref(result): 使用 phx::ref 创建一个对变量 result 的引用，使得可以在 Semantic Action 中修改外部变量 result。
⚝ qi::_1 * qi::_2: 将第一个 qi::int_ 和第二个 qi::int_ 的 Attribute 相乘。
⚝ phx::ref(result) = qi::_1 * qi::_2: 将乘积结果赋值给外部变量 result。
这个例子解析 "10 * 5"，并使用 Boost.Phoenix 将两个整数 Attribute 相乘，并将结果赋值给外部变量 result。
总结：
Attribute 和 Semantic Actions 是 Boost.Spirit 中处理解析结果的核心机制。Attribute 用于传递解析数据，Semantic Actions 用于处理 Attribute 并执行自定义操作。通过灵活地使用 Attribute 和 Semantic Actions，可以构建功能强大的解析器，将文本数据转换为程序可以处理的各种数据结构，并执行各种自定义操作。
2.4 组合解析器 (Parser Combinators)
Parser Combinators (组合解析器) 是 Boost.Spirit 最强大的特性之一。它们允许我们通过组合 (Combining) 简单的 Parser 来构建复杂的 Parser，而无需手动编写复杂的解析逻辑。组合解析器遵循组合子模式 (Combinator Pattern)，提供了一种声明式 (Declarative) 的方式来描述语法规则。
Spirit.Qi 提供了丰富的组合解析器，主要可以分为以下几类：
2.4.1 序列 (Sequence)
序列 (Sequence) 组合器 用于将多个 Parser 顺序连接起来。只有当所有 Parser 依次成功匹配时，序列组合器才算成功。序列组合器使用 右移操作符 >> 表示。
语法：
1
parser1 >> parser2 >> parser3 ...
Attribute 传播：
序列组合器的 Attribute 是由其组成 Parser 的 Attribute 组合而成的 tuple (元组)。例如，如果 parser1 的 Attribute 类型是 A，parser2 的 Attribute 类型是 B，则 parser1 >> parser2 的 Attribute 类型是 boost::fusion::tuple<A, B>。
代码示例：序列组合器
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
#include <tuple>
5
6
namespace qi = boost::spirit::qi;
7
8
int main() {
9
std::string input = "abc123def";
10
std::tuple<std::string, int, std::string> result;
11
12
// 使用序列组合器解析：字母序列 + 整数 + 字母序列
13
auto sequence_parser = qi::alpha >> qi::int_ >> qi::alpha;
14
15
bool success = qi::parse(input.begin(), input.end(), sequence_parser, result);
16
17
if (success) {
18
std::cout << "解析成功，结果为: " << std::endl;
19
std::cout << "字符串: " << std::get<0>(result) << std::endl;
20
std::cout << "整数: " << std::get<1>(result) << std::endl;
21
std::cout << "字符串: " << std::get<2>(result) << std::endl;
22
} else {
23
std::cout << "解析失败" << std::endl;
24
}
25
26
return 0;
27
}
代码解释：
⚝ auto sequence_parser = qi::alpha >> qi::int_ >> qi::alpha;：定义一个序列组合器 sequence_parser。
⚝ qi::alpha: 解析一个或多个字母字符。
⚝ qi::int_: 解析一个整数。
⚝ >>: 序列组合器，将三个 Parser 顺序连接。
⚝ std::tuple<std::string, int, std::string> result;: 定义一个 tuple result，用于存储序列组合器的 Attribute。其类型与序列组合器的 Attribute 类型匹配。
这段代码解析 "abc123def"，使用序列组合器将字母序列、整数和字母序列依次解析出来，并将结果存储在 tuple result 中。
2.4.2 选择 (Alternative)
选择 (Alternative) 组合器 用于在多个 Parser 之间进行选择。它尝试依次使用每个 Parser 进行匹配，只要其中一个 Parser 匹配成功，选择组合器就成功。选择组合器使用 或操作符 | 表示。
语法：
1
parser1 | parser2 | parser3 ...
Attribute 传播：
选择组合器的 Attribute 类型是其组成 Parser 的 Attribute 类型的 variant (变体)。Variant 是一种可以存储多种不同类型值的类型。例如，如果 parser1 的 Attribute 类型是 A，parser2 的 Attribute 类型是 B，则 parser1 | parser2 的 Attribute 类型是 boost::variant<A, B>。
代码示例：选择组合器
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/variant.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
8
int main() {
9
std::string input1 = "123";
10
std::string input2 = "abc";
11
boost::variant<int, std::string> result;
12
13
// 使用选择组合器解析：整数 或 字母序列
14
auto alternative_parser = qi::int_ | qi::alpha;
15
16
bool success1 = qi::parse(input1.begin(), input1.end(), alternative_parser, result);
17
bool success2 = qi::parse(input2.begin(), input2.end(), alternative_parser, result);
18
19
if (success1) {
20
std::cout << "解析 '" << input1 << "' 成功，结果为: ";
21
if (boost::get<int>(&result)) {
22
std::cout << "整数: " << boost::get<int>(result) << std::endl;
23
} else if (boost::get<std::string>(&result)) {
24
std::cout << "字符串: " << boost::get<std::string>(result) << std::endl;
25
}
26
} else {
27
std::cout << "解析 '" << input1 << "' 失败" << std::endl;
28
}
29
30
if (success2) {
31
std::cout << "解析 '" << input2 << "' 成功，结果为: ";
32
if (boost::get<int>(&result)) {
33
std::cout << "整数: " << boost::get<int>(result) << std::endl;
34
} else if (boost::get<std::string>(&result)) {
35
std::cout << "字符串: " << boost::get<std::string>(result) << std::endl;
36
}
37
} else {
38
std::cout << "解析 '" << input2 << "' 失败" << std::endl;
39
}
40
41
return 0;
42
}
代码解释：
⚝ auto alternative_parser = qi::int_ | qi::alpha;：定义一个选择组合器 alternative_parser。
⚝ qi::int_: 解析一个整数。
⚝ qi::alpha: 解析一个或多个字母字符。
⚝ |: 选择组合器，表示选择解析整数或字母序列。
⚝ boost::variant<int, std::string> result;: 定义一个 variant result，用于存储选择组合器的 Attribute。其类型是整数和字符串的 variant。
⚝ boost::get<int>(&result) 和 boost::get<std::string>(&result)：使用 boost::get 函数从 variant 中获取具体类型的值。
这段代码分别解析 "123" 和 "abc"，使用选择组合器尝试解析整数或字母序列。根据输入的不同，选择组合器会选择相应的 Parser 进行匹配，并将结果存储在 variant result 中。
2.4.3 重复 (Repetition)
重复 (Repetition) 组合器 用于将一个 Parser 重复执行多次。Spirit.Qi 提供了多种重复组合器：
① * (Kleene Star)：重复零次或多次。
② + (Kleene Plus)：重复一次或多次。
③ - (Optional)：重复零次或一次，等价于可选组合器。
④ []{min, max} (Range)：重复 min 次到 max 次。
⑤ []{n} (Exact)：重复 n 次。
语法：
1
*parser // 零次或多次
2
+parser // 一次或多次
3
-parser // 零次或一次 (可选)
4
parser[qi::repeat(min, max)] // min 到 max 次
5
parser[qi::repeat(n)] // n 次
Attribute 传播：
重复组合器的 Attribute 类型通常是 容器 (Container) 类型，例如 std::vector 或 std::list，用于存储每次重复解析得到的 Attribute。
代码示例：重复组合器
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
#include <vector>
5
6
namespace qi = boost::spirit::qi;
7
8
int main() {
9
std::string input = "1,2,3,4,5";
10
std::vector<int> results;
11
12
// 使用重复组合器解析：整数的逗号分隔列表
13
auto repetition_parser = qi::int_ % ','; // 使用 % 操作符，等价于 qi::int_ >> * (',' >> qi::int_)
14
15
bool success = qi::parse(input.begin(), input.end(), repetition_parser, results);
16
17
if (success) {
18
std::cout << "解析成功，结果为: ";
19
for (int val : results) {
20
std::cout << val << " ";
21
}
22
std::cout << std::endl;
23
} else {
24
std::cout << "解析失败" << std::endl;
25
}
26
27
return 0;
28
}
代码解释：
⚝ auto repetition_parser = qi::int_ % ',';：定义一个重复组合器 repetition_parser。
⚝ qi::int_: 解析一个整数。
⚝ ,: 分隔符，这里是逗号字符。
⚝ %: 重复组合器，表示重复解析整数，并使用逗号作为分隔符。等价于 qi::int_ >> * (',' >> qi::int_)。
⚝ std::vector<int> results;: 定义一个 vector results，用于存储重复组合器的 Attribute，即解析得到的整数列表。
这段代码解析 "1,2,3,4,5"，使用重复组合器解析逗号分隔的整数列表，并将结果存储在 vector results 中。
2.4.4 可选 (Optional)
可选 (Optional) 组合器 用于表示一个 Parser 是可选的，即可以出现零次或一次。可选组合器使用 前缀操作符 - 表示，或者使用 [] 包围 Parser。
语法：
1
-parser // 可选 Parser
2
[parser] // 可选 Parser (另一种语法)
Attribute 传播：
可选组合器的 Attribute 类型是 boost::optional<T>，其中 T 是被修饰的 Parser 的 Attribute 类型。如果 Parser 成功匹配，则 boost::optional 包含 Parser 的 Attribute 值；如果 Parser 没有匹配，则 boost::optional 为空。
代码示例：可选组合器
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/optional.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
8
int main() {
9
std::string input1 = "abc";
10
std::string input2 = "123";
11
boost::optional<std::string> result;
12
13
// 使用可选组合器解析：可选的字母序列
14
auto optional_parser = -qi::alpha; // 等价于 qi::omit[qi::alpha] 如果不需要 attribute
15
16
bool success1 = qi::parse(input1.begin(), input1.end(), optional_parser, result);
17
bool success2 = qi::parse(input2.begin(), input2.end(), optional_parser, result);
18
19
if (success1) {
20
std::cout << "解析 '" << input1 << "' 成功，结果为: ";
21
if (result) {
22
std::cout << "字符串: " << *result << std::endl;
23
} else {
24
std::cout << "没有匹配到字母序列" << std::endl;
25
}
26
} else {
27
std::cout << "解析 '" << input1 << "' 失败" << std::endl;
28
}
29
30
if (success2) {
31
std::cout << "解析 '" << input2 << "' 成功，结果为: ";
32
if (result) {
33
std::cout << "字符串: " << *result << std::endl;
34
} else {
35
std::cout << "没有匹配到字母序列" << std::endl; // input2 不匹配 qi::alpha，所以 result 为空
36
}
37
} else {
38
std::cout << "解析 '" << input2 << "' 失败" << std::endl;
39
}
40
41
return 0;
42
}
代码解释：
⚝ auto optional_parser = -qi::alpha;：定义一个可选组合器 optional_parser。
⚝ qi::alpha: 解析一个或多个字母字符。
⚝ -: 可选组合器，表示字母序列是可选的。
⚝ boost::optional<std::string> result;: 定义一个 boost::optional<std::string> 类型的 result，用于存储可选组合器的 Attribute。
这段代码分别解析 "abc" 和 "123"，使用可选组合器解析可选的字母序列。对于 "abc"，字母序列被成功匹配，result 包含解析到的字符串；对于 "123"，字母序列没有被匹配，result 为空。
总结：
组合解析器是 Boost.Spirit 的核心特性，通过序列、选择、重复和可选等组合器，我们可以灵活地构建各种复杂的语法解析器。组合解析器不仅简化了语法规则的描述，还提高了代码的可读性和可维护性。掌握组合解析器的使用是深入理解和应用 Boost.Spirit 的关键。
2.5 预定义的 Parser (Predefined Parsers)
Boost.Spirit.Qi 提供了丰富的 Predefined Parsers (预定义的 Parser)，可以直接使用，无需手动定义。这些预定义的 Parser 覆盖了常见的语法元素，例如字符、数字、空白符、标识符等，极大地简化了 Parser 的构建过程。
常用的预定义 Parser 包括：
① 字符 Parser (Character Parsers)
⚝ qi::char_: 匹配任意字符。
⚝ qi::lit(char) 或 'c': 匹配指定的字符 c。
⚝ qi::lit(const char*) 或 "str": 匹配指定的字符串 "str"。
⚝ qi::alnum: 匹配字母数字字符 (alphanumeric)。
⚝ qi::alpha: 匹配字母字符 (alphabetic)。
⚝ qi::digit: 匹配数字字符 (digit)。
⚝ qi::xdigit: 匹配十六进制数字字符 (hexadecimal digit)。
⚝ qi::lower: 匹配小写字母字符 (lowercase)。
⚝ qi::upper: 匹配大写字母字符 (uppercase)。
⚝ qi::punct: 匹配标点符号字符 (punctuation)。
⚝ qi::space: 匹配空白符字符 (space)。
⚝ qi::cntrl: 匹配控制字符 (control)。
⚝ qi::graph: 匹配图形字符 (graphic)。
⚝ qi::print: 匹配可打印字符 (printable)。
② 数值 Parser (Numeric Parsers)
⚝ qi::int_: 匹配整数 (integer)。
⚝ qi::uint_: 匹配无符号整数 (unsigned integer)。
⚝ qi::long_long: 匹配长长整数 (long long integer)。
⚝ qi::ulong_long: 匹配无符号长长整数 (unsigned long long integer)。
⚝ qi::double_: 匹配双精度浮点数 (double floating-point)。
⚝ qi::real_parser<>: 更灵活的实数 Parser，可以自定义实数的格式。
③ 空白符 Parser (Whitespace Parsers)
⚝ qi::space: 匹配空白符，通常用于 Skipper。
⚝ qi::blank: 匹配空格和制表符。
⚝ qi::eol: 匹配行尾符 (end-of-line)。
⚝ qi::eoi: 匹配输入结束符 (end-of-input)。
④ 其他 Parser
⚝ qi::lexeme[parser]: 禁止 Skipper 跳过 parser 匹配的内容。
⚝ qi::omit[parser]: 忽略 parser 的 Attribute，不产生 Attribute。
⚝ qi::raw[parser]: 将 parser 匹配的原始输入文本作为 Attribute 返回。
⚝ qi::attr(value): 创建一个 Parser，其 Attribute 始终为指定的值 value，不消耗任何输入。
⚝ qi::eps: 空 Parser，总是匹配成功，不消耗任何输入，Attribute 为 qi::unused_type。
⚝ qi::fail: 总是匹配失败的 Parser。
代码示例：使用预定义的 Parser
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = " Hello 123 World! ";
9
std::string hello_str, world_str;
10
int number;
11
12
// 使用预定义的 Parser 解析：空白符 + "Hello" + 空白符 + 整数 + 空白符 + "World" + 空白符 + "!" + 空白符
13
auto predefined_parser = qi::space >> qi::lit("Hello") >> qi::space >> qi::int_ >> qi::space >> qi::lit("World") >> qi::space >> qi::lit('!') >> qi::space;
14
15
bool success = qi::parse(input.begin(), input.end(), predefined_parser);
16
17
if (success) {
18
std::cout << "解析成功" << std::endl;
19
} else {
20
std::cout << "解析失败" << std::endl;
21
}
22
23
return 0;
24
}
代码解释：
⚝ auto predefined_parser = qi::space >> qi::lit("Hello") >> qi::space >> qi::int_ >> qi::space >> qi::lit("World") >> qi::space >> qi::lit('!') >> qi::space;：定义一个使用预定义 Parser 的组合 Parser。
⚝ qi::space: 匹配空白符。
⚝ qi::lit("Hello"): 匹配字符串 "Hello"。
⚝ qi::int_: 匹配整数。
⚝ qi::lit("World"): 匹配字符串 "World"。
⚝ qi::lit('!'): 匹配字符 '!'。
⚝ >>: 序列组合器，将预定义的 Parser 顺序连接。
这段代码解析 " Hello 123 World! "，使用预定义的 Parser 匹配空白符、字符串 "Hello"、整数、字符串 "World" 和字符 '!'。
总结：
预定义的 Parser 是 Boost.Spirit.Qi 提供的一组方便易用的 Parser，涵盖了常见的语法元素。使用预定义的 Parser 可以大大简化 Parser 的构建过程，提高开发效率。在实际应用中，应充分利用预定义的 Parser，并结合组合解析器来构建复杂的语法解析器。
END_OF_CHAPTER
3. chapter 3： Spirit.Karma 核心概念 (Spirit.Karma 核心概念, Core Concepts of Spirit.Karma)
3.1 Generator (生成器) 详解 (Generator (生成器) 详解, In-depth Explanation of Generators)
在 Boost.Spirit 库族中，Spirit.Karma 库承担着生成 (Generation) 的重任。与 Spirit.Qi 专注于解析 (Parsing) 不同，Karma 的核心目标是将数据结构或值转换为格式化的输出，例如字符串、文件流等。Generator (生成器) 是 Spirit.Karma 的基本构建块，它定义了如何将数据转换为目标格式。
① 什么是 Generator？
Generator 本质上是一个对象，它可以接受一个或多个输入属性，并根据预定义的规则生成输出。可以将 Generator 视为一个“数据格式化器”，它接收程序内部的数据表示，并将其转换为外部可读或可用的形式。
② Generator 的核心功能
⚝ 数据转换：Generator 的主要任务是将程序中的数据（例如，整数、字符串、结构体等）转换为文本或其他格式的输出。
⚝ 格式化输出：Generator 允许精确控制输出的格式，例如，数字的进制、浮点数的精度、字符串的对齐方式等。
⚝ 组合性：与 Spirit.Qi 的 Parser 类似，Karma 的 Generator 也具有强大的组合性。你可以使用各种 Generator Combinator 将简单的 Generator 组合成复杂的、功能强大的 Generator。
⚝ 属性驱动：Generator 的行为通常由其 attribute (属性) 驱动。输入给 Generator 的属性值决定了最终生成的输出内容。
③ Generator 的类型
Spirit.Karma 提供了多种预定义的 Generator，涵盖了常见的生成需求。同时，也允许用户自定义 Generator 以满足特定的应用场景。常见的 Generator 类型包括：
⚝ Primitive Generators (原始生成器)：用于生成基本数据类型的 Generator，例如：
▮▮▮▮⚝ int_：生成整数。
▮▮▮▮⚝ double_：生成双精度浮点数。
▮▮▮▮⚝ string：生成字符串。
▮▮▮▮⚝ char_：生成单个字符。
⚝ Composite Generators (组合生成器)：通过组合其他 Generator 构建的更复杂的 Generator，例如：
▮▮▮▮⚝ sequence：顺序生成多个部分。
▮▮▮▮⚝ alternative：选择性生成多个候选项之一。
▮▮▮▮⚝ repeat：重复生成某个模式。
▮▮▮▮⚝ optional：可选地生成某个部分。
⚝ Custom Generators (自定义生成器)：用户根据自身需求实现的特殊 Generator。
④ Generator 的声明与使用
在 Spirit.Karma 中，Generator 通常以对象 (Object) 的形式存在。你可以直接使用预定义的 Generator 对象，也可以通过 rule<> 来声明自定义的 Generator 规则。
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::string generated_string;
9
int number = 123;
10
11
// 使用 int_ 生成器将整数转换为字符串
12
karma::generate(std::back_inserter(generated_string), karma::int_, number);
13
14
std::cout << "Generated string: " << generated_string << std::endl; // 输出: Generated string: 123
15
16
return 0;
17
}
在这个简单的例子中，karma::int_ 就是一个预定义的 Generator，它负责将整数类型的数据转换为字符串形式。karma::generate 函数是 Karma 库提供的用于执行生成操作的核心函数。它接受一个输出迭代器（这里是 std::back_inserter 用于向 generated_string 追加字符）、一个 Generator 对象 (karma::int_) 和一个属性值 (number)。
⑤ Generator 与 Parser 的对比
| 特性 | Spirit.Qi (Parser) | Spirit.Karma (Generator) |
|---|---|---|
| 核心功能 | 解析输入 | 生成输出 |
| 输入 | 字符流/字符串 | 数据结构/值 |
| 输出 | 属性值/数据结构 | 字符流/字符串 |
| 方向 | 输入 -> 数据 | 数据 -> 输出 |
| 主要组件 | Parser | Generator |
| 典型应用场景 | 编译原理、协议解析 | 数据序列化、格式化输出 |
总而言之，Generator 是 Spirit.Karma 的基石，理解 Generator 的概念和使用方法是掌握 Karma 库的关键。通过灵活运用各种 Generator，我们可以轻松实现复杂的数据格式化和输出任务。
3.2 Rule (规则) 的定义与使用 (Rule (规则) 的定义与使用, Defining and Using Rules)
与 Spirit.Qi 类似，Spirit.Karma 也使用 rule (规则) 来组织和抽象 Generator。Rule 可以看作是 Generator 的容器，它允许我们为 Generator 命名、赋予其属性，并进行更高级的组合和操作。使用 rule 可以提高代码的可读性、可维护性和复用性。
① Rule 的概念
在 Spirit.Karma 中，rule 是一个具名的 Generator (Named Generator)。它封装了一个或多个 Generator，并允许我们像使用变量一样使用这个组合的 Generator。rule 的主要作用包括：
⚝ 命名和抽象：为复杂的 Generator 组合赋予有意义的名字，提高代码可读性。
⚝ 封装和复用：将常用的 Generator 模式封装成 rule，方便在代码中多次复用。
⚝ 属性管理：rule 可以显式地声明其接受和产生的属性类型，增强类型安全性和代码清晰度。
⚝ 递归定义：rule 允许递归定义，这对于处理具有递归结构的数据格式（例如，JSON、XML）非常重要。
② Rule 的定义
在 Spirit.Karma 中，rule 的定义通常使用 karma::rule<> 模板。其基本语法如下：
1
karma::rule<OutputIterator, Attribute> rule_name;
⚝ OutputIterator：指定 rule 生成输出时使用的迭代器类型。通常是 std::back_insert_iterator<std::string> 或其他输出流迭代器。
⚝ Attribute：指定 rule 接受的属性类型。如果 rule 不接受任何属性，可以使用 boost::spirit::unused_type 或 boost::fusion::void_。
⚝ rule_name：rule 的名称，可以自定义。
例如，定义一个生成整数的 rule：
1
karma::rule<std::back_insert_iterator<std::string>, int()> integer_rule;
这里，integer_rule 被定义为一个 rule，它生成字符串，接受一个 int 类型的属性。
③ Rule 的赋值
定义 rule 后，需要为其赋值具体的 Generator 表达式。赋值操作符 = 用于将 Generator 表达式赋给 rule。
1
integer_rule = karma::int_; // 将 int_ 生成器赋值给 integer_rule
现在，integer_rule 就代表了 karma::int_ 生成器。我们可以像使用 karma::int_ 一样使用 integer_rule。
④ Rule 的使用
rule 的使用方式与普通的 Generator 类似，可以将其传递给 karma::generate 函数，或者与其他 Generator 组合使用。
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::string generated_string;
9
int number = 456;
10
11
karma::rule<std::back_insert_iterator<std::string>, int()> integer_rule;
12
integer_rule = karma::int_;
13
14
karma::generate(std::back_inserter(generated_string), integer_rule, number);
15
16
std::cout << "Generated string using rule: " << generated_string << std::endl; // 输出: Generated string using rule: 456
17
18
return 0;
19
}
这个例子与之前的例子功能相同，但使用了 rule 来封装 karma::int_ 生成器。在更复杂的场景中，使用 rule 的优势会更加明显。
⑤ 带属性的 Rule
rule 可以接受属性，并将属性传递给其内部的 Generator。例如，定义一个生成带前缀的整数的 rule：
1
karma::rule<std::back_insert_iterator<std::string>, boost::fusion::tuple<std::string, int>()> prefixed_integer_rule;
2
prefixed_integer_rule = karma::string << karma::int_;
这个 rule 接受一个 boost::fusion::tuple<std::string, int> 类型的属性，其中 tuple 的第一个元素是前缀字符串，第二个元素是整数。karma::string 生成器使用 tuple 的第一个元素，karma::int_ 生成器使用 tuple 的第二个元素。
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
#include <boost/fusion/tuple.hpp>
5
6
namespace karma = boost::spirit::karma;
7
namespace fusion = boost::fusion;
8
9
int main() {
10
std::string generated_string;
11
fusion::tuple<std::string, int> data = fusion::make_tuple("Prefix: ", 789);
12
13
karma::rule<std::back_insert_iterator<std::string>, fusion::tuple<std::string, int>()> prefixed_integer_rule;
14
prefixed_integer_rule = karma::string << karma::int_;
15
16
karma::generate(std::back_inserter(generated_string), prefixed_integer_rule, data);
17
18
std::cout << "Generated string with prefix rule: " << generated_string << std::endl; // 输出: Generated string with prefix rule: Prefix: 789
19
20
return 0;
21
}
⑥ Rule 的优势总结
⚝ 代码组织：rule 帮助将复杂的生成逻辑分解为更小的、可管理的单元。
⚝ 代码复用：定义的 rule 可以在不同的生成场景中重复使用。
⚝ 类型安全：rule 的属性类型声明提高了代码的类型安全性，减少了错误。
⚝ 可读性：具名的 rule 提高了代码的可读性和可理解性。
总之，rule 是 Spirit.Karma 中重要的抽象工具，它使得 Generator 的定义和使用更加灵活和高效。在构建复杂的生成器时，合理使用 rule 是至关重要的。
3.3 Attribute (属性) 与语义动作 (Attribute (属性) 与语义动作, Attributes and Semantic Actions)
Attribute (属性) 在 Spirit.Karma 中扮演着核心角色，它是 Generator 的输入数据，驱动着生成过程。Semantic Action (语义动作) 则允许我们在生成过程中执行自定义的操作，例如数据转换、格式化控制等。理解属性和语义动作对于深入掌握 Spirit.Karma 至关重要。
① Attribute 的概念
在 Spirit.Karma 中，attribute 是 Generator 的输入数据 (Input Data)。Generator 接收属性值，并根据其内部的生成逻辑，将属性值转换为目标格式的输出。
⚝ 数据来源：Attribute 通常来源于程序中的变量、数据结构或表达式。
⚝ 类型关联：每个 Generator 都关联着特定的属性类型。例如，karma::int_ 关联的属性类型是 int，karma::string 关联的属性类型是 std::string。
⚝ 属性传递：在组合 Generator 时，属性会在不同的 Generator 之间传递和转换。
② Attribute 的类型
Spirit.Karma 支持多种属性类型，包括：
⚝ 基本类型：int, double, char, std::string 等 C++ 基本数据类型。
⚝ 容器类型：std::vector, std::list, std::array 等标准容器。
⚝ Boost.Fusion 序列：boost::fusion::tuple, boost::fusion::vector, boost::fusion::list 等 Fusion 序列，用于处理复合属性。
⚝ 自定义类型：用户自定义的结构体、类等类型。
③ Attribute 的传递与转换
在组合 Generator 时，属性的传递和转换是自动进行的。Spirit.Karma 会根据 Generator 的组合方式和属性类型，自动推导和传递属性。
例如，对于序列组合 g1 << g2，如果 g1 接受属性 A1，g2 接受属性 A2，那么组合后的 Generator 接受的属性类型通常是 boost::fusion::tuple<A1, A2>。当生成时，tuple 的第一个元素会传递给 g1，第二个元素会传递给 g2。
④ Semantic Action 的概念
Semantic Action (语义动作) 是在 Generator 生成过程中执行的函数或函数对象 (Function or Function Object)。它允许我们在生成过程的特定时刻插入自定义的逻辑，例如：
⚝ 数据转换：在生成前或生成后对属性值进行转换或处理。
⚝ 格式化控制：根据属性值动态调整生成格式。
⚝ 副作用：执行一些与生成过程相关的副作用操作，例如日志记录、状态更新等。
⑤ Semantic Action 的定义与使用
Semantic Action 可以是：
⚝ Lambda 表达式：C++11 引入的 Lambda 表达式是定义 Semantic Action 的常用方式，简洁灵活。
⚝ 函数对象 (Functor)：自定义的类，重载 operator()，使其可以像函数一样调用。
⚝ 函数指针：指向普通函数的指针。
Semantic Action 通过操作符 [] 附加到 Generator 或 Rule 上。
1
generator [semantic_action]
2
rule [semantic_action]
例如，使用 Lambda 表达式定义一个 Semantic Action，将生成的整数加上 10：
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::string generated_string;
9
int number = 100;
10
11
karma::generate(
12
std::back_inserter(generated_string),
13
karma::int_ [ [](int n) { std::cout << "Generating: " << n << std::endl; } ] << "!", // 附加 Semantic Action
14
number
15
);
16
17
std::cout << "Generated string with semantic action: " << generated_string << std::endl;
18
// 输出:
19
// Generating: 100
20
// Generated string with semantic action: 100!
21
22
return 0;
23
}
在这个例子中，Lambda 表达式 [](int n) { std::cout << "Generating: " << n << std::endl; } 被附加到 karma::int_ 生成器上。当 karma::int_ 生成整数时，这个 Lambda 表达式会被调用，并接收到生成的整数值作为参数。
⑥ Semantic Action 的返回值与属性传递
Semantic Action 可以有返回值。如果 Semantic Action 返回一个值，并且 Generator 期望一个属性，那么 Semantic Action 的返回值可以作为 Generator 的属性。这为属性的转换和传递提供了灵活的方式。
⑦ Semantic Action 的应用场景
⚝ 数据验证与转换：在生成前验证属性值的有效性，或将其转换为适合生成的格式。
⚝ 条件生成：根据属性值或其他条件，动态选择不同的生成路径。
⚝ 日志记录与调试：在生成过程中记录日志信息，方便调试和监控。
⚝ 副作用操作：执行一些与生成过程相关的副作用操作，例如更新计数器、修改全局状态等。
⑧ Attribute 与 Semantic Action 的关系
Attribute 是 Generator 的输入，Semantic Action 是在生成过程中对 Attribute 进行处理或执行额外操作的机制。它们共同协作，使得 Spirit.Karma 能够灵活地处理各种数据生成任务。
总结来说，Attribute 和 Semantic Action 是 Spirit.Karma 的核心概念。理解它们的工作原理和使用方法，可以帮助我们构建更强大、更灵活的 Generator，满足各种复杂的数据生成需求。
3.4 组合生成器 (组合生成器, Generator Combinators)
Generator Combinator (组合生成器) 是 Spirit.Karma 的强大特性之一。它允许我们将简单的 Generator 组合成更复杂的 Generator，从而构建出能够处理各种复杂数据格式的生成器。Karma 提供了丰富的 Combinator，主要分为以下几类：
3.4.1 序列 (Sequence)
Sequence (序列) Combinator 用于顺序执行多个 Generator (Sequential Execution of Generators)。它将多个 Generator 按照指定的顺序连接起来，依次执行。序列 Combinator 使用操作符 << 表示。
① 序列 Combinator 的语法
1
g1 << g2 << g3 ...
其中 g1, g2, g3 等都是 Generator。序列 Combinator 将按照 g1, g2, g3 的顺序依次执行。
② 序列 Combinator 的属性处理
如果序列中的 Generator g1, g2, g3 分别接受属性 A1, A2, A3，那么组合后的序列 Generator 接受的属性类型通常是 boost::fusion::tuple<A1, A2, A3>。当生成时，tuple 的第一个元素会传递给 g1，第二个元素会传递给 g2，以此类推。
③ 序列 Combinator 的示例
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
#include <boost/fusion/tuple.hpp>
5
6
namespace karma = boost::spirit::karma;
7
namespace fusion = boost::fusion;
8
9
int main() {
10
std::string generated_string;
11
fusion::tuple<std::string, int, double> data = fusion::make_tuple("Value: ", 123, 4.56);
12
13
// 使用序列 Combinator 组合 string, int_, double_ 生成器
14
auto sequence_generator = karma::string << karma::int_ << karma::double_;
15
16
karma::generate(std::back_inserter(generated_string), sequence_generator, data);
17
18
std::cout << "Generated string using sequence: " << generated_string << std::endl;
19
// 输出: Generated string using sequence: Value: 1234.56
20
21
return 0;
22
}
在这个例子中，karma::string << karma::int_ << karma::double_ 创建了一个序列 Generator。它首先生成字符串 "Value: "，然后生成整数 123，最后生成浮点数 4.56。输入的属性是一个 fusion::tuple，其元素分别对应序列中每个 Generator 的属性。
④ 序列 Combinator 的应用场景
⚝ 固定格式输出：生成具有固定格式的文本，例如 CSV 记录、日志行等。
⚝ 协议消息生成：按照协议规范生成消息报文。
⚝ 结构化数据输出：将结构化数据（例如，结构体、对象）转换为文本表示。
序列 Combinator 是构建复杂 Generator 的基础，通过它可以将简单的 Generator 组合成能够生成复杂输出的生成器。
3.4.2 选择 (Alternative)
Alternative (选择) Combinator 用于从多个 Generator 中选择一个执行 (Choice Among Generators)。它提供多个 Generator 候选项，并根据一定的规则选择其中一个执行。选择 Combinator 使用操作符 | 表示。
① 选择 Combinator 的语法
1
g1 | g2 | g3 ...
其中 g1, g2, g3 等都是 Generator。选择 Combinator 将尝试按照 g1, g2, g3 的顺序依次匹配，并执行第一个成功匹配的 Generator。
② 选择 Combinator 的属性处理
如果选择中的 Generator g1, g2, g3 都接受属性类型 A，那么组合后的选择 Generator 也接受属性类型 A。当生成时，属性会传递给被选中的 Generator。
如果选择中的 Generator 接受的属性类型不同，需要使用 boost::variant 或其他类型转换机制来统一属性类型。
③ 选择 Combinator 的示例
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
#include <boost/variant.hpp>
5
6
namespace karma = boost::spirit::karma;
7
namespace variant = boost::variant;
8
9
int main() {
10
std::string generated_string;
11
variant::variant<int, std::string> data = 123; // 可以是整数或字符串
12
13
// 使用选择 Combinator 选择生成整数或字符串
14
auto alternative_generator = karma::int_ | karma::string;
15
16
karma::generate(std::back_inserter(generated_string), alternative_generator, data);
17
std::cout << "Generated string using alternative (int): " << generated_string << std::endl;
18
// 输出: Generated string using alternative (int): 123
19
20
generated_string.clear();
21
data = "Hello";
22
karma::generate(std::back_inserter(generated_string), alternative_generator, data);
23
std::cout << "Generated string using alternative (string): " << generated_string << std::endl;
24
// 输出: Generated string using alternative (string): Hello
25
26
return 0;
27
}
在这个例子中，karma::int_ | karma::string 创建了一个选择 Generator。它根据输入的属性类型选择执行 karma::int_ 或 karma::string。输入的属性是一个 boost::variant，它可以存储整数或字符串。
④ 选择 Combinator 的应用场景
⚝ 多格式输出：根据不同的条件或数据类型，生成不同的输出格式。
⚝ 协议版本兼容：根据协议版本选择不同的消息生成方式。
⚝ 错误处理：在生成过程中遇到错误时，可以选择生成错误提示信息。
选择 Combinator 提供了灵活的条件生成能力，使得 Generator 可以根据不同的输入或状态生成不同的输出。
3.4.3 重复 (Repetition)
Repetition (重复) Combinator 用于重复执行某个 Generator (Repeated Execution of a Generator)。它可以指定 Generator 重复执行的次数范围，例如固定次数、零次或多次、一次或多次等。Karma 提供了多种重复 Combinator，常用的包括：
⚝ *g (zero_or_more)：重复零次或多次 g。
⚝ +g (one_or_more)：重复一次或多次 g。
⚝ repeat[n][g] (repeat_exactly)：重复 g 恰好 n 次。
⚝ repeat[min, max][g] (repeat_range)：重复 g 至少 min 次，至多 max 次。
① 重复 Combinator 的语法
⚝ *g
⚝ +g
⚝ karma::repeat[n][g]
⚝ karma::repeat[min, max][g]
其中 g 是要重复执行的 Generator，n, min, max 是重复次数。
② 重复 Combinator 的属性处理
如果被重复的 Generator g 接受属性类型 A，那么重复 Combinator 接受的属性类型通常是 std::vector<A> 或其他容器类型。当生成时，容器中的每个元素会依次传递给 Generator g。
③ 重复 Combinator 的示例
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
#include <vector>
5
6
namespace karma = boost::spirit::karma;
7
8
int main() {
9
std::string generated_string;
10
std::vector<int> numbers = {1, 2, 3, 4, 5};
11
12
// 使用 * 组合器重复生成整数，用逗号分隔
13
auto repeat_generator = *karma::int_ % ", "; // % ", " 表示用 ", " 分隔重复元素
14
15
karma::generate(std::back_inserter(generated_string), repeat_generator, numbers);
16
std::cout << "Generated string using repeat (*): " << generated_string << std::endl;
17
// 输出: Generated string using repeat (*): 1, 2, 3, 4, 5
18
19
generated_string.clear();
20
// 使用 repeat[3] 组合器重复生成整数 3 次
21
auto repeat_exactly_generator = karma::repeat[3][karma::int_];
22
std::vector<int> three_numbers = {10, 20, 30};
23
karma::generate(std::back_inserter(generated_string), repeat_exactly_generator, three_numbers);
24
std::cout << "Generated string using repeat[3]: " << generated_string << std::endl;
25
// 输出: Generated string using repeat[3]: 102030
26
27
return 0;
28
}
在这个例子中，*karma::int_ % ", " 创建了一个重复 Generator，它重复生成整数，并使用 ", " 分隔生成的整数。karma::repeat[3][karma::int_] 创建了一个重复 3 次的 Generator。
④ 重复 Combinator 的应用场景
⚝ 列表生成：生成列表、数组等重复结构的数据。
⚝ 循环数据输出：循环输出一组数据，例如表格数据、序列数据等。
⚝ 动态长度数据生成：生成长度不固定的数据，例如变长数组、动态列表等。
重复 Combinator 提供了强大的循环生成能力，可以方便地处理重复模式的数据生成任务。
3.4.4 可选 (Optional)
Optional (可选) Combinator 用于可选地执行某个 Generator (Optional Execution of a Generator)。它可以使某个 Generator 在生成过程中变为可选的，即可以生成也可以不生成。可选 Combinator 使用操作符 - 前缀表示。
① 可选 Combinator 的语法
1
-g
其中 g 是可选的 Generator。
② 可选 Combinator 的属性处理
如果可选的 Generator g 接受属性类型 A，那么可选 Combinator 接受的属性类型可以是 boost::optional<A> 或 boost::optional<boost::reference_wrapper<A>>。当生成时，如果 boost::optional 包含值，则将值传递给 g 并生成；如果 boost::optional 不包含值，则不生成任何输出。
③ 可选 Combinator 的示例
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
#include <boost/optional.hpp>
5
6
namespace karma = boost::spirit::karma;
7
namespace optional = boost::optional;
8
9
int main() {
10
std::string generated_string;
11
optional::optional<int> optional_number = 123; // 包含值
12
13
// 使用 - 组合器使整数生成器变为可选
14
auto optional_generator = -karma::int_;
15
16
karma::generate(std::back_inserter(generated_string), optional_generator, optional_number);
17
std::cout << "Generated string using optional (present): " << generated_string << std::endl;
18
// 输出: Generated string using optional (present): 123
19
20
generated_string.clear();
21
optional_number = optional::nullopt; // 不包含值
22
karma::generate(std::back_inserter(generated_string), optional_generator, optional_number);
23
std::cout << "Generated string using optional (absent): " << generated_string << std::endl;
24
// 输出: Generated string using optional (absent):
25
26
return 0;
27
}
在这个例子中，-karma::int_ 创建了一个可选 Generator。当输入的 boost::optional 包含值时，它生成整数；当 boost::optional 不包含值时，它不生成任何输出。
④ 可选 Combinator 的应用场景
⚝ 可选字段输出：生成包含可选字段的数据格式，例如 JSON、XML 中的可选属性。
⚝ 条件输出：根据条件决定是否生成某个部分，例如根据配置决定是否输出调试信息。
⚝ 默认值处理：当属性值不存在时，可以选择不生成输出，或者生成默认值。
可选 Combinator 提供了条件生成的灵活性，可以处理数据格式中可选部分的生成需求。
3.5 预定义的 Generator (预定义的 Generator, Predefined Generators)
Spirit.Karma 提供了丰富的 Predefined Generator (预定义生成器)，涵盖了常见的生成需求。这些预定义 Generator 可以直接使用，无需用户自定义，极大地简化了生成器的构建过程。预定义 Generator 主要分为以下几类：
① 字符与字符串生成器
⚝ karma::char_(c)：生成单个字符 c。
⚝ karma::string(s)：生成字符串 s。
⚝ karma::lit(s) 或 "s"：生成字符串字面量 s。
⚝ karma::raw[g]：将 Generator g 生成的输出作为原始字符序列处理，不进行任何格式化。
② 数值生成器
⚝ karma::int_：生成整数，默认十进制格式。
⚝ karma::long_long：生成长长整型。
⚝ karma::uint_：生成无符号整数。
⚝ karma::ulong_long：生成无符号长长整型。
⚝ karma::short_：生成短整型。
⚝ karma::ushort_：生成无符号短整型。
⚝ karma::byte_：生成字节。
⚝ karma::bool_：生成布尔值，输出 "true" 或 "false"。
⚝ karma::double_：生成双精度浮点数。
⚝ karma::float_：生成单精度浮点数。
⚝ karma::real_parser<>：更灵活的浮点数生成器，可以自定义格式。
⚝ karma::hex：以十六进制格式生成整数。
⚝ karma::oct：以八进制格式生成整数。
⚝ karma::bin：以二进制格式生成整数。
③ 时间与日期生成器
⚝ karma::iso_date：生成 ISO 8601 日期格式 (YYYY-MM-DD)。
⚝ karma::iso_time：生成 ISO 8601 时间格式 (HH:MM:SS)。
⚝ karma::iso_date_time：生成 ISO 8601 日期时间格式 (YYYY-MM-DDTHH:MM:SS)。
④ 其他常用生成器
⚝ karma::eol 或 karma::endl：生成换行符 (End of Line)。
⚝ karma::space：生成空格字符。
⚝ karma::blank：生成空白字符（空格、制表符等）。
⚝ karma::omit[g]：忽略 Generator g 的输出，但仍然执行 g。
⚝ karma::eps：空 Generator，不生成任何输出，总是成功匹配。
⚝ karma::fail：失败 Generator，总是生成失败。
⑤ 预定义 Generator 的使用示例
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::string generated_string;
9
10
// 使用预定义生成器生成各种数据类型
11
auto predefined_generators =
12
karma::string("Integer: ") << karma::int_ << karma::eol <<
13
karma::string("Double: ") << karma::double_ << karma::eol <<
14
karma::string("Boolean: ") << karma::bool_ << karma::eol <<
15
karma::string("Hex: ") << karma::hex << karma::int_ << karma::eol;
16
17
karma::generate(
18
std::back_inserter(generated_string),
19
predefined_generators,
20
boost::fusion::make_tuple(123, 3.14, true, 255) // 属性 tuple
21
);
22
23
std::cout << "Generated string using predefined generators:\n" << generated_string << std::endl;
24
// 输出:
25
// Generated string using predefined generators:
26
// Integer: 123
27
// Double: 3.14
28
// Boolean: true
29
// Hex: ff
30
31
return 0;
32
}
这个例子展示了如何使用一些常用的预定义 Generator，例如 karma::string, karma::int_, karma::double_, karma::bool_, karma::hex, karma::eol。通过组合这些预定义 Generator，可以快速构建出满足各种基本生成需求的生成器。
⑥ 自定义格式化
许多预定义 Generator 允许进行格式化控制。例如，karma::int_ 可以通过 karma::width, karma::left, karma::right, karma::center, karma::fill 等修饰符来控制输出宽度、对齐方式、填充字符等。浮点数生成器 karma::double_ 和 karma::float_ 可以使用 karma::precision 修饰符来控制输出精度。
1
#include <boost/spirit/karma.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::string generated_string;
9
int number = 123;
10
double pi = 3.1415926;
11
12
// 使用格式化修饰符
13
auto formatted_generators =
14
karma::string("Integer (width=10, fill='0', right): ") << karma::right << karma::fill('0') << karma::width(10) << karma::int_ << karma::eol <<
15
karma::string("Double (precision=2): ") << karma::precision(2) << karma::double_ << karma::eol;
16
17
karma::generate(
18
std::back_inserter(generated_string),
19
formatted_generators,
20
boost::fusion::make_tuple(number, pi)
21
);
22
23
std::cout << "Generated string with formatting:\n" << generated_string << std::endl;
24
// 输出:
25
// Generated string with formatting:
26
// Integer (width=10, fill='0', right): 0000000123
27
// Double (precision=2): 3.14
28
29
return 0;
30
}
预定义的 Generator 极大地简化了 Spirit.Karma 的使用，它们覆盖了常见的生成需求，并且提供了丰富的格式化选项。在实际应用中，我们通常可以直接使用预定义 Generator 或基于它们进行组合，而无需从零开始自定义 Generator。
END_OF_CHAPTER
4. chapter 4： 属性处理与转换 (属性处理与转换, Attribute Handling and Transformation)
4.1 属性语法 (属性语法, Attribute Grammar)
属性语法（Attribute Grammar）是在形式语言的上下文中，为文法符号附加属性的一种扩展。在 Boost.Spirit 中，属性语法是其核心概念之一，它允许我们在解析和生成过程中，将数据（属性）与文法规则关联起来，从而实现数据的提取、转换和生成。
在传统的上下文无关文法（Context-Free Grammar, CFG）中，文法规则主要关注语法的结构，即如何识别和构造合法的语句。而属性语法则更进一步，它不仅关注语法结构，还关注与语法结构相关联的语义信息。这些语义信息就通过“属性”来表示。
在 Boost.Spirit 中，每个 Parser（解析器）和 Generator（生成器）都可以拥有一个关联的属性类型。当解析器成功解析输入或生成器成功生成输出时，它会产生一个相应类型的属性值。这个属性值可以被后续的解析器或生成器使用，也可以通过语义动作进行处理。
属性语法的核心思想：
① 属性关联：将属性与文法规则（在 Spirit 中体现为 Parser 和 Generator）关联起来。每个规则可以有一个输入属性和一个输出属性。
② 属性传递：在解析或生成过程中，属性值可以在不同的文法规则之间传递。例如，一个复合规则的属性可能是其子规则属性的组合。
③ 语义动作：通过语义动作，我们可以在解析或生成的过程中对属性值进行操作，例如类型转换、数据计算、存储等。
Boost.Spirit 中的属性语法体现：
⚝ Parser 的属性：Spirit.Qi 的 Parser 在成功解析输入后，会产生一个属性值，该值类型由 Parser 的定义决定。例如，qi::int_ 解析器解析一个整数，其属性类型就是 int。
⚝ Generator 的属性：Spirit.Karma 的 Generator 接受一个属性值作为输入，并根据该值生成相应的输出。例如，karma::int_ 生成器接受一个 int 值，并将其格式化为字符串输出。
⚝ Rule 的属性：Rule（规则）是 Parser 和 Generator 的组合，它也可以拥有属性。Rule 的属性类型通常由其内部的 Parser 或 Generator 以及组合方式决定。
简单的例子：
假设我们要解析一个简单的加法表达式，例如 "1 + 2"。我们可以定义如下的 Spirit.Qi 解析器：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
6
int main() {
7
std::string input = "1 + 2";
8
int result;
9
10
bool success = qi::parse(input.begin(), input.end(),
11
qi::int_ >> '+' >> qi::int_,
12
result);
13
14
if (success) {
15
std::cout << "解析成功，结果: " << result << std::endl;
16
} else {
17
std::cout << "解析失败" << std::endl;
18
}
19
20
return 0;
21
}
在这个例子中，qi::int_ >> '+' >> qi::int_ 构成了一个序列解析器。但是这个例子并没有正确计算加法，因为我们没有使用语义动作来处理解析得到的整数。为了演示属性的概念，我们先关注属性的传递。
实际上，上述代码无法编译通过，因为 qi::int_ >> '+' >> qi::int_ 这个组合解析器的默认属性类型并不是 int，而是 tuple<int, char, int>。如果我们想要得到一个 int 类型的属性，我们需要使用语义动作或者调整解析器的组合方式。
正确的属性使用示例 (展示属性传递，但仍未计算加法):
为了更清晰地展示属性的传递，我们可以修改上面的例子，让解析器将解析到的两个整数作为属性返回。
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
#include <tuple>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "1 + 2";
9
std::tuple<int, char, int> result; // 使用 tuple 接收属性
10
11
bool success = qi::parse(input.begin(), input.end(),
12
qi::int_ >> '+' >> qi::int_,
13
result);
14
15
if (success) {
16
std::cout << "解析成功，属性: "
17
<< std::get<0>(result) << " "
18
<< std::get<1>(result) << " "
19
<< std::get<2>(result) << std::endl;
20
} else {
21
std::cout << "解析失败" << std::endl;
22
}
23
24
return 0;
25
}
在这个修改后的例子中，我们使用 std::tuple<int, char, int> 来接收解析器的属性。qi::int_ 解析器的属性类型是 int，'+' 解析器（实际上是 qi::lit('+') 的简写）的属性类型是 char。序列组合 >> 会将子解析器的属性组合成一个 tuple。
这个例子展示了属性语法的基本概念：解析器产生属性，组合解析器将属性组合起来。在后续的章节中，我们将深入学习如何使用语义动作来处理和转换这些属性，最终实现我们想要的计算功能。
4.2 属性类型推导 (属性类型推导, Attribute Type Deduction)
Boost.Spirit 强大的特性之一是其属性类型推导（Attribute Type Deduction）机制。这意味着我们通常不需要显式地指定 Parser 和 Generator 的属性类型，Spirit 能够根据文法规则自动推导出正确的属性类型。这大大简化了文法规则的编写，并提高了代码的可读性和可维护性。
属性类型推导的原理：
Spirit 的属性类型推导基于 C++ 的模板元编程（Template Metaprogramming, TMP）技术。它利用 SFINAE (Substitution Failure Is Not An Error) 和类型 traits 等机制，在编译期分析文法规则的结构，并根据预定义的规则推导出每个 Parser 和 Generator 的属性类型。
属性类型推导的基本规则：
① 基本 Parser/Generator 的属性类型：
▮▮▮▮⚝ 预定义的 Parser 和 Generator (如 qi::int_, qi::double_, karma::string_ 等) 都有预先定义的属性类型。例如，qi::int_ 的属性类型是 int，karma::double_ 的属性类型是 double。
▮▮▮▮⚝ Literal Parser (如 qi::lit('x'), karma::lit("hello")) 的属性类型通常是 unused_type，表示没有属性值产生或消耗。
② 组合 Parser/Generator 的属性类型：
▮▮▮▮⚝ 序列 (Sequence) >>: 序列组合符 >> 将其左右操作数的属性类型组合成一个 std::tuple 或 boost::fusion::tuple。如果操作数没有属性（unused_type），则在 tuple 中会被忽略。
▮▮▮▮⚝ 选择 (Alternative) |: 选择组合符 | 将其左右操作数的属性类型合并成一个 boost::variant。variant 可以存储多种类型的值，具体存储哪种类型取决于实际匹配到的分支。如果操作数属性类型相同，则 variant 的类型就是该类型本身，而不是 variant。
▮▮▮▮⚝ 可选 (Optional) maybe[] 或 -: 可选组合符 maybe[] 或 - 将其操作数的属性类型包装成 boost::optional。如果操作成功，optional 包含属性值；如果操作失败（可选部分未匹配），optional 为空。
▮▮▮▮⚝ 重复 (Repetition) *[], +[], {n}[], {n, m}[]: 重复组合符将其操作数的属性类型组合成一个容器，如 std::vector。例如，qi::int_ * qi::int_ 的属性类型是 std::vector<int>。
③ Rule 的属性类型：
▮▮▮▮⚝ Rule 的属性类型由其定义的 Parser 或 Generator 决定。Rule 可以显式声明属性类型，也可以让 Spirit 自动推导。
属性类型推导的示例：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/karma.hpp>
3
#include <iostream>
4
#include <tuple>
5
#include <vector>
6
#include <optional>
7
#include <boost/variant.hpp>
8
9
namespace qi = boost::spirit::qi;
10
namespace karma = boost::spirit::karma;
11
12
int main() {
13
// Qi 属性类型推导示例
14
{
15
std::string input = "123,456,789";
16
std::tuple<int, char, int, char, int> result_tuple;
17
std::vector<int> result_vector;
18
boost::variant<int, double> result_variant;
19
std::optional<int> result_optional;
20
21
// 序列: tuple<int, char, int, char, int>
22
qi::parse(input.begin(), input.end(),
23
qi::int_ >> ',' >> qi::int_ >> ',' >> qi::int_,
24
result_tuple);
25
std::cout << "Tuple Attribute: "
26
<< std::get<0>(result_tuple) << ", "
27
<< std::get<1>(result_tuple) << ", "
28
<< std::get<2>(result_tuple) << ", "
29
<< std::get<3>(result_tuple) << ", "
30
<< std::get<4>(result_tuple) << std::endl;
31
32
33
// 重复: vector<int>
34
qi::parse(input.begin(), input.end(),
35
qi::int_ % ',', // 使用 % 分隔符重复
36
result_vector);
37
std::cout << "Vector Attribute: ";
38
for (int val : result_vector) {
39
std::cout << val << " ";
40
}
41
std::cout << std::endl;
42
43
// 选择: variant<int, double>
44
qi::parse("123", qi::ascii::string::iterator_type(),
45
qi::int_ | qi::double_,
46
result_variant);
47
if (boost::get<int>(&result_variant)) {
48
std::cout << "Variant Attribute (int): " << boost::get<int>(result_variant) << std::endl;
49
} else if (boost::get<double>(&result_variant)) {
50
std::cout << "Variant Attribute (double): " << boost::get<double>(result_variant) << std::endl;
51
}
52
53
// 可选: optional<int>
54
qi::parse("123", qi::ascii::string::iterator_type(),
55
-qi::int_, // 可选的 int
56
result_optional);
57
if (result_optional) {
58
std::cout << "Optional Attribute: " << *result_optional << std::endl;
59
} else {
60
std::cout << "Optional Attribute: empty" << std::endl;
61
}
62
}
63
64
// Karma 属性类型推导示例
65
{
66
std::string generated_str;
67
std::tuple<int, char, int> data_tuple = std::make_tuple(1, '+', 2);
68
std::vector<int> data_vector = {1, 2, 3, 4, 5};
69
boost::variant<int, double> data_variant = 3.14;
70
std::optional<int> data_optional = 100;
71
72
// 序列: tuple<int, char, int>
73
karma::generate(std::back_inserter(generated_str),
74
karma::int_ << ' ' << karma::char_ << ' ' << karma::int_,
75
data_tuple);
76
std::cout << "Generated from Tuple: " << generated_str << std::endl;
77
generated_str.clear();
78
79
// 重复: vector<int>
80
karma::generate(std::back_inserter(generated_str),
81
karma::int_ % ", ", // 使用 % 分隔符重复
82
data_vector);
83
std::cout << "Generated from Vector: " << generated_str << std::endl;
84
generated_str.clear();
85
86
// 选择: variant<int, double>
87
karma::generate(std::back_inserter(generated_str),
88
karma::int_ | karma::double_,
89
data_variant);
90
std::cout << "Generated from Variant: " << generated_str << std::endl;
91
generated_str.clear();
92
93
// 可选: optional<int>
94
karma::generate(std::back_inserter(generated_str),
95
-karma::int_, // 可选的 int
96
data_optional);
97
std::cout << "Generated from Optional: " << generated_str << std::endl;
98
generated_str.clear();
99
}
100
101
return 0;
102
}
这个例子展示了 Spirit.Qi 和 Spirit.Karma 中属性类型推导的常见情况。通过理解这些规则，我们可以更好地利用 Spirit 的属性系统，编写简洁高效的解析器和生成器。
属性类型推导的优势：
⚝ 简化代码：无需手动指定复杂的属性类型，减少了代码的冗余。
⚝ 提高效率：编译期类型推导，避免了运行时的类型检查和转换开销。
⚝ 增强灵活性：更容易组合和修改文法规则，属性类型会自动适应变化。
需要注意的点：
⚝ 类型不匹配：虽然 Spirit 能够自动推导属性类型，但如果语义动作或后续处理代码期望的类型与推导出的类型不匹配，仍然会导致编译错误或运行时错误。
⚝ 歧义性：在某些复杂的文法规则中，属性类型推导可能会产生歧义。这时需要显式地指定属性类型或调整文法规则来消除歧义。
在后续章节中，我们将继续深入探讨属性类型推导在实际应用中的使用技巧和注意事项。
4.3 使用 Boost.Fusion 处理复合属性 (使用 Boost.Fusion 处理复合属性, Handling Composite Attributes with Boost.Fusion)
当我们需要处理复合属性（Composite Attributes），例如结构体、类或者需要将多个属性组合在一起时，Boost.Fusion 库就显得尤为重要。Boost.Fusion 是一个 C++ 库，用于处理异构集合（Heterogeneous Collections），例如 tuples, pairs, structs 等。它提供了一系列算法和数据结构，可以方便地操作这些复合数据类型。
Boost.Fusion 的核心概念：
⚝ 序列（Sequences）：Fusion 的核心概念是序列，它代表一个有序的元素集合。Fusion 提供了多种序列类型，包括：
▮▮▮▮⚝ boost::fusion::tuple：类似于 std::tuple，用于存储固定大小的异构元素序列。
▮▮▮▮⚝ boost::fusion::vector：类似于 std::vector，但可以存储异构元素序列。
▮▮▮▮⚝ boost::fusion::list：类似于 std::list，用于存储异构元素序列。
▮▮▮▮⚝ boost::fusion::struct_：用于将结构体或类的成员变量视为序列。
⚝ 算法（Algorithms）：Fusion 提供了丰富的算法，用于操作序列，例如：
▮▮▮▮⚝ boost::fusion::at_c<N>(seq)：访问序列 seq 中索引为 N 的元素。
▮▮▮▮⚝ boost::fusion::get<T>(seq)：访问序列 seq 中类型为 T 的元素（如果类型唯一）。
▮▮▮▮⚝ boost::fusion::for_each(seq, func)：对序列 seq 中的每个元素执行函数 func。
▮▮▮▮⚝ boost::fusion::transform(seq, func)：将函数 func 应用于序列 seq 的每个元素，并返回一个新的序列。
Spirit 与 Boost.Fusion 的集成：
Boost.Spirit 深度集成了 Boost.Fusion，使得 Spirit 可以方便地处理复合属性。当 Spirit 的解析器或生成器产生或接受复合属性时，通常会使用 Fusion 序列来表示。
使用 Fusion 处理复合属性的场景：
① 解析结构化数据：例如，解析 CSV 文件、配置文件等，每一行或每个配置项可能包含多个字段，需要将这些字段解析到一个结构体或 tuple 中。
② 生成结构化输出：例如，生成 XML、JSON 等格式的数据，需要从结构体或 tuple 中提取数据并格式化输出。
③ 语义动作中的复杂数据操作：在语义动作中，可能需要对多个属性值进行组合、转换或计算，Fusion 提供了方便的工具来处理这些复合数据。
示例：使用 Fusion 解析结构体
假设我们有一个表示点的结构体：
1
struct Point {
2
int x;
3
int y;
4
};
我们想要解析形如 (10,20) 的点坐标字符串，并将其存储到 Point 结构体中。我们可以使用 Boost.Spirit 和 Boost.Fusion 来实现：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/fusion.hpp> // 包含 Fusion 支持
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
namespace fusion = boost::fusion;
7
8
struct Point {
9
int x;
10
int y;
11
12
friend std::ostream& operator<<(std::ostream& os, const Point& p) {
13
os << "(" << p.x << ", " << p.y << ")";
14
return os;
15
}
16
};
17
18
BOOST_FUSION_ADAPT_STRUCT(Point, // 使用 BOOST_FUSION_ADAPT_STRUCT 宏
19
(int, x)
20
(int, y))
21
22
int main() {
23
std::string input = "(10,20)";
24
Point p;
25
26
bool success = qi::parse(input.begin(), input.end(),
27
'(' >> qi::int_ >> ',' >> qi::int_ >> ')',
28
p); // 直接解析到 Point 结构体
29
30
if (success) {
31
std::cout << "解析成功，Point: " << p << std::endl;
32
} else {
33
std::cout << "解析失败" << std::endl;
34
}
35
36
return 0;
37
}
代码解析：
⚝ #include <boost/spirit/include/fusion.hpp>: 引入 Fusion 头文件，启用 Spirit 的 Fusion 支持。
⚝ BOOST_FUSION_ADAPT_STRUCT 宏: 这个宏用于将 Point 结构体适配为 Fusion 序列。它告诉 Fusion 如何将 Point 的成员变量 x 和 y 视为一个序列。
⚝ qi::parse(..., '(' >> qi::int_ >> ',' >> qi::int_ >> ')', p): 解析器 '(' >> qi::int_ >> ',' >> qi::int_ >> ')' 的属性类型会被推导为 boost::fusion::tuple<int, int>。由于我们使用了 BOOST_FUSION_ADAPT_STRUCT 将 Point 适配为 Fusion 序列，Spirit 可以自动将解析得到的 tuple<int, int> 的值赋值给 Point 结构体的成员变量。
使用 Fusion Tuple 显式处理复合属性：
我们也可以不使用 BOOST_FUSION_ADAPT_STRUCT，而是显式地使用 fusion::tuple 来接收解析结果，并在语义动作中手动赋值给 Point 结构体。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/fusion.hpp>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
namespace fusion = boost::fusion;
7
8
struct Point {
9
int x;
10
int y;
11
12
friend std::ostream& operator<<(std::ostream& os, const Point& p) {
13
os << "(" << p.x << ", " << p.y << ")";
14
return os;
15
}
16
};
17
18
19
int main() {
20
std::string input = "(10,20)";
21
Point p;
22
fusion::tuple<int, int> point_tuple; // 使用 fusion::tuple 接收属性
23
24
bool success = qi::parse(input.begin(), input.end(),
25
'(' >> qi::int_ >> ',' >> qi::int_ >> ')',
26
point_tuple);
27
28
if (success) {
29
p.x = fusion::at_c<0>(point_tuple); // 使用 fusion::at_c 访问 tuple 元素
30
p.y = fusion::at_c<1>(point_tuple);
31
std::cout << "解析成功，Point: " << p << std::endl;
32
} else {
33
std::cout << "解析失败" << std::endl;
34
}
35
36
return 0;
37
}
这个例子中，我们首先将解析结果存储到 fusion::tuple<int, int> 中，然后使用 fusion::at_c<0> 和 fusion::at_c<1> 访问 tuple 的元素，并手动赋值给 Point 结构体的成员变量。
Fusion 的优势：
⚝ 类型安全：Fusion 序列是类型安全的，编译期会检查类型匹配。
⚝ 高效：Fusion 算法通常是高效的，基于模板元编程实现，避免了运行时的类型转换和虚函数调用开销。
⚝ 易于使用：Fusion 提供了简洁的 API，易于学习和使用。
⚝ 与 Spirit 深度集成：Spirit 能够无缝地与 Fusion 序列协同工作，方便处理复合属性。
在处理复杂的结构化数据时，Boost.Fusion 是 Boost.Spirit 的强大助手，能够极大地简化代码并提高效率。
4.4 属性转换与自定义属性 (属性转换与自定义属性, Attribute Transformation and Custom Attributes)
在实际应用中，我们经常需要对属性进行转换（Transformation）。例如，将字符串转换为数字、将日期字符串解析为日期对象、或者对解析得到的多个属性进行组合计算等。此外，有时预定义的属性类型可能无法满足需求，我们需要自定义属性类型（Custom Attributes）。
属性转换的场景：
① 类型转换：例如，qi::int_ 解析器返回的是 int 类型的属性，但我们可能需要将其转换为 long long 类型，或者从字符串形式的数字转换为数值类型。
② 数据格式转换：例如，解析日期字符串 "YYYY-MM-DD" 并将其转换为日期对象，或者将解析得到的多个字符串组合成一个完整的字符串。
③ 数据计算与处理：例如，解析数学表达式，需要对解析得到的数字和运算符进行计算，得到最终的结果。
属性转换的方法：
① 语义动作（Semantic Actions）: 最常用的属性转换方法是使用语义动作。我们可以在文法规则中嵌入语义动作，在解析或生成过程中对属性进行操作。语义动作可以使用 Lambda 表达式、Boost.Phoenix 或者普通的 C++ 函数对象来实现。
② 属性转换器（Attribute Converters）: Spirit 提供了一些预定义的属性转换器，例如 qi::as<T>()，可以将解析器的属性类型转换为指定的类型 T。
③ 自定义 Parser/Generator: 对于复杂的属性转换逻辑，我们可以自定义 Parser 或 Generator 组件，在组件内部实现属性转换。
使用语义动作进行属性转换的示例：
示例 1：类型转换 (字符串转数字)
假设我们想要解析一个表示十六进制数字的字符串，并将其转换为十进制整数。
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
namespace ascii = boost::spirit::ascii;
6
7
int main() {
8
std::string input = "0xAF";
9
int decimal_value;
10
11
bool success = qi::parse(input.begin(), input.end(),
12
"0x" >> qi::hex[_val = qi::_1], // 使用语义动作进行转换
13
decimal_value);
14
15
if (success) {
16
std::cout << "解析成功，十进制值: " << decimal_value << std::endl; // 输出 175 (0xAF 的十进制)
17
} else {
18
std::cout << "解析失败" << std::endl;
19
}
20
21
return 0;
22
}
代码解析：
⚝ qi::hex[_val = qi::_1]: qi::hex 解析器解析十六进制数字字符串，其属性类型是 unsigned int。[_val = qi::_1] 是一个语义动作，它使用 Lambda 表达式 [_val = qi::_1] 来进行属性转换。
▮▮▮▮⚝ qi::_1：占位符，表示 qi::hex 解析器的属性值（即解析得到的 unsigned int 值）。
▮▮▮▮⚝ _val：占位符，表示整个 qi::parse 函数的属性（即 decimal_value 变量）。
▮▮▮▮⚝ _val = qi::_1：将 qi::hex 解析器的属性值赋值给 decimal_value 变量，实现了类型转换。
示例 2：数据格式转换 (字符串拼接)
假设我们要解析 "姓名: 张三, 年龄: 30" 这样的字符串，并将其转换为 "张三 (30岁)" 的格式。
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace qi = boost::spirit::qi;
6
namespace ascii = boost::spirit::ascii;
7
8
int main() {
9
std::string input = "姓名: 张三, 年龄: 30";
10
std::string formatted_string;
11
12
bool success = qi::parse(input.begin(), input.end(),
13
"姓名: " >> qi::lexeme[+ascii::char_ - ','][_a = qi::_1] >> ", 年龄: " >> qi::int_[_val = _a + " (" + qi::_1 + "岁)"],
14
formatted_string);
15
16
if (success) {
17
std::cout << "解析成功，格式化字符串: " << formatted_string << std::endl; // 输出 "张三 (30岁)"
18
} else {
19
std::cout << "解析失败" << std::endl;
20
}
21
22
return 0;
23
}
代码解析：
⚝ qi::lexeme[+ascii::char_ - ','][_a = qi::_1]:
▮▮▮▮⚝ +ascii::char_ - ',': 解析一个或多个非逗号字符，即姓名部分。
▮▮▮▮⚝ qi::lexeme[]: qi::lexeme 组合器确保将匹配到的字符序列作为一个字符串属性返回。
▮▮▮▮⚝ [_a = qi::_1]: 将解析到的姓名字符串赋值给 Phoenix 占位符 _a，以便后续使用。
⚝ qi::int_[_val = _a + " (" + qi::_1 + "岁)"]:
▮▮▮▮⚝ qi::int_: 解析年龄，属性类型为 int。
▮▮▮▮⚝ [_val = _a + " (" + qi::_1 + "岁)"]: 将姓名 _a、年龄 qi::_1 和字符串字面量 " ("、"岁)" 拼接起来，赋值给 formatted_string (_val)。
自定义属性类型：
在某些情况下，预定义的属性类型可能无法满足需求。例如，我们需要处理复数、日期时间对象、或者自定义的数据结构。这时，我们可以自定义属性类型，并让 Spirit 能够识别和处理这些类型。
自定义属性类型通常需要：
① 定义自定义类型：例如，定义一个 Date 类或结构体。
② 提供属性转换规则：告诉 Spirit 如何将解析结果转换为自定义类型，以及如何将自定义类型转换为生成器的输出。这通常涉及到重载 Spirit 的 traits 类，例如 boost::spirit::traits::assign_to 和 boost::spirit::traits::extract_attribute 等。
③ 在语义动作中使用自定义类型：在语义动作中，可以直接使用自定义类型的对象进行操作。
自定义属性类型的示例 (简略概念性示例):
假设我们自定义了一个 Date 类，并希望解析 "YYYY-MM-DD" 格式的日期字符串，并将其转换为 Date 对象。
1
// 假设已经定义了 Date 类和相关的 traits 特化
2
class Date {
3
public:
4
int year;
5
int month;
6
int day;
7
// ...
8
};
9
10
// ... (省略 traits 特化代码) ...
11
12
#include <boost/spirit/include/qi.hpp>
13
#include <iostream>
14
15
namespace qi = boost::spirit::qi;
16
17
int main() {
18
std::string input = "2023-10-27";
19
Date date;
20
21
bool success = qi::parse(input.begin(), input.end(),
22
qi::int_ >> '-' >> qi::int_ >> '-' >> qi::int_[/* ... 语义动作将 int 转换为 Date 对象 ... */],
23
date);
24
25
if (success) {
26
std::cout << "解析成功，Date: " << date << std::endl; // 输出 Date 对象
27
} else {
28
std::cout << "解析失败" << std::endl;
29
}
30
31
return 0;
32
}
总结：
属性转换和自定义属性是 Boost.Spirit 高级应用的重要组成部分。通过灵活运用语义动作、属性转换器和自定义属性类型，我们可以构建功能强大、类型安全的解析器和生成器，处理各种复杂的数据格式和转换需求。在后续章节中，我们将结合实战案例，更深入地探讨属性转换和自定义属性的应用技巧。
END_OF_CHAPTER
5. chapter 5： 语义动作 (语义动作, Semantic Actions)
5.1 Lambda 表达式与语义动作 (Lambda Expressions and Semantic Actions)
语义动作（Semantic Actions）是 Boost.Spirit 库中至关重要的组成部分，它们允许我们在解析或生成过程中的特定时刻执行自定义的 C++ 代码。简单来说，当解析器（Parser）或生成器（Generator）成功匹配或生成了某个模式时，与其关联的语义动作就会被触发执行。语义动作赋予了 Spirit 强大的灵活性和功能，使得我们不仅仅能够验证输入数据的格式，还能在解析或生成的同时进行数据处理、转换、计算以及其他各种操作。
在 Boost.Spirit 中，语义动作通常与解析规则（Rule）或生成规则关联。当规则被成功应用时，语义动作就会被调用。语义动作本质上是一个可调用对象（Callable Object），例如函数、函数对象、Lambda 表达式等。
Lambda 表达式作为 C++11 引入的强大特性，因其简洁性和灵活性，成为了在 Boost.Spirit 中定义语义动作的首选方式。Lambda 表达式允许我们在代码中就地定义匿名函数，无需预先声明，这与语义动作需要紧凑、直接地嵌入到解析或生成规则中的需求完美契合。
Lambda 表达式作为语义动作的优势：
① 简洁性：Lambda 表达式语法简洁，可以快速定义简单的操作，减少代码冗余。
② 就地性：Lambda 表达式可以直接在规则定义的地方编写，增强代码的可读性和局部性。
③ 捕获上下文：Lambda 表达式可以捕获当前作用域的变量，方便在语义动作中访问和操作外部数据。
④ 灵活性：Lambda 表达式可以执行任何有效的 C++ 代码，提供了极高的灵活性。
Spirit.Qi 中 Lambda 语义动作示例：
假设我们需要解析一个整数，并在解析成功后将其打印到控制台。我们可以使用 qi::int_ 解析器和一个 Lambda 表达式作为语义动作来实现：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
6
int main() {
7
std::string input = "123";
8
int result;
9
10
bool success = qi::parse(input.begin(), input.end(),
11
qi::int_[ [&](int val) { std::cout << "解析到的整数: " << val << std::endl; result = val; } ],
12
qi::space); // 可选的跳过符
13
14
if (success) {
15
std::cout << "解析成功！结果: " << result << std::endl;
16
} else {
17
std::cout << "解析失败！" << std::endl;
18
}
19
20
return 0;
21
}
代码解释：
⚝ qi::int_ 是 Spirit.Qi 预定义的解析器，用于解析整数。
⚝ qi::int_[...] 方括号 [] 内的部分定义了语义动作。
⚝ [&](int val) { ... } 是一个 Lambda 表达式，[&] 表示按引用捕获外部作用域的所有变量（这里实际上没有捕获任何外部变量，[] 也可以），(int val) 定义了 Lambda 表达式的参数列表，int val 表示语义动作的输入属性类型为 int，这个 int 类型是由 qi::int_ 解析器提供的。{ ... } 内是 Lambda 表达式的函数体，即语义动作的具体代码。
⚝ std::cout << "解析到的整数: " << val << std::endl; result = val; 在 Lambda 表达式中，我们打印解析到的整数值 val，并将其赋值给外部变量 result。
⚝ qi::space 是一个跳过符（Skipper），用于忽略输入中的空白字符。
Spirit.Karma 中 Lambda 语义动作示例：
在 Spirit.Karma 中，语义动作同样可以与生成器（Generator）结合使用。例如，我们想要生成一个带有前缀 "Number: " 的整数字符串：
1
#include <boost/spirit/include/karma.hpp>
2
#include <iostream>
3
#include <sstream>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::stringstream ss;
9
int number = 456;
10
11
bool success = karma::generate(std::ostream_iterator<char>(ss),
12
karma::string("Number: ") << karma::int_ [ [&](int val) { std::cout << "正在生成整数: " << val << std::endl; } ],
13
number);
14
15
if (success) {
16
std::cout << "生成成功！结果: " << ss.str() << std::endl; // 输出: Number: 456
17
} else {
18
std::cout << "生成失败！" << std::endl;
19
}
20
21
return 0;
22
}
代码解释：
⚝ karma::string("Number: ") 生成字符串 "Number: "。
⚝ karma::int_ 生成整数。
⚝ karma::int_ [...] 方括号 [] 内定义了 Lambda 语义动作。
⚝ [&](int val) { std::cout << "正在生成整数: " << val << std::endl; } Lambda 表达式在整数生成之前被调用，我们可以在这里执行一些操作，例如打印日志。注意，虽然这里 Lambda 表达式接收了 int val 参数，但在 Karma 的上下文中，这个参数通常用于传递属性值，但在简单的生成场景中，我们可能不需要显式使用它，或者像本例中一样，仅用于日志输出。
⚝ number 是要生成的整数值，作为属性传递给 karma::int_ 生成器。
通过以上示例，我们可以看到 Lambda 表达式作为语义动作的简洁性和实用性。它们使得我们能够方便地在 Boost.Spirit 的解析和生成过程中嵌入自定义的逻辑，从而实现更复杂的功能。
5.2 使用 Boost.Phoenix (使用 Boost.Phoenix)
Boost.Phoenix 是一个强大的 C++ 库，它提供了用于函数式编程的工具，尤其擅长于创建延迟求值的表达式。在 Boost.Spirit 的上下文中，Boost.Phoenix 可以作为 Lambda 表达式的替代品，用于定义更为复杂和强大的语义动作。
Boost.Phoenix 的核心概念：
① Placeholders（占位符）：Phoenix 提供了占位符，如 phoenix::arg1, phoenix::arg2, ...，分别代表语义动作的第一个、第二个、... 属性参数。这使得我们可以像使用变量一样在语义动作表达式中引用属性值。
② Function Objects（函数对象）：Phoenix 允许我们直接使用 C++ 标准库中的函数对象（例如 std::cout, std::plus<> 等）以及自定义的函数对象。
③ Lazy Evaluation（延迟求值）：Phoenix 表达式是延迟求值的，只有在语义动作被触发时才会执行。这使得我们可以构建复杂的表达式，而无需担心过早的计算。
Boost.Phoenix 作为语义动作的优势：
① 更强大的表达式能力：Phoenix 提供了丰富的操作符重载和函数对象支持，可以构建比 Lambda 表达式更复杂的语义动作表达式。
② 可读性：对于某些复杂的语义动作，使用 Phoenix 可以使代码更具可读性，尤其是在涉及多个属性参数和嵌套操作时。
③ 与 Spirit 的深度集成：Boost.Phoenix 与 Boost.Spirit 紧密集成，可以无缝地在 Spirit 的规则中使用 Phoenix 表达式。
Spirit.Qi 中 Phoenix 语义动作示例：
我们继续使用解析整数并打印的例子，这次使用 Boost.Phoenix 实现：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/phoenix/phoenix.hpp>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
namespace phoenix = boost::phoenix;
7
8
int main() {
9
std::string input = "456";
10
int result;
11
12
bool success = qi::parse(input.begin(), input.end(),
13
qi::int_[ phoenix::ref(std::cout) << "解析到的整数: " << phoenix::arg1 << phoenix::ref(std::endl), phoenix::ref(result) = phoenix::arg1 ],
14
qi::space);
15
16
if (success) {
17
std::cout << "解析成功！结果: " << result << std::endl;
18
} else {
19
std::cout << "解析失败！" << std::endl;
20
}
21
22
return 0;
23
}
代码解释：
⚝ phoenix::ref(std::cout)：使用 phoenix::ref 包装 std::cout，使其可以在 Phoenix 表达式中延迟求值地使用。
⚝ phoenix::arg1：占位符 arg1 代表 qi::int_ 解析器传递的属性值，即解析到的整数。
⚝ phoenix::ref(std::endl)：同样使用 phoenix::ref 包装 std::endl。
⚝ phoenix::ref(result) = phoenix::arg1：将解析到的整数 arg1 赋值给外部变量 result，同样使用 phoenix::ref 包装 result。
⚝ 逗号 , 在 Phoenix 表达式中用于分隔多个操作，这些操作会依次执行。
Spirit.Karma 中 Phoenix 语义动作示例：
生成带有前缀 "Number: " 的整数字符串，使用 Phoenix 实现：
1
#include <boost/spirit/include/karma.hpp>
2
#include <boost/phoenix/phoenix.hpp>
3
#include <iostream>
4
#include <sstream>
5
6
namespace karma = boost::spirit::karma;
7
namespace phoenix = boost::phoenix;
8
9
int main() {
10
std::stringstream ss;
11
int number = 789;
12
13
bool success = karma::generate(std::ostream_iterator<char>(ss),
14
karma::string("Number: ") << karma::int_[ phoenix::ref(std::cout) << "正在生成整数: " << phoenix::arg1 << phoenix::ref(std::endl) ],
15
number);
16
17
if (success) {
18
std::cout << "生成成功！结果: " << ss.str() << std::endl; // 输出: Number: 789
19
} else {
20
std::cout << "生成失败！" << std::endl;
21
}
22
23
return 0;
24
}
代码解释：
⚝ Phoenix 的用法与 Qi 的例子类似，phoenix::arg1 在 Karma 的上下文中也代表属性值，即要生成的整数。
Lambda 表达式 vs. Boost.Phoenix：
⚝ 简单性 vs. 强大性：Lambda 表达式更简洁，适合简单的语义动作；Phoenix 更强大，适合复杂的语义动作和函数式编程风格。
⚝ 学习曲线：Lambda 表达式更容易学习和上手；Phoenix 的学习曲线稍陡峭，需要理解其占位符、函数对象和延迟求值等概念。
⚝ 性能：在简单的场景下，Lambda 表达式和 Phoenix 的性能差异可能不大；在复杂的场景下，Phoenix 的延迟求值特性可能会带来性能优势，但也可能引入额外的开销。
⚝ 可维护性：对于简单的语义动作，Lambda 表达式可能更易于维护；对于复杂的语义动作，Phoenix 的结构化表达式可能更易于维护和理解。
选择使用 Lambda 表达式还是 Boost.Phoenix 取决于具体的应用场景和个人偏好。对于简单的语义动作，Lambda 表达式通常足够且更简洁；对于复杂的语义动作，或者当需要利用函数式编程的强大功能时，Boost.Phoenix 可能是更好的选择。在实际开发中，可以根据项目的需求和团队的技能水平来权衡选择。
5.3 语义动作的返回值与属性传递 (Return Values and Attribute Propagation in Semantic Actions)
语义动作不仅可以执行一些操作，还可以返回值。语义动作的返回值在 Boost.Spirit 中扮演着重要的角色，它直接影响着属性（Attribute）的传递和规则的组合。理解语义动作的返回值和属性传递机制是深入掌握 Boost.Spirit 的关键。
语义动作的返回值：
语义动作本质上是一个可调用对象，它可以像普通函数一样返回值。在 Boost.Spirit 中，语义动作的返回值会被用来更新或转换与其关联的规则的属性。
属性传递（Attribute Propagation）：
在 Boost.Spirit 中，每个解析器和生成器都有一个关联的属性类型。当一个解析器或生成器成功匹配或生成时，它会产生一个属性值。这个属性值可以被传递给后续的语义动作或组合规则。属性传递是 Boost.Spirit 构建复杂解析和生成逻辑的基础。
语义动作如何影响属性传递：
① 默认属性传递：如果语义动作没有返回值（或者返回 void），则默认情况下，其关联的解析器或生成器的属性会直接传递下去。
② 返回值作为新属性：如果语义动作返回一个值，则这个返回值会成为新的属性，替换掉原来解析器或生成器的属性。这意味着语义动作可以用来转换属性的类型或值。
③ 属性类型推导：Boost.Spirit 具有强大的属性类型推导能力。它可以根据语义动作的返回值类型自动推导出组合规则的属性类型。
Spirit.Qi 中语义动作返回值与属性传递示例：
假设我们要解析两个整数，并将它们的和作为结果返回。我们可以使用语义动作来实现：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
6
int main() {
7
std::string input = "10 20";
8
int sum;
9
10
bool success = qi::parse(input.begin(), input.end(),
11
(qi::int_ >> qi::int_)[ [](int a, int b) { return a + b; } ] , // 语义动作返回 a+b
12
qi::space);
13
14
if (success) {
15
std::cout << "解析成功！和为: " << qi::attr_cast<int>(qi::get(_r1), qi::_val) << std::endl; // 获取语义动作的返回值
16
} else {
17
std::cout << "解析失败！" << std::endl;
18
}
19
20
return 0;
21
}
代码解释：
⚝ (qi::int_ >> qi::int_) 序列解析器，依次解析两个整数。
⚝ [ [](int a, int b) { return a + b; } ] Lambda 语义动作，接收两个整数属性 a 和 b（分别来自两个 qi::int_），并返回它们的和 a + b。
⚝ 语义动作的返回值 a + b 成为了整个序列解析器 (qi::int_ >> qi::int_) 的新属性。
⚝ qi::attr_cast<int>(qi::get(_r1), qi::_val) 这部分代码用于获取语义动作的返回值。在 Spirit.Qi 中，_r1 是一个占位符，用于访问规则的属性，qi::get(_r1) 获取属性值，qi::_val 表示要获取的值的类型，qi::attr_cast<int>(...) 将属性值转换为 int 类型。
Spirit.Karma 中语义动作返回值与属性传递示例：
在 Karma 中，语义动作的返回值也可以影响属性传递，但 Karma 的属性传递方向与 Qi 相反，是从外向内传递。在 Karma 中，语义动作通常用于在生成过程中进行一些辅助操作，返回值的使用场景相对较少，但仍然可以用于属性转换或控制生成流程。
1
#include <boost/spirit/include/karma.hpp>
2
#include <iostream>
3
#include <sstream>
4
5
namespace karma = boost::spirit::karma;
6
7
int main() {
8
std::stringstream ss;
9
int number = 123;
10
11
bool success = karma::generate(std::ostream_iterator<char>(ss),
12
karma::int_[ [](int val) { std::cout << "准备生成整数: " << val << std::endl; return val * 2; } ], // 语义动作返回 val * 2，但 Karma 中通常不直接使用返回值作为属性
13
number);
14
15
if (success) {
16
std::cout << "生成成功！结果: " << ss.str() << std::endl; // 输出: 123，注意这里仍然生成的是原始的 number，而不是语义动作的返回值
17
} else {
18
std::cout << "生成失败！" << std::endl;
19
}
20
21
return 0;
22
}
代码解释：
⚝ karma::int_[ [](int val) { ... return val * 2; } ] Lambda 语义动作，接收要生成的整数 val，并返回 val * 2。
⚝ 在 Karma 中，虽然语义动作返回了 val * 2，但这个返回值通常不会直接替换掉原始的属性 number。Karma 的属性传递主要是从外部属性向内部生成器传递，语义动作的返回值更多地用于辅助操作或控制生成流程，而不是直接改变最终生成的属性。
总结：
⚝ 在 Spirit.Qi 中，语义动作的返回值可以用来转换或替换解析器产生的属性，从而实现属性的传递和转换。
⚝ 在 Spirit.Karma 中，语义动作的返回值通常不直接用于属性传递，更多地用于辅助操作或控制生成流程。
⚝ 理解语义动作的返回值和属性传递机制对于构建复杂的 Boost.Spirit 解析器和生成器至关重要。通过合理地使用语义动作的返回值，我们可以灵活地控制属性的流动和转换，实现各种复杂的数据处理和生成逻辑。
5.4 副作用与纯语义动作 (副作用与纯语义动作, Side Effects and Pure Semantic Actions)
在编程中，函数可以根据其是否产生副作用来分类。同样，语义动作也可以分为带有副作用的语义动作和纯语义动作。理解这两种语义动作的区别以及它们在 Boost.Spirit 中的应用场景，有助于我们编写更健壮、可维护的代码。
副作用（Side Effects）：
一个操作或函数如果除了返回值之外，还修改了程序的状态（例如，修改了全局变量、执行了 I/O 操作、改变了输入参数等），那么就说它产生了副作用。
纯函数（Pure Function）/纯语义动作（Pure Semantic Action）：
一个函数或语义动作，如果对于相同的输入总是产生相同的输出，并且不产生任何副作用，那么就称之为纯函数或纯语义动作。
Boost.Spirit 中语义动作的副作用：
语义动作本质上是 C++ 代码，因此它可以执行任何 C++ 操作，包括产生副作用的操作。例如：
⚝ 修改外部变量：语义动作可以修改在 Lambda 表达式或 Phoenix 表达式中捕获的外部变量。
⚝ 执行 I/O 操作：语义动作可以使用 std::cout, std::cerr, 文件 I/O 等进行输入输出操作。
⚝ 抛出异常：语义动作可以抛出异常，用于错误处理或流程控制。
⚝ 调用其他带有副作用的函数：语义动作可以调用其他函数，如果这些函数带有副作用，那么语义动作也会间接地产生副作用。
纯语义动作的优势：
① 可测试性（Testability）：纯语义动作更容易进行单元测试，因为对于相同的输入，总是得到相同的输出，且不依赖于外部状态。
② 可预测性（Predictability）：纯语义动作的行为是可预测的，易于理解和调试。
③ 可组合性（Composability）：纯语义动作更容易组合成更复杂的逻辑，因为它们之间没有状态依赖和副作用干扰。
④ 并发安全性（Concurrency Safety）：在多线程环境下，纯语义动作通常更安全，因为它们不修改共享状态，减少了竞态条件和数据不一致的风险。
副作用语义动作的应用场景：
尽管纯语义动作有很多优点，但在某些场景下，副作用语义动作也是必要的或有用的：
① 日志记录（Logging）：在解析或生成过程中，可能需要记录一些信息，例如解析到的 token、生成的数据等，这时可以使用带有 I/O 副作用的语义动作。
② 状态管理（State Management）：在某些复杂的解析或生成任务中，可能需要在语义动作中维护一些状态信息，例如计数器、标志位等，这时需要使用带有修改状态副作用的语义动作。
③ 错误处理（Error Handling）：语义动作可以通过抛出异常来报告错误或中断解析/生成过程，这是一种副作用。
④ 性能优化（Performance Optimization）：在某些情况下，为了提高性能，可能会在语义动作中直接修改数据结构，而不是通过返回值传递，这可能涉及副作用。
最佳实践：
⚝ 尽可能使用纯语义动作：在设计 Boost.Spirit 规则时，应尽可能使用纯语义动作，以提高代码的可测试性、可维护性和可预测性。
⚝ 明确区分副作用：如果必须使用副作用语义动作，应明确注释或文档说明其副作用，以便于理解和维护。
⚝ 控制副作用范围：尽量将副作用限制在局部范围内，避免全局副作用，以减少代码的复杂性和潜在的错误。
⚝ 使用适当的工具：Boost.Spirit 和 Boost.Phoenix 提供了一些工具，例如 phoenix::ref，可以帮助我们在语义动作中安全地访问和修改外部状态。
示例：纯语义动作 vs. 副作用语义动作
纯语义动作示例（计算平方）：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
6
int main() {
7
std::string input = "5";
8
int square;
9
10
bool success = qi::parse(input.begin(), input.end(),
11
qi::int_[ [](int val) { return val * val; } ], // 纯语义动作，计算平方并返回
12
qi::space);
13
14
if (success) {
15
square = qi::attr_cast<int>(qi::get(_r1), qi::_val);
16
std::cout << "解析成功！平方为: " << square << std::endl;
17
} else {
18
std::cout << "解析失败！" << std::endl;
19
}
20
21
return 0;
22
}
副作用语义动作示例（打印日志）：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
6
int main() {
7
std::string input = "10";
8
int number;
9
10
bool success = qi::parse(input.begin(), input.end(),
11
qi::int_[ [&](int val) { std::cout << "解析到的数字是: " << val << std::endl; number = val; } ], // 副作用语义动作，打印日志并修改外部变量
12
qi::space);
13
14
if (success) {
15
std::cout << "解析成功！数字为: " << number << std::endl;
16
} else {
17
std::cout << "解析失败！" << std::endl;
18
}
19
20
return 0;
21
}
在第一个例子中，Lambda 表达式 [](int val) { return val * val; } 是一个纯语义动作，它只根据输入值计算平方并返回，没有产生任何副作用。在第二个例子中，Lambda 表达式 [&](int val) { std::cout << "解析到的数字是: " << val << std::endl; number = val; } 是一个带有副作用的语义动作，它不仅修改了外部变量 number，还执行了 I/O 操作（打印日志）。
在实际应用中，我们需要根据具体的需求权衡使用纯语义动作和副作用语义动作。对于核心的解析和生成逻辑，应尽量使用纯语义动作；对于辅助性的操作，例如日志记录、状态管理等，可以使用副作用语义动作，但需要谨慎管理其副作用，以确保代码的清晰性和可维护性。
END_OF_CHAPTER
6. chapter 6： 错误处理 (错误处理, Error Handling)
6.1 Spirit 的错误报告机制 (Spirit 的错误报告机制, Spirit's Error Reporting Mechanism)
错误处理是任何解析器库中至关重要的组成部分，Boost.Spirit 也不例外。一个健壮的解析器不仅需要能够成功解析有效的输入，更需要在遇到错误输入时提供清晰、有用的错误信息，甚至尝试从错误中恢复。Spirit 提供了灵活且可定制的错误处理机制，允许开发者根据应用需求选择合适的错误处理策略。
默认情况下，Spirit.Qi 在解析失败时会抛出异常 boost::spirit::qi::expectation_failure。这种默认行为对于快速原型开发和简单的应用场景可能足够，但在生产环境中，通常需要更精细的错误报告和处理机制。
Spirit 的错误报告机制主要围绕以下几个核心概念：
① 解析器失败 (Parser Failure)：当解析器无法匹配输入时，即发生解析失败。例如，当期望一个数字，但输入却是字母时，就会发生解析失败。
② 期望点 (Expectation Point)：Spirit.Qi 允许使用期望操作符 > 来标记解析过程中的关键点。如果期望操作符后面的解析器失败，Spirit 会抛出一个 expectation_failure 异常，指出在哪个期望点发生了错误。这为错误定位提供了更精确的信息。
③ 错误处理策略 (Error Handling Policy)：Spirit 提供了多种方式来定制错误处理行为，包括使用 on_error 指令、自定义错误处理函数等。这些机制允许开发者在解析失败时执行特定的操作，例如记录错误信息、尝试恢复解析、或者抛出自定义异常。
④ 错误信息 (Error Information)：当错误发生时，Spirit 能够提供丰富的错误信息，包括错误发生的位置（迭代器）、相关的规则信息、以及更详细的错误描述。这些信息对于调试解析器和向用户报告错误至关重要。
让我们通过一个简单的例子来了解 Spirit 的默认错误报告机制以及如何使用期望操作符 > 来改进错误信息：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "abc123def";
9
std::string result;
10
11
auto parser = qi::lexeme[+(qi::alpha) >> -(qi::int_)]; // 解析字母序列，可选的后跟一个整数
12
13
std::string::iterator begin = input.begin();
14
std::string::iterator end = input.end();
15
16
bool success = qi::parse(begin, end, parser, result);
17
18
if (success && begin == end) {
19
std::cout << "解析成功，结果: " << result << std::endl;
20
} else {
21
std::cout << "解析失败" << std::endl;
22
if (begin != end) {
23
std::cout << "剩余未解析部分: '" << std::string(begin, end) << "'" << std::endl;
24
}
25
}
26
27
return 0;
28
}
在这个例子中，我们尝试解析一个字母序列，后面可选地跟随一个整数。对于输入 "abc123def"，解析器会成功解析 "abc123"，但由于 "def" 不符合规则，解析会失败。默认情况下，qi::parse 返回 false，并且 begin 迭代器会指向未解析部分的起始位置。
现在，让我们引入期望操作符 > 来改进错误报告：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
#include <string>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "abc123def";
9
std::string result;
10
11
auto parser = qi::lexeme[+(qi::alpha) > -(qi::int_)]; // 使用期望操作符
12
13
std::string::iterator begin = input.begin();
14
std::string::iterator end = input.end();
15
16
try {
17
bool success = qi::parse(begin, end, parser, result);
18
19
if (success && begin == end) {
20
std::cout << "解析成功，结果: " << result << std::endl;
21
} else {
22
std::cout << "解析失败" << std::endl;
23
if (begin != end) {
24
std::cout << "剩余未解析部分: '" << std::string(begin, end) << "'" << std::endl;
25
}
26
}
27
} catch (const qi::expectation_failure<std::string::iterator>& e) {
28
std::cout << "期望失败异常捕获: " << e.what() << std::endl;
29
std::cout << "错误发生在输入位置: '" << std::string(e.first, input.end()) << "'" << std::endl;
30
}
31
32
return 0;
33
}
在这个修改后的例子中，我们在 +(qi::alpha) 和 -(qi::int_) 之间使用了期望操作符 >。如果 +(qi::alpha) 解析成功，但后面的 -(qi::int_) 解析失败，并且由于 > 的存在，Spirit 将会抛出一个 qi::expectation_failure 异常。我们使用 try-catch 块捕获了这个异常，并输出了异常信息。
运行这个修改后的程序，你会看到类似以下的输出：
1
期望失败异常捕获: expectation failed
2
错误发生在输入位置: '123def'
可以看到，使用期望操作符 > 后，当解析失败时，我们捕获到了 expectation_failure 异常，并且异常信息 e.what() 提示了 "expectation failed"。更重要的是，e.first 迭代器指向了错误发生的起始位置，这有助于我们定位错误。
总结来说，Spirit 的默认错误报告机制通过 expectation_failure 异常和期望操作符 > 提供了基本的错误定位能力。然而，对于更复杂的需求，例如自定义错误消息、错误恢复等，我们需要深入了解 Spirit 的自定义错误处理机制，这将在下一节中详细介绍。
6.2 自定义错误处理 (自定义错误处理, Custom Error Handling)
Spirit 强大的地方在于其高度的可定制性，错误处理也不例外。除了默认的错误报告机制，Spirit 允许开发者通过多种方式自定义错误处理行为，以满足各种复杂应用场景的需求。
最常用的自定义错误处理方式是使用 on_error 指令。on_error 指令允许我们在解析规则中注册一个错误处理函数（或函数对象），当该规则或其子规则发生解析错误时，这个错误处理函数会被调用。
on_error 指令的基本语法如下：
1
rule.on_error<ErrorAction>(error_handler);
其中：
⚝ rule 是你想要添加错误处理的 Spirit.Qi 规则。
⚝ ErrorAction 是一个占位符，通常使用 qi::fail，表示当错误发生时执行 error_handler。
⚝ error_handler 是一个可调用对象（函数、lambda 表达式、函数对象），它接受三个参数：
▮▮▮▮⚝ first：一个迭代器，指向错误发生的输入位置。
▮▮▮▮⚝ last：一个迭代器，指向输入结束位置。
▮▮▮▮⚝ error_info：一个 boost::spirit::qi::error_handler_tag 类型的对象，包含有关错误的额外信息（例如，与错误相关的规则）。
错误处理函数 error_handler 的返回值类型通常是 bool。返回 true 表示错误已被处理，解析过程可以继续（例如，尝试错误恢复）；返回 false 表示错误未被处理，解析过程应该终止（通常会抛出异常）。
让我们通过一个例子来演示如何使用 on_error 指令自定义错误处理：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/phoenix.hpp>
3
#include <iostream>
4
#include <string>
5
6
namespace qi = boost::spirit::qi;
7
namespace phx = boost::phoenix;
8
9
int main() {
10
std::string input = "abc!123def"; // 输入中包含非法字符 '!'
11
int result;
12
13
auto parser = qi::int_[phx::ref(result) = qi::_1]
14
.on_error<qi::fail>(
15
phx::bind([](auto first, auto last, auto error) {
16
std::cout << "自定义错误处理被调用!" << std::endl;
17
std::cout << "错误发生在位置: '" << std::string(first, last) << "'" << std::endl;
18
return true; // 返回 true 表示错误已被处理，尝试继续解析
19
}, qi::_1, qi::_2, qi::_3)
20
);
21
22
std::string::iterator begin = input.begin();
23
std::string::iterator end = input.end();
24
25
bool success = qi::parse(begin, end, parser);
26
27
if (success) {
28
std::cout << "解析成功，结果: " << result << std::endl;
29
} else {
30
std::cout << "解析失败 (主解析过程)" << std::endl;
31
}
32
33
return 0;
34
}
在这个例子中，我们尝试解析一个整数。我们使用了 on_error 指令为 qi::int_ 规则注册了一个 lambda 表达式作为错误处理函数。当输入 "abc!123def" 中的 "abc" 导致 qi::int_ 解析失败时，我们自定义的错误处理函数会被调用。
错误处理函数输出了错误信息，并返回 true。返回 true 的意义在于，它告诉 Spirit 错误已经被处理，解析过程可以尝试继续。在本例中，由于错误处理函数返回 true，qi::parse 函数本身仍然会返回 true (表示解析过程没有完全失败，虽然子规则 qi::int_ 失败了，但错误被处理了)。但是，由于 qi::int_ 解析失败，result 变量不会被赋值。
运行这个程序，你会看到类似以下的输出：
1
自定义错误处理被调用!
2
错误发生在位置: 'abc!123def'
3
解析成功 (主解析过程)
可以看到，当 qi::int_ 解析 "abc" 失败时，我们的自定义错误处理函数被成功调用，并输出了错误信息。由于错误处理函数返回 true，主解析过程 qi::parse 仍然返回 true。
访问错误信息
在错误处理函数中，我们可以访问到丰富的错误信息，包括：
⚝ first 和 last 迭代器：指示错误发生的输入范围。
⚝ error_info 对象（在 lambda 表达式中通过 qi::_3 访问）：虽然在当前的 Spirit 版本中，error_info 对象本身提供的额外信息有限，但在未来的版本中可能会扩展。
错误处理函数的返回值
错误处理函数的返回值至关重要：
⚝ 返回 true: 表示错误已被处理，解析器可以尝试继续解析。这通常用于实现错误恢复策略，例如跳过错误部分，尝试解析后续输入。
⚝ 返回 false: 表示错误未被处理，解析器应该终止当前规则的解析，并将错误向上传递。这通常会导致 qi::parse 返回 false，或者在使用了期望操作符 > 的情况下抛出 qi::expectation_failure 异常。
更复杂的错误处理
on_error 指令可以嵌套使用，为不同的规则设置不同的错误处理函数。你还可以使用 Boost.Phoenix 库来构建更复杂的错误处理逻辑，例如：
⚝ 记录错误日志到文件或数据库。
⚝ 根据错误类型执行不同的处理策略。
⚝ 修改解析器的状态，影响后续的解析行为。
自定义错误处理是 Spirit 的一个强大特性，它允许开发者根据具体需求定制解析器的错误行为，从而构建更加健壮和用户友好的解析应用。在实际应用中，合理地使用 on_error 指令可以显著提升解析器的错误处理能力和用户体验。
6.3 错误恢复策略 (错误恢复策略, Error Recovery Strategies)
仅仅报告错误位置和类型有时是不够的，一个优秀的解析器还应该具备一定的错误恢复能力。错误恢复策略指的是当解析过程中遇到错误时，解析器尝试从错误中恢复，并尽可能继续解析后续输入的能力。Spirit 提供了多种机制来实现错误恢复，主要包括以下几种策略：
① 跳过错误 (Skipping Errors)：这是最简单的错误恢复策略。当遇到错误时，解析器跳过错误部分，尝试从错误之后的位置继续解析。Spirit.Qi 提供了 qi::skip 指令以及 qi::eps (epsilon) 规则结合 qi::omit 指令来实现跳过错误。
② 重试解析 (Retrying Parsing)：在某些情况下，错误可能是由于输入的局部格式不正确造成的。我们可以尝试在错误发生的位置，使用不同的解析规则重新解析输入。Spirit 的选择操作符 | 可以用于实现重试解析。
③ 回溯 (Backtracking)：当解析器尝试匹配一个规则时，如果匹配失败，解析器可以回溯到之前的状态，尝试其他的解析路径。Spirit 默认支持回溯，但可以通过 qi::no_backtrack 指令禁用回溯以提高性能。
④ 同步点 (Synchronization Points)：在某些复杂的语法中，我们可以定义一些同步点。当解析错误发生时，解析器可以跳过输入直到下一个同步点，然后从同步点开始继续解析。这在解析结构化文本（如代码、配置文件）时非常有用。
让我们分别看一些例子来演示这些错误恢复策略。
跳过错误 (Skipping Errors)
假设我们要解析一个逗号分隔的整数列表，但输入中可能包含一些非数字字符，我们希望跳过这些非数字字符，只解析有效的整数。我们可以使用 qi::skip 指令结合自定义的 skipper 来实现：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/phoenix.hpp>
3
#include <iostream>
4
#include <string>
5
#include <vector>
6
7
namespace qi = boost::spirit::qi;
8
namespace phx = boost::phoenix;
9
10
// 自定义 skipper，跳过非数字和非逗号字符
11
template <typename Iterator>
12
struct error_skipper : qi::grammar<Iterator> {
13
error_skipper() : error_skipper::base_type(skip) {
14
skip = *(qi::char_ - qi::digit - ',');
15
}
16
qi::rule<Iterator> skip;
17
};
18
19
int main() {
20
std::string input = "123,abc,456,def,789"; // 输入中包含非法字符 "abc" 和 "def"
21
std::vector<int> results;
22
23
error_skipper<std::string::iterator> skipper;
24
auto parser = qi::int_ % ','; // 解析逗号分隔的整数列表
25
26
std::string::iterator begin = input.begin();
27
std::string::iterator end = input.end();
28
29
bool success = qi::phrase_parse(begin, end, parser, skipper, results); // 使用 phrase_parse 和自定义 skipper
30
31
if (success && begin == end) {
32
std::cout << "解析成功，结果: ";
33
for (int val : results) {
34
std::cout << val << " ";
35
}
36
std::cout << std::endl;
37
} else {
38
std::cout << "解析失败" << std::endl;
39
if (begin != end) {
40
std::cout << "剩余未解析部分: '" << std::string(begin, end) << "'" << std::endl;
41
}
42
}
43
44
return 0;
45
}
在这个例子中，我们定义了一个自定义的 error_skipper，它会跳过所有既不是数字也不是逗号的字符。我们使用 qi::phrase_parse 函数，并将 error_skipper 作为 skipper 传递给 phrase_parse。这样，当解析器遇到 "abc" 和 "def" 时，error_skipper 会跳过它们，解析器会继续尝试解析后续的整数。
运行这个程序，你会看到类似以下的输出：
1
解析成功，结果: 123 456 789
可以看到，尽管输入中包含了非数字字符，但解析器成功地跳过了它们，并解析出了有效的整数列表。
重试解析 (Retrying Parsing)
假设我们要解析一个日期，日期格式可能是 YYYY-MM-DD 或 MM/DD/YYYY。当第一种格式解析失败时，我们希望尝试第二种格式。我们可以使用选择操作符 | 来实现重试解析：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
#include <string>
4
#include <tuple>
5
6
namespace qi = boost::spirit::qi;
7
8
using Date = std::tuple<int, int, int>;
9
10
int main() {
11
std::string input1 = "2023-10-26"; // YYYY-MM-DD 格式
12
std::string input2 = "10/26/2023"; // MM/DD/YYYY 格式
13
std::string input3 = "invalid-date"; // 无效日期格式
14
Date date;
15
16
// 定义两种日期格式的解析器
17
auto date_format1 = qi::int_ >> '-' >> qi::int_ >> '-' >> qi::int_; // YYYY-MM-DD
18
auto date_format2 = qi::int_ >> '/' >> qi::int_ >> '/' >> qi::int_; // MM/DD/YYYY
19
20
// 使用选择操作符 | 尝试两种格式
21
auto date_parser = date_format1 | date_format2;
22
23
// 解析 input1
24
std::string::iterator begin1 = input1.begin();
25
std::string::iterator end1 = input1.end();
26
bool success1 = qi::parse(begin1, end1, date_parser, date);
27
if (success1 && begin1 == end1) {
28
std::cout << "解析成功 (格式1)，日期: " << std::get<0>(date) << "-" << std::get<1>(date) << "-" << std::get<2>(date) << std::endl;
29
} else {
30
std::cout << "解析失败 (格式1)" << std::endl;
31
}
32
33
// 解析 input2
34
std::string::iterator begin2 = input2.begin();
35
std::string::iterator end2 = input2.end();
36
bool success2 = qi::parse(begin2, end2, date_parser, date);
37
if (success2 && begin2 == end2) {
38
std::cout << "解析成功 (格式2)，日期: " << std::get<0>(date) << "-" << std::get<1>(date) << "-" << std::get<2>(date) << std::endl;
39
} else {
40
std::cout << "解析失败 (格式2)" << std::endl;
41
}
42
43
// 解析 input3
44
std::string::iterator begin3 = input3.begin();
45
std::string::iterator end3 = input3.end();
46
bool success3 = qi::parse(begin3, end3, date_parser, date);
47
if (success3 && begin3 == end3) {
48
std::cout << "解析成功 (格式3)，日期: " << std::get<0>(date) << "-" << std::get<1>(date) << "-" << std::get<2>(date) << std::endl;
49
} else {
50
std::cout << "解析失败 (格式3)" << std::endl;
51
}
52
53
return 0;
54
}
在这个例子中，date_parser 使用选择操作符 | 连接了两种日期格式的解析器 date_format1 和 date_format2。当解析器尝试解析输入时，它会首先尝试 date_format1。如果 date_format1 解析失败，解析器会自动回溯，并尝试使用 date_format2 解析。
运行这个程序，你会看到类似以下的输出：
1
解析成功 (格式1)，日期: 2023-10-26
2
解析成功 (格式2)，日期: 2023-10-26
3
解析失败 (格式3)
可以看到，对于 input1 和 input2，解析器都能成功解析，因为它们分别匹配了 date_format1 和 date_format2 两种格式。对于 input3，由于两种格式都不匹配，解析最终失败。
同步点 (Synchronization Points)
在解析复杂的结构化文本时，例如代码或配置文件，我们可以定义一些同步点，例如语句结束符（分号）、代码块开始/结束符（花括号）等。当解析错误发生时，我们可以跳过输入直到下一个同步点，然后从同步点开始继续解析。这种策略可以防止一个小的语法错误导致整个文件的解析失败。
实现同步点通常需要结合自定义 skipper 和错误处理函数。错误处理函数在检测到错误时，可以控制 skipper 跳过输入直到下一个同步点。
错误恢复策略的选择取决于具体的应用场景和需求。简单的应用可能只需要跳过错误或重试解析，而复杂的应用可能需要更精细的同步点和错误处理逻辑。Spirit 提供的灵活性使得开发者可以根据实际情况选择和组合不同的错误恢复策略，构建出健壮的解析器。
6.4 异常处理与 Spirit (异常处理与 Spirit, Exception Handling and Spirit)
Spirit 本身大量使用了 C++ 异常机制来处理解析过程中的错误和控制流。例如，qi::expectation_failure 异常就是 Spirit 默认的错误报告方式。理解 Spirit 的异常处理机制以及如何与 C++ 异常处理机制协同工作，对于编写健壮的 Spirit 解析器至关重要。
Spirit 内部的异常
Spirit.Qi 主要使用以下几种异常：
⚝ boost::spirit::qi::expectation_failure: 当使用期望操作符 > 并且期望的规则解析失败时抛出。
⚝ boost::spirit::qi::grammar_error: 在语法定义错误时抛出，例如规则循环定义。
⚝ 其他内部异常：Spirit 内部还可能抛出其他异常，通常是 std::exception 的子类，用于处理各种内部错误情况。
捕获 Spirit 异常
如我们在 6.1 节的例子中看到的，可以使用 try-catch 块来捕获 Spirit 抛出的异常，例如 qi::expectation_failure。捕获异常可以让我们在解析失败时执行一些清理工作、记录错误日志、或者向用户报告错误信息。
1
try {
2
bool success = qi::parse(begin, end, parser, result);
3
// ... 解析成功处理 ...
4
} catch (const qi::expectation_failure<std::string::iterator>& e) {
5
// ... 处理期望失败异常 ...
6
} catch (const std::exception& e) {
7
// ... 处理其他标准异常 ...
8
} catch (...) {
9
// ... 处理未知异常 ...
10
}
自定义异常与 Spirit
除了捕获 Spirit 自身的异常，我们还可以在自定义的语义动作或错误处理函数中抛出自定义异常。这允许我们根据应用逻辑，在解析过程中检测到特定错误条件时，抛出更具业务含义的异常。
例如，假设我们要解析一个年龄，年龄必须在 0 到 150 之间。如果输入的年龄超出这个范围，我们希望抛出一个自定义的 InvalidAgeException 异常。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/phoenix.hpp>
3
#include <iostream>
4
#include <string>
5
#include <stdexcept>
6
7
namespace qi = boost::spirit::qi;
8
namespace phx = boost::phoenix;
9
10
// 自定义异常类
11
struct InvalidAgeException : std::runtime_error {
12
InvalidAgeException(int age) : std::runtime_error("Invalid age: " + std::to_string(age)) {}
13
};
14
15
int main() {
16
std::string input1 = "25"; // 有效年龄
17
std::string input2 = "200"; // 无效年龄
18
19
int age;
20
auto parser = qi::int_[phx::ref(age) = qi::_1,
21
phx::if_(qi::_1 > 150)
22
[
23
phx::throw_(phx::construct<InvalidAgeException>(qi::_1)) // 抛出自定义异常
24
]];
25
26
// 解析 input1
27
std::string::iterator begin1 = input1.begin();
28
std::string::iterator end1 = input1.end();
29
try {
30
bool success1 = qi::parse(begin1, end1, parser);
31
if (success1 && begin1 == end1) {
32
std::cout << "解析成功，年龄: " << age << std::endl;
33
} else {
34
std::cout << "解析失败 (input1)" << std::endl;
35
}
36
} catch (const InvalidAgeException& e) {
37
std::cout << "捕获自定义异常: " << e.what() << std::endl;
38
} catch (const qi::expectation_failure<std::string::iterator>& e) {
39
std::cout << "捕获期望失败异常: " << e.what() << std::endl;
40
}
41
42
// 解析 input2
43
std::string::iterator begin2 = input2.begin();
44
std::string::iterator end2 = input2.end();
45
try {
46
bool success2 = qi::parse(begin2, end2, parser);
47
if (success2 && begin2 == end2) {
48
std::cout << "解析成功，年龄: " << age << std::endl;
49
} else {
50
std::cout << "解析失败 (input2)" << std::endl;
51
}
52
} catch (const InvalidAgeException& e) {
53
std::cout << "捕获自定义异常: " << e.what() << std::endl;
54
} catch (const qi::expectation_failure<std::string::iterator>& e) {
55
std::cout << "捕获期望失败异常: " << e.what() << std::endl;
56
}
57
58
return 0;
59
}
在这个例子中，我们在语义动作中使用了 Boost.Phoenix 的 phx::if_ 和 phx::throw_ 来实现条件性地抛出 InvalidAgeException 异常。当解析到的年龄大于 150 时，就会抛出这个自定义异常。我们在 try-catch 块中捕获了这个异常，并输出了异常信息。
运行这个程序，你会看到类似以下的输出：
1
解析成功，年龄: 25
2
捕获自定义异常: Invalid age: 200
可以看到，对于有效的年龄输入 "25"，解析成功。对于无效的年龄输入 "200"，我们成功捕获了自定义的 InvalidAgeException 异常。
异常处理的最佳实践
⚝ 适度使用异常: 异常处理应该用于处理真正的异常情况，例如输入格式错误、数据验证失败等。不要过度使用异常来控制正常的程序流程，因为异常处理的开销相对较高。
⚝ 清晰的异常类型: 使用具有明确含义的异常类型，例如 qi::expectation_failure 和自定义的 InvalidAgeException。这有助于在 catch 块中区分不同类型的错误，并进行相应的处理。
⚝ 异常安全: 在语义动作和错误处理函数中，要考虑异常安全。确保在异常抛出时，程序状态仍然保持一致，避免资源泄漏等问题。
⚝ 结合错误码和异常: 在某些情况下，可以结合使用错误码和异常。例如，可以使用错误码来表示轻微的错误或警告，使用异常来表示严重的、不可恢复的错误。
总而言之，Spirit 的异常处理机制是其错误处理能力的重要组成部分。通过理解和合理利用 Spirit 的异常以及 C++ 的异常处理机制，我们可以构建出更加健壮、可靠的解析器，有效地处理各种错误情况，并提供清晰的错误信息。
END_OF_CHAPTER
7. chapter 7： 跳过符与空白符处理 (跳过符与空白符处理, Skipper and Whitespace Handling)
7.1 Skipper 的概念与使用 (Skipper 的概念与使用, Concept and Usage of Skipper)
在文本解析的世界中，我们经常需要处理输入数据中存在的空白符，例如空格、制表符、换行符等。这些空白符在语法结构上通常不具有实际意义，主要用于提高代码或数据的可读性。跳过符 (Skipper) 的概念应运而生，它的主要职责就是在解析过程中自动忽略这些空白符，从而让解析器专注于处理真正有意义的语法元素。
在 Boost.Spirit 库中，Skipper 扮演着至关重要的角色，尤其是在 Spirit.Qi 组件中。Spirit.Qi 默认的行为是跳过输入流中的空白符，这极大地简化了语法规则的定义，使得我们可以更加专注于描述语言的骨架，而无需显式地处理空白符的细节。
① 什么是 Skipper？
Skipper 本质上也是一个解析器，但它的作用与我们通常理解的解析器有所不同。普通的解析器旨在识别和提取输入流中符合特定模式的元素，而 Skipper 的目标则是识别并消耗掉我们不关心的部分，通常是空白符。可以将 Skipper 视为一个“空白符过滤器”，它在主解析器工作之前预先处理输入流，将空白符“跳过”。
② 默认 Skipper：space_type
Spirit.Qi 默认使用的 Skipper 是 space_type。space_type 是一个预定义的解析器，它能够识别和跳过常见的空白符，包括：
⚝ 空格 (space)
⚝ 制表符 (tab)
⚝ 换行符 (newline)
⚝ 回车符 (carriage return)
⚝ 换页符 (form feed)
当我们使用 Spirit.Qi 构建解析器时，除非特别指定，否则 space_type 会自动被应用。这意味着，在默认情况下，我们的解析规则会自动忽略输入文本中的空白符。
③ Skipper 的使用方式
在 Spirit.Qi 中，Skipper 的使用是隐式的。当我们定义一个解析规则时，Spirit.Qi 会自动应用默认的 Skipper (space_type)。例如，考虑以下简单的解析器，用于解析一个整数：
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = " 123 "; // 输入字符串包含前导和尾随空格
9
int result;
10
11
bool success = qi::parse(input.begin(), input.end(), qi::int_, result);
12
13
if (success) {
14
std::cout << "解析成功，结果: " << result << std::endl; // 输出：解析成功，结果: 123
15
} else {
16
std::cout << "解析失败" << std::endl;
17
}
18
19
return 0;
20
}
在这个例子中，输入字符串 " 123 " 包含了前导和尾随的空格。尽管如此，qi::int_ 解析器仍然成功地解析出了整数 123。这正是因为默认的 Skipper (space_type) 在解析之前自动跳过了这些空白符。
④ 显式指定 Skipper
虽然默认的 Skipper 在很多情况下都非常方便，但在某些场景下，我们可能需要更精细地控制空白符的处理方式。Spirit.Qi 允许我们显式地指定 Skipper。
要显式指定 Skipper，我们需要在 qi::parse 函数中提供额外的参数。qi::parse 函数的完整形式如下：
1
template <typename Iterator, typename Grammar, typename Skipper, typename Attribute>
2
bool parse(Iterator& first, Iterator last, Grammar const& g, Skipper const& skipper, Attribute& attr);
其中，Skipper const& skipper 参数允许我们传入自定义的 Skipper。如果我们不想使用默认的 Skipper，或者想要使用不同的 Skipper，就可以通过这个参数来指定。
例如，如果我们想要禁用空白符跳过，可以使用 qi::space.omit 作为 Skipper。qi::space.omit 仍然会识别空白符，但不会跳过它们，而是将它们视为普通字符进行处理。实际上，更准确的禁用空白符跳过的方式是使用 qi::skip_flag::dont_skip 标志，这将在后续章节中详细介绍。
另一种常见的场景是使用不同的空白符定义。例如，我们可能只想跳过空格和制表符，而将换行符视为有意义的字符。在这种情况下，我们可以自定义一个 Skipper，只包含空格和制表符：
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
// 自定义 Skipper，只跳过空格和制表符
8
auto space_tab_skipper = qi::space | qi::tab;
9
10
int main() {
11
std::string input = " 123\n456 "; // 输入字符串包含空格、制表符和换行符
12
int result1, result2;
13
14
auto parser = qi::int_ >> qi::eol >> qi::int_; // 解析两个整数，中间用换行符分隔
15
16
auto begin = input.begin();
17
auto end = input.end();
18
19
bool success = qi::phrase_parse(begin, end, parser, space_tab_skipper, qi::tuple<int, int>{result1, result2});
20
21
if (success && begin == end) {
22
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl; // 输出：解析成功，结果: 123, 456
23
} else {
24
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl;
25
}
26
27
return 0;
28
}
在这个例子中，我们定义了一个名为 space_tab_skipper 的自定义 Skipper，它只跳过空格 (qi::space) 和制表符 (qi::tab)。我们使用 qi::phrase_parse 函数，它与 qi::parse 类似，但允许我们显式指定 Skipper。我们传入 space_tab_skipper 作为 Skipper 参数。由于 space_tab_skipper 不会跳过换行符 (\n)，因此 qi::eol 解析器能够成功匹配换行符，整个解析过程也得以成功完成。
⑤ phrase_parse 与 parse 的区别
Spirit.Qi 提供了两个主要的解析函数：qi::parse 和 qi::phrase_parse。它们的主要区别在于对 Skipper 的处理方式：
⚝ qi::parse: 使用默认的 Skipper (space_type)，并且在解析过程中始终应用 Skipper。这意味着，Skipper 会在解析规则的任何位置跳过空白符，包括规则内部。
⚝ qi::phrase_parse: 允许显式指定 Skipper，并且只在解析规则的外部应用 Skipper。也就是说，Skipper 只会在解析规则开始之前和结束之后跳过空白符，而不会在规则内部跳过空白符。
在大多数情况下，qi::phrase_parse 是更推荐使用的函数，因为它提供了更清晰的空白符处理语义。使用 qi::phrase_parse，我们可以明确地控制 Skipper 的行为，避免一些潜在的混淆。
总结来说，Skipper 是 Spirit.Qi 中处理空白符的关键机制。默认的 space_type Skipper 能够自动跳过常见的空白符，简化了解析规则的定义。同时，Spirit.Qi 也提供了显式指定和自定义 Skipper 的能力，以满足更复杂的空白符处理需求。理解 Skipper 的概念和使用方式，是掌握 Spirit.Qi 的重要一步。
7.2 自定义 Skipper (自定义 Skipper, Custom Skipper)
默认的 space_type Skipper 在处理常见的空白符场景时非常方便。然而，在实际应用中，我们可能会遇到更复杂的空白符定义，例如：
① 注释 (Comments)：在编程语言或配置文件中，注释通常被视为空白符，应该被跳过。注释的格式可能多种多样，例如 C++ 的 // 和 /* ... */ 注释，Python 的 # 注释等。
② 特定分隔符 (Specific Delimiters)：有时，除了常见的空白符之外，我们还需要跳过一些特定的分隔符，例如逗号、分号等。
③ 自定义空白符集合 (Custom Whitespace Set)：我们可能需要定义一组不同于默认空白符的字符集合作为空白符。
为了应对这些复杂场景，Spirit.Qi 允许我们自定义 Skipper。自定义 Skipper 的本质是创建一个符合 Skipper 概念的解析器，并将其作为参数传递给 qi::phrase_parse 函数。
① 自定义 Skipper 的基本方法
自定义 Skipper 的最基本方法是使用 Spirit.Qi 的语法规则来描述我们想要跳过的字符或模式。例如，如果我们想要创建一个 Skipper，除了跳过默认的空白符外，还要跳过 C++ 的行注释 //，可以这样做：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/qi_char.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
8
// 自定义 Skipper，跳过空白符和 C++ 行注释
9
auto cpp_comment_skipper =
10
qi::space // 跳过默认空白符
11
| ("//" >> *(qi::char_ - qi::eol) >> qi::eol) // 跳过 C++ 行注释
12
;
13
14
int main() {
15
std::string input = " 123 // This is a comment\n456 ";
16
int result1, result2;
17
18
auto parser = qi::int_ >> qi::eol >> qi::int_;
19
20
auto begin = input.begin();
21
auto end = input.end();
22
23
bool success = qi::phrase_parse(begin, end, parser, cpp_comment_skipper, qi::tuple<int, int>{result1, result2});
24
25
if (success && begin == end) {
26
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl; // 输出：解析成功，结果: 123, 456
27
} else {
28
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl;
29
}
30
31
return 0;
32
}
在这个例子中，我们定义了一个名为 cpp_comment_skipper 的自定义 Skipper。它使用 | 运算符将两个解析规则组合起来：
⚝ qi::space: 跳过默认的空白符。
⚝ ("//" >> *(qi::char_ - qi::eol) >> qi::eol): 跳过 C++ 行注释。这个规则的含义是：
▮▮▮▮⚝ "//": 匹配字符串 "//"，表示注释的开始。
▮▮▮▮⚝ *(qi::char_ - qi::eol): 匹配零个或多个非换行符的字符。(qi::char_ - qi::eol) 表示匹配任意字符，但不包括换行符 (qi::eol)。* 表示重复零次或多次。
▮▮▮▮⚝ qi::eol: 匹配换行符，表示注释的结束。
通过将这两个规则用 | 组合起来，cpp_comment_skipper 既可以跳过默认的空白符，也可以跳过 C++ 行注释。
② 跳过块注释 (Block Comments)
除了行注释，块注释 (例如 C++ 的 /* ... */ 注释) 也是常见的注释形式。我们可以扩展上面的 cpp_comment_skipper，使其也能跳过块注释：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/qi_char.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
8
// 自定义 Skipper，跳过空白符、C++ 行注释和块注释
9
auto cpp_comment_skipper =
10
qi::space // 跳过默认空白符
11
| ("//" >> *(qi::char_ - qi::eol) >> qi::eol) // 跳过 C++ 行注释
12
| ("/*" >> *(qi::char_ - "*/") >> "*/") // 跳过 C++ 块注释
13
;
14
15
int main() {
16
std::string input = " 123 /* This is a block comment */ 456 ";
17
int result;
18
19
bool success = qi::phrase_parse(input.begin(), input.end(), qi::int_, cpp_comment_skipper, result);
20
21
if (success) {
22
std::cout << "解析成功，结果: " << result << std::endl; // 输出：解析成功，结果: 123
23
} else {
24
std::cout << "解析失败" << std::endl;
25
}
26
27
return 0;
28
}
在这个例子中，我们向 cpp_comment_skipper 添加了第三个规则：
⚝ ("/*" >> *(qi::char_ - "*/") >> "*/"): 跳过 C++ 块注释。这个规则的含义是：
▮▮▮▮⚝ "/*": 匹配字符串 "/*"，表示块注释的开始。
▮▮▮▮⚝ *(qi::char_ - "*/"): 匹配零个或多个非 "*/" 的字符。(qi::char_ - "*/") 表示匹配任意字符，但不包括字符串 "*/"。* 表示重复零次或多次。
▮▮▮▮⚝ "*/": 匹配字符串 "*/"，表示块注释的结束。
③ 使用预定义的 Skipper 组件
Spirit.Qi 提供了一些预定义的 Skipper 组件，可以简化自定义 Skipper 的定义。例如，qi::space 本身就是一个预定义的 Skipper 组件，它等价于 qi::char_(" \t\r\n\f")。
我们可以使用这些预定义的组件来构建更复杂的 Skipper。例如，如果我们想要创建一个 Skipper，跳过空格、制表符和逗号，可以这样做：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/qi_char.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
8
// 自定义 Skipper，跳过空格、制表符和逗号
9
auto space_tab_comma_skipper = qi::space | qi::char_(',');
10
11
int main() {
12
std::string input = " 123, 456 ";
13
int result1, result2;
14
15
auto parser = qi::int_ >> ',' >> qi::int_;
16
17
auto begin = input.begin();
18
auto end = input.end();
19
20
bool success = qi::phrase_parse(begin, end, parser, space_tab_comma_skipper, qi::tuple<int, int>{result1, result2});
21
22
if (success && begin == end) {
23
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl; // 输出：解析成功，结果: 123, 456
24
} else {
25
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl;
26
}
27
28
return 0;
29
}
在这个例子中，space_tab_comma_skipper 使用 qi::space 跳过空格和制表符，使用 qi::char_(',') 跳过逗号。
④ Skipper 的组合与复用
自定义 Skipper 也可以像普通的解析规则一样进行组合和复用。我们可以将多个 Skipper 组合成一个更复杂的 Skipper，或者在一个 Skipper 中复用其他的 Skipper。
例如，假设我们已经定义了一个 cpp_comment_skipper 用于跳过 C++ 注释，现在我们想要创建一个新的 Skipper，除了跳过 C++ 注释外，还要跳过 Python 的行注释 #。我们可以复用 cpp_comment_skipper，并添加新的规则：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/qi_char.hpp>
3
#include <string>
4
#include <iostream>
5
6
namespace qi = boost::spirit::qi;
7
8
// 假设 cpp_comment_skipper 已经在前面定义
9
10
// 自定义 Skipper，跳过 C++ 注释和 Python 行注释
11
auto cpp_python_comment_skipper =
12
cpp_comment_skipper // 复用 cpp_comment_skipper
13
| ('#' >> *(qi::char_ - qi::eol) >> qi::eol) // 跳过 Python 行注释
14
;
15
16
int main() {
17
std::string input = " 123 # This is a Python comment\n456 // This is a C++ comment";
18
int result1, result2;
19
20
auto parser = qi::int_ >> qi::eol >> qi::int_;
21
22
auto begin = input.begin();
23
auto end = input.end();
24
25
bool success = qi::phrase_parse(begin, end, parser, cpp_python_comment_skipper, qi::tuple<int, int>{result1, result2});
26
27
if (success && begin == end) {
28
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl; // 输出：解析成功，结果: 123, 456
29
} else {
30
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl;
31
}
32
33
return 0;
34
}
通过自定义 Skipper，我们可以灵活地处理各种复杂的空白符场景，使得 Spirit.Qi 能够适应更广泛的解析需求。自定义 Skipper 的关键在于使用 Spirit.Qi 的语法规则来准确地描述我们想要跳过的字符或模式。
7.3 空白符策略 (空白符策略, Whitespace Policy)
除了使用 Skipper 来处理空白符外，Spirit.Qi 还提供了空白符策略 (Whitespace Policy) 的概念，用于更精细地控制空白符的处理方式。空白符策略 决定了 Skipper 在解析过程中的具体行为，例如何时应用 Skipper，以及如何处理 Skipper 无法跳过的空白符。
空白符策略 通过 qi::skip_flag 枚举类型来控制，它可以取以下值：
① qi::skip (默认策略)
qi::skip 是默认的空白符策略。当使用 qi::skip 策略时，Spirit.Qi 会在以下位置应用 Skipper：
⚝ 规则开始之前 (Before Rule)：在开始解析一个规则之前，先使用 Skipper 跳过输入流中的空白符。
⚝ 规则结束之后 (After Rule)：在成功解析完一个规则之后，再次使用 Skipper 跳过输入流中的空白符。
这意味着，在默认情况下，Spirit.Qi 会自动跳过规则之间以及规则前后的空白符。这也是我们之前例子中默认的行为。
② qi::skip_flag::postskip
qi::skip_flag::postskip 策略只在规则结束之后 (After Rule) 应用 Skipper。也就是说，在开始解析一个规则之前，不会跳过任何空白符，只有在成功解析完一个规则之后，才会跳过空白符。
使用 qi::skip_flag::postskip 策略，可以通过 qi::no_skip 操纵符来指定。例如：
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = " 123 456"; // 输入字符串，数字之间有空格
9
int result1, result2;
10
11
auto parser = qi::int_ >> qi::no_skip[qi::int_]; // 第二个 int_ 使用 no_skip 策略
12
13
auto begin = input.begin();
14
auto end = input.end();
15
16
bool success = qi::phrase_parse(begin, end, parser, qi::space, qi::tuple<int, int>{result1, result2});
17
18
if (success && begin == end) {
19
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl; // 输出：解析成功，结果: 123, 456
20
} else {
21
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl;
22
}
23
24
return 0;
25
}
在这个例子中，我们使用 qi::no_skip[qi::int_] 来修饰第二个 qi::int_ 解析器。qi::no_skip 操纵符会将 qi::int_ 的空白符策略设置为 qi::skip_flag::postskip。这意味着，第一个 qi::int_ 会在解析前后都跳过空白符 (默认策略)，而第二个 qi::int_ 只会在解析之后跳过空白符。因此，输入字符串 " 123 456" 中的空格会被正确处理，两个整数都能被成功解析。
③ qi::skip_flag::preskip
qi::skip_flag::preskip 策略只在规则开始之前 (Before Rule) 应用 Skipper。也就是说，在开始解析一个规则之前，会先使用 Skipper 跳过空白符，但在成功解析完一个规则之后，不会跳过空白符。
使用 qi::skip_flag::preskip 策略，可以通过 qi::skip_only 操纵符来指定。例如：
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = " 123 456"; // 输入字符串，数字之间有空格
9
int result1, result2;
10
11
auto parser = qi::skip_only[qi::int_] >> qi::int_; // 第一个 int_ 使用 skip_only 策略
12
13
auto begin = input.begin();
14
auto end = input.end();
15
16
bool success = qi::phrase_parse(begin, end, parser, qi::space, qi::tuple<int, int>{result1, result2});
17
18
if (success && begin == end) {
19
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl; // 输出：解析成功，结果: 123, 456
20
} else {
21
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl;
22
}
23
24
return 0;
25
}
在这个例子中，我们使用 qi::skip_only[qi::int_] 来修饰第一个 qi::int_ 解析器。qi::skip_only 操纵符会将 qi::int_ 的空白符策略设置为 qi::skip_flag::preskip。这意味着，第一个 qi::int_ 只会在解析之前跳过空白符，而第二个 qi::int_ 会在解析前后都跳过空白符 (默认策略)。
④ qi::skip_flag::dont_skip
qi::skip_flag::dont_skip 策略完全禁用 Skipper。当使用 qi::dont_skip 策略时，Spirit.Qi 不会在任何位置应用 Skipper。这意味着，空白符将不再被自动跳过，而是被视为普通的输入字符。
使用 qi::skip_flag::dont_skip 策略，可以通过 qi::lexeme 操纵符来指定。qi::lexeme 操纵符的含义实际上更广泛，它不仅禁用 Skipper，还会将内部的解析规则视为一个词元 (lexeme)，阻止 Skipper 在词元内部跳过空白符。但在这里，我们可以先将其理解为禁用 Skipper 的一种方式。例如：
1
#include <boost/spirit/include/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = " 123 456"; // 输入字符串，数字之间有空格
9
int result1, result2;
10
11
auto parser = qi::lexeme[qi::int_] >> qi::lexeme[qi::int_]; // 两个 int_ 都使用 lexeme 策略
12
13
auto begin = input.begin();
14
auto end = input.end();
15
16
bool success = qi::phrase_parse(begin, end, parser, qi::space, qi::tuple<int, int>{result1, result2});
17
18
if (success && begin == end) {
19
std::cout << "解析成功，结果: " << result1 << ", " << result2 << std::endl;
20
} else {
21
std::cout << "解析失败，剩余输入: " << std::string(begin, end) << std::endl; // 输出：解析失败，剩余输入: 456
22
}
23
24
return 0;
25
}
在这个例子中，我们使用 qi::lexeme[qi::int_] 来修饰两个 qi::int_ 解析器。qi::lexeme 操纵符会将 qi::int_ 的空白符策略设置为 qi::skip_flag::dont_skip。这意味着，两个 qi::int_ 都不会跳过空白符。因此，第一个 qi::int_ 只能解析到输入字符串 " 123 456" 的前导空格，无法解析出整数 123，解析过程会提前失败。
总结
空白符策略 提供了更细粒度的空白符处理控制。通过选择不同的空白符策略，我们可以灵活地调整 Skipper 的行为，以适应不同的解析需求。
⚝ 默认策略 qi::skip 适用于大多数场景，自动跳过规则前后和规则之间的空白符。
⚝ qi::skip_flag::postskip (通过 qi::no_skip 操纵符指定) 只在规则结束后跳过空白符。
⚝ qi::skip_flag::preskip (通过 qi::skip_only 操纵符指定) 只在规则开始前跳过空白符。
⚝ qi::skip_flag::dont_skip (通过 qi::lexeme 操纵符指定) 完全禁用 Skipper。
理解和灵活运用 空白符策略，可以帮助我们构建更精确、更强大的解析器，应对各种复杂的文本解析任务。在实际应用中，我们需要根据具体的语法规则和空白符处理需求，选择合适的 Skipper 和 空白符策略，才能达到最佳的解析效果。
END_OF_CHAPTER
8. chapter 8： 词法分析 (Lexical Analysis)
8.1 Token (词元) 的概念 (Concept of Tokens)
在编译原理和语言处理领域，词法分析 (Lexical Analysis) 是将字符序列转换为 词元 (Token) 序列的过程。词法分析器，也称为 扫描器 (Scanner) 或 分词器 (Tokenizer)，是编译器的第一个阶段，负责读取输入的字符流，并根据预定义的词法规则识别出具有独立含义的最小语法单元，即词元（Token）。
词元是程序代码或文本中具有独立意义的最小单元，例如：
① 关键字 (Keywords)：编程语言中预定义的保留字，例如 if、else、for、while 等。
② 标识符 (Identifiers)：程序员自定义的名称，用于表示变量、函数、类等，例如 variableName、functionName、ClassName。
③ 字面量 (Literals)：表示固定值的符号，例如数字字面量 123、3.14，字符串字面量 "hello"，布尔字面量 true、false。
④ 运算符 (Operators)：表示运算操作的符号，例如算术运算符 +、-、*、/，关系运算符 ==、!=、>、<，逻辑运算符 &&、||、!。
⑤ 分隔符 (Delimiters)：用于分隔代码或文本结构的符号，例如括号 ()、{}、[]，逗号 ,，分号 ;。
⑥ 注释 (Comments)：程序中用于解释代码的文本，通常会被词法分析器忽略，例如 // 单行注释，/* ... */ 多行注释。
词法分析器的主要任务包括：
① 扫描输入字符流：逐个读取输入的字符。
② 识别词元：根据预定义的词法规则，将字符序列识别为不同的词元类型。
③ 生成词元序列：将识别出的词元按照顺序组成词元序列，作为后续语法分析的输入。
④ 过滤空白符和注释：通常词法分析器会忽略输入中的空白符（空格、制表符、换行符等）和注释，只提取有意义的词元。
⑤ 错误处理：当输入字符序列不符合词法规则时，词法分析器需要报告词法错误，例如非法字符、未闭合的字符串等。
词元表示 (Token Representation)
每个词元通常包含两个关键信息：
① 词元类型 (Token Type)：标识词元的种类，例如 KEYWORD、IDENTIFIER、INTEGER_LITERAL、OPERATOR 等。
② 词元值 (Token Value) 或 词位 (Lexeme)：词元对应的具体字符串值，例如对于标识符词元，词元值可能是 "variableName"；对于整数词元，词元值可能是 "123"。
例如，对于代码片段 int count = 10;，词法分析器可能会生成如下词元序列：
| 词元值 (Lexeme) | 词元类型 (Token Type) |
|---|---|
int | KEYWORD |
count | IDENTIFIER |
= | OPERATOR |
10 | INTEGER_LITERAL |
; | DELIMITER |
Boost.Spirit.Lex 的作用
Boost.Spirit.Lex 是 Boost.Spirit 库的一个组件，专门用于构建高性能的词法分析器。它允许开发者使用 C++ 代码和 EBNF (Extended Backus-Naur Form) 语法规则来定义词法规则，并自动生成高效的词法分析器。Spirit.Lex 可以与 Spirit.Qi (用于语法分析) 和 Spirit.Karma (用于代码生成) 无缝集成，构建完整的编译工具链或文本处理应用。
使用 Spirit.Lex 的优势包括：
① 声明式语法定义：使用 EBNF 语法规则描述词法，代码简洁易懂，易于维护。
② 高性能：Spirit.Lex 生成的词法分析器性能优异，能够处理大规模文本数据。
③ 与 Spirit 库集成：可以方便地与 Spirit.Qi 和 Spirit.Karma 结合使用，构建完整的解析和生成系统。
④ 灵活性和可扩展性：支持自定义词元类型、语义动作和错误处理，满足各种复杂的词法分析需求。
8.2 使用 Spirit.Lex (Using Spirit.Lex)
要使用 Boost.Spirit.Lex，首先需要包含相应的头文件：
1
#include <boost/spirit/include/lex.hpp>
Spirit.Lex 的核心概念是 lexer (词法分析器) 和 token definition (词元定义)。
1. 定义词元 (Token Definition)
使用 boost::spirit::lex::token_def<> 来定义词元。token_def<> 接受一个正则表达式作为参数，用于匹配词元模式。
例如，定义一个整数词元和一个标识符词元：
1
namespace lex = boost::spirit::lex;
2
3
// 定义整数词元，匹配一个或多个数字
4
lex::token_def<> integer = "[0-9]+";
5
6
// 定义标识符词元，匹配字母或下划线开头，后跟字母、数字或下划线
7
lex::token_def<> identifier = "[a-zA-Z_][a-zA-Z_0-9]*";
2. 定义词法分析器 (Lexer Definition)
使用 boost::spirit::lex::lexer<> 来定义词法分析器。词法分析器需要关联一组词元定义。
1
struct my_lexer : lex::lexer<>
2
{
3
my_lexer()
4
{
5
// 将词元定义添加到词法分析器
6
this->self
7
= integer
8
| identifier
9
;
10
}
11
12
lex::token_def<> integer;
13
lex::token_def<> identifier;
14
};
在 my_lexer 结构体中，我们继承了 lex::lexer<>，并在构造函数中定义了词法规则。this->self 表示当前词法分析器对象，使用 | 运算符可以将多个词元定义组合起来，表示选择匹配其中任何一个词元。
3. 使用词法分析器 (Using the Lexer)
创建词法分析器对象，并使用 lex::tokenize() 函数对输入文本进行词法分析。lex::tokenize() 函数接受输入迭代器范围和词法分析器对象作为参数，返回一个词元迭代器范围。
1
int main()
2
{
3
std::string input = "123 abc 456 def";
4
my_lexer lexer;
5
6
auto begin = input.begin();
7
auto end = input.end();
8
9
// 使用 lex::tokenize 进行词法分析
10
auto token_begin = lexer.tokenize(begin, end);
11
auto token_end = lex::tokenize_end;
12
13
// 遍历词元序列
14
for (auto it = token_begin; it != token_end; ++it)
15
{
16
std::cout << "Token: " << it->value() << ", Type: " << it->id() << std::endl;
17
}
18
19
return 0;
20
}
在上面的代码中，it->value() 返回词元的字符串值，it->id() 返回词元的 ID，默认情况下，词元 ID 是按照词元定义在词法分析器中出现的顺序自动分配的。
4. 自定义词元 ID (Custom Token IDs)
可以为词元定义指定自定义的 ID，以便在后续处理中更方便地识别词元类型。使用 lex::token_def<token_id> 可以指定词元 ID 的类型。
1
// 定义词元 ID 枚举
2
enum token_ids
3
{
4
ID_INTEGER,
5
ID_IDENTIFIER
6
};
7
8
struct my_lexer : lex::lexer<lex::token<token_ids>> // 指定词元类型为 lex::token<token_ids>
9
{
10
my_lexer()
11
{
12
this->self
13
= integer [ lex::_tokenid = ID_INTEGER ] // 使用 lex::_tokenid 属性设置词元 ID
14
| identifier [ lex::_tokenid = ID_IDENTIFIER ]
15
;
16
}
17
18
lex::token_def<token_ids> integer = "[0-9]+";
19
lex::token_def<token_ids> identifier = "[a-zA-Z_][a-zA-Z_0-9]*";
20
};
在上面的代码中，我们定义了一个枚举 token_ids 来表示词元 ID，并在词元定义中使用 [ lex::_tokenid = ID_INTEGER ] 和 [ lex::_tokenid = ID_IDENTIFIER ] 来设置词元 ID。
5. 忽略词元 (Ignoring Tokens)
可以使用 lex::token_def<>::ignore() 来忽略某些词元，例如空白符和注释。被忽略的词元不会出现在词元序列中。
1
struct my_lexer : lex::lexer<lex::token<token_ids>>
2
{
3
my_lexer()
4
{
5
this->self
6
= integer [ lex::_tokenid = ID_INTEGER ]
7
| identifier [ lex::_tokenid = ID_IDENTIFIER ]
8
| lex::space [ lex::_tokenid = ID_SPACE, lex::_pass = lex::pass_flags::ignore ] // 忽略空白符
9
;
10
}
11
12
lex::token_def<token_ids> integer = "[0-9]+";
13
lex::token_def<token_ids> identifier = "[a-zA-Z_][a-zA-Z_0-9]*";
14
lex::token_def<token_ids> space = "\\s+"; // 匹配一个或多个空白符
15
};
在上面的代码中，我们定义了一个 space 词元，并使用 [ lex::_tokenid = ID_SPACE, lex::_pass = lex::pass_flags::ignore ] 来指定忽略该词元。lex::_pass = lex::pass_flags::ignore 表示忽略当前词元，lex::_tokenid = ID_SPACE 仍然可以为被忽略的词元设置 ID，虽然通常情况下没有必要。
8.3 自定义 Tokenizer (Custom Tokenizer)
除了使用 Spirit.Lex 提供的默认 tokenizer，还可以自定义 tokenizer 以满足更复杂的需求。自定义 tokenizer 可以实现更灵活的词元识别和处理逻辑。
1. 基于函数对象的自定义 Tokenizer
可以创建一个函数对象，实现 tokenizer 的逻辑。该函数对象需要接受输入迭代器范围作为参数，并返回一个 boost::optional<token_type>，表示识别出的词元。如果返回 boost::none，则表示没有识别出词元。
1
#include <boost/spirit/include/lex_tokenize_and_phrase.hpp>
2
#include <boost/spirit/home/lex/lexer/token.hpp>
3
#include <boost/optional/optional.hpp>
4
#include <string>
5
#include <iostream>
6
7
namespace lex = boost::spirit::lex;
8
9
// 自定义词元类型
10
struct my_token : lex::token<>
11
{
12
my_token(std::string const& value, int id) : lex::token<>(value, id) {}
13
};
14
15
// 自定义 Tokenizer 函数对象
16
struct my_tokenizer
17
{
18
template <typename Iterator>
19
boost::optional<my_token>
20
operator()(Iterator& begin, Iterator end) const
21
{
22
if (begin == end)
23
return boost::none;
24
25
if (std::isdigit(*begin))
26
{
27
Iterator current = begin;
28
while (current != end && std::isdigit(*current))
29
++current;
30
std::string value(begin, current);
31
begin = current;
32
return my_token(value, 1); // 整数词元 ID 为 1
33
}
34
else if (std::isalpha(*begin) || *begin == '_')
35
{
36
Iterator current = begin;
37
while (current != end && (std::isalnum(*current) || *current == '_'))
38
++current;
39
std::string value(begin, current);
40
begin = current;
41
return my_token(value, 2); // 标识符词元 ID 为 2
42
}
43
else
44
{
45
++begin; // 忽略其他字符
46
return boost::none;
47
}
48
}
49
};
50
51
int main()
52
{
53
std::string input = "123 abc 456 def";
54
55
auto begin = input.begin();
56
auto end = input.end();
57
58
// 使用自定义 tokenizer 进行词法分析
59
std::vector<my_token> tokens;
60
bool result = lex::tokenize(begin, end, my_tokenizer(), tokens);
61
62
if (result)
63
{
64
for (const auto& token : tokens)
65
{
66
std::cout << "Token: " << token.value() << ", Type: " << token.id() << std::endl;
67
}
68
}
69
else
70
{
71
std::cout << "Lexical analysis failed." << std::endl;
72
}
73
74
return 0;
75
}
在上面的代码中，my_tokenizer 函数对象实现了自定义的词元识别逻辑。lex::tokenize() 函数的第三个参数接受 tokenizer 函数对象，第四个参数接受存储词元序列的容器。
2. 基于状态机的自定义 Tokenizer
对于更复杂的词法规则，可以使用状态机来实现自定义 tokenizer。状态机可以更灵活地处理各种复杂的词法模式，例如嵌套注释、多行字符串等。
使用状态机实现自定义 tokenizer 涉及到更底层的 Spirit.Lex API，通常在需要处理非常复杂的词法规则时才会使用。对于大多数应用场景，使用 Spirit.Lex 提供的基于正则表达式的词元定义已经足够强大和灵活。
8.4 整合 Lex 和 Qi (Integrating Lex and Qi)
Boost.Spirit.Lex 通常与 Boost.Spirit.Qi 结合使用，构建完整的解析器。Lex 负责词法分析，将输入字符流转换为词元序列；Qi 负责语法分析，根据语法规则解析词元序列，构建抽象语法树 (AST) 或执行其他语义动作。
1. 使用 phrase_parse 进行组合解析
可以使用 boost::spirit::qi::phrase_parse() 函数将 Lex 和 Qi 组合起来进行解析。phrase_parse() 函数与 qi::parse() 类似，但它接受一个额外的参数，用于指定 skipper (跳过符)，通常使用 Lex 生成的词元序列作为输入。
1
#include <boost/spirit/include/lex_lexer_spirit.hpp>
2
#include <boost/spirit/include/qi.hpp>
3
#include <iostream>
4
#include <string>
5
6
namespace lex = boost::spirit::lex;
7
namespace qi = boost::spirit::qi;
8
9
// 词元 ID 枚举
10
enum token_ids
11
{
12
ID_INTEGER,
13
ID_IDENTIFIER,
14
ID_SPACE
15
};
16
17
// 词法分析器定义
18
struct my_lexer : lex::lexer<lex::token<token_ids>>
19
{
20
my_lexer()
21
{
22
this->self
23
= integer [ lex::_tokenid = ID_INTEGER ]
24
| identifier [ lex::_tokenid = ID_IDENTIFIER ]
25
| lex::space [ lex::_tokenid = ID_SPACE, lex::_pass = lex::pass_flags::ignore ]
26
;
27
}
28
29
lex::token_def<token_ids> integer = "[0-9]+";
30
lex::token_def<token_ids> identifier = "[a-zA-Z_][a-zA-Z_0-9]*";
31
};
32
33
// 语法分析器定义
34
template <typename Iterator>
35
struct my_parser : qi::grammar<Iterator, int()>
36
{
37
my_parser() : my_parser::base_type(start)
38
{
39
using qi::int_;
40
using qi::_val;
41
using qi::_1;
42
43
// 语法规则：整数表达式，例如 "1 + 2 + 3"
44
start =
45
integer_expr.name("integer_expression");
46
47
integer_expr =
48
int_ [_val = _1] >> +('+' >> int_ [_val += _1]);
49
}
50
51
qi::rule<Iterator, int()> start;
52
qi::rule<Iterator, int()> integer_expr;
53
};
54
55
int main()
56
{
57
std::string input = "123 + 456 + 789";
58
my_lexer lexer;
59
my_parser<lex::lexertl::token_iterator<std::string::iterator, my_lexer>> parser; // 指定词元迭代器类型
60
61
auto begin = input.begin();
62
auto end = input.end();
63
64
// 使用 lex::tokenize 进行词法分析
65
auto token_begin = lexer.tokenize(begin, end);
66
auto token_end = lex::tokenize_end;
67
68
int result = 0;
69
bool success = qi::phrase_parse(
70
token_begin, token_end,
71
parser,
72
qi::in_token_range, // 使用 qi::in_token_range 作为 skipper，表示跳过词元之间的空白符
73
result
74
);
75
76
if (success && token_begin == token_end)
77
{
78
std::cout << "Parse success, result = " << result << std::endl;
79
}
80
else
81
{
82
std::cout << "Parse failed." << std::endl;
83
}
84
85
return 0;
86
}
在上面的代码中，我们定义了一个 my_lexer 词法分析器和一个 my_parser 语法分析器。在 main() 函数中，首先使用 lexer.tokenize() 进行词法分析，得到词元迭代器范围 token_begin 和 token_end。然后，使用 qi::phrase_parse() 函数进行语法分析，将词元迭代器范围、语法分析器对象、skipper 和结果变量作为参数传递。qi::in_token_range 是一个预定义的 skipper，用于跳过词元之间的空白符。
2. 词元迭代器类型
在定义语法分析器时，需要指定词元迭代器类型。对于使用 Spirit.Lex 生成的词法分析器，词元迭代器类型通常是 lex::lexertl::token_iterator<InputIterator, Lexer>，其中 InputIterator 是输入字符迭代器类型，Lexer 是词法分析器类型。
3. Skipper 的选择
在 phrase_parse() 函数中，skipper 用于指定在语法分析过程中需要跳过的部分。对于词法分析和语法分析组合的场景，通常使用 qi::in_token_range 作为 skipper，表示跳过词元之间的空白符。如果词法分析器已经处理了空白符，也可以使用 qi::space 或自定义的 skipper。
通过整合 Spirit.Lex 和 Spirit.Qi，可以构建强大的文本处理和语言解析工具，实现从词法分析到语法分析的完整流程。Spirit.Lex 负责高效地将字符流转换为词元序列，Spirit.Qi 负责根据语法规则解析词元序列，两者协同工作，可以处理各种复杂的文本格式和编程语言。
END_OF_CHAPTER
9. chapter 9： 实战案例：解析 CSV 文件 (实战案例：解析 CSV 文件, Practical Case: Parsing CSV Files)
9.1 CSV 文件格式详解 (CSV 文件格式详解, Detailed Explanation of CSV File Format)
CSV (Comma Separated Values，逗号分隔值) 文件格式是一种广泛应用的文本文件格式，用于存储表格数据，例如电子表格或数据库。其核心思想是用纯文本表示结构化数据，易于阅读和处理，并且具有良好的跨平台兼容性。尽管 CSV 格式标准相对宽松，但也存在一些通用的约定和变体。理解 CSV 文件的格式细节是使用 Boost.Spirit 构建解析器的前提。
基本结构
CSV 文件由若干行（row）记录组成，每一行代表表格中的一行数据。每行又由多个字段（field）组成，字段之间使用特定的分隔符（delimiter）进行分隔。最常见的分隔符是逗号 ,，这也是 CSV 名称的由来，但实际上分号 ;、制表符 \t 甚至空格等字符也常被用作分隔符，尤其是在不同地区或应用场景中。
⚝ 行 (Row)：CSV 文件中的每一行都代表一条数据记录。行与行之间通常使用换行符 \n 或回车换行符 \r\n 分隔。
⚝ 字段 (Field)：每一行包含一个或多个字段，字段是实际的数据单元。
⚝ 分隔符 (Delimiter)：分隔符是用于区分一行中不同字段的字符。逗号 , 是最常用的分隔符，但也可以是分号 ;、制表符 \t 或其他字符。选择何种分隔符通常取决于数据内容本身，以及避免与数据内容冲突的考虑。
常见约定与变体
① 逗号分隔符：最原始和最常见的 CSV 格式使用逗号 , 作为字段分隔符。例如：
1
Name,Age,City
2
Alice,30,New York
3
Bob,25,London
4
Charlie,35,Paris
② 其他分隔符：考虑到数据字段中可能包含逗号的情况，例如地址信息，使用其他分隔符变得必要。分号 ; 和制表符 \t 是常见的替代方案。
▮▮▮▮⚝ 分号分隔符：
1
Name;Age;City
2
Alice;30;New York
3
Bob;25;London
4
Charlie;35;Paris
▮▮▮▮⚝ 制表符分隔符 (TSV, Tab Separated Values)：
1
Name Age City
2
Alice 30 New York
3
Bob 25 London
4
Charlie 35 Paris
③ 引号 (Quotes)：当字段内容本身包含分隔符，或者包含换行符时，需要使用引号将字段内容括起来。双引号 " 是最常用的引号字符。
▮▮▮▮⚝ 字段中包含分隔符：
1
Name,Address
2
"Alice, Smith","123 Main St, Anytown"
3
Bob,456 Oak Ave
1
在这个例子中，`Alice, Smith` 和 `123 Main St, Anytown` 字段由于包含逗号，所以被双引号括起来。
▮▮▮▮⚝ 字段中包含换行符：
1
Description
2
"This is a description
3
that spans multiple lines"
4
Another description
1
描述字段包含换行符，因此需要用双引号包围。
④ 引号转义 (Quote Escaping)：当字段内容本身包含引号字符时，需要进行转义。常见的转义方法有两种：
▮▮▮▮⚝ 双引号转义双引号：在双引号括起来的字段中，如果字段内容包含双引号，则使用两个双引号 "" 来表示一个双引号。
1
Value
2
"He said ""Hello""."
1
解析后，字段内容应该是 `He said "Hello".`。
▮▮▮▮⚝ 反斜杠转义引号：使用反斜杠 \ 来转义引号。
1
Value
2
"He said \"Hello\"."
1
解析后，字段内容同样是 `He said "Hello".`。
2
**注意**：双引号转义双引号是更标准的做法，而反斜杠转义在 CSV 中并不常见，更多见于其他文本格式。因此，在设计 CSV 解析器时，优先考虑双引号转义双引号的方式。
⑤ 空白符处理 (Whitespace Handling)：CSV 文件中字段周围的空白符（空格、制表符）处理方式不尽相同。
▮▮▮▮⚝ 忽略空白符：有些 CSV 解析器会自动忽略字段开始和结束的空白符。例如，" value " 会被解析为 value。
▮▮▮▮⚝ 保留空白符：有些解析器会保留字段周围的空白符。" value " 会被解析为 value。
▮▮▮▮⚝ 空白符作为分隔符：在某些变体中，连续的空白符甚至可以作为字段分隔符。
在设计解析器时，需要明确空白符的处理策略，并根据实际需求进行选择。通常，忽略字段周围的空白符是比较友好的做法。
⑥ 首行标题 (Header Row)：CSV 文件的第一行通常作为标题行，包含列名（column names）。标题行有助于理解 CSV 文件的结构和字段含义。并非所有 CSV 文件都包含标题行，这取决于具体的应用场景。
1
Name,Age,City
2
Alice,30,New York
3
Bob,25,London
4
Charlie,35,Paris
在这个例子中，Name, Age, City 就是标题行。
总结
CSV 文件格式灵活且多样，但也因此带来了解析上的复杂性。一个健壮的 CSV 解析器需要能够处理：
⚝ 不同的分隔符：逗号、分号、制表符等。
⚝ 带引号和不带引号的字段。
⚝ 引号转义。
⚝ 空白符处理。
⚝ 可选的标题行。
在接下来的章节中，我们将使用 Boost.Spirit.Qi 构建一个能够处理这些情况的 CSV 解析器。
9.2 设计 CSV 解析器 (设计 CSV 解析器, Designing a CSV Parser)
设计 CSV 解析器的关键在于将 CSV 文件的格式规则转化为 Boost.Spirit.Qi 可以理解的语法规则（grammar rules）。我们将自顶向下地构建解析器，从 CSV 文件的整体结构开始，逐步细化到每个组成部分。
顶层结构：CSV 文件
一个 CSV 文件可以看作是由多行记录组成的序列，每行记录之后跟着一个换行符，文件的末尾可以是文件结束符（EOF）。我们可以定义一个 csv_file 规则来表示整个 CSV 文件。
1
// csv_file = *(csv_row >> eol);
这里 csv_row 代表 CSV 文件中的一行记录，eol 代表行尾符（End of Line，换行符），* 表示零个或多个，>> 是序列组合算子。这意味着 CSV 文件由零行或多行 CSV 记录组成，每行记录后必须跟着行尾符。
行记录：CSV 行
CSV 行 csv_row 由多个字段组成，字段之间用分隔符分隔。最后一个字段之后可能没有分隔符，直接到行尾。
1
// csv_row = csv_field % delimiter;
这里 csv_field 代表一个 CSV 字段，delimiter 代表字段分隔符，% 是 list 组合算子，表示一个或多个 csv_field，并使用 delimiter 分隔。
字段：CSV 字段
CSV 字段 csv_field 可以分为两种类型：带引号的字段和不带引号的字段。
1
// csv_field = quoted_field | non_quoted_field;
这里 quoted_field 代表带双引号的字段，non_quoted_field 代表不带双引号的字段，| 是选择组合算子。
带引号的字段：quoted_field
带引号的字段以双引号开始，以双引号结束，中间可以包含任意字符，包括转义的双引号 ""。
1
// quoted_field = '"' >> *quoted_char >> '"';
2
// quoted_char = escaped_quote | regular_char;
3
// escaped_quote = "\"\"" >> attr('"'); // 解析 "" 为 "
4
// regular_char = char_ - '"'; // 除 " 以外的任意字符
⚝ '"'：匹配双引号字符。
⚝ *quoted_char：零个或多个 quoted_char。
⚝ quoted_char：可以是转义的双引号 escaped_quote，也可以是普通字符 regular_char。
⚝ escaped_quote = "\"\"" >> attr('"')：匹配两个连续的双引号 ""，并将其属性设置为一个双引号 "。attr('"') 用于生成属性值。
⚝ regular_char = char_ - '"'：匹配除了双引号以外的任意字符。char_ 是匹配任意字符的预定义 parser，- '"' 是排除算子，排除双引号。
不带引号的字段：non_quoted_field
不带引号的字段由不包含分隔符、引号和换行符的字符组成。
1
// non_quoted_field = *non_quote_char;
2
// non_quote_char = char_ - delimiter - '"' - eol;
⚝ *non_quote_char：零个或多个 non_quote_char。
⚝ non_quote_char = char_ - delimiter - '"' - eol：匹配除了分隔符、双引号和行尾符以外的任意字符。
分隔符和行尾符：delimiter 和 eol
分隔符 delimiter 和行尾符 eol 可以根据实际情况定义。对于标准的逗号分隔 CSV 文件，分隔符是逗号 ,，行尾符是换行符 \n 或回车换行符 \r\n。
1
// delimiter = char_(',');
2
// eol = eol_p; // eol_p 可以匹配 \r, \n, or \r\n
⚝ char_(',')：匹配逗号字符。
⚝ eol_p：是 Spirit.Qi 预定义的 parser，可以匹配 \r, \n, 或 \r\n 等各种行尾符。
空白符处理：skipper
为了忽略字段周围的空白符，我们可以使用 Spirit.Qi 的 skipper 功能。默认情况下，Spirit.Qi 使用 space 作为 skipper，会跳过空格、制表符等空白符。如果需要自定义 skipper，例如只跳过空格和制表符，但不跳过换行符，可以自定义 skipper parser。
1
// skipper = space; // 使用默认的 space skipper
2
// 或者自定义 skipper，例如只跳过空格和制表符
3
// skipper = space | tab;
属性 (Attribute) 设计
我们需要考虑如何存储解析后的 CSV 数据。一个 CSV 文件可以表示为一个二维的字符串向量 std::vector<std::vector<std::string>>，其中外层 vector 代表行，内层 vector 代表字段。
⚝ csv_file 的属性可以是 std::vector<std::vector<std::string>>。
⚝ csv_row 的属性可以是 std::vector<std::string>。
⚝ csv_field 的属性可以是 std::string。
通过语义动作，我们可以将解析得到的字符序列转换为字符串，并将字段、行、文件组装成最终的数据结构。
总结
通过以上分析，我们得到了 CSV 解析器的基本设计框架。接下来，我们将根据这个设计框架，使用 Boost.Spirit.Qi 实现 CSV 解析器，并进行代码实现和测试。
9.3 代码实现与测试 (代码实现与测试, Code Implementation and Testing)
现在我们将把 9.2 节的设计转化为 C++ 代码，并使用 Boost.Spirit.Qi 实现 CSV 解析器。
代码框架
首先，包含必要的头文件，并定义命名空间。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/phoenix.hpp>
3
#include <iostream>
4
#include <string>
5
#include <vector>
6
7
namespace qi = boost::spirit::qi;
8
namespace phoenix = boost::phoenix;
9
10
using namespace qi::labels;
11
using namespace std;
定义 CSV 语法规则
根据 9.2 节的设计，我们定义 CSV 文件的语法规则。
1
template <typename Iterator, typename CSVData>
2
struct csv_parser : qi::grammar<Iterator, CSVData(), qi::space_type> { // 使用 space_type 作为 skipper
3
csv_parser() : csv_parser::base_type(csv_file) {
4
csv_file = *(csv_row >> qi::eol) > qi::eoi; // 确保解析到文件末尾
5
6
csv_row = (
7
csv_field % delimiter
8
);
9
10
csv_field = quoted_field | non_quoted_field;
11
12
quoted_field =
13
qi::lexeme['"' >> *(escaped_quote | regular_char) >> '"']; // lexeme 阻止 skipper 跳过引号内的空白符
14
escaped_quote = qi::lit("\"\"") >> qi::attr('"');
15
regular_char = qi::char_ - '"';
16
17
non_quoted_field = qi::lexeme[*(non_quote_char)]; // lexeme 阻止 skipper 跳过非引号字段内的空白符
18
non_quote_char = qi::char_ - delimiter - '"' - qi::eol;
19
20
delimiter = qi::char_(','); // 逗号分隔符
21
22
// debug names for rules (optional, for debugging)
23
csv_file.name("csv_file");
24
csv_row.name("csv_row");
25
csv_field.name("csv_field");
26
quoted_field.name("quoted_field");
27
escaped_quote.name("escaped_quote");
28
regular_char.name("regular_char");
29
non_quoted_field.name("non_quoted_field");
30
non_quote_char.name("non_quote_char");
31
delimiter.name("delimiter");
32
33
qi::on_error<qi::fail>(csv_file,
34
phoenix::bind(&csv_parser::error_handler, this, _1, _2, _3, _4)
35
);
36
}
37
38
void error_handler(Iterator const& first, Iterator const& last,
39
phoenix::what_t const& what, std::string const& rule_name)
40
{
41
std::string snapshot = "...";
42
if (first != last) snapshot = std::string(first, std::min(first + 10, last));
43
std::cerr
44
<< "Error! Parsing failed at: \"" << snapshot
45
<< "...\" in rule " << rule_name << std::endl;
46
}
47
48
49
qi::rule<Iterator, CSVData(), qi::space_type> csv_file;
50
qi::rule<Iterator, std::vector<std::string>(), qi::space_type> csv_row;
51
qi::rule<Iterator, std::string(), qi::space_type> csv_field;
52
qi::rule<Iterator, std::string(), qi::space_type> quoted_field;
53
qi::rule<Iterator, char(), qi::space_type> escaped_quote;
54
qi::rule<Iterator, char(), qi::space_type> regular_char;
55
qi::rule<Iterator, std::string(), qi::space_type> non_quoted_field;
56
qi::rule<Iterator, char(), qi::space_type> non_quote_char;
57
qi::rule<Iterator, char(), qi::space_type> delimiter;
58
};
解析 CSV 数据
编写 main 函数，读取 CSV 字符串，并使用 csv_parser 进行解析。
1
int main() {
2
std::string csv_text = R"(Name,Age,City
3
"Alice, Smith",30,"New York"
4
Bob,25,London
5
Charlie,35,"Paris, France"
6
)"; // 使用 Raw string literal
7
8
using Iterator = std::string::const_iterator;
9
Iterator begin = csv_text.begin();
10
Iterator end = csv_text.end();
11
12
csv_parser<Iterator, std::vector<std::vector<std::string>>> parser;
13
std::vector<std::vector<std::string>> csv_data;
14
15
bool success = qi::phrase_parse(
16
begin, end,
17
parser,
18
qi::space, // 使用 space skipper，跳过 CSV 内容前的空白符
19
csv_data
20
);
21
22
if (success && begin == end) {
23
std::cout << "Parsing successful!" << std::endl;
24
for (const auto& row : csv_data) {
25
for (const auto& field : row) {
26
std::cout << "[" << field << "] ";
27
}
28
std::cout << std::endl;
29
}
30
} else {
31
std::cerr << "Parsing failed!" << std::endl;
32
if (begin != end) {
33
std::cerr << "Remaining unparsed input: \"" << std::string(begin, end) << "\"" << std::endl;
34
}
35
}
36
37
return 0;
38
}
编译和运行
确保你已经安装了 Boost 库，并配置了编译环境。使用支持 C++14 或更高版本的编译器编译代码。例如，使用 g++ 编译：
1
g++ -std=c++14 csv_parser.cpp -o csv_parser
运行编译后的可执行文件：
1
./csv_parser
测试与验证
使用不同的 CSV 数据进行测试，包括：
① 基本 CSV 数据：
1
Name,Age,City
2
Alice,30,New York
3
Bob,25,London
4
Charlie,35,Paris
② 带引号的字段：
1
Name,Address
2
"Alice, Smith","123 Main St, Anytown"
3
Bob,456 Oak Ave
③ 包含转义引号的字段：
1
Value
2
"He said ""Hello""."
④ 空 CSV 文件：
1
⑤ 包含空白符的字段：
1
Name,Age,City
2
Alice , 30 , New York
通过充分的测试，验证解析器的正确性和健壮性。可以根据测试结果调整语法规则和代码实现，例如修改空白符处理策略、增加错误处理机制等。
代码解释
⚝ qi::grammar<Iterator, CSVData(), qi::space_type>：定义一个 Spirit.Qi 语法分析器，输入迭代器类型为 Iterator，属性类型为 CSVData，skipper 类型为 qi::space_type（使用空格作为 skipper）。
⚝ qi::lexeme[...]：lexeme 指令用于阻止 skipper 跳过其内部规则匹配的字符。这对于带引号和不带引号的字段非常重要，因为我们不希望跳过字段内容中的空白符。
⚝ qi::eoi：eoi (End of Input) parser 确保解析器解析到输入的末尾。
⚝ qi::on_error<qi::fail>(...)：错误处理机制，当解析失败时，会调用 error_handler 函数输出错误信息。
⚝ qi::phrase_parse(...)：使用 phrase parser 进行解析，phrase parser 会使用 skipper 跳过输入中的空白符。
⚝ R"(...)"：Raw string literal，用于定义包含特殊字符的字符串，避免过多的转义。
扩展与改进
这个 CSV 解析器只是一个基础版本。可以根据实际需求进行扩展和改进，例如：
⚝ 支持自定义分隔符：将分隔符作为参数传递给 csv_parser，使其可以解析不同分隔符的 CSV 文件。
⚝ 更完善的错误处理：提供更详细的错误信息，例如错误发生的行号和列号。
⚝ 性能优化：对于大型 CSV 文件，可以考虑性能优化，例如使用更高效的 skipper、减少回溯等。
⚝ 更灵活的属性处理：使用 Boost.Fusion 或其他库，实现更复杂的属性类型和转换。
通过本章的学习和实践，你应该能够掌握使用 Boost.Spirit.Qi 解析 CSV 文件的基本方法，并能够根据实际需求构建更复杂的文本解析器。
END_OF_CHAPTER
10. chapter 10： 实战案例：解析 JSON 数据 (实战案例：解析 JSON 数据, Practical Case: Parsing JSON Data)
10.1 JSON 数据格式详解 (JSON Data Format Explanation)
JSON (JavaScript Object Notation) 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。它基于 JavaScript 编程语言的一个子集，但独立于语言，并已被广泛应用于 Web 应用中，作为服务器与客户端之间数据传输的主要格式。理解 JSON 的数据格式是使用 Boost.Spirit 解析 JSON 数据的先决条件。
JSON 数据格式主要由以下几种数据类型构成：
⚝ 值 (Value)：JSON 的值可以是以下类型：
▮▮▮▮⚝ 字符串 (String)：由双引号 " 包围的 Unicode 字符序列。例如，"hello"，"你好"。字符串中可以包含转义字符，例如 \n (换行), \t (制表符), \\ (反斜杠), \" (双引号) 等。
▮▮▮▮⚝ 数字 (Number)：可以是整数或浮点数，可以使用十进制或指数形式。例如，123，-456，3.14，6.02e23。JSON 数字格式与 JavaScript 的 Number 类型类似，但不完全相同，例如 JSON 中不允许 NaN 和 Infinity。
▮▮▮▮⚝ 布尔值 (Boolean)：只有两个值，true (真) 和 false (假)。
▮▮▮▮⚝ 空值 (Null)：只有一个值，null，表示空或不存在的值。
▮▮▮▮⚝ 对象 (Object)：由花括号 {} 包围的键值对 (key-value pairs) 集合。键值对之间用逗号 , 分隔。每个键值对包含一个键 (key) 和一个值 (value)，键必须是字符串，值可以是任何 JSON 值类型。例如，{"name": "John", "age": 30}。
▮▮▮▮⚝ 数组 (Array)：由方括号 [] 包围的有序值列表。数组中的值之间用逗号 , 分隔。数组的值可以是任何 JSON 值类型。例如，[1, 2, "apple", true]。
JSON 的基本结构可以递归定义。一个 JSON 文档可以是一个 JSON 值。由于 JSON 的值可以是对象或数组，而对象和数组又可以包含其他 JSON 值，因此可以构建非常复杂的数据结构。
以下是一些 JSON 格式的示例，帮助你更好地理解其结构：
示例 1：简单的 JSON 对象
1
{
2
"name": "Alice",
3
"age": 25,
4
"city": "New York"
5
}
示例 2：包含数组的 JSON 对象
1
{
2
"name": "Bob",
3
"hobbies": ["reading", "hiking", "coding"]
4
}
示例 3：嵌套的 JSON 对象
1
{
2
"name": "Charlie",
3
"address": {
4
"street": "Main St",
5
"city": "Los Angeles"
6
}
7
}
示例 4：包含对象的数组
1
[
2
{ "item": "apple", "price": 1.0 },
3
{ "item": "banana", "price": 0.5 }
4
]
示例 5：复杂的 JSON 结构
1
{
2
"widget": {
3
"debug": "on",
4
"window": {
5
"name": "main_window",
6
"width": 640,
7
"height": 480
8
},
9
"image": {
10
"src": "Images/Sun.png",
11
"name": "sun1",
12
"hOffset": 250,
13
"vOffset": 250,
14
"alignment": "center"
15
},
16
"text": {
17
"data": "Click Here",
18
"size": 36,
19
"style": "bold",
20
"name": "text1",
21
"hOffset": 250,
22
"vOffset": 100,
23
"alignment": "center",
24
"onMouseUp": "sun1.opacity = (sun1.opacity / 100) * 90;"
25
}
26
}
27
}
在设计 JSON 解析器时，我们需要考虑到 JSON 格式的这些规则和结构。Boost.Spirit 提供了强大的工具来定义和实现符合 JSON 语法规则的解析器。接下来的章节将介绍如何使用 Boost.Spirit.Qi 来构建一个 JSON 解析器。
10.2 设计 JSON 解析器 (Designing a JSON Parser)
设计 JSON 解析器的核心任务是将 JSON 文本转换为程序可以理解和操作的数据结构。使用 Boost.Spirit.Qi，我们可以通过定义一系列的规则 (rules) 来描述 JSON 的语法结构，并利用语义动作 (semantic actions) 将解析结果转换为 C++ 对象。
在设计 JSON 解析器之前，我们需要确定如何表示解析后的 JSON 数据。一种常见的做法是使用 boost::variant 或 std::variant 来表示 JSON 的不同值类型，例如字符串、数字、布尔值、空值、对象和数组。或者，我们也可以自定义 C++ 结构体或类来更具体地表示 JSON 对象和数组。为了简化示例，我们先考虑使用 boost::variant 来存储 JSON 值。
首先，我们定义一个 json_value 类型，它可以是 JSON 中的任何值类型：
1
#include <boost/variant.hpp>
2
#include <vector>
3
#include <map>
4
#include <string>
5
6
namespace json {
7
using json_value = boost::variant<
8
std::string,
9
double,
10
bool,
11
nullptr_t,
12
std::vector<json_value>,
13
std::map<std::string, json_value>
14
>;
15
}
接下来，我们开始设计 Spirit.Qi 解析规则。我们需要为 JSON 的每种数据类型定义相应的解析规则。
① 空白符 (Whitespace)：JSON 语法中，空白符在语法元素之间是允许的，但不影响语义。我们需要定义一个 skipper 来处理空白符。通常，空格、制表符、换行符和回车符被视为空白符。
② 字符串 (String)：JSON 字符串以双引号开始和结束，可以包含转义字符。我们需要解析双引号包围的内容，并处理转义字符。
③ 数字 (Number)：JSON 数字可以是整数或浮点数。我们需要解析符合 JSON 数字格式的字符串，并将其转换为 double 类型。
④ 布尔值 (Boolean)：JSON 布尔值是 true 或 false。我们需要解析这两个关键字，并将其转换为 C++ 的 bool 类型。
⑤ 空值 (Null)：JSON 空值是 null。我们需要解析这个关键字，并将其表示为 nullptr_t 或其他合适的空值表示。
⑥ 对象 (Object)：JSON 对象以花括号 {} 开始和结束，包含键值对，键值对之间用逗号分隔，键和值之间用冒号 : 分隔。我们需要解析花括号内的键值对，并将结果存储在 std::map<std::string, json_value> 中。
⑦ 数组 (Array)：JSON 数组以方括号 [] 开始和结束，包含值列表，值之间用逗号分隔。我们需要解析方括号内的值，并将结果存储在 std::vector<json_value> 中。
基于以上分析，我们可以初步设计 Spirit.Qi 的解析规则。我们使用 rule 对象来定义这些规则，并使用 Spirit.Qi 提供的预定义解析器和组合器来构建复杂的规则。
例如，一个简单的 JSON 字符串规则可以定义为：
1
qi::rule<std::string::iterator, std::string(), qi::space_type> string_rule;
2
string_rule = qi::lexeme['"' > *('\\' >> qi::char_ | ~qi::char_('"')) > '"'];
这个规则 string_rule 使用 qi::lexeme 来阻止 skipper 跳过字符串内部的空白符。它匹配一个双引号，然后是零个或多个字符，这些字符可以是转义字符（'\\' >> qi::char_）或非双引号字符（~qi::char_('"')），最后以另一个双引号结束。
类似地，我们可以定义数字、布尔值、空值、对象和数组的规则。然后，我们可以将这些规则组合起来，形成一个完整的 JSON 解析器。
在设计解析规则时，我们需要考虑以下几个关键点：
⚝ 规则的组合：使用 Spirit.Qi 的组合器（如 |，>>，*，+，&，! 等）将简单的规则组合成复杂的规则，以匹配 JSON 的语法结构。
⚝ 属性的传递：确保每个规则能够正确地生成其对应的属性值，并将属性值传递给组合规则或语义动作。例如，string_rule 应该生成一个 std::string 类型的属性值。
⚝ 语义动作：使用语义动作在解析过程中执行自定义操作，例如将解析后的字符串转换为数字，或者将解析后的键值对存储到 map 中。
⚝ 错误处理：考虑如何处理 JSON 文本中的语法错误，例如格式不正确的字符串、数字或结构。Spirit.Qi 提供了错误处理机制，可以用来报告错误位置和类型。
⚝ 性能优化：对于大型 JSON 数据，性能可能成为一个问题。我们需要考虑如何优化解析器的性能，例如使用合适的解析器组合器，避免不必要的回溯，以及使用编译期优化等技术。
在接下来的章节中，我们将详细展示如何使用 Boost.Spirit.Qi 实现这些规则，并构建一个完整的 JSON 解析器，并进行代码实现和测试。
10.3 代码实现与测试 (Code Implementation and Testing)
现在我们开始实现 JSON 解析器。我们将使用 Boost.Spirit.Qi 库，并结合之前设计的规则。首先，确保你已经安装了 Boost 库，并且你的编译环境配置正确。
我们创建一个名为 json_parser.cpp 的文件，并包含必要的头文件：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/spirit/include/phoenix.hpp>
3
#include <boost/variant.hpp>
4
#include <iostream>
5
#include <string>
6
#include <vector>
7
#include <map>
8
9
namespace qi = boost::spirit::qi;
10
namespace phoenix = boost::phoenix;
11
12
namespace json {
13
using json_value = boost::variant<
14
std::string,
15
double,
16
bool,
17
nullptr_t,
18
std::vector<json_value>,
19
std::map<std::string, json_value>
20
>;
21
22
template <typename Iterator>
23
struct json_parser : qi::grammar<Iterator, json_value(), qi::space_type> {
24
json_parser() : json_parser::base_type(start) {
25
using qi::lit;
26
using qi::lexeme;
27
using qi::double_;
28
using qi::bool_;
29
using qi::null_;
30
using qi::char_;
31
using qi::space;
32
using qi:: Kleene;
33
using qi::rule;
34
35
string_ %= lexeme['"' > *('\\' >> char_ | ~char_('"')) > '"'];
36
number_ %= double_;
37
bool_ %= bool_;
38
null_ %= null_;
39
40
value_ %=
41
string_
42
| number_
43
| bool_
44
| null_
45
| object_
46
| array_
47
;
48
49
object_ %= '{' > -(key_value_pair_ % ',') > '}';
50
key_value_pair_ %= string_ > ':' > value_;
51
52
array_ %= '[' > -(value_ % ',') > ']';
53
54
start %= value_;
55
56
string_.name("string");
57
number_.name("number");
58
bool_.name("bool");
59
null_.name("null");
60
value_.name("value");
61
object_.name("object");
62
key_value_pair_.name("key_value_pair");
63
array_.name("array");
64
start.name("start");
65
66
qi::on_error<qi::fail>(start,
67
phoenix::bind(&json_parser::error_handler, this, _1, _2, _3, _4)
68
);
69
}
70
71
qi::rule<Iterator, std::string(), qi::space_type> string_;
72
qi::rule<Iterator, double(), qi::space_type> number_;
73
qi::rule<Iterator, bool(), qi::space_type> bool_;
74
qi::rule<Iterator, nullptr_t(), qi::space_type> null_;
75
qi::rule<Iterator, json_value(), qi::space_type> value_;
76
qi::rule<Iterator, std::map<std::string, json_value>(), qi::space_type> object_;
77
qi::rule<Iterator, std::pair<std::string, json_value>(), qi::space_type> key_value_pair_;
78
qi::rule<Iterator, std::vector<json_value>(), qi::space_type> array_;
79
qi::rule<Iterator, json_value(), qi::space_type> start;
80
81
void error_handler(Iterator const& first, Iterator const& last,
82
Iterator const& error_pos, boost::spirit::info const& what)
83
{
84
std::string context = std::string(first, last);
85
std::string around_error;
86
int error_offset = std::distance(first, error_pos);
87
int context_start = std::max(0, error_offset - 10);
88
int context_end = std::min((int)context.length(), error_offset + 10);
89
around_error = context.substr(context_start, context_end - context_start);
90
91
std::cerr << "解析错误! 位置: " << error_offset << std::endl;
92
std::cerr << "错误附近上下文: \"" << around_error << "...\"" << std::endl;
93
std::cerr << "期望: " << what << std::endl;
94
}
95
};
96
}
97
98
int main() {
99
std::string json_text = R"({"name": "Alice", "age": 25, "city": "New York"})";
100
// std::string json_text = R"([1, 2, "apple", true])";
101
// std::string json_text = R"({"widget": {"debug": "on", "window": {"name": "main_window", "width": 640, "height": 480}}})";
102
// std::string json_text = R"({"invalid json")"; // 测试错误处理
103
104
using Iterator = std::string::const_iterator;
105
Iterator begin = json_text.begin();
106
Iterator end = json_text.end();
107
108
json::json_parser<Iterator> parser;
109
json::json_value result;
110
111
bool success = qi::phrase_parse(begin, end, parser, qi::space, result);
112
113
if (success && begin == end) {
114
std::cout << "解析成功!" << std::endl;
115
// 这里可以进一步处理解析结果，例如打印 JSON 值
116
// 为了简化，这里只打印类型信息
117
if (result.type() == typeid(std::map<std::string, json::json_value>)) {
118
std::cout << "解析结果类型: JSON Object" << std::endl;
119
} else if (result.type() == typeid(std::vector<json::json_value>)) {
120
std::cout << "解析结果类型: JSON Array" << std::endl;
121
} else if (result.type() == typeid(std::string)) {
122
std::cout << "解析结果类型: JSON String" << std::endl;
123
} else if (result.type() == typeid(double)) {
124
std::cout << "解析结果类型: JSON Number" << std::endl;
125
} else if (result.type() == typeid(bool)) {
126
std::cout << "解析结果类型: JSON Boolean" << std::endl;
127
} else if (result.type() == typeid(nullptr_t)) {
128
std::cout << "解析结果类型: JSON Null" << std::endl;
129
}
130
} else {
131
std::cerr << "解析失败!" << std::endl;
132
if (begin != end) {
133
std::cerr << "剩余未解析部分: \"" << std::string(begin, end) << "\"" << std::endl;
134
}
135
}
136
137
return 0;
138
}
代码解释：
- 头文件包含：包含了 Boost.Spirit.Qi, Boost.Phoenix, Boost.Variant 以及标准库的头文件。
- 命名空间和
json_value定义：定义了json命名空间和json_value类型，用于存储解析后的 JSON 值。 json_parser结构体：
▮▮▮▮⚝ 继承自qi::grammar，定义了 JSON 解析器的语法规则。
▮▮▮▮⚝ 构造函数中定义了各种规则，例如string_,number_,bool_,null_,object_,array_,value_,start。
▮▮▮▮⚝ 使用qi::lexeme处理字符串，qi::double_解析数字，qi::bool_解析布尔值，qi::null_解析空值。
▮▮▮▮⚝ 使用|组合符定义value_规则，表示 JSON 值可以是字符串、数字、布尔值、空值、对象或数组。
▮▮▮▮⚝ 使用'{'',''}'和'['','']'以及':'等符号和组合符定义object_,key_value_pair_,array_规则，以匹配 JSON 对象和数组的结构。
▮▮▮▮⚝start规则是解析的入口点，设置为value_，表示整个 JSON 文档是一个 JSON 值。
▮▮▮▮⚝ 使用qi::on_error定义了错误处理函数error_handler，当解析失败时会被调用，输出错误信息。error_handler函数：当解析出错时，这个函数会被调用，它会输出错误位置附近的上下文信息以及 Spirit 期望的输入类型，帮助用户诊断错误。main函数：
▮▮▮▮⚝ 定义了一个 JSON 字符串json_text用于测试。你可以修改这个字符串来测试不同的 JSON 结构和错误情况。
▮▮▮▮⚝ 创建json_parser对象。
▮▮▮▮⚝ 调用qi::phrase_parse函数进行解析。qi::phrase_parse会跳过空白符（由qi::space指定）。
▮▮▮▮⚝ 检查解析是否成功，并输出解析结果的类型或错误信息。
编译和运行：
使用支持 C++11 或更高版本的编译器编译代码，并链接 Boost 库。例如，使用 g++ 编译：
1
g++ -std=c++11 json_parser.cpp -o json_parser
然后运行生成的可执行文件：
1
./json_parser
测试：
你可以修改 main 函数中的 json_text 变量，使用不同的 JSON 字符串进行测试，包括：
⚝ 有效的 JSON 对象、数组、字符串、数字、布尔值和空值。
⚝ 嵌套的 JSON 结构。
⚝ 包含空白符的 JSON 文本。
⚝ 无效的 JSON 文本，例如语法错误、格式不正确等，来测试错误处理机制。
通过运行和测试，你可以验证 JSON 解析器是否能够正确解析 JSON 数据，并处理错误情况。这个示例提供了一个基本的 JSON 解析器框架，你可以根据需要进行扩展和优化，例如添加更完善的错误报告、支持更多的 JSON 特性、或者优化性能。
END_OF_CHAPTER
11. chapter 11： 实战案例：配置文件解析 (实战案例, Practical Case: Configuration File Parsing)
11.1 配置文件格式设计 (配置文件格式设计, Configuration File Format Design)
在软件开发中，配置文件扮演着至关重要的角色。它们允许我们在不重新编译代码的情况下修改程序的行为，从而极大地提高了软件的灵活性和可维护性。一个好的配置文件格式应该易于阅读、易于编写，并且易于解析。本节将探讨配置文件格式设计的一些关键考虑因素，并为后续的 Spirit 解析器实现奠定基础。
① 常见的配置文件格式：
⚝ INI 文件：INI 文件是一种简单文本格式，常用于 Windows 操作系统和许多其他应用程序中。它以节（section）和键值对（key-value pair）为基本结构，易于人眼阅读和编辑。然而，INI 文件格式相对简单，缺乏对复杂数据结构的支持。
⚝ JSON 文件：JSON (JavaScript Object Notation) 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。JSON 支持键值对和数组等复杂数据结构，被广泛应用于 Web 应用和数据存储。
⚝ YAML 文件：YAML (YAML Ain't Markup Language) 是一种人类友好的数据序列化标准。YAML 旨在具有良好的可读性，它使用缩进表示层级关系，支持注释，并且可以表示复杂的数据结构，如列表、字典等。YAML 常用于配置文件、数据交换和跨语言数据共享。
⚝ XML 文件：XML (eXtensible Markup Language) 是一种标记语言，设计宗旨是传输和存储数据，而非显示数据。XML 具有良好的结构化和自描述性，但其语法相对冗长，可读性不如 JSON 和 YAML。
⚝ 自定义格式：在某些特定场景下，为了满足特定的需求，开发者可能会选择自定义配置文件格式。自定义格式可以根据应用的需求进行优化，但也需要投入更多的工作来设计和实现解析器。
② 配置文件格式设计原则：
⚝ 可读性 (Readability)：配置文件首先是给人看的，因此可读性至关重要。清晰的结构、简洁的语法和适当的注释能够帮助用户快速理解和修改配置。
⚝ 易写性 (Writability)：配置文件应该易于编写，避免过于复杂的语法和规则。简单的格式可以减少用户出错的可能性，提高配置效率。
⚝ 易解析性 (Parsability)：配置文件需要被程序解析，因此易解析性也是一个重要的考虑因素。选择易于解析的格式，或者设计易于解析的自定义格式，可以降低解析器的开发难度和提高解析效率。
⚝ 灵活性 (Flexibility)：配置文件应该能够灵活地表达各种配置信息，以适应程序不断变化的需求。支持多种数据类型、嵌套结构和扩展机制可以提高配置文件的灵活性。
⚝ 可扩展性 (Extensibility)：随着软件功能的扩展，配置文件可能需要添加新的配置项。良好的可扩展性可以保证配置文件能够适应未来的变化，而无需进行大的改动。
⚝ 安全性 (Security)：如果配置文件中包含敏感信息（如密码、密钥等），则需要考虑安全性。可以采用加密、权限控制等措施来保护配置文件的安全。
③ 本章示例配置文件格式设计：
为了演示 Boost.Spirit 在配置文件解析中的应用，我们设计一个简单的、类 INI 风格的配置文件格式。该格式具有以下特点：
⚝ 节 (Section)：配置文件由多个节组成，每个节以 [section_name] 形式开始，节名用方括号括起来。节用于组织相关的配置项。
⚝ 键值对 (Key-Value Pair)：每个节下面包含多个键值对，格式为 key = value。键和值之间使用等号 = 分隔。
⚝ 注释 (Comment)：以 # 或 ; 开头的行被视为注释，解析器应忽略注释行。
⚝ 值类型 (Value Type)：值可以是字符串、整数、浮点数或布尔值。
▮▮▮▮⚝ 字符串 (String)：用双引号 " 或单引号 ' 括起来的文本。如果不需要引号，则视为纯文本字符串。
▮▮▮▮⚝ 整数 (Integer)：由数字组成的字符串，可以有正负号。
▮▮▮▮⚝ 浮点数 (Floating-point Number)：包含小数点的数字字符串，可以有正负号和指数表示。
▮▮▮▮⚝ 布尔值 (Boolean)：true、false、yes、no、on、off，不区分大小写。
⚝ 空白符 (Whitespace)：忽略键、值和分隔符周围的空白符（空格、制表符）。
⚝ 列表 (List)：使用逗号 , 分隔的值列表，例如 list_key = value1, value2, value3。
示例配置文件：
1
# 这是一个示例配置文件
2
; 另一行注释
3
4
[database]
5
host = "localhost"
6
port = 5432
7
username = 'admin'
8
password = "secret"
9
10
[server]
11
server_ip = 192.168.1.100
12
server_port = 8080
13
max_connections = 1000
14
enabled_features = feature1, feature2, feature3 # 列表值
15
debug_mode = true
16
log_level = "INFO"
17
float_value = 3.14159
18
integer_value = -123
这个配置文件格式相对简单，但足以演示如何使用 Boost.Spirit 进行解析。在接下来的章节中，我们将使用 Spirit.Qi 来构建一个解析器，用于读取和解析这种格式的配置文件。
11.2 使用 Spirit 解析配置文件 (使用 Spirit 解析配置文件, Parsing Configuration Files with Spirit)
在上一节中，我们设计了一个简单的配置文件格式。本节将使用 Boost.Spirit.Qi 库来构建一个解析器，用于解析这种格式的配置文件。我们将逐步构建解析器，从简单的元素开始，逐步组合成完整的配置文件解析器。
① Spirit.Qi 解析器设计思路：
我们将采用自底向上的方法构建解析器，首先定义基本元素的解析规则，例如空白符、注释、标识符、字符串、数字等，然后将这些基本元素组合成更复杂的规则，例如键值对、节、配置文件等。
② 基本元素解析器：
⚝ 空白符解析器 (Whitespace Parser)：我们使用 space 解析器来处理空白符。为了更灵活地控制空白符的处理，我们可以使用 qi::space 指令，并自定义跳过符 (skipper)。在本例中，我们简单地使用默认的 space 解析器即可。
1
auto skipper = qi::space; // 默认空白符跳过符
⚝ 注释解析器 (Comment Parser)：注释以 # 或 ; 开头，直到行尾。我们可以使用 qi::char_('#', ';') 匹配注释起始符，然后使用 qi::eol 匹配行尾。qi::lexeme[*qi::char_ - qi::eol] 可以匹配注释内容，但我们在这里只需要跳过注释行，所以可以简化为：
1
auto comment = qi::char_('#', ';') >> *qi::char_ - qi::eol >> qi::eol;
⚝ 标识符解析器 (Identifier Parser)：标识符用于表示节名和键名。我们定义标识符为以字母或下划线开头，后跟字母、数字或下划线的字符串。
1
auto identifier = qi::lexeme[qi::alpha | qi::char_('_') >> *(qi::alnum | qi::char_('_'))];
⚝ 字符串解析器 (String Parser)：字符串可以用双引号或单引号括起来，也可以是不带引号的纯文本字符串。
1
auto quoted_string = qi::lexeme[qi::char_('"') >> *('\\' >> qi::char_ | qi::char_ - '"') >> qi::char_('"')]
2
| qi::lexeme[qi::char_('\'') >> *('\\' >> qi::char_ | qi::char_ - '\'') >> qi::char_('\'')];
3
auto unquoted_string = qi::lexeme[+qi::char_("a-zA-Z0-9_.-")]; // 简化版本，实际应用中可能需要更严格的定义
4
auto string_value = quoted_string | unquoted_string;
⚝ 整数解析器 (Integer Parser)：整数可以有正负号。
1
auto int_value = qi::lexeme[qi::int_]; // 使用预定义的 int_ 解析器
⚝ 浮点数解析器 (Float Parser)：浮点数可以有正负号和指数表示。
1
auto float_value = qi::lexeme[qi::double_]; // 使用预定义的 double_ 解析器
⚝ 布尔值解析器 (Boolean Parser)：布尔值可以是 true、false、yes、no、on、off，不区分大小写。
1
auto bool_value = qi::lexeme[qi::no_case["true"] >> qi::attr(true)
2
| qi::no_case["false"] >> qi::attr(false)
3
| qi::no_case["yes"] >> qi::attr(true)
4
| qi::no_case["no"] >> qi::attr(false)
5
| qi::no_case["on"] >> qi::attr(true)
6
| qi::no_case["off"] >> qi::attr(false)];
这里使用了 qi::no_case 指令实现大小写不敏感匹配，qi::attr 用于为解析器赋予属性值。
⚝ 值列表解析器 (List Parser)：值列表是由逗号分隔的值组成的序列。
1
template <typename ValueParser>
2
auto list_value_parser(ValueParser value_parser) {
3
return value_parser % qi::char_(','); // 使用 % 运算符表示分隔符列表
4
}
这是一个模板函数，可以接受不同类型的值解析器，例如字符串列表、整数列表等。
③ 复合元素解析器：
⚝ 键值对解析器 (Key-Value Pair Parser)：键值对由标识符（键）、等号 = 和值组成。
1
template <typename ValueParser>
2
auto key_value_pair_parser(ValueParser value_parser) {
3
return identifier >> qi::omit[qi::char_('=')] >> value_parser; // omit 指令忽略 '=' 的属性
4
}
同样，这是一个模板函数，可以接受不同类型的值解析器。
⚝ 节解析器 (Section Parser)：节以 [section_name] 开始，包含多个键值对，直到下一个节或文件结束。
1
template <typename KeyValuePairParser>
2
auto section_parser(KeyValuePairParser key_value_pair_parser) {
3
return qi::omit[qi::char_('[')] >> identifier >> qi::omit[qi::char_(']')] >> qi::eol
4
>> *key_value_pair_parser; // * 运算符表示零个或多个键值对
5
}
这也是一个模板函数，接受键值对解析器作为参数。
⚝ 配置文件解析器 (Configuration File Parser)：配置文件由零个或多个节组成，可以包含注释和空白行。
1
template <typename SectionParser>
2
auto config_file_parser(SectionParser section_parser) {
3
return qi::skip(skipper) [ // 使用 skip 指令应用跳过符
4
*comment // 忽略注释行
5
>> *(section_parser | qi::eol) // 解析节或空行
6
];
7
}
④ 完整解析器代码示例：
1
#include <boost/spirit/include/qi.hpp>
2
#include <iostream>
3
#include <string>
4
#include <vector>
5
#include <map>
6
7
namespace qi = boost::spirit::qi;
8
namespace ascii = boost::spirit::ascii;
9
10
// ... (前面定义的各种解析器代码，例如 comment, identifier, string_value, int_value, float_value, bool_value, list_value_parser, key_value_pair_parser, section_parser, config_file_parser) ...
11
12
int main() {
13
std::string config_text = R"(
14
# 这是一个示例配置文件
15
; 另一行注释
16
17
[database]
18
host = "localhost"
19
port = 5432
20
username = 'admin'
21
password = "secret"
22
23
[server]
24
server_ip = 192.168.1.100
25
server_port = 8080
26
max_connections = 1000
27
enabled_features = feature1, feature2, feature3 # 列表值
28
debug_mode = true
29
log_level = "INFO"
30
float_value = 3.14159
31
integer_value = -123
32
)";
33
34
using iterator_type = std::string::const_iterator;
35
using ConfigMap = std::map<std::string, std::map<std::string, boost::variant<std::string, int, double, bool, std::vector<std::string>>>>;
36
ConfigMap config_data;
37
38
auto comment = qi::char_('#', ';') >> *qi::char_ - qi::eol >> qi::eol;
39
auto identifier = qi::lexeme[qi::alpha | qi::char_('_') >> *(qi::alnum | qi::char_('_'))];
40
auto quoted_string = qi::lexeme[qi::char_('"') >> *('\\' >> qi::char_ | qi::char_ - '"') >> qi::char_('"')]
41
| qi::lexeme[qi::char_('\'') >> *('\\' >> qi::char_ | qi::char_ - '\'') >> qi::char_('\'')];
42
auto unquoted_string = qi::lexeme[+qi::char_("a-zA-Z0-9_.-")];
43
auto string_value = quoted_string | unquoted_string;
44
auto int_value = qi::lexeme[qi::int_];
45
auto float_value = qi::lexeme[qi::double_];
46
auto bool_value = qi::lexeme[qi::no_case["true"] >> qi::attr(true)
47
| qi::no_case["false"] >> qi::attr(false)
48
| qi::no_case["yes"] >> qi::attr(true)
49
| qi::no_case["no"] >> qi::attr(false)
50
| qi::no_case["on"] >> qi::attr(true)
51
| qi::no_case["off"] >> qi::attr(false)];
52
53
auto list_value_parser = [&](auto value_parser) { return value_parser % qi::char_(','); };
54
auto key_value_pair_parser = [&](auto value_parser) { return identifier >> qi::omit[qi::char_('=')] >> value_parser; };
55
auto section_parser = [&](auto key_value_pair_parser) {
56
return qi::omit[qi::char_('[')] >> identifier >> qi::omit[qi::char_(']')] >> qi::eol
57
>> *key_value_pair_parser;
58
};
59
auto config_file_parser = [&](auto section_parser) {
60
return qi::skip(ascii::space) [
61
*comment
62
>> *(section_parser | qi::eol)
63
];
64
};
65
66
auto section_rule = section_parser(key_value_pair_parser([&](){
67
return string_value | float_value | int_value | bool_value | list_value_parser(string_value); // 支持多种值类型
68
}()));
69
auto config_file_rule = config_file_parser(section_rule);
70
71
72
iterator_type begin = config_text.begin();
73
iterator_type end = config_text.end();
74
75
bool success = qi::parse(begin, end, config_file_rule, config_data);
76
77
if (success && begin == end) {
78
std::cout << "Config file parsed successfully!" << std::endl;
79
// 打印解析结果 (仅用于演示)
80
for (const auto& section_pair : config_data) {
81
std::cout << "[" << section_pair.first << "]" << std::endl;
82
for (const auto& kv_pair : section_pair.second) {
83
std::cout << " " << kv_pair.first << " = ";
84
if (kv_pair.second.type() == typeid(std::string)) {
85
std::cout << boost::get<std::string>(kv_pair.second) << std::endl;
86
} else if (kv_pair.second.type() == typeid(int)) {
87
std::cout << boost::get<int>(kv_pair.second) << std::endl;
88
} else if (kv_pair.second.type() == typeid(double)) {
89
std::cout << boost::get<double>(kv_pair.second) << std::endl;
90
} else if (kv_pair.second.type() == typeid(bool)) {
91
std::cout << std::boolalpha << boost::get<bool>(kv_pair.second) << std::endl;
92
} else if (kv_pair.second.type() == typeid(std::vector<std::string>)) {
93
const auto& list = boost::get<std::vector<std::string>>(kv_pair.second);
94
std::cout << "[";
95
for (size_t i = 0; i < list.size(); ++i) {
96
std::cout << list[i] << (i < list.size() - 1 ? ", " : "");
97
}
98
std::cout << "]" << std::endl;
99
}
100
}
101
}
102
} else {
103
std::cerr << "Config file parsing failed!" << std::endl;
104
if (begin != end) {
105
std::cerr << "Remaining unparsed input: " << std::string(begin, end) << std::endl;
106
}
107
}
108
109
return 0;
110
}
这段代码演示了如何使用 Spirit.Qi 构建一个配置文件解析器。我们定义了各种解析规则，并将它们组合成一个完整的配置文件解析器。程序读取配置文件文本，使用 qi::parse 函数进行解析，并将解析结果存储在 config_data 变量中。最后，程序打印解析结果。
11.3 配置项的动态处理 (配置项的动态处理, Dynamic Handling of Configuration Items)
配置文件解析的最终目的是为了在程序中动态地使用配置项。解析器将配置文件内容转换为程序可以理解和操作的数据结构。本节将讨论如何动态地处理解析后的配置项，包括访问配置值、处理不同类型的值、以及实现默认值和可选配置项。
① 配置数据存储结构：
在上一节的代码示例中，我们使用了 std::map<std::string, std::map<std::string, boost::variant<std::string, int, double, bool, std::vector<std::string>>>> 作为配置数据的存储结构。
⚝ 外层 std::map: 键是节名（std::string），值是内层 std::map。
⚝ 内层 std::map: 键是键名（std::string），值是 boost::variant。
⚝ boost::variant<std::string, int, double, bool, std::vector<std::string>>: 用于存储不同类型的值，包括字符串、整数、浮点数、布尔值和字符串列表。
使用 boost::variant 可以方便地存储多种类型的值，并在需要时通过 boost::get 函数获取特定类型的值。
② 访问配置值：
解析配置文件后，我们可以通过节名和键名来访问配置值。例如，要获取 database 节下的 host 配置项的值，可以使用以下代码：
1
std::string host = boost::get<std::string>(config_data["database"]["host"]);
在访问配置值之前，应该先检查节名和键名是否存在，以避免访问不存在的元素导致程序崩溃。可以使用 config_data.count("section_name") 和 config_data["section_name"].count("key_name") 来检查。
③ 处理不同类型的值：
由于配置值可能具有不同的类型，我们需要根据实际类型进行处理。boost::variant 提供了 type() 方法来获取当前存储值的类型，以及 boost::get 函数来获取特定类型的值。在代码示例中，我们已经展示了如何根据 kv_pair.second.type() 来判断值的类型，并使用 boost::get 获取相应类型的值。
④ 实现默认值：
在某些情况下，我们希望为配置项设置默认值，当配置文件中没有指定该配置项时，程序使用默认值。我们可以通过在访问配置值时进行判断，如果配置项不存在，则使用默认值。
1
std::string log_level = "DEBUG"; // 默认日志级别
2
if (config_data.count("server") && config_data["server"].count("log_level")) {
3
log_level = boost::get<std::string>(config_data["server"]["log_level"]);
4
}
5
// 使用 log_level
更通用的方法可以封装一个函数，用于安全地获取配置值，并提供默认值。
1
template <typename T>
2
T get_config_value(const ConfigMap& config, const std::string& section, const std::string& key, const T& default_value) {
3
if (config.count(section) && config.at(section).count(key)) {
4
try {
5
return boost::get<T>(config.at(section).at(key));
6
} catch (const boost::bad_get& e) {
7
std::cerr << "Error: Type mismatch for config item [" << section << "][" << key << "]. Using default value." << std::endl;
8
}
9
}
10
return default_value;
11
}
12
13
// 使用示例
14
std::string host = get_config_value(config_data, "database", "host", std::string("localhost"));
15
int port = get_config_value(config_data, "database", "port", 3306);
16
bool debug_mode = get_config_value(config_data, "server", "debug_mode", false);
这个 get_config_value 函数模板可以安全地获取配置值，并处理类型不匹配的情况，同时提供默认值。
⑤ 处理可选配置项：
有些配置项是可选的，配置文件中可能存在，也可能不存在。我们可以通过检查配置项是否存在来判断是否需要处理该配置项。
1
if (config_data.count("server") && config_data["server"].count("optional_feature")) {
2
// 可选配置项存在，进行处理
3
std::string optional_feature = boost::get<std::string>(config_data["server"]["optional_feature"]);
4
std::cout << "Optional feature: " << optional_feature << std::endl;
5
} else {
6
// 可选配置项不存在，使用默认行为或忽略
7
std::cout << "Optional feature not configured." << std::endl;
8
}
⑥ 配置验证与错误处理：
在实际应用中，配置文件的内容可能不符合预期，例如值类型错误、值范围错误、缺少必要的配置项等。为了保证程序的健壮性，需要对解析后的配置数据进行验证，并进行适当的错误处理。
⚝ 类型验证：在使用 boost::get 获取配置值时，如果类型不匹配，会抛出 boost::bad_get 异常。可以使用 try-catch 块捕获异常并进行处理。
⚝ 范围验证：对于数值类型的配置项，可以验证其值是否在合理的范围内。
⚝ 必要性验证：检查必要的配置项是否都存在。
⚝ 自定义验证：根据业务逻辑，可以进行更复杂的自定义验证。
配置验证可以在解析后进行，也可以在访问配置值时进行。根据应用的复杂程度和对错误处理的要求，可以选择合适的验证策略。
通过本章的学习，我们了解了配置文件格式设计的基本原则，并使用 Boost.Spirit.Qi 构建了一个简单的配置文件解析器。我们还探讨了如何动态地处理解析后的配置项，包括访问配置值、处理不同类型的值、实现默认值和可选配置项。这些知识和技能可以帮助读者在实际项目中应用 Boost.Spirit 进行配置文件解析，提高软件的灵活性和可维护性。
END_OF_CHAPTER
12. chapter 12： 高级主题：性能优化 (高级主题：性能优化, Advanced Topics: Performance Optimization)
12.1 Spirit 性能瓶颈分析 (Spirit 性能瓶颈分析, Performance Bottleneck Analysis in Spirit)
Boost.Spirit 作为一个强大的 C++ 库，为构建复杂的解析器和生成器提供了优雅且富有表现力的方法。然而，如同任何强大的工具一样，不当的使用也可能导致性能瓶颈。理解 Spirit 的潜在性能瓶颈对于构建高效的应用至关重要。本节将深入分析 Spirit 中常见的性能瓶颈，帮助读者在开发过程中避免这些陷阱，从而编写出高性能的 Spirit 代码。
① 模板实例化开销 (Template Instantiation Overhead)：Spirit heavily relies on C++ 模板元编程（Template Metaprogramming）。模板的广泛使用虽然带来了极大的灵活性和编译期优化潜力，但也引入了模板实例化开销。
▮▮▮▮ⓑ 编译时间 (Compile Time)：复杂的 Spirit 解析器可能导致大量的模板实例化，从而显著增加编译时间。尤其是在大型项目中，这可能会成为一个不可忽视的问题。
▮▮▮▮ⓒ 代码膨胀 (Code Bloat)：模板实例化还会导致代码膨胀，即最终生成的可执行文件体积增大。虽然现代编译器在优化方面已经做得很好，但过度的模板使用仍然可能影响程序的加载时间和缓存效率。
② 回溯 (Backtracking) 与无限前瞻 (Unlimited Lookahead)：Spirit 默认采用回溯解析策略。当解析器尝试匹配输入时，如果当前路径失败，它会自动回溯到之前的状态并尝试其他可能的路径。
▮▮▮▮ⓑ 性能影响 (Performance Impact)：回溯在处理复杂的语法时非常有用，但也可能成为性能瓶颈。特别是当语法规则存在歧义或者解析器需要尝试大量分支时，回溯会导致大量的重复计算和状态恢复，从而降低解析速度。
▮▮▮▮ⓒ 无限前瞻的潜在问题 (Potential Issues with Unlimited Lookahead)：某些 Spirit 构造，如 longest[] 组合子，可能导致无限前瞻。这意味着解析器在决定如何匹配之前，需要扫描剩余的所有输入。在处理大型输入时，这会造成严重的性能问题。
③ 语义动作的开销 (Semantic Action Overhead)：语义动作是在解析过程中执行的 C++ 代码，用于处理解析结果。虽然语义动作提供了强大的灵活性，但不当的语义动作也可能成为性能瓶颈。
▮▮▮▮ⓑ 复杂计算 (Complex Computations)：如果在语义动作中执行复杂的计算，例如文件 I/O、数据库操作或复杂的算法，会显著增加解析的总时间。语义动作应该尽可能轻量级，避免在解析过程中执行耗时的操作。
▮▮▮▮ⓒ 不必要的拷贝 (Unnecessary Copies)：语义动作中不必要的数据拷贝也会引入性能开销。尤其是在处理大型属性时，频繁的拷贝操作会降低效率。应该尽量使用移动语义（Move Semantics）和引用传递（Pass-by-Reference）来避免不必要的拷贝。
④ 动态分配内存 (Dynamic Memory Allocation)：虽然 Spirit 自身尽量避免动态内存分配，但在某些情况下，例如使用某些容器作为属性类型，或者在语义动作中进行动态内存分配，仍然可能引入动态内存分配的开销。
▮▮▮▮ⓑ 分配与释放的开销 (Overhead of Allocation and Deallocation)：动态内存分配和释放操作相对耗时，尤其是在高频调用的解析器中，频繁的内存操作会降低性能。
▮▮▮▮ⓒ 内存碎片 (Memory Fragmentation)：长时间运行的程序中，频繁的动态内存分配和释放可能导致内存碎片，降低内存利用率，并可能影响程序的整体性能。
⑤ 输入流的读取效率 (Input Stream Reading Efficiency)：Spirit 解析器的性能也受到输入流读取效率的影响。
▮▮▮▮ⓑ 字符逐个读取 (Character-by-Character Reading)：如果输入流的读取方式效率低下，例如每次只读取一个字符，会显著降低解析速度。
▮▮▮▮ⓒ 缓冲读取 (Buffered Reading)：使用缓冲输入流可以显著提高读取效率。例如，可以使用 std::istream 的 rdbuf() 方法获取缓冲区，或者使用 boost::iostreams 库提供的缓冲流。
⑥ 不必要的属性传递与转换 (Unnecessary Attribute Passing and Transformation)：Spirit 的属性机制非常强大，但也可能因为不必要的属性传递和转换而引入性能开销。
▮▮▮▮ⓑ 属性的拷贝与移动 (Copying and Moving Attributes)：属性在解析器组合子和语义动作之间传递时，可能会发生拷贝或移动操作。如果属性类型复杂或者体积较大，频繁的拷贝和移动会降低性能。
▮▮▮▮ⓒ 不必要的属性转换 (Unnecessary Attribute Conversions)：Spirit 允许在不同类型的属性之间进行转换。如果不加注意，可能会引入不必要的类型转换，增加计算开销。
理解这些潜在的性能瓶颈是优化 Spirit 代码的第一步。在后续章节中，我们将介绍各种优化技巧和策略，帮助读者有效地解决这些问题，构建高性能的 Spirit 解析器和生成器。
12.2 优化技巧与策略 (优化技巧与策略, Optimization Techniques and Strategies)
针对上一节分析的 Spirit 性能瓶颈，本节将介绍一系列优化技巧与策略，帮助读者提升 Spirit 代码的性能。这些技巧涵盖了从语法规则设计到代码实现等多个方面，旨在提供全面的优化指导。
① 减少回溯 (Reduce Backtracking)：回溯是 Spirit 性能开销的主要来源之一。通过精心设计语法规则，可以有效地减少回溯的发生。
▮▮▮▮ⓑ 确定性语法 (Deterministic Grammar)：尽量设计确定性语法，即在任何给定的输入位置，解析器都应该只有一个明确的解析路径。避免使用可能导致歧义的语法规则，例如：
1
// 避免歧义的规则示例
2
auto ambiguous_rule = rule<> = a | (a >> b); // 歧义：输入 "ab" 可以匹配 a 或 a >> b
3
auto deterministic_rule = rule<> = a >> -b; // 确定性：输入 "ab" 只能匹配 a >> b，输入 "a" 匹配 a
▮▮▮▮ⓑ 使用 expect[] 组合子 (Using expect[] Combinator)：expect[] 组合子可以在解析失败时立即抛出异常，而不是回溯。这在已知输入应该符合特定模式时非常有用，可以避免不必要的回溯尝试。
1
// 使用 expect[] 强制匹配
2
auto rule_with_expect = rule<> = expect[a] >> b; // 如果没有匹配到 a，立即抛出异常
▮▮▮▮ⓒ 前瞻断言 (Lookahead Assertions)：使用前瞻断言 & (positive lookahead) 和 ! (negative lookahead) 可以提前检查后续输入是否符合预期，从而避免不必要的回溯。
1
// 使用前瞻断言避免回溯
2
auto rule_with_lookahead = rule<> = &a >> a >> b; // 只有当输入以 a 开头时，才尝试匹配 a >> b
② 限制前瞻深度 (Limit Lookahead Depth)：对于可能导致无限前瞻的组合子，例如 longest[]，应该谨慎使用，并考虑是否有其他替代方案。如果必须使用，可以考虑限制其前瞻深度，例如通过设置最大匹配长度。
③ 优化语义动作 (Optimize Semantic Actions)：语义动作的性能直接影响解析器的整体性能。优化语义动作的关键在于减少不必要的计算和数据拷贝。
▮▮▮▮ⓑ 轻量级语义动作 (Lightweight Semantic Actions)：语义动作应该尽可能轻量级，只执行必要的处理逻辑。避免在语义动作中执行耗时的操作，例如文件 I/O 和复杂的计算。可以将这些操作延迟到解析完成后进行。
▮▮▮▮ⓒ 避免不必要的拷贝 (Avoid Unnecessary Copies)：使用移动语义和引用传递来避免不必要的数据拷贝。尤其是在处理大型属性时，应该尽量使用移动操作，或者直接操作原始数据。
1
// 使用移动语义避免拷贝
2
struct Data {
3
std::vector<int> large_data;
4
Data() : large_data(1000000) {}
5
Data(const Data&) = delete; // 禁用拷贝构造函数
6
Data(Data&&) = default; // 启用移动构造函数
7
};
8
9
auto data_rule = rule<>() = ... >> [](Data data){ /* 使用移动后的 data */ };
▮▮▮▮ⓒ 延迟语义动作 (Deferred Semantic Actions)：对于某些可以延迟执行的语义动作，可以考虑将其延迟到解析完成后再执行。例如，可以将解析结果先存储在一个中间数据结构中，然后在解析完成后再进行统一处理。
④ 静态分配内存 (Static Memory Allocation)：尽量使用栈内存（Stack Memory）和静态内存（Static Memory），避免频繁的动态内存分配。可以使用固定大小的缓冲区（Fixed-Size Buffer）来存储解析结果，或者使用 boost::container 库提供的静态容器。
⑤ 高效的输入流处理 (Efficient Input Stream Handling)：提高输入流的读取效率可以显著提升解析速度。
▮▮▮▮ⓑ 缓冲输入 (Buffered Input)：使用缓冲输入流，例如 std::istream 的 rdbuf() 方法或者 boost::iostreams 库提供的缓冲流，可以减少系统调用次数，提高读取效率。
▮▮▮▮ⓒ 批量读取 (Bulk Reading)：如果可能，尽量批量读取输入数据，而不是逐个字符读取。例如，可以使用 std::istream::read() 方法一次读取多个字符。
⑥ 属性优化 (Attribute Optimization)：合理设计属性类型和属性传递方式，可以减少不必要的开销。
▮▮▮▮ⓑ 选择合适的属性类型 (Choose Appropriate Attribute Types)：根据实际需求选择最合适的属性类型。避免使用过于复杂的属性类型，或者使用不必要的容器。例如，如果只需要存储一个整数，就不要使用 std::vector<int>。
▮▮▮▮ⓒ 减少属性转换 (Reduce Attribute Conversions)：尽量避免不必要的属性类型转换。在设计语法规则时，可以尽量保持属性类型的一致性，减少类型转换的开销。
▮▮▮▮ⓓ 使用 BOOST_SPIRIT_ATTRIBUTE_UNUSED (Using BOOST_SPIRIT_ATTRIBUTE_UNUSED)：对于不需要使用的属性，可以使用 BOOST_SPIRIT_ATTRIBUTE_UNUSED 显式声明，避免不必要的属性传递和存储。
⑦ 编译期优化 (Compile-time Optimization)：Spirit 具有强大的编译期优化潜力。合理利用编译期特性，可以显著提升性能。
▮▮▮▮ⓑ 内联 (Inlining)：确保关键的解析器和语义动作能够被编译器内联。可以使用 inline 关键字显式声明内联函数，或者使用链接时优化（Link-Time Optimization, LTO）来启用跨模块内联。
▮▮▮▮ⓒ 常量表达式 (Constant Expressions)：尽可能使用常量表达式（Constant Expressions）来定义解析器和规则。这可以帮助编译器在编译期进行更多的优化。
1
// 使用常量表达式定义规则
2
constexpr auto const integer = qi::int_;
3
auto rule_with_constexpr = rule<> = integer >> ...;
▮▮▮▮ⓒ 禁用异常处理 (Disable Exception Handling)：在某些性能敏感的场景下，可以考虑禁用异常处理。Spirit 提供了 noexcept 解析器修饰符，可以禁用特定解析器的异常处理，从而减少运行时开销。但需要注意的是，禁用异常处理可能会影响错误处理的灵活性。
⑧ 使用 Spirit.Lex (Using Spirit.Lex)：对于需要进行词法分析的场景，可以考虑使用 Spirit.Lex 库。Spirit.Lex 专门用于构建高效的词法分析器，可以将词法分析和语法分析分离，提高整体性能。
⑨ 性能分析与调优 (Performance Profiling and Tuning)：最后，性能优化是一个迭代的过程。应该使用性能分析工具（Profiling Tools）来定位性能瓶颈，并根据分析结果进行针对性的优化。常用的性能分析工具包括 gprof, valgrind, perf 等。
通过应用上述优化技巧和策略，可以有效地提升 Spirit 代码的性能，构建高效、稳定的解析器和生成器。在实际开发中，应该根据具体的应用场景和性能需求，选择合适的优化方法，并进行充分的测试和验证。
12.3 编译期优化与运行期优化 (编译期优化与运行期优化, Compile-time and Runtime Optimization)
性能优化可以从编译期和运行期两个层面进行。编译期优化主要通过模板元编程和常量表达式等技术，在编译时完成尽可能多的计算和代码生成，从而减少运行时的开销。运行期优化则是在程序运行时，通过算法优化、数据结构选择、缓存机制等手段，提高程序的执行效率。本节将分别探讨 Spirit 中的编译期优化和运行期优化策略。
① 编译期优化 (Compile-time Optimization)：Spirit 本身就是一个 heavily 基于模板元编程的库，因此天然具备编译期优化的潜力。
▮▮▮▮ⓑ 模板元编程 (Template Metaprogramming)：Spirit 使用 C++ 模板元编程技术，在编译期生成高效的解析器代码。例如，解析器组合子的组合和规则的定义都是在编译期完成的。这意味着最终生成的代码已经针对特定的语法规则进行了优化，避免了运行时的解释和动态调度开销。
▮▮▮▮ⓒ 常量表达式 (Constant Expressions)：如前所述，使用 constexpr 关键字定义的解析器和规则，可以进一步提升编译期优化的效果。编译器可以在编译期对常量表达式进行求值，并将结果直接嵌入到最终的代码中，从而减少运行时的计算量。
1
// 编译期计算的规则示例
2
constexpr auto const space = qi::char_(' ');
3
constexpr auto const comma = qi::char_(',');
4
constexpr auto const integer = qi::int_;
5
constexpr auto const csv_row = rule<> = integer % comma; // csv_row 在编译期完成组合
▮▮▮▮ⓒ 内联 (Inlining)：编译器内联是编译期优化的重要手段。Spirit 鼓励使用短小精悍的解析器和语义动作，这有助于编译器进行内联优化。通过内联，可以消除函数调用开销，并为编译器提供更多的优化空间。可以使用链接时优化（LTO）来进一步提升内联效果，LTO 允许编译器跨模块进行内联优化。
▮▮▮▮ⓓ 静态初始化 (Static Initialization)：Spirit 的解析器和规则对象通常可以声明为静态变量或全局变量，利用静态初始化机制，可以在程序启动前完成解析器对象的初始化，避免运行时的初始化开销。
② 运行期优化 (Runtime Optimization)：虽然 Spirit 已经做了大量的编译期优化，但运行期优化仍然是提升性能的重要手段。
▮▮▮▮ⓑ 减少内存分配 (Reduce Memory Allocation)：运行期内存分配是昂贵的。在 Spirit 中，可以通过以下方式减少内存分配：
▮▮▮▮▮▮▮▮❸ 栈分配 (Stack Allocation)：尽量使用栈内存，避免动态内存分配。可以使用 boost::spirit::repository::ptr_list 等栈分配容器来存储解析结果。
▮▮▮▮▮▮▮▮❹ 预分配缓冲区 (Pre-allocate Buffers)：对于需要缓冲输入或输出的场景，可以预先分配固定大小的缓冲区，避免运行时动态分配。
▮▮▮▮ⓔ 缓存 (Caching)：对于重复使用的解析结果或中间计算结果，可以使用缓存机制来避免重复计算。例如，可以使用 std::map 或 std::unordered_map 来缓存解析结果。
▮▮▮▮ⓕ 算法优化 (Algorithm Optimization)：在语义动作中，应该选择高效的算法和数据结构。例如，可以使用 std::vector 代替 std::list，使用 std::unordered_map 代替 std::map，根据具体场景选择最合适的算法。
▮▮▮▮ⓖ 并行处理 (Parallel Processing)：对于大型输入，可以考虑使用并行处理来提高解析速度。可以将输入数据分割成多个块，然后使用多线程或多进程并行解析。但需要注意的是，并行处理会引入额外的线程管理和同步开销，只有当解析任务足够耗时时，并行处理才能带来性能提升。
▮▮▮▮ⓗ I/O 优化 (I/O Optimization)：输入输出操作是性能瓶颈的常见来源。可以使用缓冲 I/O、批量 I/O 等技术来提高 I/O 效率。例如，可以使用 std::ifstream 的 rdbuf() 方法获取缓冲区，或者使用 boost::iostreams 库提供的缓冲流。
③ 编译期与运行期优化的平衡 (Balancing Compile-time and Runtime Optimization)：编译期优化和运行期优化各有优缺点，需要在实际应用中进行权衡。
▮▮▮▮ⓑ 编译时间与运行时间 (Compile Time vs. Runtime)：过度的编译期优化可能会导致编译时间过长。在开发迭代频繁的项目中，过长的编译时间会降低开发效率。因此，需要在编译时间和运行时间之间进行权衡。
▮▮▮▮ⓒ 代码复杂度 (Code Complexity)：某些编译期优化技术，例如模板元编程，可能会增加代码的复杂度，降低代码的可读性和可维护性。需要在性能提升和代码复杂度之间进行权衡。
▮▮▮▮ⓓ 平台差异 (Platform Differences)：不同编译器和平台对编译期优化的支持程度可能不同。某些优化技术在某些平台上可能效果显著，而在另一些平台上可能效果不佳甚至适得其反。需要进行充分的跨平台测试和验证。
总而言之，Spirit 的性能优化是一个多层次、多角度的问题。既要充分利用 Spirit 提供的编译期优化潜力，也要在运行期采取有效的优化策略。通过深入理解 Spirit 的性能瓶颈，并结合具体的应用场景，选择合适的优化方法，才能构建出真正高性能的 Spirit 应用。性能优化是一个持续改进的过程，需要不断地进行性能分析、测试和调优，才能达到最佳的性能表现。
END_OF_CHAPTER
13. chapter 13： 高级主题：自定义 Parser 组件 (Advanced Topics: Custom Parser Components)
13.1 Parser 组件的设计原则 (Design Principles of Parser Components)
在深入探索 Boost.Spirit 的高级应用中，自定义 Parser 组件的开发无疑占据着核心地位。正如软件工程中的其他组件一样，优秀的 Parser 组件并非随意构建，而是需要遵循一系列的设计原则，以确保其有效性、可维护性和可重用性。本节将详细阐述自定义 Parser 组件的设计原则，为读者构建强大且灵活的解析器奠定坚实的基础。
首先，我们需要理解为什么需要自定义 Parser 组件。Boost.Spirit 提供了丰富的预定义 Parser 和组合子，足以应对绝大多数常见的解析任务。然而，在面对特定领域语言（Domain Specific Language, DSL）、复杂协议或高度定制化的数据格式时，预定义的组件可能无法直接满足需求。此时，自定义 Parser 组件就显得至关重要，它允许我们根据具体的解析任务，精确地控制解析逻辑，实现更高效、更专业的解析方案。
以下是自定义 Parser 组件设计时应遵循的关键原则：
① 单一职责原则 (Single Responsibility Principle, SRP)：
一个 Parser 组件应该只负责一项明确的任务。这意味着组件的设计应尽可能专注于完成特定的解析子任务，例如，一个组件负责解析整数，另一个组件负责解析字符串，再一个组件负责解析日期。 遵循 SRP 原则可以提高组件的内聚性 (Cohesion)，降低耦合性 (Coupling)，使得组件更易于理解、测试和维护。当需求变更时，我们只需修改或替换负责特定职责的组件，而不会影响到其他部分。
② 可重用性 (Reusability)：
优秀的 Parser 组件应该具有高度的可重用性。这意味着组件应该设计得足够通用，以便在不同的解析场景中复用。为了实现可重用性，我们需要将组件设计得参数化和可配置化。例如，一个解析逗号分隔值的组件，应该能够通过参数配置来处理不同类型的分隔符，或者处理不同类型的元素。通过提高组件的可重用性，我们可以减少重复开发，提高开发效率，并保持代码库的整洁和一致性。
③ 清晰性和可读性 (Clarity and Readability)：
Parser 组件的代码应该清晰易懂，易于阅读和理解。由于 Boost.Spirit 本身就是一种嵌入式的 DSL，其代码往往具有一定的复杂性。因此，在自定义 Parser 组件时，更应该注重代码的清晰性和可读性。这包括：
▮▮▮▮ⓐ 良好的命名：使用具有描述性的名称来命名 Parser 组件、规则和变量，使其能够清晰地表达其功能和用途。
▮▮▮▮ⓑ 合理的代码结构：采用清晰的代码结构和缩进，使代码逻辑一目了然。
▮▮▮▮ⓒ 充分的注释：对于复杂的解析逻辑或设计决策，添加必要的注释进行解释说明，帮助其他开发者（或未来的自己）快速理解代码。
▮▮▮▮ⓓ 避免过度复杂化：尽量使用简洁明了的方式实现解析逻辑，避免为了追求极致的性能或灵活性而过度复杂化组件的设计，牺牲代码的可读性。
④ 效率 (Efficiency)：
虽然代码的可读性和可维护性非常重要，但在某些性能敏感的应用场景中，效率也是一个不可忽视的设计原则。自定义 Parser 组件应该尽可能地高效，避免不必要的性能开销。这包括：
▮▮▮▮ⓐ 选择合适的解析策略：根据具体的解析任务，选择最合适的解析策略和算法。例如，对于简单的固定格式的解析，可以使用更高效的直接匹配方式；对于复杂的、回溯较多的解析，可能需要考虑使用前瞻 (Lookahead) 或其他优化技术。
▮▮▮▮ⓑ 减少回溯 (Backtracking)：过度的回溯会显著降低解析性能。在设计 Parser 组件时，应尽量减少不必要的回溯。可以使用commit操作符 ! 或 expect操作符 > 来控制回溯行为，提高解析效率。
▮▮▮▮ⓒ 避免不必要的属性拷贝：Boost.Spirit 的属性机制非常强大，但也可能带来一定的性能开销，尤其是在处理大型数据结构时。在自定义 Parser 组件时，应仔细考虑属性的传递和转换，避免不必要的属性拷贝操作。
⑤ 可测试性 (Testability)：
任何软件组件都应该具有良好的可测试性，Parser 组件也不例外。为了确保自定义 Parser 组件的正确性和可靠性，我们需要对其进行充分的测试。在设计 Parser 组件时，应考虑到其可测试性，使其易于编写单元测试用例。这包括：
▮▮▮▮ⓐ 模块化设计：遵循 SRP 原则进行模块化设计，使得每个组件都可以独立地进行测试。
▮▮▮▮ⓑ 清晰的接口：定义清晰的输入和输出接口，方便构造测试用例和验证测试结果。
▮▮▮▮ⓒ 边界条件和错误处理：充分考虑各种边界条件和错误情况，编写相应的测试用例，确保组件在各种情况下都能正确处理。
⑥ 扩展性 (Extensibility)：
在软件开发过程中，需求往往是不断变化的。优秀的 Parser 组件应该具有一定的扩展性，以便在需求变化时能够方便地进行扩展和修改。这包括：
▮▮▮▮ⓐ 开放封闭原则 (Open/Closed Principle, OCP)：组件应该对扩展开放，对修改封闭。这意味着我们应该能够在不修改组件源代码的情况下，通过添加新的功能或组件来扩展其功能。例如，可以通过组合现有的 Parser 组件或自定义新的组件来扩展解析能力。
▮▮▮▮ⓑ 组合优于继承：在设计 Parser 组件时，应优先考虑使用组合 (Composition) 而不是继承 (Inheritance)。组合能够提供更大的灵活性和可维护性。Boost.Spirit 本身就鼓励使用组合的方式来构建复杂的解析器。
综上所述，自定义 Parser 组件的设计是一个涉及多方面考虑的复杂过程。遵循上述设计原则，可以帮助我们构建出高质量、高效率、易于维护和扩展的 Parser 组件，从而更好地应对各种复杂的解析任务。在接下来的章节中，我们将深入探讨如何具体实现、测试和调试自定义 Parser 组件。
13.2 实现自定义 Parser (Implementing Custom Parsers)
在 Boost.Spirit 中，实现自定义 Parser 组件是扩展解析能力的关键手段。Spirit 提供了多种机制来创建自定义 Parser，从简单的函数对象到复杂的类 Parser，都能够满足不同的需求。本节将详细介绍几种常用的自定义 Parser 实现方法，并通过代码示例进行演示。
1. 使用 Lambda 表达式和函数对象 (Lambda Expressions and Function Objects)
对于简单的、内联的 Parser 逻辑，我们可以使用 Lambda 表达式 或 函数对象 (Function Object) 来快速定义自定义 Parser。这种方式简洁高效，特别适用于实现一些小的、辅助性的解析功能。
例如，假设我们需要一个 Parser 组件，用于解析由双引号 " 包裹的字符串，并且允许字符串中包含转义字符 \。我们可以使用 Lambda 表达式来实现：
1
#include <boost/spirit/home/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "\"hello \\\"world\\\"\"";
9
std::string parsed_string;
10
11
auto string_parser = qi::lexeme['"' >> *(('\\' >> qi::char_) | (~qi::char_('"'))) >> '"'];
12
13
bool success = qi::parse(input.begin(), input.end(), string_parser, parsed_string);
14
15
if (success) {
16
std::cout << "解析成功: " << parsed_string << std::endl; // 输出: 解析成功: hello "world"
17
} else {
18
std::cout << "解析失败" << std::endl;
19
}
20
21
return 0;
22
}
在这个例子中，string_parser 就是一个使用 Lambda 表达式定义的自定义 Parser。qi::lexeme[...] 用于创建一个词素 Parser，确保整个字符串作为一个整体被解析。'"' 匹配双引号，*(...) 表示零个或多个括号内的内容，('\\' >> qi::char_) 匹配转义字符 \ 后面的任意字符，~qi::char_('"') 匹配除了双引号以外的任意字符。
2. 使用 qi::rule<> (Using qi::rule<>)
qi::rule<> 是 Boost.Spirit 中最常用的定义 Parser 的方式。它允许我们命名和组合 Parser，构建更复杂的解析逻辑。qi::rule<> 可以接受模板参数，用于指定 Parser 的属性类型和 Skipper 类型。
以下示例展示了如何使用 qi::rule<> 定义一个解析整数列表的 Parser：
1
#include <boost/spirit/home/qi.hpp>
2
#include <vector>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
int main() {
8
std::string input = "1, 2, 3, 4";
9
std::vector<int> parsed_numbers;
10
11
qi::rule<std::string::iterator, std::vector<int>(), qi::space_type> number_list_rule;
12
13
number_list_rule = qi::int_ % ','; // 使用 % 操作符表示逗号分隔的列表
14
15
bool success = qi::parse(input.begin(), input.end(), number_list_rule, parsed_numbers);
16
17
if (success) {
18
std::cout << "解析成功: ";
19
for (int num : parsed_numbers) {
20
std::cout << num << " "; // 输出: 解析成功: 1 2 3 4
21
}
22
std::cout << std::endl;
23
} else {
24
std::cout << "解析失败" << std::endl;
25
}
26
27
return 0;
28
}
在这个例子中，number_list_rule 是一个使用 qi::rule<> 定义的规则。qi::rule<std::string::iterator, std::vector<int>(), qi::space_type> 声明了规则的迭代器类型为 std::string::iterator，属性类型为 std::vector<int>，Skipper 类型为 qi::space_type（表示使用空格作为跳过符）。qi::int_ % ',' 使用 % 操作符将 qi::int_ Parser 重复解析，并使用逗号 , 分隔，解析结果将存储到 std::vector<int> 类型的属性中。
3. 使用类 Parser (Class Parsers)
对于更复杂的、需要维护内部状态或实现特定算法的 Parser 组件，我们可以通过定义类 Parser 的方式来实现。类 Parser 需要满足 Boost.Spirit 的 Parser 接口要求，通常需要重载 parse() 方法。
以下示例展示了如何定义一个自定义的 Parser，用于解析十六进制数字：
1
#include <boost/spirit/home/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
// 自定义十六进制数字 Parser
8
struct hex_digit_parser : qi::parser<hex_digit_parser, char()> {
9
template <typename Iterator, typename Context, typename Skipper, typename Attribute>
10
bool parse(Iterator& first, Iterator const& last, Context& context, Skipper& skipper, Attribute& attr) const {
11
if (first == last) return false;
12
char ch = *first;
13
if (std::isdigit(ch) || (ch >= 'a' && ch <= 'f') || (ch >= 'A' && ch <= 'F')) {
14
attr = ch;
15
++first;
16
return true;
17
}
18
return false;
19
}
20
};
21
22
// 声明 BOOST_SPIRIT_DEFINE_PARSER 宏，使其成为 Spirit Parser
23
BOOST_SPIRIT_DEFINE_PARSER(hex_digit_parser);
24
25
int main() {
26
std::string input = "a";
27
char parsed_digit;
28
29
bool success = qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit);
30
31
if (success) {
32
std::cout << "解析成功: " << parsed_digit << std::endl; // 输出: 解析成功: a
33
} else {
34
std::cout << "解析失败" << std::endl;
35
}
36
37
input = "g";
38
success = qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit);
39
if (!success) {
40
std::cout << "解析 'g' 失败，符合预期" << std::endl; // 输出: 解析 'g' 失败，符合预期
41
}
42
43
return 0;
44
}
在这个例子中，hex_digit_parser 是一个自定义的类 Parser，它继承自 qi::parser<hex_digit_parser, char()>，并重载了 parse() 方法。parse() 方法实现了具体的解析逻辑，判断当前字符是否为十六进制数字，如果是，则将字符赋值给属性 attr，并返回 true，否则返回 false。BOOST_SPIRIT_DEFINE_PARSER(hex_digit_parser) 宏用于将 hex_digit_parser 声明为 Spirit Parser，使其可以像其他 Spirit Parser 一样使用。
4. 组合自定义 Parser (Combining Custom Parsers)
自定义 Parser 组件可以像预定义的 Parser 一样进行组合，构建更复杂的解析器。例如，我们可以将上面定义的 hex_digit_parser 与其他 Parser 组合使用，解析更复杂的十六进制数据格式。
1
#include <boost/spirit/home/qi.hpp>
2
#include <string>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
7
// ... (hex_digit_parser 的定义，与上例相同) ...
8
9
int main() {
10
std::string input = "0xAF";
11
std::string parsed_hex_string;
12
13
auto hex_string_parser = qi::lexeme["0x" >> +hex_digit_parser()]; // 使用 + 操作符解析一个或多个十六进制数字
14
15
bool success = qi::parse(input.begin(), input.end(), hex_string_parser, parsed_hex_string);
16
17
if (success) {
18
std::cout << "解析成功: " << parsed_hex_string << std::endl; // 输出: 解析成功: AF
19
} else {
20
std::cout << "解析失败" << std::endl;
21
}
22
23
return 0;
24
}
在这个例子中，hex_string_parser 使用 qi::lexeme 和组合操作符 >> 和 +，将字符串 "0x" 和 hex_digit_parser 组合起来，实现了解析以 "0x" 开头的十六进制字符串的功能。
总而言之，Boost.Spirit 提供了多种灵活的方式来实现自定义 Parser 组件。开发者可以根据具体的解析需求和复杂度，选择合适的实现方法。从简单的 Lambda 表达式到复杂的类 Parser，都能够有效地扩展 Spirit 的解析能力，构建强大的、定制化的解析器。
13.3 测试与调试自定义 Parser (Testing and Debugging Custom Parsers)
自定义 Parser 组件的开发并非一蹴而就，测试和调试是确保其正确性和可靠性的关键环节。如同软件开发的任何阶段一样，充分的测试和有效的调试方法能够帮助我们尽早发现和修复错误，提高代码质量。本节将介绍针对自定义 Parser 组件的测试策略和调试技巧。
1. 单元测试 (Unit Testing)
单元测试 是测试自定义 Parser 组件最基本也是最重要的手段。单元测试的目标是验证每个组件的功能是否符合预期，确保其在各种输入情况下都能正确工作。对于 Parser 组件，单元测试通常包括以下几个方面：
① 正常输入测试：
使用符合语法规则的正常输入数据进行测试，验证 Parser 组件是否能够正确解析，并生成预期的属性值。例如，对于一个解析整数的 Parser，可以使用 "123", "0", "-456" 等输入进行测试。
② 边界条件测试：
测试 Parser 组件在处理边界条件时的行为。例如，对于一个解析数字范围的 Parser，需要测试最小值、最大值、空值等边界情况。
③ 错误输入测试：
使用不符合语法规则的错误输入数据进行测试，验证 Parser 组件是否能够正确识别错误，并进行适当的错误处理。例如，对于一个解析整数的 Parser，可以使用 "abc", "12.34" 等非整数输入进行测试。
④ 性能测试 (可选)：
对于性能敏感的应用场景，可以进行性能测试，评估 Parser 组件的解析效率和资源消耗。
为了方便进行单元测试，可以使用 C++ 的单元测试框架，例如 Google Test、Boost.Test 等。以下示例展示了如何使用 Google Test 框架对之前定义的 hex_digit_parser 进行单元测试：
1
#include "gtest/gtest.h" // 引入 Google Test 框架
2
#include "hex_digit_parser.hpp" // 假设 hex_digit_parser 定义在 hex_digit_parser.hpp 文件中
3
#include <boost/spirit/home/qi.hpp>
4
#include <string>
5
6
namespace qi = boost::spirit::qi;
7
8
TEST(HexDigitParserTest, ValidHexDigits) {
9
char parsed_digit;
10
std::string input;
11
12
input = "a";
13
EXPECT_TRUE(qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit));
14
EXPECT_EQ(parsed_digit, 'a');
15
16
input = "F";
17
EXPECT_TRUE(qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit));
18
EXPECT_EQ(parsed_digit, 'F');
19
20
input = "5";
21
EXPECT_TRUE(qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit));
22
EXPECT_EQ(parsed_digit, '5');
23
}
24
25
TEST(HexDigitParserTest, InvalidHexDigits) {
26
char parsed_digit;
27
std::string input;
28
29
input = "g";
30
EXPECT_FALSE(qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit));
31
32
input = " ";
33
EXPECT_FALSE(qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit));
34
35
input = "-";
36
EXPECT_FALSE(qi::parse(input.begin(), input.end(), hex_digit_parser{}, parsed_digit));
37
}
38
39
int main(int argc, char** argv) {
40
::testing::InitGoogleTest(&argc, argv);
41
return RUN_ALL_TESTS();
42
}
在这个例子中，我们定义了两个测试用例 ValidHexDigits 和 InvalidHexDigits，分别测试了 hex_digit_parser 在处理有效和无效十六进制数字时的行为。EXPECT_TRUE 和 EXPECT_FALSE 断言用于验证解析是否成功，EXPECT_EQ 断言用于验证解析结果是否符合预期。
2. 调试技巧 (Debugging Techniques)
当单元测试失败时，我们需要进行调试，找出 Parser 组件中的错误。以下是一些常用的调试技巧：
① 打印调试信息 (Print Debugging)：
在 Parser 组件的代码中添加打印语句，输出关键的解析过程信息，例如当前解析位置、匹配的字符、属性值等。这是一种简单有效的调试方法，可以帮助我们了解 Parser 的执行流程。
② 使用 Spirit 的调试工具 (Spirit Debugging Tools)：
Boost.Spirit 提供了一些内置的调试工具，例如 qi::debug() 操作符 和 BOOST_SPIRIT_DEBUG_NODE() 宏。qi::debug() 操作符可以用于在解析过程中输出调试信息，BOOST_SPIRIT_DEBUG_NODE() 宏可以用于在编译时生成更详细的调试信息。
1
#include <boost/spirit/home/qi.hpp>
2
#include <iostream>
3
4
namespace qi = boost::spirit::qi;
5
6
int main() {
7
std::string input = "abc";
8
qi::rule<std::string::iterator, qi::space_type> r;
9
10
r = qi::debug(qi::char_ >> qi::char_ >> qi::char_); // 使用 qi::debug() 操作符
11
12
bool success = qi::phrase_parse(input.begin(), input.end(), r, qi::space);
13
14
if (success) {
15
std::cout << "解析成功" << std::endl;
16
} else {
17
std::cout << "解析失败" << std::endl;
18
}
19
20
return 0;
21
}
运行这段代码，当解析到 qi::debug(qi::char_ >> qi::char_ >> qi::char_) 规则时，Spirit 会在控制台输出调试信息，包括规则的名称、输入位置、匹配结果等，帮助我们分析解析过程。
③ 使用调试器 (Debugger)：
使用 C++ 调试器，例如 GDB、LLDB 或 Visual Studio Debugger，可以单步执行 Parser 组件的代码，查看变量的值，跟踪程序执行流程。这是一种更深入的调试方法，可以帮助我们定位更复杂的错误。
④ 简化和隔离 (Simplify and Isolate)：
当遇到复杂的解析错误时，可以尝试简化输入数据和 隔离问题组件。将复杂的输入数据简化为最小的能够复现错误的输入，将复杂的 Parser 拆分成更小的、独立的组件，分别进行测试和调试。这可以帮助我们缩小错误范围，更快地找到问题所在。
⑤ 代码审查 (Code Review)：
代码审查是一种有效的发现错误和改进代码质量的方法。将自定义 Parser 组件的代码交给其他开发者进行审查，可以帮助我们发现潜在的逻辑错误、设计缺陷和性能问题。
通过综合运用单元测试和调试技巧，我们可以有效地测试和调试自定义 Parser 组件，确保其正确性、可靠性和高效性，为构建健壮的解析器奠定坚实的基础。
END_OF_CHAPTER
14. chapter 14： Boost.Spirit 与其他 Boost 库的集成 (Boost.Spirit 与其他 Boost Libraries 的集成, Integration of Boost.Spirit with Other Boost Libraries)
14.1 与 Boost.Phoenix 的集成 (与 Boost.Phoenix 的集成, Integration with Boost.Phoenix)
Boost.Phoenix 库为 C++ 带来了强大的函数式编程能力，尤其擅长于创建匿名函数对象（lambda functions）和延迟求值（lazy evaluation）。在 Boost.Spirit 的上下文中，Boost.Phoenix 提供了一种优雅且强大的方式来定义语义动作（Semantic Actions）。语义动作是在解析过程中的特定点执行的 C++ 代码，用于处理解析结果、构建抽象语法树（Abstract Syntax Tree, AST）或执行其他自定义逻辑。
在传统的 Boost.Spirit 用法中，语义动作通常使用普通的 C++ 函数或函数对象。然而，当语义动作变得复杂，或者需要访问解析器的属性（Attribute）时，使用 Boost.Phoenix 可以显著提高代码的可读性和简洁性。Phoenix 允许我们直接在 Spirit 的规则定义中嵌入 C++ 代码片段，这些代码片段可以像普通函数一样被调用，但具有延迟执行和访问上下文数据的能力。
① Phoenix 的核心概念：
⚝ Placeholders（占位符）：Phoenix 提供了占位符，如 _1, _2, _3 等，用于代表语义动作的参数。在 Spirit 的语义动作中，_1 通常代表当前解析规则的属性值。例如，如果一个解析器解析得到一个整数，那么在与其关联的语义动作中，_1 就代表这个整数值。
⚝ Actors（动作）：Phoenix 动作是函数对象，可以是标准库中的函数对象（如 std::cout），也可以是用户自定义的函数对象。Phoenix 允许我们“提升”（lift）普通的函数和操作符，使其成为 Phoenix 动作，从而可以在 Phoenix 表达式中使用。
⚝ Expressions（表达式）：Phoenix 表达式是由占位符、动作和操作符组合而成的，用于描述需要执行的计算或操作。Phoenix 表达式可以像普通的 C++ 表达式一样组合和嵌套，从而构建复杂的语义动作。
② Phoenix 与 Spirit.Qi 的集成：
在 Spirit.Qi 中，我们可以使用 [ ] 运算符将 Phoenix 表达式嵌入到规则定义中，从而指定语义动作。例如，假设我们要解析一个整数，并在解析成功后将其打印到控制台，可以使用以下代码：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/phoenix/phoenix.hpp>
3
#include <iostream>
4
5
namespace qi = boost::spirit::qi;
6
namespace phoenix = boost::phoenix;
7
8
int main() {
9
std::string input = "123";
10
int result = 0;
11
12
bool success = qi::parse(
13
input.begin(), input.end(),
14
qi::int_[phoenix::ref(result) = qi::_1], // 语义动作：将解析到的整数赋值给 result
15
qi::space
16
);
17
18
if (success) {
19
std::cout << "解析成功，结果为: " << result << std::endl;
20
} else {
21
std::cout << "解析失败" << std::endl;
22
}
23
24
return 0;
25
}
在这个例子中，qi::int_ 是一个解析整数的 Spirit.Qi 解析器。[phoenix::ref(result) = qi::_1] 部分定义了一个语义动作。
⚝ phoenix::ref(result) 创建了一个对变量 result 的引用，使其可以在 Phoenix 表达式中被修改。
⚝ qi::_1 是一个占位符，代表 qi::int_ 解析器成功解析得到的整数值。
⚝ = 是 Phoenix 提供的赋值操作符，它被“提升”为 Phoenix 动作。
⚝ 整个语义动作的含义是将解析到的整数值（qi::_1）赋值给变量 result。
③ 使用 Phoenix 构建复杂的语义动作：
Phoenix 的强大之处在于可以构建非常复杂的语义动作，而无需编写显式的函数对象。例如，假设我们要解析一个简单的算术表达式，并计算其值。我们可以使用 Phoenix 来定义语义动作，直接在解析过程中完成计算：
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/phoenix/phoenix.hpp>
3
#include <iostream>
4
#include <string>
5
6
namespace qi = boost::spirit::qi;
7
namespace phoenix = boost::phoenix;
8
9
int main() {
10
std::string input = "10 + 20 * 3";
11
int result = 0;
12
13
auto calculator = qi::rule<std::string::iterator, int(), qi::space_type>()
14
= qi::int_[phoenix::ref(result) = qi::_1]
15
>> qi::omit[+(qi::char_('+') | qi::char_('-') | qi::char_('*') | qi::char_('/')) >> qi::int_]; // 忽略运算符和后续的整数，仅保留第一个整数
16
17
bool success = qi::phrase_parse(
18
input.begin(), input.end(),
19
calculator,
20
qi::space
21
);
22
23
if (success) {
24
std::cout << "解析成功，第一个操作数为: " << result << std::endl; // 仅输出了第一个操作数，实际计算需要更完整的解析器和语义动作
25
} else {
26
std::cout << "解析失败" << std::endl;
27
}
28
29
return 0;
30
}
这个例子展示了如何使用 Phoenix 和 Spirit.Qi 结合，定义简单的语义动作。虽然这个例子中的计算逻辑非常简化（仅提取了第一个整数），但它说明了 Phoenix 可以用于在解析过程中执行各种操作，包括数值计算、字符串处理、数据结构操作等。通过组合 Phoenix 的占位符、动作和表达式，可以构建出强大且灵活的语义动作，极大地增强 Boost.Spirit 解析器的功能。
④ Phoenix 的优势总结：
⚝ 简洁性：使用 Phoenix 可以将语义动作直接嵌入到 Spirit 规则中，减少了样板代码，提高了代码的紧凑性。
⚝ 可读性：Phoenix 表达式通常比手写的函数对象更易于理解，尤其是在语义动作较为简单的情况下。
⚝ 灵活性：Phoenix 提供了丰富的占位符、动作和操作符，可以构建各种复杂的语义动作，满足不同的解析需求。
⚝ 延迟求值：Phoenix 的延迟求值特性使得语义动作只在解析器成功匹配时才执行，避免了不必要的计算开销。
总而言之，Boost.Phoenix 是 Boost.Spirit 的强大盟友。通过与 Phoenix 的集成，Boost.Spirit 的语义动作定义变得更加简洁、灵活和强大，使得开发者能够更高效地构建复杂的解析器和生成器。在实际应用中，尤其是在需要处理复杂数据结构、执行复杂逻辑或与外部系统交互时，Phoenix 往往是不可或缺的工具。
14.2 与 Boost.Variant 的集成 (与 Boost.Variant 的集成, Integration with Boost.Variant)
Boost.Variant 库提供了一种判别式联合（Discriminated Union）类型，它可以安全地存储来自不同类型集合的值。在 Boost.Spirit 的上下文中，Boost.Variant 特别适用于处理异构属性（Heterogeneous Attributes）。当解析规则可能产生多种不同类型的结果时，使用 Boost.Variant 可以方便地表示和处理这些结果。
① Variant 的核心概念：
⚝ 类型安全的联合：与 C/C++ 中的联合体（union）不同，Boost.Variant 是类型安全的。它在运行时跟踪当前存储的类型，并防止类型错误的使用。
⚝ 访问者模式（Visitor Pattern）：要访问 Variant 中存储的值，通常需要使用访问者（Visitor）模式。访问者是一个函数对象，针对 Variant 可能存储的每种类型都提供一个重载的 operator()。
⚝ 多种类型的存储：一个 Variant 对象可以存储预先定义的一组类型中的任何一个值。例如，boost::variant<int, double, std::string> 可以存储一个整数、一个浮点数或一个字符串。
② Variant 在 Spirit.Qi 中的应用：
在 Spirit.Qi 中，解析规则的属性（Attribute）类型决定了规则解析成功后产生的结果类型。当一个规则可能解析出不同类型的结果时，例如，一个规则可能解析出一个整数或一个字符串，这时就需要使用 Boost.Variant 来作为规则的属性类型。
假设我们要解析一个配置值，这个配置值可能是整数、浮点数或字符串。我们可以定义一个 boost::variant<int, double, std::string> 类型来表示这个配置值，并使用 Spirit.Qi 规则来解析不同类型的输入，并将结果存储到 Variant 对象中。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/variant.hpp>
3
#include <iostream>
4
#include <string>
5
6
namespace qi = boost::spirit::qi;
7
8
// 定义 Variant 类型，可以存储 int, double, string
9
using config_value_t = boost::variant<int, double, std::string>;
10
11
int main() {
12
std::string input_int = "123";
13
std::string input_double = "3.14";
14
std::string input_string = "\"hello\"";
15
16
config_value_t value;
17
18
// 解析整数
19
bool success_int = qi::parse(
20
input_int.begin(), input_int.end(),
21
qi::int_ >> qi::space,
22
value // 将解析结果存储到 value (config_value_t)
23
);
24
25
if (success_int) {
26
std::cout << "解析整数成功，值为: " << boost::get<int>(value) << std::endl;
27
}
28
29
// 解析浮点数
30
bool success_double = qi::parse(
31
input_double.begin(), input_double.end(),
32
qi::double_ >> qi::space,
33
value // 再次将解析结果存储到 value
34
);
35
36
if (success_double) {
37
std::cout << "解析浮点数成功，值为: " << boost::get<double>(value) << std::endl;
38
}
39
40
// 解析字符串 (简单示例，未处理转义字符等)
41
bool success_string = qi::parse(
42
input_string.begin(), input_string.end(),
43
qi::lexeme['"' >> +qi::char_("a-zA-Z0-9") >> '"'] >> qi::space,
44
value // 再次将解析结果存储到 value
45
);
46
47
if (success_string) {
48
std::cout << "解析字符串成功，值为: " << boost::get<std::string>(value) << std::endl;
49
}
50
51
return 0;
52
}
在这个例子中，config_value_t 被定义为 boost::variant<int, double, std::string>。我们尝试分别解析整数、浮点数和字符串，并将解析结果存储到同一个 value 变量中。由于 value 是一个 Variant 类型，它可以安全地存储不同类型的结果。使用 boost::get<T>(value) 可以安全地提取 Variant 中存储的特定类型的值。如果 Variant 中存储的类型不是 T，boost::get<T> 将抛出异常。为了安全地访问 Variant 的值，通常会结合 boost::variant::which() 或 boost::apply_visitor 使用。
③ 使用访问者模式处理 Variant：
为了更安全和灵活地处理 Variant 中存储的值，可以使用访问者模式。访问者是一个函数对象，针对 Variant 可能存储的每种类型都提供一个重载的 operator()。boost::apply_visitor 函数可以将一个访问者应用于 Variant 对象，并根据 Variant 当前存储的类型调用相应的 operator() 重载。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/variant.hpp>
3
#include <iostream>
4
#include <string>
5
6
namespace qi = boost::spirit::qi;
7
8
using config_value_t = boost::variant<int, double, std::string>;
9
10
// 定义访问者
11
struct config_value_visitor : boost::static_visitor<> {
12
void operator()(int i) const {
13
std::cout << "配置值是整数: " << i << std::endl;
14
}
15
void operator()(double d) const {
16
std::cout << "配置值是浮点数: " << d << std::endl;
17
}
18
void operator()(const std::string& s) const {
19
std::cout << "配置值是字符串: " << s << std::endl;
20
}
21
};
22
23
int main() {
24
std::string input_variant = "3.14";
25
config_value_t value_variant;
26
27
bool success_variant = qi::parse(
28
input_variant.begin(), input_variant.end(),
29
qi::double_ >> qi::space,
30
value_variant
31
);
32
33
if (success_variant) {
34
config_value_visitor visitor;
35
boost::apply_visitor(visitor, value_variant); // 应用访问者
36
}
37
38
return 0;
39
}
在这个例子中，config_value_visitor 是一个访问者类，它为 int, double, std::string 类型提供了重载的 operator()。boost::apply_visitor(visitor, value_variant) 会根据 value_variant 当前存储的类型，调用 visitor 相应的 operator() 重载，从而实现类型安全的处理。
④ Variant 的优势总结：
⚝ 处理异构数据：Boost.Variant 允许 Spirit.Qi 规则处理和产生多种不同类型的结果，非常适合解析结构复杂、类型多样的输入数据。
⚝ 类型安全：Variant 提供了类型安全的联合，避免了传统联合体的类型安全问题。
⚝ 与访问者模式集成：通过访问者模式，可以方便、安全地处理 Variant 中存储的不同类型的值，使得代码更加清晰和可维护。
⚝ 灵活性：Variant 可以与其他 Boost 库（如 Boost.Fusion, Boost.Phoenix）以及标准库组件灵活组合使用，构建强大的解析解决方案。
总而言之，Boost.Variant 是处理 Spirit.Qi 解析器产生的异构属性的理想选择。它提供了一种类型安全、灵活且高效的方式来表示和操作多种可能类型的解析结果，是构建健壮且可扩展的解析器的重要工具。在需要处理例如配置文件、数据交换格式（如 JSON, XML）等复杂数据格式时，Variant 往往能发挥关键作用。
14.3 与 Boost.Fusion 的集成 (与 Boost.Fusion 的集成, Integration with Boost.Fusion)
Boost.Fusion 库提供了一系列元组（Tuple）和容器（Container）的概念，用于处理异构数据集合（Heterogeneous Collections of Data）。在 Boost.Spirit 的上下文中，Boost.Fusion 主要用于处理结构化属性（Structured Attributes）。当解析规则需要产生多个相关联的属性值时，例如，解析一个点的坐标 (x, y)，使用 Boost.Fusion 可以方便地将这些属性值组织成一个结构化的数据单元。
① Fusion 的核心概念：
⚝ 异构容器：Fusion 提供了多种异构容器，如 boost::fusion::tuple, boost::fusion::vector, boost::fusion::struct_ 等。这些容器可以存储不同类型的数据，并保持数据的顺序和结构。
⚝ 元组（Tuple）：boost::fusion::tuple 类似于 std::tuple，但它是 Fusion 库的一部分，可以与 Fusion 的其他组件无缝集成。
⚝ 序列操作：Fusion 提供了丰富的算法和操作，用于处理 Fusion 容器中的元素，例如，访问元素、迭代元素、转换元素等。
⚝ 反射（Reflection）：Fusion 具有一定的反射能力，可以自动适应用户自定义的结构体和类，使其可以像 Fusion 容器一样被操作。
② Fusion 在 Spirit.Qi 中的应用：
在 Spirit.Qi 中，当一个解析规则需要产生多个属性值时，可以将规则的属性类型定义为 Boost.Fusion 容器。例如，假设我们要解析一个点的坐标，坐标格式为 (x, y)，其中 x 和 y 都是整数。我们可以使用 boost::fusion::tuple<int, int> 作为规则的属性类型，来存储解析得到的 x 和 y 坐标。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/fusion/tuple.hpp>
3
#include <boost/fusion/adapted/std_pair.hpp> // 为了使用 std::pair
4
#include <iostream>
5
#include <string>
6
7
namespace qi = boost::spirit::qi;
8
namespace fusion = boost::fusion;
9
10
// 定义 Fusion tuple 类型，存储两个 int
11
using point_t = fusion::tuple<int, int>;
12
13
int main() {
14
std::string input_point = "(10, 20)";
15
point_t point;
16
17
auto point_parser = qi::rule<std::string::iterator, point_t(), qi::space_type>()
18
= qi::char_('(')
19
>> qi::int_ >> qi::char_(',') >> qi::int_
20
>> qi::char_(')');
21
22
bool success_point = qi::phrase_parse(
23
input_point.begin(), input_point.end(),
24
point_parser,
25
qi::space,
26
point // 将解析结果存储到 point (point_t)
27
);
28
29
if (success_point) {
30
std::cout << "解析点坐标成功，x = " << fusion::at_c<0>(point) << ", y = " << fusion::at_c<1>(point) << std::endl;
31
} else {
32
std::cout << "解析点坐标失败" << std::endl;
33
}
34
35
return 0;
36
}
在这个例子中，point_t 被定义为 fusion::tuple<int, int>。point_parser 规则解析形如 (int, int) 的坐标，并将解析得到的两个整数存储到 point 变量中。fusion::at_c<N>(tuple) 用于访问 Fusion 元组中索引为 N 的元素。
③ 使用 Fusion 结构体（Struct）：
除了元组，Fusion 还提供了 boost::fusion::struct_，用于表示结构化的数据。我们可以定义一个 C++ 结构体，并使用 BOOST_FUSION_ADAPT_STRUCT 宏将其适配为 Fusion 结构体。这样，我们就可以像操作 Fusion 容器一样操作这个结构体，并将其作为 Spirit.Qi 规则的属性类型。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/fusion/adapted/struct.hpp>
3
#include <boost/fusion/include/adapt_struct.hpp> // 引入 BOOST_FUSION_ADAPT_STRUCT
4
#include <iostream>
5
#include <string>
6
7
namespace qi = boost::spirit::qi;
8
namespace fusion = boost::fusion;
9
10
// 定义 C++ 结构体
11
struct Point {
12
int x;
13
int y;
14
};
15
16
// 适配 Point 结构体为 Fusion 结构体
17
BOOST_FUSION_ADAPT_STRUCT(
18
Point,
19
(int, x)
20
(int, y)
21
)
22
23
int main() {
24
std::string input_point_struct = "(10, 20)";
25
Point point_struct;
26
27
auto point_struct_parser = qi::rule<std::string::iterator, Point(), qi::space_type>()
28
= qi::char_('(')
29
>> qi::int_ >> qi::char_(',') >> qi::int_
30
>> qi::char_(')');
31
32
bool success_point_struct = qi::phrase_parse(
33
input_point_struct.begin(), input_point_struct.end(),
34
point_struct_parser,
35
qi::space,
36
point_struct // 将解析结果存储到 point_struct (Point)
37
);
38
39
if (success_point_struct) {
40
std::cout << "解析点坐标结构体成功，x = " << point_struct.x << ", y = " << point_struct.y << std::endl;
41
} else {
42
std::cout << "解析点坐标结构体失败" << std::endl;
43
}
44
45
return 0;
46
}
在这个例子中，我们定义了一个 Point 结构体，并使用 BOOST_FUSION_ADAPT_STRUCT 宏将其适配为 Fusion 结构体。现在，Point 类型可以作为 Spirit.Qi 规则的属性类型，并且可以直接访问结构体的成员变量 x 和 y。
④ Fusion 与语义动作的结合：
Fusion 容器可以与 Spirit.Qi 的语义动作灵活结合使用。例如，我们可以使用 Phoenix 和 Fusion 来构建更复杂的语义动作，操作 Fusion 容器中的元素。
1
#include <boost/spirit/include/qi.hpp>
2
#include <boost/fusion/tuple.hpp>
3
#include <boost/phoenix/phoenix.hpp>
4
#include <iostream>
5
#include <string>
6
7
namespace qi = boost::spirit::qi;
8
namespace fusion = boost::fusion;
9
namespace phoenix = boost::phoenix;
10
11
using point_t = fusion::tuple<int, int>;
12
13
int main() {
14
std::string input_point_action = "(10, 20)";
15
point_t point_action;
16
17
auto point_action_parser = qi::rule<std::string::iterator, point_t(), qi::space_type>()
18
= qi::char_('(')
19
>> qi::int_
20
>> qi::char_(',')
21
>> qi::int_
22
>> qi::char_(')')
23
[
24
phoenix::at_c<0>(qi::_val) = qi::_1, // 将第一个 int 赋值给 tuple 的第一个元素
25
phoenix::at_c<1>(qi::_val) = qi::_2 // 将第二个 int 赋值给 tuple 的第二个元素
26
];
27
28
bool success_point_action = qi::phrase_parse(
29
input_point_action.begin(), input_point_action.end(),
30
point_action_parser,
31
qi::space,
32
point_action
33
);
34
35
if (success_point_action) {
36
std::cout << "解析点坐标并执行语义动作成功，x = " << fusion::at_c<0>(point_action) << ", y = " << fusion::at_c<1>(point_action) << std::endl;
37
} else {
38
std::cout << "解析点坐标并执行语义动作失败" << std::endl;
39
}
40
41
return 0;
42
}
在这个例子中，我们在 point_action_parser 规则中添加了语义动作。
⚝ qi::_val 是一个特殊的占位符，在语义动作中代表当前规则的属性值，即 point_t 类型的 point_action 变量。
⚝ qi::_1 和 qi::_2 分别代表规则中第一个和第二个 qi::int_ 解析器的属性值。
⚝ 语义动作使用 Phoenix 的 phoenix::at_c<N> 和赋值操作符，将解析得到的两个整数分别赋值给 point_action 元组的第一个和第二个元素。
⑤ Fusion 的优势总结：
⚝ 处理结构化数据：Boost.Fusion 使得 Spirit.Qi 能够方便地处理和产生结构化的属性，例如，坐标、记录、对象等。
⚝ 异构容器：Fusion 提供了多种异构容器，可以灵活地组织不同类型的数据。
⚝ 与语义动作集成：Fusion 容器可以与 Spirit.Qi 的语义动作无缝集成，实现复杂的数据处理逻辑。
⚝ 反射能力：Fusion 的反射能力使得它可以方便地与用户自定义的结构体和类集成，提高了代码的复用性和可维护性。
总而言之，Boost.Fusion 是 Boost.Spirit 处理结构化属性的关键组件。通过与 Fusion 的集成，Spirit.Qi 可以解析和生成更复杂的数据结构，例如，配置文件、数据交换格式、领域特定语言（Domain Specific Language, DSL）等。Fusion 提供的异构容器和序列操作，以及与语义动作的灵活结合，使得开发者能够构建强大且易于维护的解析和生成解决方案。
END_OF_CHAPTER
15. chapter 15： API 参考 (API Reference)
15.1 Spirit.Qi API 详解 (Spirit.Qi API 详解)
Spirit.Qi 库是 Boost.Spirit 框架中用于解析 (Parsing) 的组件，它提供了一系列强大的工具来构建复杂的解析器。本节将详细介绍 Spirit.Qi 的核心 API，帮助读者快速查阅和理解其功能。
15.1.1 核心概念 (Core Concepts)
Spirit.Qi 的核心概念围绕着解析器 (Parser)、规则 (Rule)、属性 (Attribute) 和 语义动作 (Semantic Action)。
① Parser (解析器)：
Spirit.Qi 的基础构建块，负责识别输入流中的特定模式。解析器可以是预定义的，也可以通过组合其他解析器来创建。
⚝ qi::parser<...>：所有 Qi 解析器的基类。
⚝ qi::grammar<...>：用于组织和定义一组规则的类。
⚝ qi::rule<...>：将解析器与属性和语义动作关联的实体。
② Rule (规则)：
规则是命名的解析器，可以被重用和组合。规则可以关联属性和语义动作，从而在解析过程中执行自定义操作。
⚝ qi::rule<Iterator, Attribute, Skipper>：定义一个规则，接受迭代器类型 Iterator，具有属性类型 Attribute，并使用跳过符类型 Skipper。
⚝ qi::as_parser[...]：将 lambda 表达式或函数对象转换为解析器。
③ Attribute (属性)：
属性是解析器成功匹配输入后产生的值。属性类型由解析器决定，并可以传递给语义动作或组合成更复杂的属性。
⚝ 属性类型推导：Spirit.Qi 能够自动推导解析器的属性类型。
⚝ qi::attr(value)：创建一个返回固定值的解析器。
⚝ qi::omit[...]：创建一个忽略属性的解析器。
④ Semantic Action (语义动作)：
语义动作是在解析器成功匹配后执行的 C++ 函数或函数对象。语义动作可以访问解析器的属性，并执行自定义操作，例如数据转换、验证或存储。
⚝ [...] 操作符：将语义动作附加到解析器。
⚝ Boost.Phoenix：用于创建灵活的 lambda 表达式和函数对象，常用于语义动作。
⚝ 属性传递：语义动作可以修改或传递解析器的属性。
⑤ Skipper (跳过符)：
跳过符用于在解析过程中忽略输入流中的某些字符，例如空白符。
⚝ qi::space：预定义的跳过符，匹配空白字符。
⚝ qi::blank：预定义的跳过符，匹配空格和制表符。
⚝ 自定义 Skipper：可以创建自定义的跳过符来满足特定的需求。
15.1.2 预定义 Parser (Predefined Parsers)
Spirit.Qi 提供了丰富的预定义解析器，涵盖了常见的字符、字符串、数字和符号等。
① 字符解析器 (Character Parsers)：
⚝ qi::char_：匹配单个字符。
⚝ qi::wchar_：匹配宽字符。
⚝ qi::lit(char)：匹配字面字符。
⚝ qi::eol：匹配行尾符。
⚝ qi::eoi：匹配输入结束符。
⚝ qi::alnum：匹配字母数字字符。
⚝ qi::alpha：匹配字母字符。
⚝ qi::digit：匹配数字字符。
⚝ qi::xdigit：匹配十六进制数字字符。
⚝ qi::punct：匹配标点符号字符。
⚝ qi::space：匹配空白字符。
⚝ qi::blank：匹配空格或制表符。
⚝ qi::cntrl：匹配控制字符。
⚝ qi::graph：匹配图形字符。
⚝ qi::lower：匹配小写字母字符。
⚝ qi::print：匹配可打印字符。
⚝ qi::upper：匹配大写字母字符。
⚝ qi::ascii：匹配 ASCII 字符。
② 字符串解析器 (String Parsers)：
⚝ qi::string(str) 或 qi::lit(str)：匹配字面字符串。
⚝ qi::no_case[parser]：忽略大小写匹配。
③ 数值解析器 (Numeric Parsers)：
⚝ qi::int_：匹配整数。
⚝ qi::long_：匹配长整数。
⚝ qi::ulong_：匹配无符号长整数。
⚝ qi::short_：匹配短整数。
⚝ qi::ushort_：匹配无符号短整数。
⚝ qi::double_：匹配双精度浮点数。
⚝ qi::float_：匹配单精度浮点数。
⚝ qi::real_parser<>：更灵活的实数解析器，可以自定义格式。
④ 其他预定义解析器 (Other Predefined Parsers)：
⚝ qi::eps：永远成功匹配，不消耗任何输入。
⚝ qi::fail：永远匹配失败。
⚝ qi::raw[...]：返回匹配输入的原始迭代器范围。
⚝ qi::lexeme[...]：阻止跳过符在内部解析器之前和之后跳过空白符。
⚝ qi::omit[...]：忽略内部解析器的属性。
⚝ qi::attr(value)：返回固定值的解析器。
15.1.3 Parser Combinator (解析器组合子)
Spirit.Qi 提供了丰富的解析器组合子 (Parser Combinator)，允许用户通过组合简单的解析器来构建复杂的解析逻辑。
① 序列组合 (Sequence Combinator)：
⚝ p1 >> p2：顺序执行 p1 和 p2，只有当 p1 和 p2 都成功匹配时，整个序列才算成功。属性是 p1 和 p2 属性的组合（通常是 std::tuple 或 std::pair）。
② 选择组合 (Alternative Combinator)：
⚝ p1 | p2：尝试匹配 p1，如果失败则尝试匹配 p2。只要 p1 或 p2 其中一个成功匹配，整个选择就成功。属性类型需要兼容，或者使用 boost::variant 来统一。
③ 重复组合 (Repetition Combinator)：
⚝ *p：零次或多次重复匹配 p。属性类型通常是 std::vector。
⚝ +p：一次或多次重复匹配 p。属性类型通常是 std::vector。
⚝ qi::repeat(n)[p]：重复匹配 p 恰好 n 次。
⚝ qi::repeat(min, max)[p]：重复匹配 p 至少 min 次，至多 max 次。
⚝ qi::repeat(min)[p]：重复匹配 p 至少 min 次。
④ 可选组合 (Optional Combinator)：
⚝ -p 或 qi::omit[p]：尝试匹配 p，无论成功与否，都认为可选部分匹配成功。如果 p 成功匹配，则产生 boost::optional<Attribute> 或 Attribute (取决于是否使用 qi::omit)，否则不产生属性或产生默认属性。
⑤ 期望组合 (Expectation Combinator)：
⚝ p > q 或 qi::expect[p >> q]：类似于序列组合，但如果 p 成功匹配而 q 匹配失败，则会产生期望异常 (Expectation Exception)，用于更严格的错误处理。
⑥ 否定组合 (Negation Combinator)：
⚝ !p 或 qi::not_[p]：如果 p 匹配成功，则整个否定组合匹配失败；如果 p 匹配失败，则整个否定组合匹配成功，但不消耗任何输入。属性通常是 unused_type。
⑦ And 谓词 (And Predicate)：
⚝ &p 或 qi::and_[p]：如果 p 匹配成功，则整个 And 谓词匹配成功，且不消耗任何输入；如果 p 匹配失败，则整个 And 谓词匹配失败。属性与 p 的属性相同。
15.1.4 Directive (指令)
指令 (Directive) 用于修改解析器的行为，例如跳过符处理、大小写敏感性等。
① Skipper 指令 (Skipper Directives)：
⚝ qi::skip[skipper][parser]：显式指定跳过符 skipper 用于解析 parser。
⚝ qi::noskip[parser]：禁用跳过符。
⚝ qi::skip_flag::dont_postskip：控制是否在解析器之后应用跳过符。
② Case 指令 (Case Directives)：
⚝ qi::no_case[parser]：使 parser 进行大小写不敏感匹配。
⚝ qi::case_[parser]：使 parser 进行大小写敏感匹配（默认行为）。
③ Encoding 指令 (Encoding Directives)：
⚝ qi::ascii::char_，qi::unicode::char_，qi::iso8859_1::char_ 等：指定字符编码。
④ Lexeme 指令 (Lexeme Directive)：
⚝ qi::lexeme[parser]：阻止跳过符在 parser 内部跳过空白符，常用于词法单元解析。
⑤ Raw 指令 (Raw Directive)：
⚝ qi::raw[parser]：返回匹配输入的原始迭代器范围，而不是属性。
⑥ Attr 指令 (Attr Directive)：
⚝ qi::attr(value)：创建一个返回固定值 value 的解析器。
⚝ qi::omit[parser]：忽略 parser 的属性。
15.1.5 错误处理 API (Error Handling API)
Spirit.Qi 提供了机制来处理解析过程中的错误。
① qi::phrase_parse 函数：
使用跳过符进行解析的主函数，返回 bool 值指示解析是否成功，并提供迭代器指向解析结束的位置。
② qi::parse 函数：
不使用跳过符进行解析的函数，其他与 qi::phrase_parse 类似。
③ qi::expectation_failure 异常：
当使用期望组合子 > 且期望的解析器匹配失败时抛出的异常。可以通过 try-catch 块捕获。
④ qi::fail 解析器：
总是匹配失败的解析器，可以用于显式触发错误。
⑤ 自定义错误处理：
可以通过自定义语义动作和错误处理逻辑来实现更精细的错误报告和恢复。
15.1.6 其他常用 API (Other Common APIs)
① qi::grammar<...> 类：
用于组织和定义一组规则的类。通常需要继承 qi::grammar<> 并重载 start 规则。
② qi::rule<...> 类：
用于定义规则，可以绑定属性类型、跳过符类型和语义动作。
③ qi::on_error<...>：
用于定义错误处理的语义动作，当解析器发生错误时会被调用。
④ qi::debug[parser]：
用于调试解析器，输出详细的解析过程信息。
⑤ qi::locals<...>：
用于在规则内部定义局部变量，供语义动作使用。
15.2 Spirit.Karma API 详解 (Spirit.Karma API 详解)
Spirit.Karma 库是 Boost.Spirit 框架中用于生成 (Generation) 的组件，它允许用户使用类似解析器的方式来定义数据的生成格式。本节将详细介绍 Spirit.Karma 的核心 API。
15.2.1 核心概念 (Core Concepts)
Spirit.Karma 的核心概念与 Spirit.Qi 类似，但侧重于数据生成，包括 Generator (生成器)、Rule (规则)、Attribute (属性) 和 Semantic Action (语义动作)。
① Generator (生成器)：
Karma 的基础构建块，负责根据给定的属性生成输出。生成器可以是预定义的，也可以通过组合其他生成器来创建。
⚝ karma::generator<...>：所有 Karma 生成器的基类。
⚝ karma::grammar<...>：用于组织和定义一组生成规则的类。
⚝ karma::rule<...>：将生成器与属性和语义动作关联的实体。
② Rule (规则)：
与 Spirit.Qi 规则类似，Karma 规则是命名的生成器，可以重用和组合。规则可以关联属性和语义动作，从而在生成过程中执行自定义操作。
⚝ karma::rule<OutputIterator, Attribute>：定义一个规则，接受输出迭代器类型 OutputIterator，并接受属性类型 Attribute。
⚝ karma::as_generator[...]：将 lambda 表达式或函数对象转换为生成器。
③ Attribute (属性)：
属性是传递给生成器的数据，用于控制生成过程。属性类型由生成器决定。
⚝ 属性类型推导：Karma 能够自动推导生成器的属性类型。
⚝ karma::attr(value)：创建一个生成固定值的生成器。
⚝ karma::omit[...]：创建一个忽略属性的生成器。
④ Semantic Action (语义动作)：
与 Spirit.Qi 语义动作类似，Karma 语义动作是在生成器生成输出前后执行的 C++ 函数或函数对象。语义动作可以访问生成器的属性，并执行自定义操作，例如数据格式化或转换。
⚝ [...] 操作符：将语义动作附加到生成器。
⚝ Boost.Phoenix：用于创建灵活的 lambda 表达式和函数对象，常用于语义动作。
⚝ 属性传递：语义动作可以修改或传递生成器的属性。
15.2.2 预定义 Generator (Predefined Generators)
Spirit.Karma 提供了丰富的预定义生成器，涵盖了常见的字符、字符串、数字和符号等。
① 字符生成器 (Character Generators)：
⚝ karma::char_：生成单个字符。
⚝ karma::wchar_：生成宽字符。
⚝ karma::lit(char)：生成字面字符。
⚝ karma::eol：生成行尾符。
⚝ karma::eoi：生成输入结束符（通常不用于生成）。
⚝ karma::alnum：生成字母数字字符。
⚝ karma::alpha：生成字母字符。
⚝ karma::digit：生成数字字符。
⚝ karma::xdigit：生成十六进制数字字符。
⚝ karma::punct：生成标点符号字符。
⚝ karma::space：生成空白字符。
⚝ karma::blank：生成空格或制表符。
⚝ karma::cntrl：生成控制字符。
⚝ karma::graph：生成图形字符。
⚝ karma::lower：生成小写字母字符。
⚝ karma::print：生成可打印字符。
⚝ karma::upper：生成大写字母字符。
⚝ karma::ascii：生成 ASCII 字符。
② 字符串生成器 (String Generators)：
⚝ karma::string(str) 或 karma::lit(str)：生成字面字符串。
⚝ karma::no_case[generator]：生成的字符串忽略大小写（通常不适用，更多用于解析）。
③ 数值生成器 (Numeric Generators)：
⚝ karma::int_：生成整数。
⚝ karma::long_：生成长整数。
⚝ karma::ulong_：生成无符号长整数。
⚝ karma::short_：生成短整数。
⚝ karma::ushort_：生成无符号短整数。
⚝ karma::double_：生成双精度浮点数。
⚝ karma::float_：生成单精度浮点数。
⚝ karma::real_generator<>：更灵活的实数生成器，可以自定义格式。
⚝ karma::hex，karma::oct，karma::bin：生成不同进制的数值。
④ 格式化生成器 (Format Generators)：
⚝ karma::left，karma::right，karma::center：控制对齐方式。
⚝ karma::setw(width)：设置字段宽度。
⚝ karma::setprecision(precision)：设置浮点数精度。
⚝ karma::pad(char)：设置填充字符。
⑤ 其他预定义生成器 (Other Predefined Generators)：
⚝ karma::eps：永远成功生成，不产生任何输出。
⚝ karma::fail：永远生成失败。
⚝ karma::attr(value)：生成固定值。
⚝ karma::omit[...]：忽略内部生成器的属性。
15.2.3 Generator Combinator (生成器组合子)
Spirit.Karma 提供了丰富的生成器组合子 (Generator Combinator)，允许用户通过组合简单的生成器来构建复杂的生成逻辑。
① 序列组合 (Sequence Combinator)：
⚝ g1 << g2：顺序执行 g1 和 g2，将 g1 和 g2 的输出连接起来。属性是 g1 和 g2 属性的组合（通常是 std::tuple 或 std::pair）。
② 选择组合 (Alternative Combinator)：
⚝ g1 | g2：根据输入属性的类型选择执行 g1 或 g2。通常需要使用 boost::variant 或 boost::mpl::if_ 来进行类型选择。
③ 重复组合 (Repetition Combinator)：
⚝ *g：零次或多次重复执行 g。属性类型通常是 std::vector。
⚝ +g：一次或多次重复执行 g。属性类型通常是 std::vector。
⚝ karma::repeat(n)[g]：重复执行 g 恰好 n 次。
⚝ karma::repeat(min, max)[g]：重复执行 g 至少 min 次，至多 max 次。
⚝ karma::repeat(min)[g]：重复执行 g 至少 min 次。
④ 可选组合 (Optional Combinator)：
⚝ -g 或 karma::omit[g]：可选地执行 g。如果属性是 boost::optional 且包含值，则执行 g，否则不执行。
⑤ Attribute 转换组合 (Attribute Transformation Combinator)：
⚝ karma::copy[g]：复制属性。
⚝ karma::move[g]：移动属性。
⚝ karma::ref(attribute)[g]：引用外部属性。
15.2.4 Directive (指令)
Karma 的指令 (Directive) 用于修改生成器的行为，例如格式化输出、编码等。
① Format 指令 (Format Directives)：
⚝ karma::left，karma::right，karma::center：控制对齐方式。
⚝ karma::setw(width)：设置字段宽度。
⚝ karma::setprecision(precision)：设置浮点数精度。
⚝ karma::pad(char)：设置填充字符。
⚝ karma::delimit(generator)：在重复生成的元素之间插入分隔符。
② Encoding 指令 (Encoding Directives)：
⚝ karma::ascii::char_，karma::unicode::char_，karma::iso8859_1::char_ 等：指定字符编码。
③ Endian 指令 (Endian Directives)：
⚝ karma::big_endian，karma::little_endian，karma::native_endian：控制字节序，用于生成二进制数据。
④ 其他指令 (Other Directives)：
⚝ karma::omit[generator]：忽略 generator 的属性。
⚝ karma::attr(value)：创建一个生成固定值 value 的生成器。
15.2.5 生成函数 API (Generation Function API)
① karma::generate 函数：
执行生成操作的主函数，接受输出迭代器、生成器和属性，返回输出迭代器指向生成结束的位置。
② karma::generate_delimited 函数：
与 karma::generate 类似，但允许指定分隔符生成器，用于在生成的元素之间插入分隔符。
15.2.6 其他常用 API (Other Common APIs)
① karma::grammar<...> 类：
用于组织和定义一组生成规则的类。通常需要继承 karma::grammar<> 并重载 start 规则。
② karma::rule<...> 类：
用于定义规则，可以绑定属性类型和语义动作。
③ karma::locals<...>：
用于在规则内部定义局部变量，供语义动作使用。
④ karma::debug[generator]：
用于调试生成器，输出详细的生成过程信息。
15.3 Spirit.Lex API 详解 (Spirit.Lex API 详解)
Spirit.Lex 库是 Boost.Spirit 框架中用于词法分析 (Lexical Analysis) 的组件，它允许用户定义词法规则，将输入流分解为 Token (词元) 序列。本节将详细介绍 Spirit.Lex 的核心 API。
15.3.1 核心概念 (Core Concepts)
Spirit.Lex 的核心概念包括 Token (词元)、Lexer (词法分析器)、Tokenizer (分词器) 和 State Machine (状态机)。
① Token (词元)：
词法分析的基本单位，代表输入流中具有特定意义的片段，例如关键字、标识符、运算符、字面量等。
⚝ Token 类型：用户可以自定义 Token 类型，通常包含 Token 的 ID、值和位置信息。
⚝ Token 定义：使用 Spirit.Lex 规则定义 Token 的模式。
② Lexer (词法分析器)：
负责读取输入流，根据定义的词法规则识别 Token，并将输入流转换为 Token 序列。
⚝ lex::lexer<LexerDef>：Lexer 类，接受 Lexer 定义 LexerDef。
⚝ Lexer 定义：通常是一个继承自 lex::lexer_def<> 的类，在其中定义 Token 规则。
③ Tokenizer (分词器)：
将 Lexer 与输入流连接起来，提供迭代器接口，用于遍历 Token 序列。
⚝ lex::tokenize(Iterator begin, Iterator end, Lexer)：创建 Tokenizer，接受输入迭代器范围和 Lexer 对象。
⚝ Tokenizer 迭代器：用于遍历生成的 Token 序列。
④ State Machine (状态机)：
Spirit.Lex 内部使用状态机来实现词法分析。用户可以通过定义规则来配置状态机的行为。
⚝ 状态：词法分析器在不同阶段的状态，例如初始状态、标识符状态、数字状态等。
⚝ 转换：状态之间的转换，由输入的字符和规则触发。
15.3.2 Token 定义 API (Token Definition API)
Spirit.Lex 使用宏和规则来定义 Token。
① BOOST_SPIRIT_LEX_TOKEN_DEF 宏：
用于定义 Token 类型和关联的枚举值。
1
BOOST_SPIRIT_LEX_TOKEN_DEF(token_type, token_enum)
② Token 规则定义：
在 Lexer 定义类中使用规则来定义 Token 的模式。
⚝ 字面值规则："keyword"，'+'，'=' 等，匹配字面字符串或字符。
⚝ 正则表达式规则：使用 Spirit.Regex 库的正则表达式来定义 Token 模式。
⚝ 预定义规则：lex::token_def<>()，lex::token_def<State>()，lex::token_def<Attribute>()，lex::token_def<State, Attribute>() 等，用于定义不同类型的 Token 规则。
③ Token 属性 (Token Attributes)：
Token 可以关联属性，用于存储 Token 的值，例如标识符的名称、数字字面量的值等。
⚝ 属性类型：可以自定义 Token 属性的类型。
⚝ 属性提取：在 Token 规则的语义动作中提取 Token 属性。
15.3.3 Lexer 定义 API (Lexer Definition API)
Lexer 通过继承 lex::lexer_def<> 并定义 Token 规则来创建。
① lex::lexer_def<Token> 类：
定义 Lexer 的基类，模板参数 Token 是 Token 类型。
② 构造函数：
在 Lexer 定义类的构造函数中定义 Token 规则，并将规则与 Token ID 关联。
1
lexer_def()
2
{
3
// 定义 Token 规则
4
this->self = ...;
5
}
③ this->self：
表示 Lexer 本身，用于组合 Token 规则。
④ Token 规则组合：
使用 Spirit.Qi 的组合子（例如 |，>>）来组合 Token 规则。
⑤ 状态管理 (State Management)：
Spirit.Lex 支持状态机，可以定义不同的词法分析状态，并在不同状态下应用不同的 Token 规则。
⚝ 状态类型：用户可以自定义状态类型，通常是枚举或类。
⚝ 状态转换：在 Token 规则的语义动作中进行状态转换。
⚝ lex::state<>：用于定义状态规则。
⚝ lex::initial_state：初始状态。
15.3.4 Tokenizer API (Tokenizer API)
Tokenizer 用于将 Lexer 应用于输入流并生成 Token 序列。
① lex::tokenize 函数：
创建 Tokenizer 的函数，接受输入迭代器范围和 Lexer 对象。
1
auto tokenizer = lex::tokenize(input_begin, input_end, my_lexer);
② Tokenizer 迭代器：
tokenizer.begin() 和 tokenizer.end() 返回 Tokenizer 迭代器，用于遍历 Token 序列。
⚝ 迭代器类型：lex::token_iterator<Iterator, Lexer>。
⚝ 迭代器操作：支持前向迭代器操作，例如 *it（获取当前 Token），++it（移动到下一个 Token）。
③ Token 访问：
通过 Tokenizer 迭代器访问 Token 对象。
⚝ it->id()：获取 Token ID。
⚝ it->value()：获取 Token 值（如果 Token 有属性）。
⚝ it->position()：获取 Token 在输入流中的位置信息。
15.3.5 与其他 Spirit 组件集成 (Integration with Other Spirit Components)
Spirit.Lex 通常与 Spirit.Qi 结合使用，先使用 Lex 进行词法分析，将输入流转换为 Token 序列，然后使用 Qi 对 Token 序列进行语法分析。
① Token 流作为 Qi 的输入：
将 Lex 生成的 Token 序列作为 Spirit.Qi 解析器的输入。
⚝ 使用 token_iterator 作为 Qi 解析器的迭代器类型。
② qi::tokenize[lexer] 指令：
Spirit.Qi 提供的指令，可以直接在 Qi 解析器中使用 Lexer 进行词法分析。
15.3.6 其他常用 API (Other Common APIs)
① lex::actor<>：
用于在 Token 规则中执行语义动作。
② lex::pass_flags::pass_white_space，lex::pass_flags::dont_pass_white_space：
控制是否将空白符 Token 传递给后续处理阶段。
③ lex::match<>：
用于匹配 Token 规则。
④ lex::eol_token<>：
用于定义行尾符 Token。
⑤ lex::omit_token<>：
用于忽略 Token，不将其传递给后续处理阶段。
本章API参考旨在为读者提供一个快速查阅 Boost.Spirit 各个组件核心 API 的指南。在实际使用中，建议结合具体的示例代码和官方文档进行深入学习和实践。
END_OF_CHAPTER