Filesystem(文件系统) API

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

• filesystem.isAutorunEnabled(): boolean
  返回autorun（自动运行）功能是否启用。若返回值为true，则新挂载文件系统时电脑会在其根目录中查找是否存在名为autorun[.lua]的文件。若存在，则会执行此文件。
  
  
• filesystem.setAutorunEnabled(value: boolean)
  设置是否在系统启动时执行autorun（自动运行）文件。
  
  
• 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和一条报错信息。