# io 库模块帮助文档 ## io 成员列表 # 文件、文件流相关函数库, 包含控制台标准输入输出流操作, 直接操作控制台请使用 console函数库，这是自动导入的内置库, [使用手册相关文档](https://www.aardio.com/zh-cn/doc/library-guide/builtin/io/file.html) ### io._exedir # 主程序所在目录, 返回完整长路径，不会返回8.3短路径，不会返回相对路径目录路径以反斜杠结束 ### io._exefile # 主程序文件名 ### io._exepath # 主程序文件路径返回完整长路径，不会返回8.3短路径，不会返回相对路径 ### io.appData # 获取 %LocalAppData% 目录下的绝对路径。可选使用指定需要存入的数据 ### io.appData(path,data) # 将@path指定的相对路径转换为系统 %LocalAppData% 目录下的绝对路径, 可选使用 @data 指定需要存入的数据, 存入文件与目标文件长度不同或 PE 时间戳不同则允许替换旧文件, 指定 @data 参数后如果无法创建文件返回null, 最后返回转换所得的完整路径 ### io.close() # 关闭控制台窗口。程序退出也会自动关闭控制台窗口。调用 execute("pause") 或 console.pause() 可等待用户按键以避免立即退出 ### io.createDir("/") # 创建目录如果有多个参数则首先用io.joinpath拼接如果父目录尚未创建将自动创建成功返回完整路径,失败返回空值 ### io.curDir # 获取或修改当前目录 ### io.curDir() # 无参数获取当前目录 ### io.curDir(dir) # 将 @dir 参数指定的目录路径转换为完整路径并设为当前目录成功返回 true ### io.dirname(path) # 等价于 io.splitpath(path).dir 。返回参数 @path 指定路径的目录部分路径。也就是取最后一个斜杆或反斜杆之前的路径。返回路径不会转换斜杆为反斜杆，也不会转为完整路径。改用 fsys.getParentDir 函数取父目录。改用 io.splitpath 可获取路径的文件名、后缀、分区号等。 ### io.exist # 判断文件路径是否存在，也可以用于判断文件是否可读写。包含不可见字符的错误路径可用「工具>文本文件>十六进制编辑器」或 string.hex 函数查看 ### io.exist("文件路径") # 判断文件路径是否存在存在则转换为绝对路径并返回该路径,不存在返回null 参数@1不是有效字符串返回null ### io.exist("文件路径",2) # 测试文件是否可写成功则转换为绝对路径并返回该路径,失败返回null 目录或只读文件直接返回null 参数@1不是有效字符串返回null ### io.exist("文件路径",4) # 测试文件是否可读成功则转换为绝对路径并返回该路径,失败返回null 目录返回null 参数@1不是有效字符串返回null ### io.exist("文件路径",6) # 判断文件是否可读写成功则转换为绝对路径并返回该路径,失败返回null 目录返回null 参数@1不是有效字符串返回null ### io.file # 打开文件,成功返回文件对象, 失败返回 null,错误信息,错误代码。此函数创建的文件对象作为调用原生 API 的参数时可自动转换为系统文件句柄（存为指针类型）。 ### io.file("/文件路径","读写模式",共享模式) # 参数@1指定路径, 路径首字符可用斜杠表示应用程序根目录，用~加斜杠表示EXE根目录。如果`~\`或`~/`开头的EXE根目录路径不存在，自动转换为应用程序根目录下的路径重试。参数@2指定打开文件的读写模式，支持以下选项: w+ 可读写模式，创建新文件清空源文件 w 只写模式，清空原文件 r+ 可读写模式，文件必须存在,不清空文件内容 r 只读模式,文件必须存在 a+ 可读写追加模式，可打开原文件移动指针到文件尾，也可创建新文件 a 只写追加模式，可打开原文件移动指针到文件尾，也可创建新文件 b二进制模式，不转换回车换行 t文本模式，输入使用单换行,输出使用回车换行,遇到 ``'\x1A'``或 ``'\0'``字符终止输入 R 随机优化 S 连续优化 D 创建临时文件,关闭对象后删除文件注意: r,w,a只能且必须选择其中一个作为读写模式的第一个字符参数@3 可选以 _SH_前缀常量指定共享模式 ### io.file() # 第一个参数为 null 或空字符串时创建并返回临时文件 [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### io.file(系统文件句柄,读写模式) # 系统文件句柄转换为文件对象读写模式为字符串,同样使用"r","w","b"等标记必须与原来的文件句柄使用相同的模式 ### io.fullpath("字符串参数") # 将相对路径转换为绝对路径，转换规则如下: 如果路径以双反斜杠 `\\` 开始，不作转换直接返回，路径前加 `\\?\` 可避免转换并支持畸形路径，如果路径以双正斜杠 `//` 开始，移除第一个斜杠后返回，不作其他转换，用于表示系统分区根目录。如果以单个 `\` `/` 字符开始，作为 aardio 应用程序根目录下的相对路径转换并返回完整路径。如果路径以 `~` 开始,作为当前运行的EXE根目录下的相对路径转换并返回完整路径。其他路径按系统规则转换为完整路径。转为完整路径时会将斜杆规范为反斜杆。传入空字符串或空值返回 null 注意相对路径 `.\` 易被改变，例如打开文件对话框可能改变相对路径。而 aardio 提供的应用程序根目录表示确定的位置。 ### io.getSize() # 获取参数@1指定路径的文件字节长度, 返回数值 ### io.getSpecial(_CSIDL) # 获取特殊文件夹, 参数@1使用 _CSIDL 开头的常量指定特殊文件夹的 CSIDL, 不指定参数@1则默认值为 _CSIDL_DESKTOP, 可选增加任意个拼接到目录后的子路径参数这个函数与fsys.getSpecial函数用法接近, 但支持不定个数子路径参数, 不支持返回PIDL fsys.knownFolder 可用于获取更多已知的特殊文件夹 ### io.getText(可选指定缓冲区大小) # 读取控制台文本不包含尾部的回车换行, 相比使用io.stdin.read函数,io.getText 可更好的支持 Unicode 字符 ### io.joinpath # 用于拼接多个文件路径。此函数可以避免文件路径首尾连接处缺少、或多余反斜杠的问题。 ### io.joinpath(dir,...) # 用于拼接多个文件路径参数。此函数首先会将斜杠自动转换为反斜杠。如果连接的非空路径之间没有至少一个反斜杠，则添加反斜杠。如果连接处双方都有反斜杠，则去掉其中一个。也可用参数 @1 指定目录参数，然后参数 @2 指定一个要按上述规则追加到尾部的反斜杠。 ### io.libpath("字符串参数") # 将库路径转换为文件路径; 如果库存在则返回 2 个值:库文件路径,库文件所在目录否则库路径返回null空值,按用户库合法格式返回目录路径, 返回的库目录路径以反斜杠结束. ### io.lines # 创建用于 for in 语句的迭代器,逐行读取文件, 按行拆分普通字符串请使用 string.lines 函数 ### io.lines() # 无参数时逐行读取标准输入（控制台输入） ### io.lines(文件对象） # 创建用于 for in 语句的迭代器,逐行读取文件。参数请指定一个用 io.file 打开的文件流对象，等价于调用对象的 lines 成员函数。如果以文本模式打开文件,返回文本不含换行符, 如果以二进制模式打开文件仅移除换行符（不移除回车符）,遇`'\0'`会丢弃后续字符。不负责关闭参数传入的文件对象 ### io.lines(文件路径） # 创建用于 for in 语句的迭代器,逐行读取文件以文本模式打开文件，遇到``'\x1A'``、``'\0'``终止输入。返回的文本不包含换行。循环结束立即关闭此函数打开的文件对象。但是：如果使用 break,return 等语句中断循环，则打开的文件对象可能不会立即关闭（稍后内存回收后关闭）。改为传入文件对象作为参数，可自行控制何时关闭文件 ### io.localpath("字符串参数") # 如果路径使用了 aardio 专用格式转换为系统支持的完整路径，否则返回空值。转换规则如下：如果路径以双反斜杠 `\\` 开始，不作转换直接返回 null 空值, 如果路径以双正斜杠 `//` 开始，移除第一个斜杠后返回，不作其他转换，可用于表示系统分区根目录。如果以单个 `\` `/` 字符开始，将参数作为 aardio 应用程序根目录下的相对路径转换并返回完整路径。如果路径以 `~` 开始，将参数作为当前启动 EXE 根目录下的相对路径转换并返回完整路径。其他格式路径不作转换返 null 空值。 ### io.open() # 此函数用于打开控制台。除可选用参数 @2 自定义控制台标题（参数 @1 必须为 null 值），不可指定任何其他参数。改用基于 io.open 的 console.open 打开控制台可提供更多功能： - console 的很多库函数可自动按需调用 console.open - console.open 不会像 io.open 那样重置控制台并清除之前输出的内容 - console.open 将更好地设置的控制台选项 - console.open 会自动重定向 msvcrt.dll 的标准输入输出流 - console.open 发布 afterConsoleOpen 消息，其他库可响应该消息并自动重定向标准输入输出到控制台。 ! [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### io.popen() # [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### io.popen(命令行,读写模式) # 执行参数 @1 指定的命令，成功返回进程管道对象。失败返回 null,错误信息,错误代码。参数 @1 如果为完整路径且包含空格，应在首尾加上双引号。读写模式为 "r" ( 或省略 )返回绑定目标进程输入流的管道对象，读写模式为 "w" 返回绑定绑定目标进程输出流的管道对象。此函数不隐藏目标程序控制台，建议提前打开控制台。建议改用更强大的 process.popen（支持隐藏控制台） ### io.print # 在标准输出流（默认为控制台）输出信息。此函数没有自动打开控制台的功能。改用 print，console.log 函数可自动打开控制台窗口。 ### io.print(...) # 在标准输出流（默认为控制台）输出信息。可指定任意个参数，参数自动调用 tostring 函数转为字符串。多参数输出时自动以制表符分开，最后会输出一个换行。 ### io.remove("字符串参数") # 删除参数 @1 指定路径的文件。在路径前加上 `\\?\` 可支持畸形路径。成功返回 true，失败返回 null，错误信息，错误代码。此函数仅用于删除文件，删除目录请改用 fsys.delete、fsys.deleteEx 或 fsys.remove 函数。 ### io.rename # 重命名文件 ### io.rename(from,to) # 将参数 @1 指定路径的文件重命名为参数 @2 指定的文件路径。成功返回 true，失败返回 null ### io.specialData(path,data,csidl) # 将 @path 指定的相对路径转换为特殊文件夹下的绝对路径, 可选使用 @data 指定需要存入的数据, 存入文件与目标文件长度不同或 PE 时间戳不同则允许替换旧文件, 指定 @data 参数后如果无法创建文件返回null, 参数@csidl 使用 _CSIDL 开头的常量指定特殊文件夹的 CSIDL, 不指定@csidl 则默认值为 _CSIDL_DESKTOP, 最后返回转换所得的完整路径 ### io.splitpath() # 拆分文件路径为目录、文件名、后缀名、分区号等。返回 io.pathInfo 对象（类据类型为 `table`）。返回对象可修改 drive,path,name,ext 等字段，并提供 dir（目录路径）与 file（文件名）两个只读字段。返回对象也可作为 tostring 函数的参数重新合并为文件路径。此函数不会转换斜杠与反斜杆，不会扩展与置换 `..` 或 `.`目录，也不会转换为完整路径。 [返回对象:ioSplitFileInfoObject](#ioSplitFileInfoObject) ### io.stderr # 标准错误输出, 在二进制模式下不做任何转换, 但在文本模式下始终以 Unicode 编码输出文本, [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### io.stdin # 标准输入, 在二进制模式下不做任何转换, 但在文本模式下始终以 Unicode 编码读取返回UTF-8编码文本, 自控制台读取字符时,使用io.getText可以更好的支持Unicode字符 [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### io.stdout # 标准输出, 在二进制模式下不做任何转换, 但在文本模式下始终以 Unicode 编码输出文本, [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### io.tmpname # 生成系统临时文件目录下的临时文件路径。此函数不会生成实际的文件，即使密集调用也不会生成相同的文件名。 ### io.tmpname(prefix,ext) # 生成临时文件路径，可选用 @prefix 参数指定前缀名，可选用 @ext 参数指定后缀名，后缀名应包含点 ### io.updateData # 更新指定文件的数据 ### io.updateData(data,path,...) # 更新指定 @path 指定路径的文件为 @data 指定的数据。如果添加更多参数，则首先调用 io.joinpath 拼接到 @path 后面。存入文件与目标文件长度不同或 PE 时间戳不同则允许替换旧文件。替换失败返回 null，否则返回文件路径 ### io.utf8 # 设为true允许控制台启用UTF8模式所有线程设置必须相同,否则会导致重新打开控制台, WIN10 以上系统默认值为 true 。在 WIN10 以下的系统不建议设为 true, console 标准库始终使用 unicode 输出文本 io.stdin,io.stdout,io.stderr 在默认的非二进制模式也使用 unicode 编码 ## io.file 成员列表 # ### io.file.read(文件路径) # string.load 函数的别名。以二进制模式读取文件或内嵌资源文件，返回普通字符串。路径开始可用单斜杠（或单反斜杠）表示应用程序根目录，前面再加`~`表示 EXE 根目录。如果`~\`或`~/`开头的EXE根目录路径不存在，自动转换为应用程序根目录下的路径重试。 ### io.file.write(path,...) # 以二进制模式创建或打开文件并写入数据（清空原数据）。参数 @1 指定要写入的文件路径。其他一个或多个参数指定要写入的数据（可指定字符串，数值，buffer，或结构体）。成功返回 true，失败返回 null,错误信息,错误代码。 string.save 函数作用类似但仅支持单个参数（只能是字符串或 buffer 类型）。另外，string.save 将参数 @2 设为 true 可以追加而不清空数据。 ## ioFileObject 成员列表 # ### ioFileObject.close() # 关闭文件流 ### ioFileObject.flush() # 输出缓冲区数据成功返回 true，失败返回 null,错误信息,错误代码 ### ioFileObject.lines() # ```aardio for line in ioFileObject.lines(){ /*逐行读取文件，循环返回当前行（字符串值）。如果以文本模式打开文件，返回文本不含换行符。如果以二进制模式打开文件仅移除换行符（不移除回车符）,遇'\0'会丢弃后续字符。*/ } ``` ### ioFileObject.mode() # 不指定参数时返回表示文件读写模式的数值，对于标准输入输出流,aardio在二进制模式不转换编码,在文本模式负责自动转换编码普通文件对象 aardio 以 UTF8 编码或二进制模式读写, 不会自动转换文本编码。 ### ioFileObject.mode(mode) # 修改文件模式参数可设为二进制模式 _O_BINARY 或文本模式 _O_TEXT, 其他_O_WTEXT,_O_U16TEXT,_O_U8TEXT要求UTF-16读写，用于多字节或二进制操作会导致程序异常返回表示文件读写模式的数值，失败返回 null,错误信息,错误代码。指定错误的模式参数时会抛出异常 ### ioFileObject.read # 自文件读取数据。支持不定个数参数，每个参数指定一个读取标志并增加一个返回值。参数为"%s"读取并返回一行，参数数为 "%d" 读取一个数值。参数为数值则读取指定字节长度的数据并返回字符串。参数为结构体则读取数据并填充结构体的值。函数执行失败返回 null,错误信息,错误代码。 ### ioFileObject.read("%d") # 从当前位置,向后读取下一个数值，支持多参数。失败返回 null,错误信息,错误代码。 ### ioFileObject.read("%s") # 从当前位置,向后读取下一行，支持多参数。失败返回 null,错误信息,错误代码。 ### ioFileObject.read() # 从当前位置,向后读取下一行。失败返回 null,错误信息,错误代码。 ### ioFileObject.read(-1) # 向后读取到文件尾部。参数为负数表示读取到从文件尾部倒计数位置，支持多参数。成功返回读取数据，失败返回 null,错误信息,错误代码。读取普通文件全部数据使用 string.load 或 string.loadBuffer 更方便。 ### ioFileObject.read(0) # 检测是否未读取到文件尾。如果未到文件尾返回空字符串，已到文件尾则返回 null。注意在布尔表达式中空字符串等于 true，null 等于 false。 ### ioFileObject.readAll() # 移动指针到文件头，读取到文件尾返回全部数据。改用 -1 为参数调用 read 函数可自当前位置读取到文件尾。简单读取普通文件全部数据使用 string.load 或 string.loadBuffer 更方便 ### ioFileObject.readBuffer # 读取数据到 buffer，成功返回读取长度，失败返回null ### ioFileObject.readBuffer(buffer指针,读取长度) # 直接读数据到内存，参数 @1 可以是 buffer,或内存指针。如果参数 @1 是指针则必须指定读取长度，否则可选是否指定长度参数。成功返回读取长度。 ### ioFileObject.readTo() # 读取到指定结束字符前面的所有字符, 参数@1指定结束字符的字节码（数值）, 单引号包含字符并加#号取字节码，例如 `'\0'#` 如果没有指定参数,则参数默认为`'\0'#` 返回字符串不包含结束字符,但文件指针会移到该字符后面, 如果未遇到指定字符,则读取到文件尾 ### ioFileObject.readUtf16(读取字符数) # 读取 UTF-16 编码数据,如果文件头有 BOM 会自动移除, 参数按字符计数，不是按字节计数, 如果已到文件尾读取长度可能小于参数指定的长度 ### ioFileObject.readUtf16(读取字符数,true) # 读取 UTF-16 编码数据,并直接返回 UTF-16 编码的字符串, 参数按字符计数，不是按字节计数 ### ioFileObject.readback() # 从当前位置,向前读取上一行仅支持UTF8或ANSI换行符,不支持UTF16换行符正数参数表示从当前位置向前读取n个字节 ### ioFileObject.readback(-1) # 向前读取到文件头部负数表示从文件头部倒计数位置 ### ioFileObject.readback(0) # 检测是否读取到文件头 ### ioFileObject.reopen("CONOUT$","w") # 可使用"CONOUT$"重定向到控制台输出缓冲区, 使用"CONOUT$"重定向到控制台输入缓冲区, 重定向到控制台只能使用文本模式参数@2不可使用ccs标记指定编码成功返回 true，失败返回 null,错误信息,错误代码 ### ioFileObject.reopen("字符串参数","w+") # 重定向文件流成功返回 true，失败返回 null,错误信息,错误代码 ### ioFileObject.seek("cur",) # 移动至相对当前位置的指定偏移量，偏移量应当是一个普通数值。 1表示向后移动1字节,-1表示向前倒退1字节, 成功返回当前位置（相对于文件开始计数）, 失败返回null,错误信息,注意超越文件尾是允许的 ### ioFileObject.seek("end") # 移动指针至结束处,并返回文件长度获取文件大小推荐使用 size() 函数 ### ioFileObject.seek("end",) # 移动至相对结束处的指定偏移量，偏移量应当是一个普通数值。成功返回当前位置（相对于文件开始计数）, 失败返回 null,错误信息,错误代码。注意超越文件尾是允许的 ### ioFileObject.seek("set") # 移动指针到开始 ### ioFileObject.seek("set",) # 移动至相对开始处的指定偏移量。注意0表示文件开始,1表示第一个字节后面,准备读取的是应该是第2字节, 成功返回当前位置（相对于文件开始计数）, 失败返回 null,错误信息,错误代码。注意超越文件尾是允许的。偏移量应当是一个普通数值。普通数值的整数上限为 8PB，没有可能会写这么大的文件。所以偏移量不支持、也不必要使用 math.size64 对象 ### ioFileObject.seek() # 得到当前位置（相对于文件开始计数） ### ioFileObject.seteof() # 将当前文件位置设为文件末尾, 用于快速改变文件大小成功返回true ### ioFileObject.setvbuf("full",) # 设为完全缓冲模式，读缓冲区直致为空再从流读入数据，写满缓冲区后向流写入数据参数@2使用字节数指定缓冲区大小 ### ioFileObject.setvbuf("line",) # 设为行缓冲模式，每次从流中读取或写入一行数据参数@2使用字节数指定缓冲区大小 ### ioFileObject.setvbuf("no") # 禁用缓冲 ### ioFileObject.size() # 返回文件总大小，返回值为普通数值。该函数不会改变文件指针当前位置，此函数不需要指定任何参数。 size 函数可以表示的大小为 8PB，一般没有必要使用 size64 函数。 ### ioFileObject.size64() # 返回文件总大小，返回值为 math.size64 对象。此函数不会改变文件指针当前位置。 size 函数可以表示的大小为 8PB，一般没有必要使用 size64 函数。 [返回对象:mathSize64Object](https://www.aardio.com/zh-cn/doc/library-reference/math/_.html#mathSize64Object) ### ioFileObject.type() # 获取文件对象的类型例如控制台，管道，本地文件....等等返回值请参考_FILE_TYPE_前缀的常量 ### ioFileObject.write # 写数据 ### ioFileObject.write() # [返回对象:ioFileObject](https://www.aardio.com/zh-cn/doc/library-reference/io/_.html#ioFileObject) ### ioFileObject.write(, ) # 写数据，可指定一个或多个参数。所有参数都支持字符串、buffer、数值、结构体等类型。成功返回对象自身（可作为逻辑真值），失败返回 null,错误信息,错误代码 ### ioFileObject.writeBuffer # 写入内存数据，成功返回写入长度,失败返回 null ### ioFileObject.writeBuffer(bufferOrPointer,writeSize) # 直接写内存数据到文件中。参数 @bufferOrPointer 可以是 buffer、字符串、内存指针，如果参数 @bufferOrPointer 是指针则参数 @writeSize 必须指定写入长度，否则 @writeSize 参数可选（默认自动获取字符串或 buffer 参数的长度）。成功返回写入长度。