文件路径

一. aardio 文件路径解析规范

在 aardio 中，相对于易受系统环境干扰的当前工作目录（./ 或 .\），aardio 提供了一套更可靠的内置路径解析机制。

特殊路径前缀语法

aardio 规定了两种特殊的路径标识符：

1. 应用级虚拟绝对路径（Virtual Absolute Path）

   • 语法： 以单斜杠 / 或单反斜杠 \ 作为前导首字符。
   • 解析： 目标路径将被严格锚定至当前的应用程序基准目录。

   应用程序基准目录（Runtime Application Base Directory） 是 aardio 解析相对路径的核心锚点。该目录在生命周期内具有不可变性（仅在创建线程或纤程时可以自定义，运行时无法篡改），其具体指向会根据运行上下文自动确定：

   • 开发环境：
     • 运行工程内的源文件：指向 aardio 工程根目录。
     • 独立运行工程外部的源文件：指向 该代码文件所在目录。
     • 在代码编辑器运行未保存的代码：指向 aardio.exe 所在目录。
   • 发布运行：
     • 运行生成的独立程序：指向 启动 EXE 文件所在目录。
   • 启动线程或纤程：
     • 线程（以 aardio 源文件作为启动参数）：指向 启动源文件所在目录*。
     • 纤程（fiber.create(func, appBaseDir)）：可由 appBaseDir 参数 自定义。

2. 可执行文件目录路径（Executable Directory Path）

   • 语法： 以波浪号加斜杠（ ~/ 或 ~\ ）作为前缀。
   • 解析： 目标路径将被严格锚定至当前启动 EXE 文件所在目录（在开发调试阶段，即指向 aardio.exe 所在目录）。

   aardio 内部仍将单个 ~ 前导的路径处理为 EXE 根目录路径，但不再建议这样写（请改用更明确的 ~/ 或 ~\ 前缀）。

适用范围： aardio 中基本所有需要用到文件路径参数的方法、属性或功能 —— 如 string.load, string.save 等内置库或标准库函数、文件包含操作符（$）、UI 控件的图片路径均原生支持上述路径语法。

路径自动退化机制（Fallback Mechanism）

在部分资源加载场景下，aardio 为 ~/ (EXE 目录) 提供了智能的路径退化策略：

当路径以 ~/ 或 ~\ 开头，但在 EXE 目录下并未找到对应的实际文件时，引擎会自动将其前缀降级转换为 / 或 \，转而在应用程序基准目录下进行二次寻址重试。

支持此退化机制的指令与函数包括：

• 二进制内嵌操作符：$ （例如 $"~/res/config.json"）
• 加载外部动态库：raw.loadDll(path)
• 加载字符串文本：string.load(path)
• 加载数据缓冲区：string.loadBuffer(path)

转换为通用格式

将使用了 aardio 专用格式的文件路径传入外部接口（例如 DLL 导入的 API，COM 控件对象接口）前应进行转换，常用转换方法：

• io.fullpath(path) 将 path 参数转换为绝对路径。
• io.localpath(path) || path 仅在 path 参数是以单个\、/或 ~字符开始的文件路径才会转换为绝对路径，否则直接返回。

自定义基准目录

• io.joinpath2(baseDir,subPath) 将参数 @baseDir 指定的目录作为基准目录，即使 @subPath 以 ~ 或单个 /、\ 开始仍会视为相对路径并执行拼接。
• io.fullpath2(path,baseDir) 将参数 @baseDir 指定的目录作为基准目录，即使 @path 以 ~ 或单个 /、\ 开始仍会视为相对路径并执行拼接，然后再转换为绝对路径。

二. 常用函数与属性

io.localpath 函数 #

1. 函数原型：

   绝对路径 = io.localpath( 相对路径 )

