Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
:sectnums:
:sectnumlevels: 5

= UTL_URL 实现

== 按字节编码

`UTL_URL` 包调用 `contrib/ivorysql_ora/src/builtin_packages/utl_url/utl_url.c` 中的 C 入口。`ESCAPE` 先将输入转为指定编码,再逐字节处理。ASCII 字母、数字和非保留标点会保留。布尔参数控制是否保留分隔符,其余字节各转换为一个使用大写十六进制的 `%XX` 序列。

== 批量解码连续转义

`UNESCAPE` 先收集连续的 `%XX` 序列,再将还原的字节转为数据库编码。一组转义字节可以构成一个多字节字符。字面文本已采用数据库编码,会单独复制。解析器校验每组的两个十六进制数字,并拒绝转义的零字节。

可运行的示例见 xref:master/oracle_compatibility/compat_utl_url.adoc[UTL_URL 包]。
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
:sectnums:
:sectnumlevels: 5

= UTL_URL 包

== 转义 URL 或其中的组件

请用具有包执行权限的角色连接 Oracle 兼容模式。对整个 URL 使用 `UTL_URL.ESCAPE(url)` 时,`/`、`?` 和 `&` 等分隔符会保留。如果输入将作为 URL 的一个组件,且其中的分隔符需要转义,请将第二个参数设为 `true`。两种用法都会将空格编码为 `%20`。

如果转义字节需要使用指定编码,请将字符集(例如 `UTF8`)传给 `ESCAPE` 的第三个参数或 `UNESCAPE` 的第二个参数。省略字符集或传入 NULL 时,包使用数据库编码。

[source,sql]
----
SELECT utl_url.escape('https://example.test/a b?q=a+b') AS url;
SELECT utl_url.escape('a+b&c=d', true) AS query_value;
SELECT utl_url.escape('中文', false, 'UTF8') AS encoded;
SELECT utl_url.unescape('%E4%B8%AD%E6%96%87+a%20b', 'UTF8') AS decoded;
----

四条查询依次返回 `https://example.test/a%20b?q=a+b`、`a%2Bb%26c%3Dd`、`%E4%B8%AD%E6%96%87` 和 `中文+a b`。解码时字面加号仍为加号。

== 解码百分号转义

`UNESCAPE` 将 `%XX` 序列还原为字节。请传入生成这些序列时使用的字符集。无效或不完整的转义会报错。由于 `ESCAPE` 也会转义输入中的百分号,请对原始值调用该函数。

实现细节见 xref:master/compatibility_features_design/utl_url_impl.adoc[UTL_URL 实现]。
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
:sectnums:
:sectnumlevels: 5

= UTL_URL Implementation

== Encode bytes

The `UTL_URL` package delegates to the C entry points in `contrib/ivorysql_ora/src/builtin_packages/utl_url/utl_url.c`. `ESCAPE` converts the input to the requested encoding before examining its bytes. ASCII letters, digits and the unreserved punctuation pass through. The boolean argument controls whether reserved delimiters pass through. Each other byte becomes one uppercase hexadecimal `%XX` group.

== Decode consecutive groups

`UNESCAPE` accumulates consecutive `%XX` groups before converting the resulting bytes to the database encoding. A group of escaped bytes can form one multibyte character. Literal text is already in the database encoding and is copied separately. The parser checks the two hexadecimal digits in each group and rejects an escaped zero byte.

For runnable examples, see xref:master/oracle_compatibility/compat_utl_url.adoc[UTL_URL package].
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
:sectnums:
:sectnumlevels: 5

= UTL_URL Package

== Escape a URL or a component

Connect in Oracle compatibility mode with a role that can execute the package. Use `UTL_URL.ESCAPE(url)` on a URL when you want to preserve delimiters such as `/`, `?` and `&`. Pass `true` as the second argument when a value will be inserted into a URL component and its delimiters need escaping. Spaces become `%20` in both cases.

Pass a character set such as `UTF8` as the third argument to `ESCAPE` or the second argument to `UNESCAPE` when the encoded bytes need a specific encoding. With an omitted or NULL character set, the package uses the database encoding.

[source,sql]
----
SELECT utl_url.escape('https://example.test/a b?q=a+b') AS url;
SELECT utl_url.escape('a+b&c=d', true) AS query_value;
SELECT utl_url.escape('中文', false, 'UTF8') AS encoded;
SELECT utl_url.unescape('%E4%B8%AD%E6%96%87+a%20b', 'UTF8') AS decoded;
----

The results are `https://example.test/a%20b?q=a+b`, `a%2Bb%26c%3Dd`, `%E4%B8%AD%E6%96%87` and `中文+a b`, respectively. A literal plus remains a plus when decoding.

== Decode percent escapes

`UNESCAPE` decodes `%XX` byte sequences. Supply the same character set used to produce those sequences. Invalid or incomplete escapes raise an error. A percent sign in the input to `ESCAPE` is itself escaped, so apply it to the original value.

See xref:master/compatibility_features_design/utl_url_impl.adoc[UTL_URL implementation].
Loading