Ruby JSON 实现技术文档

1. 安装指南

1.1 使用扩展版本

推荐使用扩展版本的 JSON，因为它比纯 Ruby 版本更快。可以通过以下命令安装：

# rake install

该命令将构建扩展并安装到系统中。

1.2 使用纯 Ruby 版本

如果无法构建扩展版本，可以选择安装纯 Ruby 版本：

# rake install_pure

或者

# ruby install.rb

1.3 使用 Rubygems 安装

如果你使用 Rubygems，可以通过以下命令安装最新版本的 JSON：

# gem install json

如果你只想安装纯 Ruby 版本的 JSON，可以使用以下命令：

# gem install json_pure

1.4 手动编译扩展

如果你想从 parser.rl 文件生成 parser.c 文件，或者绘制状态机的 Graphviz 图像，你需要安装 [Ragel]。

2. 项目使用说明

2.1 加载 JSON 库

要使用 JSON 库，首先需要加载它：

require 'json'

这将加载已安装的 JSON 变体（扩展版本或纯 Ruby 版本）。如果你安装了扩展版本，可以选择加载扩展版本或纯 Ruby 版本：

require 'json/ext'  # 加载扩展版本
require 'json/pure' # 加载纯 Ruby 版本

2.2 解析 JSON 文档

要将 JSON 文档解析为 Ruby 数据结构，可以调用 JSON.parse：

data = JSON.parse(document)

2.3 生成 JSON 文档

要从 Ruby 数据结构生成 JSON 文档，可以调用 JSON.generate：

json = JSON.generate(data)

你还可以使用 pretty_generate 方法生成更易读的输出，或者使用 fast_generate 方法生成不进行安全检查的输出。

2.4 使用 JSON 方法

你还可以使用 JSON 和 JSON[] 方法来解析或生成 JSON 文档：

document = JSON 'test' => 23 # => "{\"test\":23}"
data = JSON '{"test":23}'    # => {"test"=>23}

2.5 添加核心对象支持

如果你需要对 Ruby 核心对象进行序列化/反序列化，可以加载 json/add/core：

require 'json/add/core'

例如，加载后可以序列化/反序列化 Ruby 范围对象：

JSON JSON(1..10) # => 1..10

2.6 序列化异常

默认情况下，JSON 模块不会扩展 Exception。如果你需要序列化异常对象的详细信息，可以加载 json/add/exception：

require 'json/add/exception'

3. 项目 API 使用文档

3.1 JSON.parse

将 JSON 文档解析为 Ruby 数据结构。

data = JSON.parse('{"name":"John", "age":30}')
# => {"name"=>"John", "age"=>30}

3.2 JSON.generate

将 Ruby 数据结构生成 JSON 文档。

json = JSON.generate({name: "John", age: 30})
# => "{\"name\":\"John\",\"age\":30}"

3.3 JSON.pretty_generate

生成更易读的 JSON 文档。

puts JSON.pretty_generate({name: "John", age: 30})
# 输出：
# {
#   "name": "John",
#   "age": 30
# }

3.4 JSON.fast_generate

生成不进行安全检查的 JSON 文档。

json = JSON.fast_generate({name: "John", age: 30})
# => "{\"name\":\"John\",\"age\":30}"

3.5 JSON[]

解析或生成 JSON 文档。

document = JSON['test' => 23] # => "{\"test\":23}"
data = JSON['{"test":23}']    # => {"test"=>23}

4. 项目安装方式

4.1 使用扩展版本

# rake install

4.2 使用纯 Ruby 版本

# rake install_pure

或者

# ruby install.rb

4.3 使用 Rubygems 安装

# gem install json

或者

# gem install json_pure