2. 函数说明：

   如果参数指定的文件路径使用了 aardio 专用格式则转换为系统支持的完整路径，否则返回空值。

   转换规则如下：

   • 如果文件路径以双反斜杠 \\ 开始，不作转换直接返回 null 空值。
   • 如果文件路径以双正斜杠 // 开始，移除第一个斜杠后返回，不作其他转换，可用于表示系统分区根目录。
   • 如果文件路径以单个 \ / 字符开始，将参数作为 aardio 应用程序基准目录下的相对路径转换为完整路径。

   • 如果文件路径以 ~/ 或 ~\ 开始，将参数作为当前启动 EXE 根目录下的相对路径转换并返回完整路径。

     此函数仍将单个 ~ 前导的路径处理为 EXE 根目录路径，但不再建议这样写（请改用更明确的 ~/ 或 ~\ 前缀）。

   • 其他格式路径不作转换返回 null 空值。

io.fullpath 函数 #

1. 函数原型：

   绝对路径 = io.fullpath( 相对路径 )

2. 函数说明：

   io.fullpath 将输入参数指定的相对路径转换为绝对路径。

   转换规则如下:

   • 如果文件路径以双反斜杠 \\ 开始，不作转换直接返回，路径前加 \\?\ 可避免转换并支持畸形路径。
   • 如果文件路径以双正斜杠 // 开始，移除第一个斜杠后返回，不作其他转换，可用于表示当前分区根目录。注意 string.save,io.file 等函数并不支持这种写法。
   • 如果文件路径以单个 \ 或/ 字符开始的应用级虚拟绝对路径（Virtual Absolute Path），则会作为 aardio 应用程序基准目录下（Runtime Application Base Directory）的相对路径转换为完整路径。

   • 如果文件路径以 ~/ 或 ~\ 开始，作为当前运行的 EXE 根目录下的相对路径转换并返回完整路径。

     此函数仍将单个 ~ 前导的路径处理为 EXE 根目录路径，但不再建议这样写（请改用更明确的 ~/ 或 ~\ 前缀）。

   • 其他路径按系统规则转换为完整路径。

   • 传入空字符串或空值返回 null 。

   此函数并不会检测路径是否存在，但会检测参数是否正确的路径名，并纠正错误的写法，例如将正斜杠修正为反斜杠。

   aardio 自带的文件操作函数基本都会自动调用 io.fullpath 转换参数传入的文件路径。

   但是要注意在文件路径开始以 ~/ 或 ~\ 表示 EXE 启动目录以及用单个前导 \ 或 / 表示 aardio 应用程序基准目录的写法仅适用于 aardio，其他外部组件或外部接口并不支持，我们需要调用 io.fullpath 将 aardio 路径转换为其他外部程序可以识别的绝对路径。

3. 调用示例：

   var path = io.fullpath( "/res/test.jpg" )
   

io.fullpath2 函数 #

1. 函数原型：

   fullpath = io.fullpath2(path,baseDir)

2. 函数说明：

   如果参数 @path 为 null 则返回 null 。
   如果未指定参数 @baseDir 则将 @path 转换为绝对路径。
   否则调用 io.joinpath2 拼接并转换为绝对路径。

   拼接规则如下：

   1. 如果 @subPath 是以盘符、\\开始的绝对路径则直接返回，
      
   2. 如果 @subPath 是以 //开始的路径转换为单个斜杆开始的路径后返回，
      
   3. 否则调用 io.joinpath 拼接 @baseDir 与 @subPath 。@subPath 以 ~ 或单个 /、\ 开始仍会执行拼接。
      

3. 调用示例：

   var path = io.fullpath2( "/example/test.jpg","/base-dir/" )
   

io.joinpath 函数 #

1. 函数原型：

   fullpath = io.joinpath( dir,... )

2. 函数说明：

   用于拼接任意多个文件路径。
   此函数可以避免文件路径首尾连接处缺少、或多余反斜杠的问题。

   此函数首先会将斜杠自动转换为反斜杠。
   如果连接的非空路径之间没有至少一个反斜杠，则添加反斜杠。
   如果连接处双方都有反斜杠，则去掉其中一个。

