Differences

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

--- api:filesystem:zh [2022/08/11 10:28]
fight_xing created
+++ api:filesystem:zh [2023/11/29 13:46] (current)
hfsr [Filesystem(文件系统) API]
@@ Line 1: / Line 1: @@
-Filesystem API
+Filesystem(文件系统) API
 ============
+此运行库提供了与文件系统组件交互的通用方法。每个文件系统组件都是一个“文件夹”，这些文件夹可以被“挂载”到全局文件目录树的某个位置，这样用户可以顺利地同时访问多个文件系统组件。
-**本篇文章的部分/全部内容还没有进行翻译。**
+请不要将此API与[[component:filesystem:zh|文件系统组件API]]的作用混淆。
-This library allows a general way of interacting with file system components. While each component is it's own "folder", these folders can be "mounted" somewhere into a global directory tree. This allows seamlessly interacting on multiple file system components. Not to be confused with the [[component:filesystem|Filesystem component]] with which this API works.
 - `filesystem.isAutorunEnabled(): boolean`
-  Returns whether autorun is currently enabled. If this is `true`, newly mounted file systems will be checked for a file named `autorun[.lua]` in their root directory. If such a file exists, it is executed.
+  返回autorun（自动运行）功能是否启用。若返回值为`true`，则新挂载文件系统时电脑会在其根目录中查找是否存在名为`autorun[.lua]`的文件。若存在，则会执行此文件。
+\\
 - `filesystem.setAutorunEnabled(value: boolean)`
-  Sets whether autorun files should be ran on startup.
+  设置是否在系统启动时执行autorun（自动运行）文件。
+\\
 - `filesystem.canonical(path: string): string`
-  Returns the canonical form of the specified path, i.e. a path containing no "indirections" such as `.` or `..`. For example, the paths `/tmp/../bin/ls.lua` and `/bin/./ls.lua` are equivalent, and their canonical form is `/bin/ls.lua`.
+  返回指定路径的规范形式。即不含“间接引用”，如 `.` 或 `..`的形式。
-  Note that this function truncates relative paths to their topmost "known" directory. For example, `../bin/ls.lua` becomes `bin/ls.lua`. It stays a relative path, however - mind the lack of a leading slash.
+  例如， `/tmp/../bin/ls.lua`和`/bin/./ls.lua` 两个路径是等价的，它们的规范路径为`/bin/ls.lua`。
+  请注意，此函数会将相对路径截断到其最顶层的"已知"目录。例如，`../bin/ls.lua`会变成`bin/ls.lua`。然而，它仍然是一个相对路径——注意开头没有斜杠。
+\\
 - `filesystem.segments(path: string): table`
-  Returns a table containing one entry for each //canonical// segment of the given path.
+  返回一个表，其中分条目给出了指定路径的每个**规范段**。（规范段即规范路径的每一部分）
-  Examples:
+  样例：
   * `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`
-  Concatenates two or more paths. Note that all paths other than the first are treated as relative paths, even if they begin with a slash. The canonical form of the resulting concatenated path is returned, so `fs.concat("a", "..")` results in an empty string.
+  拼接多个路径。请注意，除第一个路径外，其他所有路径即使以斜杠开头也都被视为相对路径。返回值为拼接后路径的规范形式，因此`fs.concat("a", "..")`的结果将是空字符串。
+\\
 - `filesystem.path(path: string): string`
-  Returns the path component of a path to a file, i.e. everything before the last slash in the canonical form of the specified path.
+  返回某文件路径的路径部分，即给定路径规范形式中最后一个斜杠之前的所有内容。
+\\
 - `filesystem.name(path: string): string`
-  Returns the file name component of a path to a file, i.e. everything after the last slash in the canonical form of the specified path.
+  返回某文件路径的文件名，即给定路径规范形式中最后一个斜杠之后的所有内容。
+\\
 - `filesystem.proxy(filter: string): table or nil, string`
-  This is similar to `component.proxy`, except that the specified string may also be a file system component's label. We check for the label first, if no file system has the specified label we fall back to `component.proxy`.
+  此函数类似于`component.proxy`，区别为给定字符串也可以为文件系统组件的标签。系统将会首先检查是否存在对应标签，若不存在拥有对应标签的文件系统，系统将回退执行 `component.proxy`。
-  Returns the proxy of the specified file system, or `nil` and an error message if no file system matching the specified filter was found.
+  返回值为指定文件系统的代理对象，若未找到匹配给定过滤器的文件系统则会返回 `nil` 和一条报错信息。
+\\
 - `filesystem.mount(fs: table or string, path: string): boolean or nil, string`
