Lumesh fs模块

wiki libs

Lumesh 文件系统模块使用文档

模块概述

Lumesh 的文件系统模块提供了丰富的文件/目录操作功能,分为以下几个功能组:

获取信息类函数 (Get)

fs.dirs

  • 功能: 获取系统标准目录路径
  • 返回值: 返回包含系统目录路径的映射表
  • 示例:
fs.dirs()  #-- 返回 {home="...", config="...", cache="...", data="...", pic="...", desk="...", docs="...", down="...", current="..."}

fs.ls

  • 功能: 列出目录内容
  • 参数:
    • 可选路径参数 (字符串)
    • 可选选项参数 (符号或字符串):
      • -l: 显示详细信息
      • -a: 显示隐藏文件
      • -L: 跟随符号链接
      • -U: 显示UNIX时间戳
      • -k: 以KB显示大小,默认以人类可读模式显示
      • -u: 显示用户ID(Unix)
      • -m: 显示权限模式(Unix)
      • -p: 显示完整路径
  • 返回值: 文件/目录列表,详细模式下返回包含元数据的映射表
  • 示例:
fs.ls()          # -- 列出当前目录
fs.ls("-l") # -- 详细列表
fs.ls("-l -a") # -- 详细列表包含隐藏文件
fs.ls("~/Downloads") -- 列出下载目录
  • 文件大小
    是一种特殊数据类型,由数字和单位组成,可以直接比较大小。
1024K==1M              # 返回: True

fs.ls -l | where(size > 5K)

# 返回:

+---------------------------------------------------------------+
| MODE MODIFIED NAME SIZE TYPE |
+===============================================================+
| 420 2025-06-02T06:26:18.518753376 Cargo.lock 46K file |
| 420 2025-06-02T04:40:56.185300249 CHANGELOG.md 9K file |
+---------------------------------------------------------------+
  • 时间
    也是一种数据类型,可以直接比较,或参与时间运算:
fs.ls -l | where(modified > time.parse('2025-06-01'))

# 返回:
+--------------------------------------------------------------------+
| MODE MODIFIED NAME SIZE TYPE |
+====================================================================+
| 493 2025-06-02T05:15:40.117198118 src 346 directory |
| 420 2025-06-02T06:26:18.518753376 Cargo.lock 46K file |
| 493 2025-06-03T04:32:11.980565126 wiki 528 directory |
| 420 2025-06-02T04:40:56.185300249 CHANGELOG.md 9K file |
| 420 2025-06-02T06:26:31.105350975 Cargo.toml 2K file |
+--------------------------------------------------------------------+


fs.ls -l | where(time.diff('d',modified)>2)

# 返回:
+--------------------------------------------------------------------+
| MODE MODIFIED NAME SIZE TYPE |
+====================================================================+
| 420 2025-03-23T05:32:28.669533898 LICENSE 1K file |
| 493 2025-05-13T10:57:43.452389275 assets 102 directory |
| 493 2025-04-06T12:21:40.016431660 benches 66 directory |
| 493 2025-03-23T11:58:56.124332786 target_ 128 directory |
| 511 2025-03-29T05:58:39.035865303 target 11 symlink |
| 420 2025-05-29T12:57:07.160557939 README.md 4K file |
| 420 2025-05-29T12:57:07.160557939 README-cn.md 4K file |
+--------------------------------------------------------------------+

fs.glob

  • 功能: 使用通配符模式匹配文件
  • 参数:
    • 模式字符串 (如 *.txt)
  • 返回值: 匹配的文件路径列表
  • 示例:
fs.glob("*.txt")  # -- 匹配当前目录下所有txt文件

fs.tree

  • 功能: 获取目录树结构
  • 参数:
    • 可选参数1: 最大深度(整数)或路径(字符串)
    • 可选参数2: 路径(字符串)
  • 返回值: 嵌套的目录树结构
  • 示例:
fs.tree()        # -- 当前目录完整树结构
fs.tree(2) # -- 当前目录2层深度
fs.tree(3, "~/projects") -- 指定目录3层深度

fs.canon

  • 功能: 规范化路径(解析...和符号链接)
  • 参数: 路径字符串
  • 返回值: 规范化后的路径字符串
  • 示例:
