PostRank URI 技术文档

PostRank URI 是一个用于处理 URI 提取、转义、规范化和标准化的 Ruby 库。它提供了一系列便捷的方法，帮助开发者从各种文本格式中提取 URI，并对其进行处理，以确保 URI 的一致性和可参考性。本文将详细介绍如何安装、使用该库，并对其 API 进行说明。

1. 安装指南

1.1 通过 RubyGems 安装

PostRank URI 可以通过 RubyGems 进行安装。在终端中运行以下命令即可：

gem install postrank-uri

1.2 通过 Bundler 安装

如果你在项目中使用 Bundler 管理依赖，可以在 Gemfile 中添加以下内容：

gem 'postrank-uri'

然后运行以下命令安装依赖：

bundle install

2. 项目的使用说明

PostRank URI 提供了多种方法来处理 URI。以下是其主要功能的使用示例：

2.1 提取 URI

你可以使用 PostRank::URI.extract 方法从文本中提取 URI：

require 'postrank-uri'

text = 'some random text with http://link.to somecanadiansite.ca'
uris = PostRank::URI.extract(text)
puts uris
# 输出: ["http://link.to/", "http://somecanadiansite.ca/"]

2.2 清理 URI

PostRank::URI.clean 方法可以对 URI 进行转义、规范化和标准化处理：

uri = 'link.to?a=b&utm_source=FeedBurner#stuff'
cleaned_uri = PostRank::URI.clean(uri)
puts cleaned_uri
# 输出: ["http://link.to/?a=b"]

2.3 规范化 URI

PostRank::URI.normalize 方法可以应用 RFC 规范化规则，去除多余的路径字符和锚点：

uri = 'http://igvita.com/a/../?utm_source%3Danalytics'
normalized_uri = PostRank::URI.normalize(uri)
puts normalized_uri
# 输出: "http://igvita.com/"

2.4 转义与反转义 URI

PostRank::URI.escape 和 PostRank::URI.unescape 方法分别用于转义和反转义 URI：

uri = 'http://igvita.com/a b'
escaped_uri = PostRank::URI.escape(uri)
puts escaped_uri
# 输出: "http://igvita.com/a%20b"

unescaped_uri = PostRank::URI.unescape(escaped_uri)
puts unescaped_uri
# 输出: "http://igvita.com/a b"

3. 项目 API 使用文档

3.1 PostRank::URI.extract(text)

从文本中提取 URI，并自动过滤掉无效的顶级域名（TLD）。

参数：

• text：包含 URI 的文本字符串。

返回值：

• 提取到的 URI 数组。

3.2 PostRank::URI.clean(uri)

对 URI 进行转义、规范化和标准化处理。

参数：

• uri：需要处理的 URI 字符串。

返回值：

• 处理后的 URI 数组。

3.3 PostRank::URI.normalize(uri)

应用 RFC 规范化规则，去除多余的路径字符和锚点。

参数：

• uri：需要规范化的 URI 字符串。

返回值：

• 规范化后的 URI 字符串。

3.4 PostRank::URI.unescape(uri)

反转义 URI 中的特殊字符。

参数：

• uri：需要反转义的 URI 字符串。

返回值：

• 反转义后的 URI 字符串。

3.5 PostRank::URI.escape(uri)

转义 URI 中的特殊字符。

参数：

• uri：需要转义的 URI 字符串。

返回值：

• 转义后的 URI 字符串。

4. 项目安装方式

4.1 通过 RubyGems 安装

gem install postrank-uri

4.2 通过 Bundler 安装

在 Gemfile 中添加：

gem 'postrank-uri'

然后运行：

bundle install

4.3 开发环境设置

如果你需要在开发环境中运行测试，可以按照以下步骤进行设置：

bundle install
bundle exec rake

4.4 运行依赖评估

为了验证 postrank-uri 在不同版本的运行时依赖下的兼容性，可以运行以下命令：

bundle exec appraisal install
bundle exec rake appraisal

这将使用不同版本的依赖项执行测试套件。

---

通过本文，你应该已经掌握了如何安装、使用 PostRank URI 库，并了解了其主要 API 的功能。希望这篇文档能帮助你更好地理解和使用该库。如果你在使用过程中遇到任何问题，欢迎反馈或提交 Pull Request。