-  Mounts a file system at the specified path. The first parameter can be either a file system component's proxy, its address or its label. The second is a path into the global directory tree. Returns true if the file system was successfully mounted, `nil` and an error message otherwise.
+  将某个文件系统挂载到给定路径。第一个参数可以为某个文件系统的代理对象、地址或标签。第二个参数为指向全局文件目录树的一个路径。若文件系统挂载成功则返回`true`，若挂载失败返回`nil`和一条报错信息。
+\\
 - `filesystem.mounts(): function -> table, string`
-  Returns an iterator function over all currently mounted file system component's proxies and the paths at which they are mounted. This means the same proxy may appear multiple times, but with different mount paths.
+  返回一个迭代器函数，遍历当前挂载的所有文件系统的代理对象与其挂载路径。这意味着同一个代理对象可能会多次出现，但挂载路径不同。
+\\
 - `filesystem.umount(fsOrPath: table or string): boolean`
-  Unmounts a file system. The parameter can either be a file system component's proxy or (abbreviated) address, in which case all mount points of this file system will be removed, or a path into the global directory structure, in which case the file system mount containing that directory will be unmounted.
+  将某文件系统取消挂载。参数可以为某文件系统组件的代理对象或（可为简写的）地址，此种情况下，文件系统的所有挂载点都将被清除。参数还可以为一条全局路径，此种情况下，包含此路径的文件系统挂载记录都将被清除。
+\\
 - `filesystem.isLink(path: string): boolean[, string]`
-  Checks if the object at the specified path is a symlink, if so returns the path to where it links (as of 1.3.3).
+  检查指定路径的对象是否为符号链接，如果是则返回它链接到的路径（自1.3.3版本起添加）。
+\\
 - `filesystem.link(target: string, linkpath: string): boolean or nil, string`
-  Creates a symbolic link to the specified target path at the specified path. This is a 'soft' link, i.e. it the target file does not actually have to exist at the time of creation, and the link will not be deleted if the target file is deleted. Symbolic links do not persist across reboots.
+  在指定路径下创建一条链接到指定目标路径的符号链接。此链接为“软链接”，即目标文件在创建时不一定需要存在，目标文件被删除时链接也不会删除。符号链接在重启后不会保留。
+\\
 - `filesystem.get(path: string): table, string or nil, string`
-  Gets the file system component's proxy that contains the specified path. Returns the proxy and mount path, or `nil` and an error message.
+  获取包含给定路径的文件系统组件的代理对象。成功时返回值为代理对象与挂载路径，失败时返回`nil`与一条报错信息。
+\\
 - `filesystem.exists(path: string): boolean`
-  Checks whether a file or folder exist at the specified path.
+  检查是否存在指定路径对应的文件或文件夹。
+\\
 - `filesystem.size(path: string): number`
-  Gets the file size of the file at the specified location. Returns 0 if the path points to anything other than a file.
+  获取指定文件的大小。若指定路径并未指向文件则返回0。
+\\
 - `filesystem.isDirectory(path: string): boolean`
-  Gets whether the path points to a directory. Returns false if not, either because the path points to a file, or `file.exists(path)` is false.
+  获取指定路径是否为目录。若不是则返回`false`，不论是因为路径指向了文件还是因为`file.exists(path)`的返回值为`false`，即路径不存在。
+\\
 - `filesystem.lastModified(path: string): number`
-  Returns the *real world* unix timestamp of the last time the file at the specified path was modified. For directories this is usually the time of their creation.
+  返回给定路径指向文件的最后一次修改时**现实世界**的UNIX时间戳。对于目录而言此时间戳通常为其创建时间。
+\\
 - `filesystem.list(path: string): function -> string or nil, string`
-  Returns an iterator over all elements in the directory at the specified path. Returns `nil` and an error messages if the path is invalid or some other error occurred.
+  返回一个迭代器，遍历给定路径指向目录中的所有元素。若路径无效或发生其他错误，则返回`nil`和一条报错信息。
-  Note that directories usually are postfixed with a slash, to allow identifying them without an additional call to `fs.isDirectory`.
+  请注意目录的路径末尾通常会加斜杠，以在不额外调用`fs.isDirectory`的情况下识别其是否为目录。
+\\
 - `filesystem.makeDirectory(path: string): boolean or nil, string`
-  Creates a new directory at the specified path. Creates any parent directories that do not exist yet, if necessary. Returns `true` on success, `nil` and an error message otherwise.
+  在指定路径处新建目录，必要的时候会创建一切尚不存在的父目录。成功时返回`true`，失败时返回`nil`和一条报错信息。
+\\
 - `filesystem.remove(path: string): boolean or nil, string`
