# Builtin - 资源 / 文件

## `readFile(data_type, alias, file_name, pos, length, data)`

声明：function

将本地的文件读取出来。文件格式可以是字符流、整数流、实数流、字节流等。

| 参数        | 类型    | 说明                                                                                                                                                                                                                      |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data_type` | integer | 整数类型。参考文件读写类型函数。                                                                                                                                                                                          |
| `alias`     | string  | 字符串类型。参考目录别名。                                                                                                                                                                                                |
| `file_name` | string  | 字符串类型。文件名称。                                                                                                                                                                                                    |
| `pos`       | integer | 整数类型。读文件的偏移位置，执行结束后将返回新的位置。                                                                                                                                                                    |
| `length`    | integer | 整数类型。需要读入的数据长度，一次读取的最大长度为100w。                                                                                                                                                                  |
| `data`      |         | 当读文件执行出错，则存贮错误信息，如果执行正确，则用来存贮读出的数据。如果文件类型为rwRaw或者rwBinary则返回一个长度为Length的字符串或者二进制流，否则，返回一个长度为Length的数组。例如类型为rwReal就是返回一个实数数组。 |

返回：bool

### 示例

```tsl
// 按原始类型读出文件的数据
size := rdo2 fileSize("", "c:\\test.txt"); // 获取文件大小
ret := rdo2 readFile(rwRaw(), "", "c:\\test.txt", 0, size, data);
if ret then
return data;
```

## `fileModeToStr()`

声明：function

文件模式数值转换成文件模式字符串。仅NG客户端中支持。

返回：string

### 示例

```tsl
// 本地存在备份文件c:\test11.txt
attr := rdo2 fileMode("", "c:\\test11.txt");
ret := rdo2 fileModeToStr(attr);
return ret;
// 输出：” A”
```

## `zipCompress(zip_alias, zip_filename, alias, filename, path)`

声明：function

将文件压缩到ZIP文件中，如果压缩文件不存在，函数会创建一个。ZIP格式的压缩不支持加密。

| 参数           | 类型   | 说明                          |
| -------------- | ------ | ----------------------------- |
| `zip_alias`    | string | 字符串，ZIP文件的目录别名     |
| `zip_filename` | string | 字符串，ZIP文件名称           |
| `alias`        | string | 字符串，被压缩文件的目录别名  |
| `filename`     | string | 字符串，文件名称              |
| `path`         | string | 字符串，文件在ZIP文件中的路径 |

返回：bool

### 示例

```tsl
// 把文件d:\a.txt压缩到d:\a.zip文件中的/hello/world/a.txt中
zipCompress('', 'd:\\a.zip', '', 'd:\\a.txt', 'hello/world/a.txt');
// 将d:\tmp目录压缩到d:\a.zip文件中
zipCompress('', 'd:\\a.zip', '', 'd:\\tmp', 'test');
```

## `zipExtract(zip_alias, zip_filename, alias, path, password)`

声明：function

将ZIP文件解压到指定目录

| 参数           | 类型   | 说明                       |
| -------------- | ------ | -------------------------- |
| `zip_alias`    | string | 字符串 ，ZIP文件的目录别名 |
| `zip_filename` | string | 字符串 ，ZIP文件名称       |
| `alias`        | string | 字符串，文件解压目录别名   |
| `path`         | string | 字符串，文件解压路径       |
| `password`     | string | 字符串，可选参数，加密密码 |

返回：bool

### 示例

```tsl
// 将ZIP文件解压，可以使用ZipExtract函数，例如将d:\a.zip文件解压到d:\tmp目录
zipExtract('', 'd:\\a.zip', '', 'd:\\tmp', '123');
```

## `rarExtract(rar_alias, rar_filename, alias, path, password)`

声明：function

将RAR文件解压到指定目录

| 参数           | 类型   | 说明                       |
| -------------- | ------ | -------------------------- |
| `rar_alias`    | string | 字符串 ，RAR文件的目录别名 |
| `rar_filename` | string | 字符串 ，RAR文件名称       |
| `alias`        | string | 字符串，文件解压目录别名   |
| `path`         | string | 字符串，文件解压路径       |
| `password`     | string | 字符串，可选参数，加密密码 |

返回：bool

### 示例

```tsl
// 将RAR文件解压，可以使用RarExtract函数，例如将d:\a.rar文件解压到d:\tmp目录
rarExtract('', 'd:\\a.rar', '', 'd:\\tmp', '123');
```

## `listTable()`

声明：function

返回用户数据的名称列表(一维数组)。

返回：array

### 示例

```tsl
return listTable();
// 输出：如下：
```

## `loadTable(name, table_type)`

声明：function

提取用户数据，装入用户表，从name指定的位置将数据导出。TableType参数可省略，默认为0；0或省略时表示装入当前用户表，1表示装入系统表，即可导入系统账号system的用户数据。

| 参数         | 类型   | 说明                                |
| ------------ | ------ | ----------------------------------- |
| `name`       | string | 字符串，数据存储位置的名称          |
| `table_type` | bool   | 布尔类型，数据类型，可省略，默认为0 |

返回：any

### 示例

```tsl
// 将savetable范例中保存的用户数据testA提取出来
return loadTable('testA');
```

## `fileAttrToStr()`

声明：function

文件属性数值转换成文件属性字符串。仅NG客户端中支持。

返回：string

### 示例

```tsl
// 本地存在备份文件c:\test11.txt
attr := rdo2 fileAttr("", "c:\\test11.txt");
ret := rdo2 fileAttrToStr(attr);
return ret;
// 输出：”A”
```

## `strToFileAttr(str)`

声明：function

文件属性字符串转换成文件属性数值。仅NG客户端中支持。

| 参数  | 类型   | 说明                         |
| ----- | ------ | ---------------------------- |
| `str` | string | 字符串类型，文件属性字符串。 |

返回：integer

### 示例

```tsl
str1 := "A";
return rdo2 strToFileAttr(str1);
// 输出：32
```

## `strToFileMode(str)`

声明：function

文件模式字符串转换成文件模式数值。仅NG客户端中支持。

| 参数  | 类型   | 说明                         |
| ----- | ------ | ---------------------------- |
| `str` | string | 字符串类型，文件模式字符串。 |

返回：integer

### 示例

```tsl
str1 := "A";
return rdo2 strToFileMode(str1);
// 输出：32
```

## `ftCsv()`

声明：function

逗号分割文件类型。

返回：integer

## `ftXls()`

声明：function

Excel文件类型。默认会打开EXCEL来读写文件，如果EXCEL未安装，会尝试用文件读写的模式来访问。

返回：integer

## `ftXls2()`

声明：function

支持多表头的Excel文件类型。

返回：integer

## `ftXls3()`

声明：function

Excel文件类型,默认采用文件读写的方式访问，效率高，兼容性稍差，当文件读写的模式无法正确访问，会打开EXCEL来读写文件。

返回：integer

## `ftStream()`

声明：function

天软对象流文件类型。

返回：integer

## `ftString()`

声明：function

天软对象字符串文件类型。

返回：integer

## `ftXml()`

声明：function

XML文件类型。

返回：integer

## `ftdbf()`

声明：function

dbf文件类型。

返回：integer

## `rwByte()`

声明：function

字节流读写类型。读/写字节数组

返回：integer

### 示例

```tsl
size := rdo2 fileSize("", "c:\\test.txt"); // 获取文件大小
ret := rdo2 readFile(rwByte(), "", "c:\\test.txt", 0, size, data);
ret := rdo2 readFile(rwRaw(), "", "c:\\test.txt", 0, size, data1);
if ret then
return data1;
```

## `rwInt()`

声明：function

整数流读写类型。读/写整数数组

返回：integer

## `rwReal()`

声明：function

实数流读写类型。读/写实数数组

返回：integer

## `rwStr()`

声明：function

字符串流读写类型。读/写字符串数组

返回：integer

## `rwObj()`

声明：function

对象流读写类型。读/写对象数组。

返回：integer

## `rwRaw()`

声明：function

原始读写类型。读/写指定长度的字节流。

返回：integer

## `rwBinary()`

声明：function

二进制读写类型。读/写指定长度的字节流。读写的操作使用Binary数据类型。

返回：integer

## `sysClientInfo()`

声明：function

在平台应用可获得客户机信息,这些信息除了客户端收集的有限信息：包括MAC地址/IP/HOSTNAME/操作系统类型以外，还存在其他客户端的信息插件提供的内容，例如一些交易插件会收集交易需要的本地识别码。

返回：array

## `sysExecName()`

声明：function

获得解析器的全路径（包含名称）。

返回：string

### 示例

```tsl
// 客户端中本地执行
return rdo2 sysExecName();
// 输出：C: \Program Files\Tinysoft\AnalyseNG.NET\TSExpert.exe
// 本地解析器中运行
echo sysExecName();
// 打印信息：C: \Program Files\Tinysoft\AnalyseNG.NET\TSL.exe
```

## `pluginPath()`

声明：function

获得解析器的插件目录的全路径（包含名称）。当在WORD里或者EXCEL使用TSL程序的时候，由于宿主程序是WORD，解释器的路径并不在SysExecName下，那么PluginPath的父目录就是解释器的路径。

返回：string

### 示例

```tsl
// 客户端中本地执行
return rdo2 pluginPath();
// 输出：C: \Program Files\Tinysoft\AnalyseNG.NET\Plugin\
```

## `getlogicdrive()`

声明：function

获取本地逻辑驱动器。

返回：integer

### 示例

```tsl
return rdo2 getlogicdrive();
// 有C、D盘，结果为12，即0b1100
```

## `createlink(link_name, target_name, hard)`

声明：function

创建一个目标为TargetName名为LinkName的链接。在Linux系统中用的较多。

| 参数          | 类型   | 说明                                                                 |
| ------------- | ------ | -------------------------------------------------------------------- |
| `link_name`   | string | 字符串，指定链接生成的路径及连接名。无路径时默认生成在天软安装目录。 |
| `target_name` | string | 字符串，文件路径。                                                   |
| `hard`        | bool   | 布尔值，为真表示创建硬链接，否则创建软链接（符号链接）。             |

返回：bool

### 示例

范例01：创建硬链接

```tsl
path := "D:\\test\\test.txt"; // 已经存在的文件
return rdo2 createlink("D:\\test\\txt", path, 1); // 创建一个硬链接
// 输出：创建链接成功，返回1
```

范例02：创建软链接

```tsl
path := "D:\\test\\test.txt"; // 已存在的文件
return rdo2 createlink("D:\\test\\txt", path, 0); // 创建一个软链接
// 输出：链接成功，返回1
```

## `realpath(name)`

声明：function

获取文件真实路径与名称。如果是链接类型文件，或者所处在一个链接目录中，可以得到该文件的真实存贮位置。在Windows上，返回的是一个UNC名称。

| 参数   | 类型   | 说明                         |
| ------ | ------ | ---------------------------- |
| `name` | string | 字符串，文件路径或链接别名。 |

返回：string

### 示例

范例01：获取文件的真实路径

```tsl
path := "D:\\test\\test.txt";
return rdo2 realpath(path);
// 输出：
// 0
```

范例02：获取软链接的真实路径

```tsl
path := "D:\\Links\\soft\\s2";
return rdo2 realpath(path);
// 输出：
// 0
```

范例03：获取硬链接的真实路径

```tsl
path := "D:\\Links\\hard\\h1";
return rdo2 realpath(path);
// 输出：
// 0
```

## `exportFile(_type, alias, file_name, data, include_header, include_index)`

声明：function

将数据导出为文件。支持将INF以及NAN导出到Excel，INF对应为EXCEL的DIV0，NAN对应为NA

| 参数             | 类型    | 说明 |
| ---------------- | ------- | ---- |
| `_type`          | integer |      |
| `alias`          | string  |      |
| `file_name`      | string  |      |
| `data`           | any     |      |
| `include_header` |         |      |
| `include_index`  | bool    |      |

返回：bool|string

### 示例

范例01：

```tsl
data := rand(10, 5);
ret := rdo2 exportFile(ftXls(), "", "c:\\test.xls", data);
if ret=1 then return "导出成功";
else return ret; // 出错
// 输出："导出成功"  (表示数据导出成功，可以在c盘看到test.xls文件)
```

范例02：

```tsl
// 导出INF及NAN异常数值
data := `array('a': (1, 2, 3), 'b': array(4, 5, 6), 'c': array(1/0, 0.0/0.0, 0));
ret := rdo2 exportFile(ftXls(), '', 'C:\\testdata2.xlsx', data);
if ret=1 then return "导出成功";
else return ret; // 出错
// 结果
// 天软数据：
// 导出到Excel中的数据：
```

