Gyoku 项目技术文档

本文档将详细介绍如何安装和使用 Gyoku 项目，该项目可以将 Ruby Hashes 转换为 XML。以下是安装指南、项目使用说明、项目 API 使用文档以及项目安装方式的详细内容。

1. 安装指南

Gyoku 可以通过 Rubygems 获得，并可以通过以下命令安装：

$ gem install gyoku

或者将以下内容添加到你的 Gemfile 中：

gem 'gyoku', '~> 1.0'

2. 项目使用说明

Gyoku 提供了将 Ruby Hash 转换为 XML 的功能。下面是一个简单的例子：

Gyoku.xml(:find_user => { :id => 123, "v1:Key" => "api" })
# 输出: "<findUser><id>123</id><v1:Key>api</v1:Key></findUser>"

Hash 键

Hash 键符号会转换为 lowerCamelCase 字符串。例如：

Gyoku.xml(:lower_camel_case => "key")
# 输出: "<lowerCamelCase>key</lowerCamelCase>"

你可以通过传递第二个 Hash 作为 .xml 方法的参数来更改默认的转换公式为 :camelcase、:upcase 或 :none。

Gyoku.xml({ :camel_case => "key" }, { :key_converter => :camelcase })
# 输出: "<CamelCase>key</CamelCase>"

Hash 值

DateTime 对象会被转换为 xs:dateTime 字符串，其他响应 :to_datetime 方法的对象（除了字符串）也会被转换为 xs:dateTime 字符串。TrueClass 和 FalseClass 对象会被转换为 "true" 和 "false" 字符串，NilClass 对象会被转换为 xsi:nil 标签。

数组值

数组项默认会被包装在容器标签中，这可能会产生意外的结果。例如：

Gyoku.xml({languages: [{language: 'ruby'},{language: 'java'}]})
# 输出: "<languages><language>ruby</language></languages><languages><language>java</language></languages>"

你可以设置 unwrap 选项来移除这种行为：

Gyoku.xml({languages: [{language: 'ruby'},{language: 'java'}]}, { unwrap: true})
# 输出: "<languages><language>ruby</language><language>java</language></languages>"

特殊字符

Gyoku 会对特殊字符进行转义，除非 Hash 键以感叹号结尾。

Gyoku.xml(:escaped => "<tag />", :not_escaped! => "<tag />")
# 输出: "<escaped>&lt;tag /&gt;</escaped><notEscaped><tag /></notEscaped>"

自我关闭标签

Hash 键以正斜杠结尾会创建自我关闭标签。

Gyoku.xml(:"self_closing/" => "", "selfClosing/" => nil)
# 输出: "<selfClosing/><selfClosing/>"

排序 XML 标签

如果你需要 XML 标签以特定顺序出现，你可以通过在 :order! 键下存储一个附加数组来指定顺序。

Gyoku.xml(:name => "Eve", :id => 1, :order! => [:id, :name])
# 输出: "<id>1</id><name>Eve</name>"

XML 属性

添加 XML 属性可能看起来不太优雅，但可以通过在 :attributes! 键下指定一个附加 Hash 来实现。

Gyoku.xml(:person => "Eve", :attributes! => { :person => { :id => 1 } })
# 输出: "<person id=\"1\">Eve</person>"

明确的 XML 属性

除了使用 :attributes! 键外，还可以通过以 "@" 符号开头的键来指定属性。这对于自我关闭标签特别有用。

Gyoku.xml(
  "foo/" => {
    :@bar => "1",
    :@biz => "2",
    :@baz => "3",
    :content! => ""
  })
# 输出: "<foo baz=\"3\" bar=\"1\" biz=\"2\"/>"

数组解包

你可以为 unwrap 选项指定一个布尔标志（默认为 false）或一个键白名单来修改数组的默认行为。

Gyoku.xml({
  "foo" => [
    {:is => 'great' },
    {:is => 'awesome'}
  ]
}, unwrap: true)
# 输出: "<foo><is>great</is><is>awesome</is></foo>"

美化输出

你可以通过以下选项来美化输出的 XML，使其更易于阅读：

• pretty_print – 控制美化模式（默认：false）
• indent – 指定缩进空间数（默认：2）
• compact – 控制紧凑模式（默认：true）

puts Gyoku.xml({user: { name: 'John', job: { title: 'Programmer' }, :@status => 'active' }}, pretty_print: true)
# 输出:
# <user status='active'>
#   <name>John</name>
#   <job>
#     <title>Programmer</title>
#   </job>
# </user>

3. 项目 API 使用文档

请参考项目的 GitHub 页面和 Wiki 获取详细的 API 使用文档。

4. 项目安装方式

请按照“安装指南”中的步骤进行项目安装。