3. 调用示例：

    var path = io.joinpath(dir,subdir,"test.txt");
   

   ❌ 错误用法: dir ++ subdir ++ "test.txt"
   ✅ 正确用法: io.joinpath(dir,subdir,"test.txt")

io.joinpath2 函数 #

1. 函数原型：

   path = io.joinpath2(baseDir,subPath)

2. 函数说明：

   拼接路径。
   如果 @baseDir 为 null 则直接返回 @subPath，
   否则@baseDir 与 @subPath 都必须指定字符串。

   如果 @subPath 是以盘符、\\、//开始的绝对路径则直接返回。
   否则调用 io.joinpath 拼接 @baseDir 与 @subPath 。@subPath 以 ~ 或单个 /、\ 开始仍会执行拼接。

   io.joinpath 则支持不定个数参数，但只做简单拼接，不识别绝对路径。io.joinpath 与 io.joinpath2 都不会调用 io.fullpath 将返回值转换为绝对路径

3. 调用示例：

   var path = io.joinpath2("/base-dir/","/example/test.jpg");
   

io.exist 函数

1. 函数原型：

   fullpath = io.exist( path,mode )

2. 函数说明：

   指定的文件路径参数 @path 如果不是字符串、不是一个合法的路径、或是一个空字符串时该函数返回 null 值。否则，此函数调用 io.fullpath 将文件路径转换为绝对路径，如果文件存在返回绝对路径,否则返 回 null 。

   参数 @mode 用于添加检测条件，可选值如下：

   • null 值或省略，仅检查文件路径是否存在。
   • 2，检查文件是否可写，失败返回 null 值，路径如果是目录或只读文件返回 null。
   • 4，检查文件是否可读，失败返回 null 值，路径如果是一个目录返回 null。
   • 6，检查文件是否可读写，失败返回 null 值，路径如果是一个目录返回 null。

   传入错误的参数 @path 时，io.exist 不会抛出异常，而是返回 null 值。

   null 在条件表达式中可以转换为 false , 表示条件假值。

3. 调用示例：

   var fullpath = io.exist(  "/res/test.jpg" );
   
   if(!fullpath){
     error("文件不存在")
   }
   

io.splitpath 函数

1. 函数原型：

   var pathInfo = io.splitpath( filepath )
   

2. 函数说明：

   该函数拆分参数 filepath 指定的文件路径为多个部分，并返回包含这些拆分部分的对象 pathInfo 。

   pathInfo 有以下成员:

   • pathInfo.dir 表示文件路径所在的目录路径，以斜杠结束
     
   • pathInfo.name 表示文件名(无后缀)
     
   • pathInfo.ext 表示文件后缀名(包含圆点)
     
   • pathInfo.file 包含后缀名的完整文件名
     
   • pathInfo.drive 所在的分区号,以冒号结束。
     
   • pathInfo.dir ++ pathInfo.file 等于完整的文件路径。
     

3. 调用示例：

   //新建一个控制台程序，main.aardio 代码如下
   
   //将参数去掉引号
   var path = string.trim( _CMDLINE ,'"');
   
   //拆分为目录名,文件名,后缀名,分区号
   var pathInfo = io.splitpath(path)
   
   //重命名
   io.rename( path,pathInfo.dir ++ pathInfo.ext )
   
   //发布该程序为 exe 文件,将需要去掉文件名字的文件 - 往该 exe 上一拖即可.
   

io._exepath

只读属性，返回启动主程序的exe文件路径，开发环境中此属性返回 aardio.exe 的完整文件路径。

io._exedir

只读属性，返回启动主程序的 exe 文件所在的目录路径，开发环境中此属性返回 aardio.exe 所在的目录路径。

io._exefile

只读属性，返回启动主程序的 exe 文件名

Markdown 格式