mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-06-22 21:23:21 +00:00
Code Issues Releases Wiki Activity

Added Javadoc for currently undocumented functions (#490)

Browse Source 
This PR adds some documentation for APIs that did not have docs in the
source yet. This includes the:

* drive peripheral
* FS API
* OS PAI
* printer peripheral
* speaker peripheral
This commit is contained in:
JackMacWindows 2020-07-05 03:26:37 -04:00 committed by GitHub
parent 45297665c6
commit 3075f89797
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 415 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
src/main/java/dan200/computercraft/core/apis/FSAPI.java
View File

@ -61,6 +61,13 @@ public void shutdown()
fileSystem = null;
}
/**
* Returns a list of files in a directory.
*
* @param path The path to list.
* @return A table with a list of files in the directory.
* @throws LuaException If the path doesn't exist.
*/
@LuaFunction
public final String[] list( String path ) throws LuaException
{
@ -75,24 +82,51 @@ public final String[] list( String path ) throws LuaException
}
}
/**
* Combines two parts of a path into one full path, adding separators as
* needed.
*
* @param pathA The first part of the path. For example, a parent directory path.
* @param pathB The second part of the path. For example, a file name.
* @return The new path, with separators added between parts as needed.
*/
@LuaFunction
public final String combine( String pathA, String pathB )
{
return fileSystem.combine( pathA, pathB );
}
/**
* Returns the file name portion of a path.
*
* @param path The path to get the name from.
* @return The final part of the path (the file name).
*/
@LuaFunction
public final String getName( String path )
{
return FileSystem.getName( path );
}
/**
* Returns the parent directory portion of a path.
*
* @param path The path to get the directory from.
* @return The path with the final part removed (the parent directory).
*/
@LuaFunction
public final String getDir( String path )
{
return FileSystem.getDirectory( path );
}
/**
* Returns the size of the specified file.
*
* @param path The file to get the file size of.
* @return The size of the file, in bytes.
* @throws LuaException If the path doesn't exist.
*/
@LuaFunction
public final long getSize( String path ) throws LuaException
{
@ -106,6 +140,12 @@ public final long getSize( String path ) throws LuaException
}
}
/**
* Returns whether the specified path exists.
*
* @param path The path to check the existence of.
* @return Whether the path exists.
*/
@LuaFunction
public final boolean exists( String path )
{
@ -119,6 +159,12 @@ public final boolean exists( String path )
}
}
/**
* Returns whether the specified path is a directory.
*
* @param path The path to check.
* @return Whether the path is a directory.
*/
@LuaFunction
public final boolean isDir( String path )
{
@ -132,6 +178,12 @@ public final boolean isDir( String path )
}
}
/**
* Returns whether a path is read-only.
*
* @param path The path to check.
* @return Whether the path cannot be written to.
*/
@LuaFunction
public final boolean isReadOnly( String path )
{
@ -145,6 +197,12 @@ public final boolean isReadOnly( String path )
}
}
/**
* Creates a directory, and any missing parents, at the specified path.
*
* @param path The path to the directory to create.
* @throws LuaException If the directory couldn't be created.
*/
@LuaFunction
public final void makeDir( String path ) throws LuaException
{
@ -159,6 +217,15 @@ public final void makeDir( String path ) throws LuaException
}
}
/**
* Moves a file or directory from one path to another.
*
* Any parent directories are created as needed.
*
* @param path The current file or directory to move from.
* @param dest The destination path for the file or directory.
* @throws LuaException If the file or directory couldn't be moved.
*/
@LuaFunction
public final void move( String path, String dest ) throws LuaException
{
@ -173,6 +240,15 @@ public final void move( String path, String dest ) throws LuaException
}
}
/**
* Copies a file or directory to a new path.
*
* Any parent directories are created as needed.
*
* @param path The file or directory to copy.
* @param dest The path to the destination file or directory.
* @throws LuaException If the file or directory couldn't be copied.
*/
@LuaFunction
public final void copy( String path, String dest ) throws LuaException
{
@ -187,6 +263,15 @@ public final void copy( String path, String dest ) throws LuaException
}
}
/**
* Deletes a file or directory.
*
* If the path points to a directory, all of the enclosed files and
* subdirectories are also deleted.
*
* @param path The path to the file or directory to delete.
* @throws LuaException If the file or directory couldn't be deleted.
*/
@LuaFunction
public final void delete( String path ) throws LuaException
{
@ -201,6 +286,24 @@ public final void delete( String path ) throws LuaException
}
}
// FIXME: Add individual handle type documentation
/**
* Opens a file for reading or writing at a path.
*
* The mode parameter can be {@code r} to read, {@code w} to write (deleting
* all contents), or {@code a} to append (keeping contents). If {@code b} is
* added to the end, the file will be opened in binary mode; otherwise, it's
* opened in text mode.
*
* @param path The path to the file to open.
* @param mode The mode to open the file with.
* @return A file handle object for the file, or {@code nil} + an error message on error.
* @throws LuaException If an invalid mode was specified.
* @cc.treturn [1] table A file handle object for the file.
* @cc.treturn [2] nil If the file does not exist, or cannot be opened.
* @cc.treturn string|nil A message explaining why the file cannot be opened.
*/
@LuaFunction
public final Object[] open( String path, String mode ) throws LuaException
{
@ -255,6 +358,14 @@ public final Object[] open( String path, String mode ) throws LuaException
}
}
/**
* Returns the name of the mount that the specified path is located on.
*
* @param path The path to get the drive of.
* @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.
* @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.
*/
@LuaFunction
public final Object[] getDrive( String path ) throws LuaException
{
@ -268,6 +379,15 @@ public final Object[] getDrive( String path ) throws LuaException
}
}
/**
* Returns the amount of free space available on the drive the path is
* located on.
*
* @param path The path to check the free space for.
* @return The amount of free space available, in bytes.
* @cc.treturn number|"unlimited" The amount of free space available, in bytes, or "unlimited".
* @throws LuaException If the path doesn't exist.
*/
@LuaFunction
public final Object getFreeSpace( String path ) throws LuaException
{
@ -282,6 +402,18 @@ public final Object getFreeSpace( String path ) throws LuaException
}
}
/**
* Searches for files matching a string with wildcards.
*
* This string is formatted like a normal path string, but can include any
* number of wildcards ({@code *}) to look for files matching anything.
* For example, {@code rom/* /command*} will look for any path starting with
* {@code command} inside any subdirectory of {@code /rom}.
*
* @param path The wildcard-qualified path to search for.
* @return A list of paths that match the search string.
* @throws LuaException If the path doesn't exist.
*/
@LuaFunction
public final String[] find( String path ) throws LuaException
{

131
src/main/java/dan200/computercraft/core/apis/OSAPI.java
View File

@ -153,24 +153,58 @@ private static long getEpochForCalendar( Calendar c )
return c.getTime().getTime();
}
/**
* Adds an event to the event queue. This event can later be pulled with
* os.pullEvent.
*
* @param name The name of the event to queue.
* @param args The parameters of the event.
* @cc.tparam string name The name of the event to queue.
* @cc.param ... The parameters of the event.
* @cc.see os.pullEvent To pull the event queued
*/
@LuaFunction
public final void queueEvent( String name, IArguments args )
{
apiEnvironment.queueEvent( name, args.drop( 1 ).getAll() );
}
/**
* Starts a timer that will run for the specified number of seconds. Once
* the timer fires, a timer event will be added to the queue with the ID
* returned from this function as the first parameter.
*
* @param timer The number of seconds until the timer fires.
* @return The ID of the new timer.
* @throws LuaException If the time is below zero.
*/
@LuaFunction
public final int startTimer( double timer ) throws LuaException
{
return apiEnvironment.startTimer( Math.round( checkFinite( 0, timer ) / 0.05 ) );
}
/**
* Cancels a timer previously started with startTimer. This will stop the
* timer from firing.
*
* @param token The ID of the timer to cancel.
* @see #startTimer To start a timer.
*/
@LuaFunction
public final void cancelTimer( int token )
{
apiEnvironment.cancelTimer( token );
}
/**
* Sets an alarm that will fire at the specified world time. When it fires,
* an alarm event will be added to the event queue.
*
* @param time The time at which to fire the alarm, in the range [0.0, 24.0).
* @return The ID of the alarm that was set.
* @throws LuaException If the time is out of range.
*/
@LuaFunction
public final int setAlarm( double time ) throws LuaException
{
@ -184,6 +218,13 @@ public final int setAlarm( double time ) throws LuaException
}
}
/**
* Cancels an alarm previously started with setAlarm. This will stop the
* alarm from firing.
*
* @param token The ID of the alarm to cancel.
* @see #setAlarm To set an alarm.
*/
@LuaFunction
public final void cancelAlarm( int token )
{
@ -193,24 +234,41 @@ public final void cancelAlarm( int token )
}
}
/**
* Shuts down the computer immediately.
*/
@LuaFunction( "shutdown" )
public final void doShutdown()
{
apiEnvironment.shutdown();
}
/**
* Reboots the computer immediately.
*/
@LuaFunction( "reboot" )
public final void doReboot()
{
apiEnvironment.reboot();
}
/**
* Returns the ID of the computer.
*
* @return The ID of the computer.
*/
@LuaFunction( { "getComputerID", "computerID" } )
public final int getComputerID()
{
return apiEnvironment.getComputerID();
}
/**
* Returns the label of the computer, or {@code nil} if none is set.
*
* @return The label of the computer.
* @cc.treturn string The label of the computer.
*/
@LuaFunction( { "getComputerLabel", "computerLabel" } )
public final Object[] getComputerLabel()
{
@ -229,12 +287,37 @@ public final void setComputerLabel( Optional<String> label )
apiEnvironment.setLabel( StringUtil.normaliseLabel( label.orElse( null ) ) );
}
/**
* Returns the number of seconds that the computer has been running.
*
* @return The computer's uptime.
*/
@LuaFunction
public final double clock()
{
return m_clock * 0.05;
}
/**
* Returns the current time depending on the string passed in. This will
* always be in the range [0.0, 24.0).
*
* * If called with {@code ingame}, the current world time will be returned.
* This is the default if nothing is passed.
* * If called with {@code utc}, returns the hour of the day in UTC time.
* * If called with {@code local}, returns the hour of the day in the
* timezone the server is located in.
*
* This function can also be called with a table returned from {@link #date},
* which will convert the date fields into a UNIX timestamp (number of
* seconds since 1 January 1970).
*
* @param args The locale of the time, or a table filled by {@code os.date("*t")} to decode. Defaults to {@code ingame} locale if not specified.
* @return The hour of the selected locale, or a UNIX timestamp from the table, depending on the argument passed in.
* @cc.tparam [opt] string|table locale The locale of the time, or a table filled by {@code os.date("*t")} to decode. Defaults to {@code ingame} locale if not specified.
* @see #date To get a date table that can be converted with this function.
* @throws LuaException If an invalid locale is passed.
*/
@LuaFunction
public final Object time( IArguments args ) throws LuaException
{
@ -255,6 +338,20 @@ public final Object time( IArguments args ) throws LuaException
}
}
/**
* Returns the day depending on the locale specified.
*
* * If called with {@code ingame}, returns the number of days since the
* world was created. This is the default.
* * If called with {@code utc}, returns the number of days since 1 January
* 1970 in the UTC timezone.
* * If called with {@code local}, returns the number of days since 1
* January 1970 in the server's local timezone.
*
* @param args The locale to get the day for. Defaults to {@code ingame} if not set.
* @return The day depending on the selected locale.
* @throws LuaException If an invalid locale is passed.
*/
@LuaFunction
public final int day( Optional<String> args ) throws LuaException
{
@ -271,6 +368,20 @@ public final int day( Optional<String> args ) throws LuaException
}
}
/**
* Returns the number of seconds since an epoch depending on the locale.
*
* * If called with {@code ingame}, returns the number of seconds since the
* world was created. This is the default.
* * If called with {@code utc}, returns the number of seconds since 1
* January 1970 in the UTC timezone.
* * If called with {@code local}, returns the number of seconds since 1
* January 1970 in the server's local timezone.
*
* @param args The locale to get the seconds for. Defaults to {@code ingame} if not set.
* @return The seconds since the epoch depending on the selected locale.
* @throws LuaException If an invalid locale is passed.
*/
@LuaFunction
public final long epoch( Optional<String> args ) throws LuaException
{
@ -299,6 +410,26 @@ public final long epoch( Optional<String> args ) throws LuaException
}
}
/**
* Returns a date string (or table) using a specified format string and
* optional time to format.
*
* The format string takes the same formats as C's {@code strftime} function
* (http://www.cplusplus.com/reference/ctime/strftime/). In extension, it
* can be prefixed with an exclamation mark ({@code !}) to use UTC time
* instead of the server's local timezone.
*
* If the format is exactly {@code *t} (optionally prefixed with {@code !}), a
* table will be returned instead. This table has fields for the year, month,
* day, hour, minute, second, day of the week, day of the year, and whether
* Daylight Savings Time is in effect. This table can be converted to a UNIX
* timestamp (days since 1 January 1970) with {@link #date}.
*
* @param formatA The format of the string to return. This defaults to {@code %c}, which expands to a string similar to "Sat Dec 24 16:58:00 2011".
* @param timeA The time to convert to a string. This defaults to the current time.
* @return The resulting format string.
* @throws LuaException If an invalid format is passed.
*/
@LuaFunction
public final Object date( Optional<String> formatA, Optional<Long> timeA ) throws LuaException
{

64
src/main/java/dan200/computercraft/shared/peripheral/diskdrive/DiskDrivePeripheral.java
View File

@ -16,6 +16,7 @@
import net.minecraft.item.ItemStack;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Optional;
/**
@ -47,12 +48,23 @@ public String getType()
return "drive";
}
/**
* Returns whether a disk is currently inserted in the drive.
*
* @return Whether a disk is currently inserted in the drive.
*/
@LuaFunction
public final boolean isDiskPresent()
{
return !diskDrive.getDiskStack().isEmpty();
}
/**
* Returns the label of the disk in the drive if available.
*
* @return The label of the disk, or {@code nil} if either no disk is inserted or the disk doesn't have a label.
* @cc.treturn string The label of the disk, or {@code nil} if either no disk is inserted or the disk doesn't have a label.
*/
@LuaFunction
public final Object[] getDiskLabel()
{
@ -61,6 +73,17 @@ public final Object[] getDiskLabel()
return media == null ? null : new Object[] { media.getLabel( stack ) };
}
/**
* Sets or clears the label for a disk.
*
* If no label or {@code nil} is passed, the label will be cleared.
*
* If the inserted disk's label can't be changed (for example, a record),
* an error will be thrown.
*
* @param labelA The new label of the disk, or {@code nil} to clear.
* @throws LuaException If the disk's label can't be changed.
*/
@LuaFunction( mainThread = true )
public final void setDiskLabel( Optional<String> labelA ) throws LuaException
{
@ -76,18 +99,36 @@ public final void setDiskLabel( Optional<String> labelA ) throws LuaException
diskDrive.setDiskStack( stack );
}
/**
* Returns whether a disk with data is inserted.
*
* @param computer The computer object
* @return Whether a disk with data is inserted.
*/
@LuaFunction
public final boolean hasData( IComputerAccess computer )
{
return diskDrive.getDiskMountPath( computer ) != null;
}
/**
* Returns the mount path for the inserted disk.
*
* @param computer The computer object
* @return The mount path for the disk, or {@code nil} if no data disk is inserted.
*/
@LuaFunction
@Nullable
public final String getMountPath( IComputerAccess computer )
{
return diskDrive.getDiskMountPath( computer );
}
/**
* Returns whether a disk with audio is inserted.
*
* @return Whether a disk with audio is inserted.
*/
@LuaFunction
public final boolean hasAudio()
{
@ -96,7 +137,13 @@ public final boolean hasAudio()
return media != null && media.getAudio( stack ) != null;
}
/**
* Returns the title of the inserted audio disk.
*
* @return The title of the audio, or {@code nil} if no audio disk is inserted.
*/
@LuaFunction
@Nullable
public final Object getAudioTitle()
{
ItemStack stack = diskDrive.getDiskStack();
@ -104,24 +151,41 @@ public final Object getAudioTitle()
return media != null ? media.getAudioTitle( stack ) : false;
}
/**
* Plays the audio in the inserted disk, if available.
*/
@LuaFunction
public final void playAudio()
{
diskDrive.playDiskAudio();
}
/**
* Stops any audio that may be playing.
*
* @see #playAudio
*/
@LuaFunction
public final void stopAudio()
{
diskDrive.stopDiskAudio();
}
/**
* Ejects any disk that may be in the drive.
*/
@LuaFunction
public final void ejectDisk()
{
diskDrive.ejectDisk();
}
/**
* Returns the ID of the disk inserted in the drive.
*
* @return The ID of the disk in the drive, or {@code nil} if no disk with an ID is inserted.
* @cc.treturn number The The ID of the disk in the drive, or {@code nil} if no disk with an ID is inserted.
*/
@LuaFunction
public final Object[] getDiskID()
{

57
src/main/java/dan200/computercraft/shared/peripheral/printer/PrinterPeripheral.java
View File

@ -42,6 +42,13 @@ public String getType()
// FIXME: None of our page modification functions actually mark the tile as dirty, so the page may not be
// persisted correctly.
/**
* Writes text to the current page.
*
* @param arguments The values to write to the page.
* @cc.tparam string|number ... The values to write to the page.
* @throws LuaException If any values couldn't be converted to a string, or if no page is started.
*/
@LuaFunction
public final void write( IArguments arguments ) throws LuaException
{
@ -51,6 +58,14 @@ public final void write( IArguments arguments ) throws LuaException
page.setCursorPos( page.getCursorX() + text.length(), page.getCursorY() );
}
/**
* Returns the current position of the cursor on the page.
*
* @return The position of the cursor.
* @cc.treturn number The X position of the cursor.
* @cc.treturn number The Y position of the cursor.
* @throws LuaException If a page isn't being printed.
*/
@LuaFunction
public final Object[] getCursorPos() throws LuaException
{
@ -60,6 +75,13 @@ public final Object[] getCursorPos() throws LuaException
return new Object[] { x + 1, y + 1 };
}
/**
* Sets the position of the cursor on the page.
*
* @param x The X coordinate to set the cursor at.
* @param y The Y coordinate to set the cursor at.
* @throws LuaException If a page isn't being printed.
*/
@LuaFunction
public final void setCursorPos( int x, int y ) throws LuaException
{
@ -67,6 +89,14 @@ public final void setCursorPos( int x, int y ) throws LuaException
page.setCursorPos( x - 1, y - 1 );
}
/**
* Returns the size of the current page.
*
* @return The size of the page.
* @cc.treturn number The width of the page.
* @cc.treturn number The height of the page.
* @throws LuaException If a page isn't being printed.
*/
@LuaFunction
public final Object[] getPageSize() throws LuaException
{
@ -76,12 +106,23 @@ public final Object[] getPageSize() throws LuaException
return new Object[] { width, height };
}
/**
* Starts printing a new page.
*
* @return Whether a new page could be started.
*/
@LuaFunction( mainThread = true )
public final boolean newPage()
{
return printer.startNewPage();
}
/**
* Finalizes printing of the current page and outputs it to the tray.
*
* @return Whether the page could be successfully finished.
* @throws LuaException If a page isn't being printed.
*/
@LuaFunction( mainThread = true )
public final boolean endPage() throws LuaException
{
@ -89,6 +130,12 @@ public final boolean endPage() throws LuaException
return printer.endCurrentPage();
}
/**
* Sets the title of the current page.
*
* @param title The title to set for the page.
* @throws LuaException If a page isn't being printed.
*/
@LuaFunction
public final void setPageTitle( Optional<String> title ) throws LuaException
{
@ -96,12 +143,22 @@ public final void setPageTitle( Optional<String> title ) throws LuaException
printer.setPageTitle( StringUtil.normaliseLabel( title.orElse( "" ) ) );
}
/**
* Returns the amount of ink left in the printer.
*
* @return The amount of ink available to print with.
*/
@LuaFunction
public final int getInkLevel()
{
return printer.getInkLevel();
}
/**
* Returns the amount of paper left in the printer.
*
* @return The amount of paper available to print with.
*/
@LuaFunction
public final int getPaperLevel()
{

31
src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
View File

@ -58,6 +58,20 @@ public String getType()
return "speaker";
}
/**
* Plays a sound through the speaker.
*
* This plays sounds similar to the {@code /playsound} command in Minecraft.
* It takes the namespaced path of a sound (e.g. {@code minecraft:block.note_block.harp})
* with an optional volume and speed multiplier, and plays it through the speaker.
*
* @param context The Lua context
* @param name The name of the sound to play.
* @param volumeA The volume to play the sound at, from 0.0 to 3.0. Defaults to 1.0.
* @param pitchA The speed to play the sound at, from 0.5 to 2.0. Defaults to 1.0.
* @return Whether the sound could be played.
* @throws LuaException If the sound name couldn't be decoded.
*/
@LuaFunction
public final boolean playSound( ILuaContext context, String name, Optional<Double> volumeA, Optional<Double> pitchA ) throws LuaException
{
@ -77,6 +91,23 @@ public final boolean playSound( ILuaContext context, String name, Optional<Doubl
return playSound( context, identifier, volume, pitch, false );
}
/**
* Plays a note block note through the speaker.
*
* This takes the name of a note to play, as well as optionally the volume
* and pitch to play the note at.
*
* The pitch argument uses semitones as the unit. This directly maps to the
* number of clicks on a note block. For reference, 0, 12, and 24 map to F#,
* and 6 and 18 map to C.
*
* @param context The Lua context
* @param name The name of the note to play.
* @param volumeA The volume to play the note at, from 0.0 to 3.0. Defaults to 1.0.
* @param pitchA The pitch to play the note at in semitones, from 0 to 24. Defaults to 12.
* @return Whether the note could be played.
* @throws LuaException If the instrument doesn't exist.
*/
@LuaFunction
public final synchronized boolean playNote( ILuaContext context, String name, Optional<Double> volumeA, Optional<Double> pitchA ) throws LuaException
{