Differences

This shows you the differences between two versions of the page.

--- api:filesystem:zh [2023/10/19 06:51]
hfsr [Filesystem(文件系统) API]
+++ api:filesystem:zh [2023/11/29 13:46] (current)
hfsr [Filesystem(文件系统) API]
@@ Line 1: / Line 1: @@
 Filesystem(文件系统) API
 ============
-此运行库提供了与文件系统组件交互的通用方法。每个文件系统组件都是自己的“文件夹”，这些文件夹可以被“挂载”到全局文件目录树的某个位置，这样用户可以顺利地同时访问多个文件系统组件。请不要将此API与[[component:filesystem:zh|文件系统组件]]混淆，后者是此API起作用的地方。
+此运行库提供了与文件系统组件交互的通用方法。每个文件系统组件都是一个“文件夹”，这些文件夹可以被“挂载”到全局文件目录树的某个位置，这样用户可以顺利地同时访问多个文件系统组件。
+请不要将此API与[[component:filesystem:zh|文件系统组件API]]的作用混淆。
 - `filesystem.isAutorunEnabled(): boolean`
-  返回自动运行功能是否启用。若返回值为`true`，则新挂载文件系统时电脑会在其根目录中查找是否存在名为`autorun[.lua]`的文件。若存在，则会执行此文件。
+  返回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`。然而，它仍然是一个相对路径——注意开头没有斜杠。
+  例如， `/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.segments("foo/bar/../baz")` -> `{"foo","baz"}`  \\
+\\
 - `filesystem.concat(pathA: string, pathB: string[, ...]): string`
-  拼接多个路径。请注意，除第一个路径外，其他所有路径即使以斜杠开头也都被视为相对路径。返回值为拼接后路径的规范形式，因此 `fs.concat("a", "..")` 的结果将是空字符串。
+  拼接多个路径。请注意，除第一个路径外，其他所有路径即使以斜杠开头也都被视为相对路径。返回值为拼接后路径的规范形式，因此`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`。
+  此函数类似于`component.proxy`，区别为给定字符串也可以为文件系统组件的标签。系统将会首先检查是否存在对应标签，若不存在拥有对应标签的文件系统，系统将回退执行 `component.proxy`。
   返回值为指定文件系统的代理对象，若未找到匹配给定过滤器的文件系统则会返回 `nil` 和一条报错信息。
+\\
 - `filesystem.mount(fs: table or string, path: string): boolean or nil, string`
-  将某个文件系统挂载到给定路径。第一个参数可以为某个文件系统的代理对象、地址或标签。第二个参数为指向全局文件目录树的一个路径。若文件系统挂载成功则返回 `true` ，若挂载失败返回 `nil` 和一条报错信息。
+  将某个文件系统挂载到给定路径。第一个参数可以为某个文件系统的代理对象、地址或标签。第二个参数为指向全局文件目录树的一个路径。若文件系统挂载成功则返回`true`，若挂载失败返回`nil`和一条报错信息。
+\\
 - `filesystem.mounts(): function -> table, string`
-  返回一个迭代器，其中包含当前挂载的文件系统的代理对象与其挂载路径。这意味着同一个代理对象可能会多次出现，但是挂载路径不同。
+  返回一个迭代器函数，遍历当前挂载的所有文件系统的代理对象与其挂载路径。这意味着同一个代理对象可能会多次出现，但挂载路径不同。
+\\
 - `filesystem.umount(fsOrPath: table or string): boolean`
-  将某文件系统取消挂载。参数可以为某文件系统组件的代理对象或地址（可为简写），此种情况下，文件系统的所有挂载点都将被清除。参数还可以为一条全局路径，此种情况下，包含此路径的文件系统挂载记录都将被清除。
+  将某文件系统取消挂载。参数可以为某文件系统组件的代理对象或（可为简写的）地址，此种情况下，文件系统的所有挂载点都将被清除。参数还可以为一条全局路径，此种情况下，包含此路径的文件系统挂载记录都将被清除。
+\\
 - `filesystem.isLink(path: string): boolean[, string]`
-  检查指定路径的对象是否为符号链接，如果是则返回它链接到的路径（自1.3.3版本起）。
+  检查指定路径的对象是否为符号链接，如果是则返回它链接到的路径（自1.3.3版本起添加）。
+\\
 - `filesystem.link(target: string, linkpath: string): boolean or nil, string`
-  在指定路径下创建一条链接到指定目标的符号链接。此链接为“软链接”，即目标文件在创建时不一定需要存在，目标文件被删除时链接也不会删除。符号链接在重启后不会保留。
+  在指定路径下创建一条链接到指定目标路径的符号链接。此链接为“软链接”，即目标文件在创建时不一定需要存在，目标文件被删除时链接也不会删除。符号链接在重启后不会保留。
+\\
 - `filesystem.get(path: string): table, string or nil, string`
-  获取包含给定路径的文件系统组件的代理对象。成功时返回值为代理对象与挂载路径，失败时返回 `nil` 与一条报错信息。
+  获取包含给定路径的文件系统组件的代理对象。成功时返回值为代理对象与挂载路径，失败时返回`nil`与一条报错信息。
+\\
 - `filesystem.exists(path: string): boolean`
-  检查是否存在给定路径对应的文件或文件夹。
+  检查是否存在指定路径对应的文件或文件夹。
+\\
 - `filesystem.size(path: string): number`
-  获取指定文件的大小。如果给定路径并未指向文件则返回0。
+  获取指定文件的大小。若指定路径并未指向文件则返回0。
+\\
 - `filesystem.isDirectory(path: string): boolean`
-  获取指定路径是否为目录。若否则返回 false ，不论是因为路径指向了文件还是因为 `file.exists(path)` 返回值 false ，即路径不存在。
+  获取指定路径是否为目录。若不是则返回`false`，不论是因为路径指向了文件还是因为`file.exists(path)`的返回值为`false`，即路径不存在。
+\\
 - `filesystem.lastModified(path: string): number`
-  返回给定路径指向的文件最后一次修改时*现实世界*的UNIX时间戳。对于目录而言此时间戳通常为其创建时间。
+  返回给定路径指向文件的最后一次修改时**现实世界**的UNIX时间戳。对于目录而言此时间戳通常为其创建时间。
+\\
 - `filesystem.list(path: string): function -> string or nil, string`
-  返回一个迭代器，其中包含了给定路径指向的目录中的所有元素。若路径无效或发生其他错误，则返回 `nil` 和一条报错信息。
+  返回一个迭代器，遍历给定路径指向目录中的所有元素。若路径无效或发生其他错误，则返回`nil`和一条报错信息。
-  请注意目录的路径末尾通常会加斜杠，以在不额外调用 `fs.isDirectory` 的情况下识别其是否为目录。
+  请注意目录的路径末尾通常会加斜杠，以在不额外调用`fs.isDirectory`的情况下识别其是否为目录。
+\\
 - `filesystem.makeDirectory(path: string): boolean or nil, string`
-  在指定路径处新建目录，必要的时候会创建一切尚不存在的父目录。成功时返回 `true` ，失败时返回 `nil`和一条报错信息。
+  在指定路径处新建目录，必要的时候会创建一切尚不存在的父目录。成功时返回`true`，失败时返回`nil`和一条报错信息。
+\\
 - `filesystem.remove(path: string): boolean or nil, string`
-  删除某文件或目录。若路径指向文件夹，则递归删除其中的所有文件与子目录。成功时返回 `true` ，失败时返回 `nil`和一条报错信息。
+  删除某文件或目录。若路径指向文件夹，则递归删除其中的所有文件与子目录。成功时返回`true`，失败时返回`nil`和一条报错信息。
+\\
 - `filesystem.rename(oldPath: string, newPath: string): boolean or nil, string`
   将某文件或文件夹重命名（改变路径）。若新路径指向了不同的文件系统组件，则此函数只会对文件起效。因为此函数实际上是先执行了一次复制操作，然后如果复制成功则删除原有文件。
-  成功时返回 `true` ，失败时返回 `nil`和一条报错信息。
+  成功时返回`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`。
+  打开给定路径的文件以供读写。若不指定打开模式则默认为`r`。打开模式可以为：`r`、`rb`、`w`、`wb`、`a`与`ab`。
-  成功时返回一个文件流（见下文），失败时返回 `nil`和一条报错信息。
+  成功时返回一个文件流（见下文），失败时返回`nil`和一条报错信息。
-  请注意你在一个文件系统中同时打开的文件数是有限的。打开的文件会在触发垃圾回收机制时自动关闭，但通常来说在文件使用完毕后调用 `close` 手动关闭文件流更好。
+  请注意你在一个文件系统中同时打开的文件数是有限的。打开的文件会在触发垃圾回收机制时自动关闭，但通常来说在文件使用完毕后调用`close`手动关闭文件流更好。
-  **重要*：通常更推荐使用 `io.open` 而不是此函数，因为可以获得文件流的有缓冲包装版本。
+**注意：**通常更推荐使用`io.open`而不是此函数，因为可以获得文件流的有缓冲包装版本。
+使用filesystem(文件系统) API直接打开文件时会获得文件流，其为包含四个函数的表。这些函数是文件系统代理对象回调函数的轻量化包装，意味着读写操作**不带**缓冲，因此频繁读写少量内容时会很慢。推荐你使用`io.open`代替。
-使用filesystem(文件系统) API手动打开文件时会获得文件流，其为包含四个函数的表。这些函数是文件系统代理对象回调函数的轻量化包装，意味着读写操作*不带*缓冲，因此频繁读写少量内容时会很慢。推荐你使用 `io.open` 代替。
+\\
 - `file:close()`
   关闭文件流，释放对底层文件系统的句柄。
+\\
 - `file:read(n: number): string or nil, string`
-  尝试从文件流中读取指定数量的字节。返回读取到的字符串，此字符串可能比指定数量短。当文件流到达末尾时返回 `nil` 。当发生错误时返回 `nil`和一条报错信息。
+  尝试从文件流中读取指定数量的字节。返回读取到的字符串，此字符串可能比指定数量短。当文件流到达末尾时返回`nil`。当发生错误时返回`nil`和一条报错信息。
+\\
 - `file:seek(whence: string[, offset: number]): number or nil, string`
-  如果可能的话，跳转到文件流中的指定位置。仅支持以可读模式打开的文件流。第一个参数决定了搜索开始的位置，可以为 `cur` （当前位置）、`set` （文件流开头）或 `end` （文件流结尾）。第二个参数为更改位置的偏移量。成功时返回新位置，失败时返回 `nil`和一条报错信息。
+  如果可能的话，跳转到文件流中的指定位置。仅支持以可读模式打开的文件流。第一个参数决定了搜索开始的位置，可以为`cur`（当前位置）、`set`（文件流开头）或`end`（文件流结尾）。第二个参数为更改位置的偏移量。成功时返回新位置，失败时返回 `nil`和一条报错信息。
-  第二个参数的默认值为 0，因此 `f:seek("set")` 会将位置重置为文件开头，`f:seek("cur")` 将会返回当前在文件中的位置。
+  第二个参数的默认值为0，因此`f:seek("set")`会将位置重置为文件开头，`f:seek("cur")`将会返回当前在文件中的位置。
+\\
 - `file:write(str: value): boolean or nil, string`
-  将给定数据写入到文件流。成功时返回 `true` ，失败时返回 `nil`和一条报错信息。
+  将给定数据写入到文件流。成功时返回`true`，失败时返回`nil`和一条报错信息。
 目录
 -----------
 {{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}}