Houdini 技术文档

本文档旨在帮助用户安装、使用及深入了解 Houdini 项目。以下内容将涵盖安装指南、项目使用说明以及项目 API 使用文档。

1. 安装指南

Houdini 不是一个传统意义上的库。事实上，作者甚至没有编写 Makefile（不过其他人有编写）。它零依赖且模块化。您只需将所需的文件放入您的项目中。或者，通过 git submodule 添加所有文件，并使用在调用 GNU make 时默认构建的静态库。

项目安装方式

1. 克隆 GitHub 仓库：

   git clone https://github.com/yourusername/houdini.git
   

2. 将所需的文件复制到您的项目中，或直接在项目中使用 git submodule。

   git submodule add https://github.com/yourusername/houdini.git path/to/houdini
   

3. 使用 GNU make 构建：

   make
   

2. 项目的使用说明

Houdini 是一个用于网页文本转义的简单 API，同时也支持反转义。以下是一些基本的使用示例：

gh_buf *ob = gh_buf_new(256);

// 转义 HTML
houdini_escape_html(ob, "Hello, <world>!", strlen("Hello, <world>!"));

// 反转义 HTML
houdini_unescape_html(ob, "&lt;Hello, world&gt;", strlen("&lt;Hello, world&gt;"));

// 转义 XML
houdini_escape_xml(ob, "Hello, <world>!", strlen("Hello, <world>!"));

// 转义 URI
houdini_escape_uri(ob, "Hello, /world!", strlen("Hello, /world!"));

// 转义 URL
houdini_escape_url(ob, "Hello, /world!", strlen("Hello, /world!"));

// 转义 HREF
houdini_escape_href(ob, "Hello, /world!", strlen("Hello, /world!"));

// 反转义 URI
houdini_unescape_uri(ob, "Hello%2C%20%2Fworld%21", strlen("Hello%2C%20%2Fworld%21"));

// 反转义 URL
houdini_unescape_url(ob, "Hello%2C%20%2Fworld%21", strlen("Hello%2C%20%2Fworld%21"));

// 转义 JavaScript
houdini_escape_js(ob, "Hello, 'world'!", strlen("Hello, 'world'!"));

// 反转义 JavaScript
houdini_unescape_js(ob, "Hello, %27world%27!", strlen("Hello, %27world%27!"));

gh_buf_free(ob);

3. 项目 API 使用文档

以下是一些常用的 API 函数及其用途：

• houdini_escape_html: 转义 HTML 字符。
• houdini_escape_html0: 转义 HTML 字符，带有安全选项。
• houdini_unescape_html: 反转义 HTML 字符。
• houdini_escape_xml: 转义 XML 字符。
• houdini_escape_uri: 转义 URI 字符。
• houdini_escape_url: 转义 URL 字符。
• houdini_escape_href: 转义 HREF 字符。
• houdini_unescape_uri: 反转义 URI 字符。
• houdini_unescape_url: 反转义 URL 字符。
• houdini_escape_js: 转义 JavaScript 字符。
• houdini_unescape_js: 反转义 JavaScript 字符。

这些函数接收一个 gh_buf 类型的输出缓冲区、一个指向输入字符串的指针以及输入字符串的大小。如果需要进行转义或反转义，函数将返回 1；如果不需要，将返回 0 并清空输出缓冲区。

请注意，Houdini 只支持 UTF-8 编码的字符串。如果您使用其他编码，请在传递字符串给 Houdini 之前进行转码。