Filesystem(文件系统) API

此运行库提供了与文件系统组件交互的通用方法。每个文件系统组件都是自己的“文件夹”，这些文件夹可以被“挂载”到全局文件目录树的某个位置，这样用户可以顺利地同时访问多个文件系统组件。请不要将此API与文件系统组件混淆，后者是此API起作用的地方。

• filesystem.isAutorunEnabled(): boolean
  返回自动运行功能是否启用。若返回值为true，则新挂载文件系统时电脑会在其根目录中查找是否存在名为autorun[.lua]的文件。若存在，则会执行此文件。
• filesystem.setAutorunEnabled(value: boolean)
  设置是否在系统启动时执行自动运行文件。
• filesystem.canonical(path: string): string
  返回指定路径的规范路径。也即不含“间接引用”，比如 . 或 ..的路径。例如， /tmp/../bin/ls.lua 和 /bin/./ls.lua 两个路径是等价的，它们的规范路径为 /bin/ls.lua。 请注意，此函数将相对路径截断为其最顶层的“已知”目录。例如， ../bin/ls.lua 会变成 bin/ls.lua。然而，它仍然是一个相对路径——注意开头没有斜杠。
• filesystem.segments(path: string): table
  返回一个表，其中包含给定路径的每个规范段的一个条目。规范段即规范路径的每一部分。 样例：

  • filesystem.segments("foo/bar") → {"foo","bar"}
  • filesystem.segments("foo/bar/../baz") → {"foo","baz"}
• filesystem.concat(pathA: string, pathB: string[, ...]): string
  拼接多个路径。请注意，除第一个路径外，其他所有路径即使以斜杠开头也都被视为相对路径。返回值为拼接后路径的规范形式，因此 fs.concat("a", "..") 的结果将是空字符串。
• filesystem.path(path: string): string
  返回某文件路径的路径组件，即给定路径的规范形式中最后一个斜杠之前的所有内容。
• filesystem.name(path: string): string
  返回某文件路径的文件名，即给定路径的规范形式中最后一个斜杠之后的所有内容。
• filesystem.proxy(filter: string): table or nil, string
  此函数类似于 component.proxy，区别为给定字符串也可以为文件系统组件的标签。系统将会首先检查是否存在对应标签，若不存在拥有对应标签的文件系统，系统将回退到 component.proxy。 返回值为指定文件系统的代理对象，若未找到匹配给定过滤器的文件系统则会返回 nil 和一条报错信息。
• filesystem.mount(fs: table or string, path: string): boolean or nil, string
  将某个文件系统挂载到给定路径。第一个参数可以为某个文件系统的代理对象、地址或标签。第二个参数为指向全局文件目录树的一个路径。若文件系统挂载成功则返回 true ，若挂载失败返回 nil 和一条报错信息。
• filesystem.mounts(): function -> table, string
  返回一个迭代器，其中包含当前挂载的文件系统的代理对象与其挂载路径。这意味着同一个代理对象可能会多次出现，但是挂载路径不同。
• filesystem.umount(fsOrPath: table or string): boolean
  将某文件系统取消挂载。参数可以为某文件系统组件的代理对象或地址（可为简写），此种情况下，文件系统的所有挂载点都将被清除。参数还可以为一条全局路径，此种情况下，包含此路径的文件系统挂载记录都将被清除。
• filesystem.isLink(path: string): boolean[, string]
  检查指定路径的对象是否为符号链接，如果是则返回它链接到的路径（自1.3.3版本起）。
• filesystem.link(target: string, linkpath: string): boolean or nil, string
  在指定路径下创建一条链接到指定目标的符号链接。此链接为“软链接”，即目标文件在创建时不一定需要存在，目标文件被删除时链接也不会删除。符号链接在重启后不会保留。
• filesystem.get(path: string): table, string or nil, string
  获取包含给定路径的文件系统组件的代理对象。成功时返回值为代理对象与挂载路径，失败时返回 nil 与一条报错信息。
• filesystem.exists(path: string): boolean
  检查是否存在给定路径对应的文件或文件夹。
• filesystem.size(path: string): number
  获取指定文件的大小。如果给定路径并未指向文件则返回0。
• filesystem.isDirectory(path: string): boolean
  获取指定路径是否为目录。若否则返回 false ，不论是因为路径指向了文件还是因为 file.exists(path) 返回值 false ，即路径不存在。
• filesystem.lastModified(path: string): number
  返回给定路径指向的文件最后一次修改时现实世界的UNIX时间戳。对于目录而言此时间戳通常为其创建时间。
• filesystem.list(path: string): function -> string or nil, string
  返回一个迭代器，其中包含了给定路径指向的目录中的所有元素。若路径无效或发生其他错误，则返回 nil 和一条报错信息。 请注意目录的路径末尾通常会加斜杠，以在不额外调用 fs.isDirectory 的情况下识别其是否为目录。
• filesystem.makeDirectory(path: string): boolean or nil, string
  在指定路径处新建目录，必要的时候会创建一切尚不存在的父目录。成功时返回 true ，失败时返回 nil和一条报错信息。
• filesystem.remove(path: string): boolean or nil, string
  删除某文件或目录。若路径指向文件夹，则递归删除其中的所有文件与子目录。成功时返回 true ，失败时返回 nil和一条报错信息。
• filesystem.rename(oldPath: string, newPath: string): boolean or nil, string
  将某文件或文件夹重命名（改变路径）。若新路径指向了不同的文件系统组件，则此函数只会对文件起效。因为此函数实际上是先执行了一次复制操作，然后如果复制成功则删除原有文件。 成功时返回 true ，失败时返回 nil和一条报错信息。
• filesystem.copy(fromPath: string, toPath: string): boolean or nil, string
  将某文件复制到指定位置。目标路径需包含目标文件名。此函数不支持复制文件夹。
• filesystem.open(path: string[, mode: string]): table or nil, string
  打开给定路径的文件以供读写。若不指定打开模式则默认为 r 。打开模式可以为：r、rb、w、wb、a与ab。 成功时返回一个文件流（见下文），失败时返回 nil和一条报错信息。 请注意你在一个文件系统中同时打开的文件数是有限的。打开的文件会在触发垃圾回收机制时自动关闭，但通常来说在文件使用完毕后调用 close 手动关闭文件流更好。

  • 重要：通常更推荐使用 io.open 而不是此函数，因为可以获得文件流的有缓冲包装版本。

  使用filesystem(文件系统) API手动打开文件时会获得文件流，其为包含四个函数的表。这些函数是文件系统代理对象回调函数的轻量化包装，意味着读写操作不带缓冲，因此频繁读写少量内容时会很慢。推荐你使用 io.open 代替。

• file:close()
  关闭文件流，释放对底层文件系统的句柄。
• file:read(n: number): string or nil, string
  尝试从文件流中读取指定数量的字节。返回读取到的字符串，此字符串可能比指定数量短。当文件流到达末尾时返回 nil 。当发生错误时返回 nil和一条报错信息。
• file:seek(whence: string[, offset: number]): number or nil, string
  如果可能的话，跳转到文件流中的指定位置。仅支持以可读模式打开的文件流。第一个参数决定了搜索开始的位置，可以为 cur （当前位置）、set （文件流开头）或 end （文件流结尾）。第二个参数为更改位置的偏移量。成功时返回新位置，失败时返回 nil和一条报错信息。 第二个参数的默认值为 0，因此 f:seek("set") 会将位置重置为文件开头，f:seek("cur") 将会返回当前在文件中的位置。
• file:write(str: value): boolean or nil, string
  将给定数据写入到文件流。成功时返回 true ，失败时返回 nil和一条报错信息。