范例03：导出数据为csv格式

```tsl
t := rand(10, array("A", "B", "C"));
lj := "D:\\Test\\20241204.csv";
r := rdo2 exportFile(ftCsv(), "", lj, t);
return r;
```

## `importFile(_type, alias, file_name, data, include_header, include_index, force_single, sheet_name, range)`

声明：function

从文件中导入数据。对EXCEL文件自动识别.xls或者.xlsx的文件格式，支持将INF以及NAN导入

| 参数             | 类型            | 说明 |
| ---------------- | --------------- | ---- |
| `_type`          | integer         |      |
| `alias`          |                 |      |
| `file_name`      | string          |      |
| `data`           | array           |      |
| `include_header` |                 |      |
| `include_index`  |                 |      |
| `force_single`   | bool            |      |
| `sheet_name`     |                 |      |
| `range`          | string\|integer |      |

返回：bool

### 示例

范例01：

```tsl
data1 := rand(10, 5);
ret1 := rdo2 exportFile(ftXls(), "", "c:\\test.xls", data1);
if ret1 then
begin
ret2 := rdo2 importFile(ftXls(), "", "c:\\test.xls", data2);
if ret2 then
return data2;
else
return "导出失败";
end
else
return 0;
// 输出：
// 无输出。
```

范例02：