-  Deletes a file or folder. If the path specifies a folder, deletes all files and subdirectories in the folder, recursively. Return `true` on success, `nil` and an error message otherwise.
+  删除某文件或目录。若路径指向文件夹，则递归删除其中的所有文件与子目录。成功时返回`true`，失败时返回`nil`和一条报错信息。
+\\
 - `filesystem.rename(oldPath: string, newPath: string): boolean or nil, string`
-  Renames a file or folder. If the paths point to different file system components this will only work for files, because it actually perform a copy operation, followed by a deletion if the copy succeeds.
+  将某文件或文件夹重命名（改变路径）。若新路径指向了不同的文件系统组件，则此函数只会对文件起效。因为此函数实际上是先执行了一次复制操作，然后如果复制成功则删除原有文件。
-  Returns `true` on success, `nil` and an error message otherwise.
+  成功时返回`true`，失败时返回`nil`和一条报错信息。
+\\
 - `filesystem.copy(fromPath: string, toPath: string): boolean or nil, string`
-  Copies a file to the specified location. The target path has to contain the target file name. Does not support folders.
+  将某文件复制到指定位置。目标路径需包含目标文件名。此函数不支持复制文件夹。
+\\
 - `filesystem.open(path: string[, mode: string]): table or nil, string`
-  Opens a file at the specified path for reading or writing. If mode is not specified it defaults to "r". Possible modes are: `r`, `rb`, `w`, `wb`, `a` and `ab`.
+  打开给定路径的文件以供读写。若不指定打开模式则默认为`r`。打开模式可以为：`r`、`rb`、`w`、`wb`、`a`与`ab`。
-  Returns a file stream (see below) on success, `nil` and an error message otherwise.
+  成功时返回一个文件流（见下文），失败时返回`nil`和一条报错信息。
-  Note that you can only open a limited number of files per file system at the same time. Files will be automatically closed when the garbage collection kicks in, but it is generally a good idea to call `close` on the file stream when done with the file.
+  请注意你在一个文件系统中同时打开的文件数是有限的。打开的文件会在触发垃圾回收机制时自动关闭，但通常来说在文件使用完毕后调用`close`手动关闭文件流更好。
-  **Important**: it is generally recommended to use `io.open` instead of this function, to get a buffered wrapper for the file stream.
+**注意：**通常更推荐使用`io.open`而不是此函数，因为可以获得文件流的有缓冲包装版本。
+使用filesystem(文件系统) API直接打开文件时会获得文件流，其为包含四个函数的表。这些函数是文件系统代理对象回调函数的轻量化包装，意味着读写操作**不带**缓冲，因此频繁读写少量内容时会很慢。推荐你使用`io.open`代替。
-When opening files directly via the file system API you will get a file stream, a table with four functions. These functions are thin wrappers to the file system proxy's callbacks, which also means that read/write operations are *not* buffered, and can therefore be slow when reading few bytes often. You'll usually want to use `io.open` instead.
+\\
 - `file:close()`
-  Closes the file stream, releasing the handle on the underlying file system.
+  关闭文件流，释放对底层文件系统的句柄。
+\\
 - `file:read(n: number): string or nil, string`
-  Tries to read the specified number of bytes from the file stream. Returns the read string, which may be shorter than the specified number. Returns `nil` when the end of the stream was reached. Returns `nil` and an error message if some error occurred.
+  尝试从文件流中读取指定数量的字节。返回读取到的字符串，此字符串可能比指定数量短。当文件流到达末尾时返回`nil`。当发生错误时返回`nil`和一条报错信息。
+\\
 - `file:seek(whence: string[, offset: number]): number or nil, string`
-  Jumps to the specified position in the file stream, if possible. Only supported by file streams opened in read mode. The first parameter determines the relative location to seek from and can be `cur` for the current position, `set` for the beginning of the stream and `end` for the end of the stream. The second parameter is the offset by which to modify the position. Returns the new position or `nil` and an error message if some error occurred.
+  如果可能的话，跳转到文件流中的指定位置。仅支持以可读模式打开的文件流。第一个参数决定了搜索开始的位置，可以为`cur`（当前位置）、`set`（文件流开头）或`end`（文件流结尾）。第二个参数为更改位置的偏移量。成功时返回新位置，失败时返回 `nil`和一条报错信息。
-  The default value for the second parameter is 0, so `f:seek("set")` will reset the position to the start of the file, `f:seek("cur")` will return the current position in the file.
+  第二个参数的默认值为0，因此`f:seek("set")`会将位置重置为文件开头，`f:seek("cur")`将会返回当前在文件中的位置。
+\\
 - `file:write(str: value): boolean or nil, string`
-  Writes the specified data to the stream. Returns `true` on success, `nil` and an error message otherwise.
+  将给定数据写入到文件流。成功时返回`true`，失败时返回`nil`和一条报错信息。
 目录
 -----------
 {{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}}