Snail 项目技术文档

1. 安装指南

1.1 安装环境要求

• Ruby 版本：2.0 及以上
• 操作系统：支持主流操作系统（Windows、macOS、Linux）

1.2 安装步骤

1. 打开终端或命令行工具。
2. 使用 gem 命令安装 Snail：

   gem install snail
   

3. 安装完成后，可以通过以下命令确认安装是否成功：

   gem list snail
   

2. 项目的使用说明

2.1 基本用法

Snail 是一个用于格式化国际邮件地址的 Ruby Gem。它可以帮助用户将常规数据格式化为符合国际邮寄标准的地址。

示例代码

require 'snail'

address = Snail.new(
  name: "Jon Doe",
  line_1: "12345 Somewhere Ln",
  line_2: nil,
  city: "Bentley",
  region: "WA",
  postal_code: "6102",
  country: "AU"
)

puts address.to_s
# 输出: "Jon Doe\n12345 Somewhere Ln\nBENTLEY WA  6102\nAUSTRALIA"

2.2 设置默认国家

默认情况下，Snail 会将地址中的国家代码为 "USA" 的地址视为国内地址，并省略国家名称。可以通过设置 home_country 来更改默认国家。

示例代码

Snail.home_country = "Australia"

address = Snail.new(
  name: "Jon Doe",
  line_1: "12345 Somewhere Ln",
  line_2: nil,
  city: "Bentley",
  region: "WA",
  postal_code: "6102",
  country: "AU"
)

puts address.to_s
# 输出: "Jon Doe\n12345 Somewhere Ln\nBENTLEY WA  6102"

2.3 强制显示国家名称

可以通过 with_country 参数强制显示或隐藏国家名称。

示例代码

Snail.home_country = "Australia"

address = Snail.new(
  name: "Jon Doe",
  line_1: "12345 Somewhere Ln",
  line_2: nil,
  city: "Bentley",
  region: "WA",
  postal_code: "6102",
  country: "AU"
)

puts address.to_s(with_country: true)
# 输出: "Jon Doe\n12345 Somewhere Ln\nBENTLEY WA  6102\nAUSTRALIA"

3. 项目API使用文档

3.1 Snail.new

创建一个新的 Snail 对象，用于格式化地址。

参数

• name: 收件人姓名
• line_1: 地址第一行
• line_2: 地址第二行（可选）
• city: 城市
• region: 地区或州
• postal_code: 邮政编码
• country: 国家代码（如 "AU" 表示澳大利亚）

返回值

返回一个 Snail 对象。

3.2 to_s

将 Snail 对象转换为格式化后的字符串。

参数

• with_country: 布尔值，是否显示国家名称（可选，默认为 false）

返回值

返回格式化后的地址字符串。

3.3 Snail.home_country=

设置默认的国家代码。

参数

• country: 国家名称或代码（如 "Australia" 或 "AU"）

返回值

无返回值。

4. 项目安装方式

4.1 使用 gem 安装

gem install snail

4.2 在项目中使用

在 Ruby 项目中，可以通过以下方式引入 Snail：

require 'snail'

4.3 更新 Snail

如果需要更新 Snail 到最新版本，可以使用以下命令：

gem update snail

---

通过以上文档，您可以轻松安装、使用和了解 Snail 项目的基本功能和 API。希望这篇文档能帮助您更好地使用 Snail 进行国际邮件地址的格式化。