```tsl
// 导入excel中的INF及NAN
ret := rdo2 importFile(ftXls(), '', 'C:\\testdata.xlsx', data);
if ret then
return data;
else return ret;
// 输出：
// 无输出。
// Excel中的数据：
// 导入到天软中的数据：
```

范例03：

```tsl
// .xls文件与.xlsx 文件行列最大限制不一样，xls文件最大256列，.xlsx文件最大限制16384
// 列，此处有数据16000列的.xlsx文件，后缀名改为.xls文件，仍可以导入16000列，说明//该函数可以自动识别.xls或者.xlsx的文件格式
ret := rdo2 importFile(ftXls(), '', 'C:\\testdata4.xls', data);
if ret then
return data;
else return ret;
// 结果
```

范例04：导入csv文件

```tsl
lj := "D:\\Test\\20241204.csv";
r := rdo2 importFile(ftCsv(), "", lj, t);
return t;
```

## `iniWriteBool(alias, file_name, section, ident, value)`

声明：function

将BOOL值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将Bool值Value写入到INI文件指定的键

| 参数        | 类型   | 说明                        |
| ----------- | ------ | --------------------------- |
| `alias`     | string | 字符串类型。目录名称        |
| `file_name` | string | 字符串类型。INI文件名称     |
| `section`   | string | 字符串类型。INI文件的节名称 |
| `ident`     | string | 字符串类型。INI文件的键名称 |
| `value`     | bool   | 布尔类型。要写入的键值      |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData9]
bool=1
}
ret := rdo2 iniWriteBool("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata9", "bool", 1);
return ret;
// 输出：0，写入成功
// 文件写入：
```

## `iniWriteDate(alias, file_name, section, ident, value)`

声明：function

将日期值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将日期值Value写入到INI文件指定的键

| 参数        | 类型   | 说明                        |
| ----------- | ------ | --------------------------- |
| `alias`     | string | 字符串类型。目录名称        |
| `file_name` | string | 字符串类型。INI文件名称     |
| `section`   | string | 字符串类型。INI文件的节名称 |
| `ident`     | string | 字符串类型。INI文件的键名称 |
| `value`     | tdate  | 日期类型。要写入的日期值    |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData2]
date=2014/1/12
}
ret := rdo2 iniWriteDate("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata2", "date", 41651);
return ret;
// 输出：0 ，设置成功
// 文件修改：
```

