Filesystem(文件系统) API
============
此运行库提供了与文件系统组件交互的通用方法。每个文件系统组件都是一个“文件夹”，这些文件夹可以被“挂载”到全局文件目录树的某个位置，这样用户可以顺利地同时访问多个文件系统组件。  
请不要将此API与[[component:filesystem:zh|文件系统组件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`和一条报错信息。

目录
-----------
{{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}}