Psych 项目技术文档

1. 安装指南

Psych 项目是 Ruby 的一个 YAML 解析器和发射器。安装 Psych 之前，请确保您的环境中已安装 MRI 1.9.2 或更高版本，因为 Psych 从 MRI 1.9.2 起已被包含在内，并且在 1.9.3 中是默认的 YAML 解析器。

若需要安装最新版本的 Psych gem，可以使用以下命令：

gem install psych

如果您需要与特定版本的 libyaml 源码静态构建 Psych，可以使用以下命令：

gem install psych -- --with-libyaml-source-dir=/path/to/libyaml-0.2.5

在您的应用中使用 gem 版本的 Psych 而不是标准库版本时，需要在您的项目中添加以下依赖：

gem 'psych'
require 'psych'

如果您使用 Bundler，请在 Gemfile 文件中添加：

gem 'psych'

JRuby 捆绑了 Psych 的纯 Java 实现。

2. 项目的使用说明

Psych 提供了将 YAML 文档解析成 Ruby 对象以及将 Ruby 对象转换为 YAML 文档的功能。以下是一些基本的使用示例：

解析 YAML

将 YAML 安全地加载为 Ruby 对象：

Psych.safe_load('--- foo') # => 'foo'

从字符串中加载 YAML：

Psych.load("---\n - a\n - b") # => ['a', 'b']

从文件中加载 YAML：

Psych.load_file('data.yml', permitted_classes: [Date])
Psych.load_file('trusted_database.yml')

发射 YAML

将 Ruby 对象转换为 YAML：

Psych.dump(['a', 'b']) # => "---\n- a\n- b\n"

将 Ruby 对象转换为 YAML 并写入文件：

File.open('database.yml', 'w') do |file|
  file.write(Psych.dump(['a', 'b']))
end

3. 项目API使用文档

Psych 提供了多种层次的 API 来解析和发射 YAML。以下是简要的 API 文档：

解析

• Psych.parse(yaml): 解析 YAML 字符串。
• Psych.parse_file(file_path): 从文件中解析 YAML。
• Psych.parse_stream(stream): 解析 YAML 流。

发射

• Psych.dump(data): 将 Ruby 数据结构转换为 YAML。
• Psych.dump_stream(data): 创建 YAML 流。

异常处理

• Psych.SyntaxError: 当解析 YAML 时遇到语法错误，会抛出此异常。

安全性

• Psych.safe_load(yaml): 安全地加载 YAML，防止加载未知类。

4. 项目安装方式

Psych 项目可以通过 Ruby 的包管理器 gem 进行安装。按照以下步骤操作：

1. 打开命令行终端。
2. 输入以下命令安装 Psych：

gem install psych

3. 如果您需要指定 libyaml 源码目录进行静态构建，请使用：

gem install psych -- --with-libyaml-source-dir=/path/to/libyaml-0.2.5

4. 在您的 Ruby 项目中添加 gem 依赖，并在代码中引入 Psych：

gem 'psych'
require 'psych'

或者，如果您使用 Bundler，确保 Gemfile 中包含以下内容：

gem 'psych'

运行 bundle install 来安装依赖项。