## `iniWriteDateTime(alias, file_name, section, ident, value)`

声明：function

将日期时间值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将日期时间值Value写入到INI文件指定的键

| 参数        | 类型      | 说明                             |
| ----------- | --------- | -------------------------------- |
| `alias`     | string    | 字符串类型。目录名称             |
| `file_name` | string    | 字符串类型。INI文件名称          |
| `section`   | string    | 字符串类型。INI文件的节名称      |
| `ident`     | string    | 字符串类型。INI文件的键名称      |
| `value`     | tdatetime | 日期时间类型。要写入的日期时间值 |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData3]
datetime=2014/1/12 14: 00: 00
}
ret := rdo2 iniWriteDateTime("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata3", "datetime", 41651.5833334);
return ret;
// 输出：0，修改成功
// 文件修改：
```

## `iniWriteFloat(alias, file_name, section, ident, value)`

声明：function

将浮点值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将浮点值Value写入到INI文件指定的键

| 参数        | 类型   | 说明                        |
| ----------- | ------ | --------------------------- |
| `alias`     | string | 字符串类型。目录名称        |
| `file_name` | string | 字符串类型。INI文件名称     |
| `section`   | string | 字符串类型。INI文件的节名称 |
| `ident`     | string | 字符串类型。INI文件的键名称 |
| `value`     | real   | 浮点类型。要写入的浮点数值  |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData4]
float=9.9
}
ret := rdo2 iniWriteFloat("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata4", "float", 9.9);
return ret;
// 输出：0，修改成功
// 文件修改：
```