fs.canon(".././dir")  # -- 返回解析后的绝对路径

修改操作类函数 (Modify)

fs.mkdir

  • 功能: 创建目录
  • 参数: 目录路径(字符串)
  • 返回值: 无
  • 示例:
fs.mkdir("new_dir")  # -- 创建new_dir目录

fs.rmdir

  • 功能: 删除空目录
  • 参数: 目录路径(字符串)
  • 返回值: 无
  • 示例:
fs.rmdir("empty_dir")  # -- 删除empty_dir目录

fs.mv

  • 功能: 移动文件/目录
  • 参数:
    • 源路径(字符串)
    • 目标路径(字符串)
  • 返回值: 无
  • 示例:
fs.mv("old.txt", "new.txt")  # -- 重命名文件
fs.mv("dir1", "dir2") # -- 移动目录

fs.cp

  • 功能: 复制文件/目录
  • 参数:
    • 源路径(字符串)
    • 目标路径(字符串)
  • 返回值: 无
  • 示例:
fs.cp("file.txt", "backup.txt")  # -- 复制文件
fs.cp("src_dir", "dst_dir") # -- 递归复制目录

fs.rm

  • 功能: 删除文件/目录
  • 参数: 路径(字符串)
  • 返回值: 无
  • 示例:
fs.rm("file.txt")    # -- 删除文件
fs.rm("dir") # -- 递归删除目录

检查类函数 (Check)

fs.exists

  • 功能: 检查路径是否存在
  • 参数: 路径(字符串)
  • 返回值: 布尔值
  • 示例:
fs.exists("file.txt")  # -- 返回true或false

fs.is_dir

  • 功能: 检查路径是否为目录
  • 参数: 路径(字符串)
  • 返回值: 布尔值
  • 示例:
fs.is_dir("path")  # -- 检查是否为目录

fs.is_file

  • 功能: 检查路径是否为文件
  • 参数: 路径(字符串)
  • 返回值: 布尔值
  • 示例:
fs.is_file("path")  # -- 检查是否为文件

读写类函数 (Read/Write)

fs.head

  • 功能: 读取文件前N行
  • 参数:
    • 行数(整数),省略则为10
    • 文件路径(字符串)
  • 返回值: 字符串
  • 示例:
fs.head(10, "log.txt")  # -- 读取前10行

fs.tail

  • 功能: 读取文件最后N行
  • 参数:
    • 行数(整数),省略则为10
    • 文件路径(字符串)
  • 返回值: 字符串
  • 示例:
fs.tail(10, "log.txt")  # -- 读取最后10行

fs.read

  • 功能: 读取文件内容
  • 参数: 文件路径(字符串)
  • 返回值: 字符串(文本文件)或字节数组(二进制文件)
  • 示例:
fs.read("file.txt")  # -- 读取文本文件

fs.write

  • 功能: 写入文件(覆盖)
  • 参数:
    • 文件路径(字符串)
    • 内容(字符串或字节数组)
  • 返回值: 无
  • 示例:
fs.write("file.txt", "content")  # -- 写入文本
fs.write("data.bin", bytes) # -- 写入二进制

fs.append

  • 功能: 追加内容到文件
  • 参数:
    • 文件路径(字符串)
    • 内容(字符串或字节数组)
  • 返回值: 无
  • 示例:
fs.append("log.txt", "new entry\n")  # -- 追加文本

辅助类函数 (assistant)

fs.base_name

  • 功能: 从给定路径返回文件名
  • 参数:
    • 是否分割扩展名(可选)
    • 文件路径(字符串)
  • 返回值: 字符串
  • 示例:
fs.base_name("~/Documents/log.txt")  # -- 返回 log.txt
fs.base_name(True, "~/Documents/log.tar.gz") # -- 返回 [log,tar.gz]

fs.join

  • 功能: 连接多个路径
  • 参数:
    • 文件路径(字符串),多个
  • 返回值: 字符串
  • 示例:
fs.join("~","Documents/mydoc", "log.txt")  # -- 返回 "~/Documents/mydoc/log.txt"

其他

错误处理

操作失败时会返回错误信息,包含详细的失败原因和路径信息。

平台差异

  • Unix特有功能: 用户ID、权限模式、符号链接目标等
  • Windows平台会忽略Unix特有参数