X-Path

• X-Path
• 使用案例
  • 配置文件
  • 明确期望
  • 可测试
  • 跨平台
  • 方便
• 设计目标
• 限制
  • 字符
  • 路径分隔符（斜杠）和驱动器
  • 路径组件
  • 文件名
• 路径解析
• 环境变量
• 路径比较
• 参考

⚠️ 警告

这是一个正在进行中的工作，尚未准备就绪

使用案例

配置文件

以下路径在任何平台上都是有效的。它们将在加载时被清理并解析环境变量。

dir1 = "~/mydir/${SOME_ENV}/../"
dir2 = "c:\\anotherdir\\%ANOTHER_ENV%"

明确期望

使用以下之一来传达您的函数或 API 期望的内容。

fn mirror(file: RelFilePath, from: AbsDirPath, to: AbsDirPath) {}

可测试

#[test]
fn test() -> anyhow::Result<()> {
    // imagine that the path string is read from a conf.toml file:
    let dir = AbsDirPath::new(r"~/dir1//..\dir2");
    
    // when using the alternative debug specifier, if the path starts
    // with current working directory or user home, then they are replaced
    // with '.' or '~' respectively. The path separator used is always '/'.
    assert_eq!(format!("{:#?}", dir), "AbsDirPath(~/dir2)");
    
    // standard debug output uses the internal representation of the path
    // which uses the full path with platform specific path separators.
    // linux:
    assert_eq!(format!("{:?}", dir), "AbsDirPath(/home/me/code/dir2)");
    // windows:
    assert_eq!(format!("{:?}", dir), r"AbsDirPath(c:\Users\me\code\dir2)");
}

跨平台

所有平台都可以使用 Windows 风格和 Unix 风格的路径。它们都将被解析并转换为可比较的统一格式。

读取时强制执行典型的文件系统限制。在 Windows 上，应用了 NTFS、VFAT 和 exFAT 限制，这些限制比 Unix 更严格。如果要在 Unix 上运行时应用相同的限制，请启用功能 strict。

方便

作为 &str 访问路径，所有路径都实现了

• 显示 以便于显示。
• AsRef<Path> 以与所有 std::fs 操作进行互操作性。
• 使用 path.segments() 将路径段作为 &strings 遍历。
• 许多方便的功能：请参阅每个路径类型的文档。

设计目标

• 让 rust 的典型 "if it compiles it works" 体验也能适用于跨平台路径处理。
• 使路径可比较，即它们在内存中解析为通用格式，并在使用时转换为特定平台的格式。
• 使用跨平台兼容的路径（尽可能）来编写配置文件。
• AnyPath 适用于通用情况，而特定路径则用于确保兼容性。
• 提供区分绝对路径或相对路径、目录或文件的类型。
  • FilePath, FileAbsPath, FileRelPath
  • DirPath, DirAbsPath, DirAbsPath
• 支持主要操作系统和文件系统。
  • Linux & Unix：大多数文件系统。
  • macOS：HFS+，APFS。
  • Windows：exFAT，NTFS。启用 strict 功能。
• 可比较的路径（因为它们被解析，见下面的路径比较）。

非目标

• 最大性能。
• 疯狂的文件名。即仅支持 UTF-8 文件名。

其他

• 显示解析后的路径或使用 .native_string() 或 format("{path:#}") 输出 OS 本地字符串。
• 错误
  • 处理使用 anyhow 旨在产生全面且易于阅读的消息，而不是可解析的消息。
  • 消息总是包括相关的路径。
  • 消息包括相对路径的当前工作目录。

限制

在创建和操作路径时验证限制。默认情况下，在基于 Unix 的平台上，只应用少数限制。在 Windows 上，有更多的自动限制。

如果您想确保路径在所有平台上无缝工作（尽可能），则启用 strict Cargo 功能。

字符

保留字符

• 斜杠（/ 和 \）：在所有平台上用作路径分隔符。
• $ 和 %：如果位于路径的开头或紧接斜杠之后，将解释为环境变量，见环境变量部分。
• . 和 ~：如果位于路径的开头，后跟斜杠或无字符，则分别解释为当前工作目录和用户主目录。

始终禁止

• 非 UTF-8 字符（即不要使用 OsStr 或 OsString）
• NULL，:

在 strict 模式下或运行在 Windows 上时禁止

• Ascii 控制字符：0x00-0x1F，0x7F
• ", *, /, <, >, ?, \, |
• 文件名：CON，PRN，AUX，NUL，COM0 - COM9 和 LPT0 - LPT9。以及这些文件名后的任何扩展名（例如：.txt）。

路径分隔符（斜杠）和驱动器

路径分隔符保留在内存中，并以平台本机表示形式显示，即使用二进制文件运行的平台。对于 Windows，它是 \，对于其他平台，它是 /。

在 Windows 上，任何驱动器字母都保持小写，在其他平台上则被丢弃。

这意味着以 c:\my\path 或 /my/path 编写的字符串将被转换并存储在内存中，并按以下方式显示：

• Windows：当当前目录的驱动器字母为 c 时，为 c:\my\path
• 其他平台：为 /my/path

路径组件

路径组件限制为最多 255 个字符。

文件名

在严格模式或Windows平台上运行时禁止：CON、PRN、AUX、NUL、COM0 - COM9 和 LPT0 - LPT9。还包括这些文件名加上扩展名（例如：.txt）。

路径解析

路径解析不涉及文件系统访问，因此路径不需要存在。

说明

• ^* - 任何/也可以是\。
• nix - 基于Unix的平台：Linux、Unix、macOS。
• win - Windows
• current_dir() - 指的是rust的std::env::current_dir()
• var() - 指的是rust的std::env::var(key)
• home_dir() - 指的是dirs_sys::home_dir()

环境变量

对于环境变量有有限的支撑，其中只有以Unix风格开始的路径段：以${开头并以}结尾，或者在Windows风格中以%开头和结尾的路径段会被解释为环境变量并在读取时展开。比通常更严格的限制减少了与正常路径的干扰。

解释为环境变量

• /dir/${MYVAR}/、${MYVAR}、${MYVAR}/dir、/dir/${MYVAR}
• /dir/%MYVAR%/、%MYVAR%、%MYVAR%/dir、/dir/%MYVAR%

不被解释为环境变量

• $MYVAR - 缺少大括号
• hi${MYVAR，${MYVARhi，hi%MYVAR%，%MYVAR%hi - 前后不是斜杠的任何字符。
• ${MYVAR，%MYVAR - 未关闭。
• ${MY-VAR}，%MY-VAR%：不允许在环境变量中使用该字符。

返回错误

• ${}，\${}，\${}\ - 空键是无效的
• %MYVAR 当环境变量 MYVAR 未定义时。