## `iniWriteInteger(alias, file_name, section, ident, value)`

声明：function

将整数值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将整数值Value写入到INI文件指定的键

| 参数        | 类型    | 说明                        |
| ----------- | ------- | --------------------------- |
| `alias`     | string  | 字符串类型。目录名称        |
| `file_name` | string  | 字符串类型。INI文件名称     |
| `section`   | string  | 字符串类型。INI文件的节名称 |
| `ident`     | string  | 字符串类型。INI文件的键名称 |
| `value`     | integer | 整数类型。要写入的整数值    |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData5]
INT=100
}
ret := rdo2 iniWriteInteger("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata5", "INT", 100);
return ret;
// 输出：0，修改成功
// 文件修改：
```

## `iniWriteTime(alias, file_name, section, ident, value)`

声明：function

将时间值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将时间值Value写入到INI文件指定的键

| 参数        | 类型   | 说明                        |
| ----------- | ------ | --------------------------- |
| `alias`     | string | 字符串类型。目录名称        |
| `file_name` | string | 字符串类型。INI文件名称     |
| `section`   | string | 字符串类型。INI文件的节名称 |
| `ident`     | string | 字符串类型。INI文件的键名称 |
| `value`     | ttime  | 时间类型。要写入的时间值    |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData6]
time=12: 00: 00
}
ret := rdo2 iniWriteTime("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata6", "time", 0.5);
return ret;
// 输出：0，修改成功
// 文件修改：
```

## `iniWriteString(alias, file_name, section, ident, value)`

声明：function

将字符串值写入INI。如果不存在FileName，或者不存在Section，或者不存在Ident，则其会根据输入的FileName，Section，Ident创建对应的INI文件，INI文件的节名称，INI文件的键名称，并将字符串Value写入到INI文件指定的键

| 参数        | 类型   | 说明                        |
| ----------- | ------ | --------------------------- |
| `alias`     | string | 字符串类型。目录名称        |
| `file_name` | string | 字符串类型。INI文件名称     |
| `section`   | string | 字符串类型。INI文件的节名称 |
| `ident`     | string | 字符串类型。INI文件的键名称 |
| `value`     | string | 字符串类型。要写入的字符串  |

返回：any

### 示例

```tsl
{写本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini，
// 设置节内容为：
[IniData7]
String=Hello Tinysoft
}
ret := rdo2 iniWriteString("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "IniData7", "String", 'Hello Tinysoft');
return ret;
// 输出：0，修改成功
// 文件修改：
```

## `iniDeleteKey(alias, file_name, section, ident)`

声明：function

删除INI中的标识符。

| 参数        | 类型   | 说明                                |
| ----------- | ------ | ----------------------------------- |
| `alias`     | string | 字符串类型。目录名称                |
| `file_name` | string | 字符串类型。INI文件名称             |
| `section`   | string | 字符串类型。INI文件中的节名称       |
| `ident`     | string | 字符串类型。INI文件中要删除的键名称 |

返回：any

### 示例

```tsl
{删除本地文件：C: \Program Files\Tinysoft\Analyse.NET\Plugin\test.ini中节Inidata9的键名为bool的内容}
ret := rdo2 iniDeleteKey("",
"C:\\Program Files\\Tinysoft\\Analyse.NET\\plugin\\test.ini", "Inidata9", "bool");
return ret;
// 输出：0，删除成功
```
