✨ feat(tsl-api-reference): expand and reorganize api catalog

Flatten builtin pages, add third-party and platform scopes, and import financial and data warehouse references. Keep the existing generated index without rebuilding after signature normalization.
2026-08-10 18:26:24 +08:00
parent 2938300acb
commit 9010829c6d
1186 changed files with 243901 additions and 219769 deletions
@@ -0,0 +1,577 @@
+# Builtin - CGI
+
+## `httpGetAuthType()`
+
+声明：function
+
+返回当前 CGI 请求使用的认证类型。
+
+<!-- tags: CGI HTTP 认证类型 AUTH_TYPE authentication -->
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：AUTH_TYPE=Basic
+echo httpGetAuthType();
+// 输出：Basic
+```
+
+## `httpGetContent()`
+
+声明：function
+
+返回前端发送的内容串，如果内容串长度和HttpGetContentLength不一致，则需要用TWebRequest类来读取剩余内容。
+
+返回：string
+
+### 示例
+
+以下示例假定请求方法为 `POST`，stdin 正文为 `name=alice&role=dev`。
+
+```tsl
+return httpGetContent();
+// 输出：name=alice&role=dev
+```
+
+## `httpGetContentLength()`
+
+声明：function
+
+返回前端发送的内容串的长度。
+
+返回：integer
+
+### 示例
+
+以下示例假定请求方法为 `POST`，`CONTENT_LENGTH=19`。
+
+```tsl
+return httpGetContentLength();
+// 输出：19
+```
+
+## `httpGetCookie()`
+
+声明：function
+
+返回Cookie串。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：HTTP_COOKIE=sid=abc123
+return httpGetCookie();
+// 输出：sid=abc123
+```
+
+## `httpGetEnvVar(env_name)`
+
+声明：function
+
+返回指定名称的环境串。
+
+| 参数       | 类型   | 说明                     |
+| ---------- | ------ | ------------------------ |
+| `env_name` | string | 字符串类型，环境变量名。 |
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：CGI_FIXTURE=env-value
+return httpGetEnvVar("CGI_FIXTURE");
+// 输出：env-value
+```
+
+## `httpGetGatewayInterface()`
+
+声明：function
+
+返回网关接口。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：GATEWAY_INTERFACE=CGI/1.1
+return httpGetGatewayInterface();
+// 输出：CGI/1.1
+```
+
+## `httpGetHttpAccept()`
+
+声明：function
+
+返回接受的类型种类。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：HTTP_ACCEPT=text/plain
+return httpGetHttpAccept();
+// 输出：text/plain
+```
+
+## `httpGetHttpUserAgent()`
+
+声明：function
+
+返回用户代理串。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：HTTP_USER_AGENT=TestAgent/1.0
+return httpGetHttpUserAgent();
+// 输出：TestAgent/1.0
+```
+
+## `httpGetPathInfo()`
+
+声明：function
+
+返回所执行的CGI的虚拟路径名。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：PATH_INFO=/cgi/demo
+return httpGetPathInfo();
+// 输出：/cgi/demo
+```
+
+## `httpGetPathTranslated()`
+
+声明：function
+
+返回所执行的CGI的实路径名。
+
+返回：string
+
+## `httpGetQueryString()`
+
+声明：function
+
+返回前端发送的查询串。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：QUERY_STRING=name=alice&role=admin
+return httpGetQueryString();
+// 输出：name=alice&role=admin
+```
+
+## `httpGetQueryValueByName(name, additional_info)`
+
+声明：function
+
+得到指定参数的查询串的值。
+
+| 参数              | 类型   | 说明                                                                                                                                   |
+| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`            | string | 字符串类型。查询串中的变量名。                                                                                                         |
+| `additional_info` | string | 字符串类型，返回附加信息。最常见的是当查询的Name为文件上传的ID时，函数返回文件的内容，而AdditionalInfo返回包括文件名等内容的附加信息。 |
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：QUERY_STRING=name=alice&role=admin
+additional_info := "";
+value := httpGetQueryValueByName("name", additional_info);
+return array(value, additional_info);
+// 输出：array("alice","")
+```
+
+上传文件时，`additional_info` 会包含文件头等附加信息。
+
+## `httpGetQueryValueByNameEx(name)`
+
+声明：function
+
+得到查询串的值，网页多文件一次性上传可能会用多同名多个内容的情况，返回二维数组结构。
+
+| 参数   | 类型   | 说明                       |
+| ------ | ------ | -------------------------- |
+| `name` | string | 字符串，查询串中的变量名。 |
+
+返回：array
+
+### 示例
+
+以下示例假定 multipart 请求包含两个同名 `upload` 文件，内容分别为 `alpha` 和 `beta`。
+
+```tsl
+// 需 CGI 环境：multipart/form-data
+return httpGetQueryValueByNameEx("upload");
+// 输出：
+// array(
+// ("alpha","Content-Disposition: form-data; name=\"upload\"; filename=\"a.txt\"\r\nContent-Type: text/plain\r\n\r\n"),
+// ("beta","Content-Disposition: form-data; name=\"upload\"; filename=\"b.txt\"\r\nContent-Type: text/plain\r\n\r\n"))
+```
+
+## `httpGetQueryValues()`
+
+声明：function
+
+分解前端发送的查询串为字符串下标的字符串数组。
+
+返回：array[key:string] of string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：QUERY_STRING=name=alice&role=admin
+return httpGetQueryValues();
+// 输出：array("name":"alice","role":"admin")
+```
+
+## `httpGetRemoteAddr()`
+
+声明：function
+
+返回所执行的CGI的前端IP地址。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：REMOTE_ADDR=198.51.100.7
+return httpGetRemoteAddr();
+// 输出：198.51.100.7
+```
+
+## `httpGetRemoteHost()`
+
+声明：function
+
+返回所执行的CGI的前端主机名。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：REMOTE_HOST=client.test
+return httpGetRemoteHost();
+// 输出：client.test
+```
+
+## `httpGetRemoteIdent()`
+
+声明：function
+
+返回所执行的CGI的远端识别串。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：REMOTE_IDENT=ident-1
+return httpGetRemoteIdent();
+// 输出：ident-1
+```
+
+## `httpGetRemoteUser()`
+
+声明：function
+
+返回所执行的CGI的远端登录用户名。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：REMOTE_USER=alice
+return httpGetRemoteUser();
+// 输出：alice
+```
+
+## `httpGetRequestMethod()`
+
+声明：function
+
+返回前端发送请求的类型。如get或者put。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：REQUEST_METHOD=GET
+return httpGetRequestMethod();
+// 输出：GET
+```
+
+## `httpGetScriptName()`
+
+声明：function
+
+返回所执行的CGI名。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：SCRIPT_NAME=/cgi/demo.tsl
+return httpGetScriptName();
+// 输出：/cgi/demo.tsl
+```
+
+## `httpGetServerName()`
+
+声明：function
+
+返回服务器名。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：SERVER_NAME=test.local
+return httpGetServerName();
+// 输出：test.local
+```
+
+## `httpGetServerPort()`
+
+声明：function
+
+返回服务器端口。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：SERVER_PORT=8080
+return httpGetServerPort();
+// 输出：8080
+```
+
+## `httpGetServerProtocol()`
+
+声明：function
+
+返回服务器协议类别。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：SERVER_PROTOCOL=HTTP/1.1
+return httpGetServerProtocol();
+// 输出：HTTP/1.1
+```
+
+## `httpGetServerSoftware()`
+
+声明：function
+
+返回服务器软件的名称。
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 环境：SERVER_SOFTWARE=fixture/1.0
+return httpGetServerSoftware();
+// 输出：fixture/1.0
+```
+
+## `httpSetHeadString(header)`
+
+声明：function
+
+设置返回的HTTP头。
+
+| 参数     | 类型   | 说明                                             |
+| -------- | ------ | ------------------------------------------------ |
+| `header` | string | 字符串类型，Http头，以连续两个回车换行作为结尾。 |
+
+返回：string
+
+### 示例
+
+```tsl
+// 需 CGI 宿主环境
+httpSetHeadString("Status: 201 Created"#13#10"Content-Type: text/plain"#13#10#13#10);
+echo "OK";
+// 输出：
+// Status: 201 Created
+// Content-Type: text/plain
+// OK
+```
+
+## `isEchoRedirect()`
+
+声明：function
+
+判断当前输出是否已被 `setEchoString()` 重定向。
+
+返回：bool
+
+### 示例
+
+```tsl
+setEchoString();
+redirected := isEchoRedirect();
+unsetEchoString();
+echo redirected;
+// 输出：1
+```
+
+## `read(count[, disp_char])`
+
+声明：function
+
+从控制台读取字符串并返回结果。
+
+<!-- tags: 控制台 输入 读取 字符 密码 stdin -->
+
+| 参数        | 类型    | 说明                                                       |
+| ----------- | ------- | ---------------------------------------------------------- |
+| `count`     | integer | 要读取的字符数；为 `0` 时读取到回车结束。                  |
+| `disp_char` | string  | 可选。指定回显字符；为空字符串时不回显，适用于密码等输入。 |
+
+返回：string
+
+### 示例
+
+以下示例通过 stdin 输入字符 `A`。
+
+```tsl
+value := read(1, "");
+echo value;
+// 输出：A
+```
+
+## `readLn()`
+
+声明：function
+
+从控制台读字符串并返回结果（输入以回车结束）。
+
+返回：string
+
+### 示例
+
+以下示例通过 stdin 输入一行 `fixture-line`。
+
+```tsl
+return readLn();
+// 输出：fixture-line
+```
+
+## `setEchoString()`
+
+声明：function
+
+将 `echo`、`write` 和 `writeln` 的输出重定向到内部字符串；使用 `unsetEchoString()` 取得并清空重定向内容。
+
+<!-- tags: 控制台 输出重定向 捕获输出 echo write writeln redirect -->
+
+返回：integer
+
+### 示例
+
+```tsl
+setEchoString();
+echo "captured";
+captured := unsetEchoString();
+echo captured;
+// 输出：captured
+```
+
+## `unsetEchoString()`
+
+声明：function
+
+取得 `setEchoString()` 重定向的输出内容，并清空输出重定向状态。
+
+返回：string
+
+### 示例
+
+```tsl
+setEchoString();
+echo "captured";
+captured := unsetEchoString();
+echo captured;
+// 输出：captured
+```
+
+## `write(p1, pn)`
+
+声明：function
+
+输出字符串，如果在平台运行，会输出信息到客户端。
+
+<!-- tags: 打印 输出 output print write writeln -->
+
+| 参数 | 类型   | 说明           |
+| ---- | ------ | -------------- |
+| `p1` | string | string 字符串1 |
+| `pn` | string | string 字符串n |
+
+返回：any
+
+### 示例
+
+```tsl
+// 需 CGI 宿主环境
+write("A", "B");
+// 输出：AB
+```
+
+## `writeln(p1, pn)`
+
+声明：function
+
+带回车地输出字符串，如果在平台运行，会输出信息到客户端。
+
+<!-- tags: 打印 输出 output print write writeln -->
+
+支持任意多个参数，按传入顺序逐个输出其内容。
+
+| 参数 | 类型   | 说明           |
+| ---- | ------ | -------------- |
+| `p1` | string | string 字符串1 |
+| `pn` | string | string 字符串n |
+
+返回：any
+
+### 示例
+
+以下示例先输出 `111222`，再换行输出 `333`。
+
+```tsl
+// 需 CGI 宿主环境
+echo "111", "222", "\n", "333";
+// 输出：
+// 111222
+// 333
+```