Loofah 项目技术文档

1. 安装指南

安装环境要求

• Ruby 版本：建议使用 Ruby 2.5 及以上版本。
• 依赖库：Loofah 依赖于 Nokogiri，确保你的系统已经安装了 Nokogiri。

安装步骤

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

   gem install loofah
   

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

   ruby -r loofah -e "puts Loofah::VERSION"
   

   如果输出了 Loofah 的版本号，说明安装成功。

2. 项目的使用说明

概述

Loofah 是一个基于 Nokogiri 的通用库，用于操作和转换 HTML/XML 文档和片段。它提供了内置的 HTML 清理功能，并且支持自定义的文档转换。

主要功能

• HTML/XML 文档和片段的转换：Loofah 提供了多种内置的转换功能，如去除不安全的标签、转义不安全的标签、清理标记等。
• 自定义转换：用户可以编写自己的转换逻辑，使用 Loofah::Scrubber 来实现自定义的文档转换。
• HTML 清理：Loofah 提供了基于 html5lib 的安全列表的 HTML 清理功能，支持 strip、prune、escape 和 whitewash 等操作。

示例代码

以下是一个简单的示例，展示如何使用 Loofah 清理 HTML 片段：

require 'loofah'

unsafe_html = "ohai! <div>div is safe</div> <script>but script is not</script>"

doc = Loofah.html5_fragment(unsafe_html).scrub!(:prune)
puts doc.to_s    # 输出: "ohai! <div>div is safe</div> "

3. 项目API使用文档

Loofah::HTML5::Document 和 Loofah::HTML5::DocumentFragment

• Loofah.html5_document(html)：解析 HTML 文档。
• Loofah.html5_fragment(html)：解析 HTML 片段。

Loofah::HTML4::Document 和 Loofah::HTML4::DocumentFragment

• Loofah.html4_document(html)：解析 HTML4 文档。
• Loofah.html4_fragment(html)：解析 HTML4 片段。

Loofah::XML::Document 和 Loofah::XML::DocumentFragment

• Loofah.xml_document(xml)：解析 XML 文档。
• Loofah.xml_fragment(xml)：解析 XML 片段。

Loofah::Scrubber

• Loofah::Scrubber.new：创建一个自定义的文档转换器。
• scrub!(scrubber)：对文档或片段应用转换器。

内置 HTML 清理器

• :strip：替换不安全的标签为它们的内部文本。
• :prune：移除不安全的标签及其子树。
• :escape：转义不安全的标签。
• :whitewash：清理标记，移除所有属性和命名空间节点。

4. 项目安装方式

通过 RubyGems 安装

gem install loofah

在 Gemfile 中添加

如果你使用的是 Ruby on Rails 或其他基于 Bundler 的项目，可以在 Gemfile 中添加以下内容：

gem 'loofah'

然后运行：

bundle install

手动安装

1. 下载 Loofah 的源代码。
2. 解压后进入目录，运行以下命令进行安装：

   ruby setup.rb
   

通过以上步骤，你就可以成功安装并使用 Loofah 项目了。