1
0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-12-14 20:20:30 +00:00

Improve fs API introduction

Again, not perfect, but better than a single sentence.
This commit is contained in:
Jonathan Coates 2021-12-21 14:39:08 +00:00
parent 0c6c0badde
commit aa009df740
No known key found for this signature in database
GPG Key ID: B9E431FF07C98D06
2 changed files with 37 additions and 2 deletions

View File

@ -158,7 +158,7 @@ dependencies {
testModImplementation sourceSets.main.output testModImplementation sourceSets.main.output
cctJavadoc 'cc.tweaked:cct-javadoc:1.4.4' cctJavadoc 'cc.tweaked:cct-javadoc:1.4.5'
} }
// Compile tasks // Compile tasks

View File

@ -30,7 +30,36 @@ import java.util.OptionalLong;
import java.util.function.Function; import java.util.function.Function;
/** /**
* The FS API allows you to manipulate files and the filesystem. * The FS API provides access to the computer's files and filesystem, allowing you to manipulate files, directories and
* paths. This includes:
*
* <ul>
* <li>**Reading and writing files:** Call {@link #open} to obtain a file "handle", which can be used to read from or
* write to a file.</li>
* <li>**Path manipulation:** {@link #combine}, {@link #getName} and {@link #getDir} allow you to manipulate file
* paths, joining them together or extracting components.</li>
* <li>**Querying paths:** For instance, checking if a file exists, or whether it's a directory. See {@link #getSize},
* {@link #exists}, {@link #isDir}, {@link #isReadOnly} and {@link #attributes}.</li>
* <li>**File and directory manipulation:** For instance, moving or copying files. See {@link #makeDir}, {@link #move},
* {@link #copy} and {@link #delete}.</li>
* </ul>
*
* :::note
* All functions in the API work on absolute paths, and do not take the @{shell.dir|current directory} into account.
* You can use @{shell.resolve} to convert a relative path into an absolute one.
* :::
*
* ## Mounts
* While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For
* instance, the {@link dan200.computercraft.shared.peripheral.diskdrive.DiskDrivePeripheral drive peripheral} mounts
* its disk's contents at {@code "disk/"}, {@code "disk1/"}, etc...
*
* You can see which mount a path belongs to with the {@link #getDrive} function. This returns {@code "hdd"} for the
* computer's main filesystem ({@code "/"}), {@code "rom"} for the rom ({@code "rom/"}).
*
* Most filesystems have a limited capacity, operations which would cause that capacity to be reached (such as writing
* an incredibly large file) will fail. You can see a mount's capacity with {@link #getCapacity} and the remaining
* space with {@link #getFreeSpace}.
* *
* @cc.module fs * @cc.module fs
*/ */
@ -440,6 +469,12 @@ public class FSAPI implements ILuaAPI
* @return The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files. * @return The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files.
* @throws LuaException If the path doesn't exist. * @throws LuaException If the path doesn't exist.
* @cc.treturn string The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files. * @cc.treturn string The name of the drive that the file is on; e.g. {@code hdd} for local files, or {@code rom} for ROM files.
* @cc.usage Print the drives of a couple of mounts:
*
* <pre>{@code
* print("/: " .. fs.getDrive("/"))
* print("/rom/: " .. fs.getDrive("rom"))
* }</pre>
*/ */
@LuaFunction @LuaFunction
public final Object[] getDrive( String path ) throws LuaException public final Object[] getDrive( String path ) throws LuaException