mirrors/CC-Tweaked
1
0
Fork 0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-12-12 03:00:30 +00:00
Code Issues Releases Wiki Activity

Add a whole tonne of documentation

Browse Source 
There's a bit of duplication here, so we might try to clean this up, but
it's a good starting point.
This commit is contained in:
SquidDev 2020-07-09 21:59:19 +01:00 committed by Jonathan Coates
parent 3f277a7a7b
commit a6a1b9b8e5
No known key found for this signature in database
GPG Key ID: D6D4CB5BFBBB5CB8
19 changed files with 424 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
build.gradle
View File

@ -122,7 +122,7 @@ dependencies {
deployerJars "org.apache.maven.wagon:wagon-ssh:3.0.0"
cctJavadoc 'cc.tweaked:cct-javadoc:1.0.0'
cctJavadoc 'cc.tweaked:cct-javadoc:1.1.0'
}
// Compile tasks

38
doc/stub/fs.lua
View File

@ -14,27 +14,21 @@
-- @see getDrive
function isDriveRoot(path) end
-- Defined in bios.lua
function complete(sPath, sLocation, bIncludeFiles, bIncludeDirs) end
--[[- Provides completion for a file or directory name, suitable for use with
@{read}.
--- A file handle which can be read from.
--
-- @type ReadHandle
-- @see fs.open
local ReadHandle = {}
function ReadHandle.read(count) end
function ReadHandle.readAll() end
function ReadHandle.readLine(with_trailing) end
function ReadHandle.seek(whence, offset) end
function ReadHandle.close() end
When a directory is a possible candidate for completion, two entries are
included - one with a trailing slash (indicating that entries within this
directory exist) and one without it (meaning this entry is an immediate
completion candidate). `include_dirs` can be set to @{false} to only include
those with a trailing slash.
--- A file handle which can be written to.
--
-- @type WriteHandle
-- @see fs.open
local WriteHandle = {}
function WriteHandle.write(text) end
function WriteHandle.writeLine(text) end
function WriteHandle.flush(text) end
function WriteHandle.seek(whence, offset) end
function WriteHandle.close() end
@tparam string path The path to complete.
@tparam string location The location where paths are resolved from.
@tparam[opt] boolean include_files When @{false}, only directories will be
included in the returned list.
@tparam[opt] boolean include_dirs When @{false}, "raw" directories will not be
included in the returned list.
@treturn { string... } A list of possible completion candidates.
]]
function complete(path, location, include_files, include_dirs) end

41
doc/stub/http.lua
View File

@ -93,47 +93,6 @@ function get(...) end
-- @treturn Response|nil The failing http response, if available.
function post(...) end
--- A http response. This acts very much like a @{fs.ReadHandle|file}, though
-- provides some http specific methods.
--
-- #### `http_success` event
-- #### `http_failure` event
--
-- @type Response
-- @see http.request On how to make a http request.
local Response = {}
--- Returns the response code and response message returned by the server
--
-- @treturn number The response code (i.e. 200)
-- @treturn string The response message (i.e. "OK")
function Response.getResponseCode() end
--- Get a table containing the response's headers, in a format similar to that
-- required by @{http.request}. If multiple headers are sent with the same
-- name, they will be combined with a comma.
--
-- @treturn { [string]=string } The response's headers.
-- Make a request to [example.computercraft.cc](https://example.computercraft.cc),
-- and print the returned headers.
-- ```lua
-- local request = http.get("https://example.computercraft.cc")
-- print(textutils.serialize(request.getResponseHeaders()))
-- -- => {
-- -- [ "Content-Type" ] = "text/plain; charset=utf8",
-- -- [ "content-length" ] = 17,
-- -- ...
-- -- }
-- request.close()
-- ```
function Response.getResponseHeaders() end
function Response.read(count) end
function Response.readAll() end
function Response.readLine(with_trailing) end
function Response.seek(whence, offset) end
function Response.close() end
--- Asynchronously determine whether a URL can be requested.
--
-- If this returns `true`, one should also listen for [`http_check`

50
doc/stub/term.lua
View File

@ -1,50 +0,0 @@
function write(text) end
function scroll(lines) end
function setCursorPos(x, y) end
function setCursorBlink(blink) end
function getCursorPos() end
function getSize() end
function clear() end
function clearLine() end
function setTextColour(colour) end
setTextColor = setTextColour
function setBackgroundColour(colour) end
setBackgroundColor = setBackgroundColour
function isColour() end
isColor = isColour
function getTextColour() end
getTextColor = getTextColor
function getBackgroundColour() end
getBackgroundColor = getBackgroundColour
function blit(text, text_colours, background_colours) end
function setPaletteColour(colour, ...) end
setPaletteColor = setPaletteColour
function getPaletteColour(colour, ...) end
getPaletteColor = getPaletteColour
--- @type Redirect
local Redirect = {}
Redirect.write = write
Redirect.scroll = scroll
Redirect.setCursorPos = setCursorPos
Redirect.setCursorBlink = setCursorBlink
Redirect.getCursorPos = getCursorPos
Redirect.getSize = getSize
Redirect.clear = clear
Redirect.clearLine = clearLine
Redirect.setTextColour = setTextColour
Redirect.setTextColor = setTextColor
Redirect.setBackgroundColour = setBackgroundColour
Redirect.setBackgroundColor = setBackgroundColor
Redirect.isColour = isColour
Redirect.isColor = isColor
Redirect.getTextColour = getTextColour
Redirect.getTextColor = getTextColor
Redirect.getBackgroundColour = getBackgroundColour
Redirect.getBackgroundColor = getBackgroundColor
Redirect.blit = blit
Redirect.setPaletteColour = setPaletteColour
Redirect.setPaletteColor = setPaletteColor
Redirect.getPaletteColour = getPaletteColour
Redirect.getPaletteColor = getPaletteColor

8
illuaminate.sexp
View File

@ -76,15 +76,10 @@
;; Suppress warnings for currently undocumented modules.
(at
(; Java APIs
/doc/stub/fs.lua
/doc/stub/http.lua
/doc/stub/os.lua
/doc/stub/term.lua
/doc/stub/turtle.lua
; Java generated APIs
/doc/javadoc/fs.lua
/doc/javadoc/http.lua
/doc/javadoc/os.lua
/doc/javadoc/turtle.lua
; Peripherals
/doc/javadoc/drive.lua
@ -101,7 +96,8 @@
(/src/main/resources/*/computercraft/lua/rom/apis/textutils.lua
/src/main/resources/*/computercraft/lua/rom/modules/main/cc/completion.lua
/src/main/resources/*/computercraft/lua/rom/modules/main/cc/shell/completion.lua
/src/main/resources/*/computercraft/lua/rom/programs/shell.lua)
/src/main/resources/*/computercraft/lua/rom/programs/shell.lua
/doc/stub/fs.lua)
(linters -doc:unresolved-reference))
(at /src/test/resources/test-rom

2
src/main/java/dan200/computercraft/core/apis/TermAPI.java
View File

@ -5,6 +5,7 @@
*/
package dan200.computercraft.core.apis;
import dan200.computercraft.api.lua.IArguments;
import dan200.computercraft.api.lua.ILuaAPI;
import dan200.computercraft.api.lua.LuaException;
import dan200.computercraft.api.lua.LuaFunction;
@ -45,6 +46,7 @@ public class TermAPI extends TermMethods implements ILuaAPI
* @cc.treturn number The red channel, will be between 0 and 1.
* @cc.treturn number The green channel, will be between 0 and 1.
* @cc.treturn number The blue channel, will be between 0 and 1.
* @see TermMethods#setPaletteColour(IArguments) To change the palette colour.
*/
@LuaFunction( { "nativePaletteColour", "nativePaletteColor" } )
public final Object[] nativePaletteColour( int colour ) throws LuaException

174
src/main/java/dan200/computercraft/core/apis/TermMethods.java
View File

@ -20,7 +20,6 @@ import javax.annotation.Nonnull;
* A base class for all objects which interact with a terminal. Namely the {@link TermAPI} and monitors.
*
* @cc.module term.Redirect
* @hidden
*/
public abstract class TermMethods
{
@ -40,6 +39,16 @@ public abstract class TermMethods
public abstract boolean isColour() throws LuaException;
/**
* Write {@code text} at the current cursor position, moving the cursor to the end of the text.
*
* Unlike functions like {@code write} and {@code print}, this does not wrap the text - it simply copies the
* text to the current terminal line.
*
* @param arguments The text to write.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.param text The text to write.
*/
@LuaFunction
public final void write( IArguments arguments ) throws LuaException
{
@ -52,12 +61,29 @@ public abstract class TermMethods
}
}
/**
* Move all positions up (or down) by {@code y} pixels.
*
* Every pixel in the terminal will be replaced by the line {@code y} pixels below it. If {@code y} is negative, it
* will copy pixels from above instead.
*
* @param y The number of lines to move up by. This may be a negative number.
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction
public final void scroll( int y ) throws LuaException
{
getTerminal().scroll( y );
}
/**
* Get the position of the cursor.
*
* @return The cursor's position.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.treturn number The x position of the cursor.
* @cc.treturn number The y position of the cursor.
*/
@LuaFunction
public final Object[] getCursorPos() throws LuaException
{
@ -65,6 +91,13 @@ public abstract class TermMethods
return new Object[] { terminal.getCursorX() + 1, terminal.getCursorY() + 1 };
}
/**
* Set the position of the cursor. {@link #write(IArguments) terminal writes} will begin from this position.
*
* @param x The new x position of the cursor.
* @param y The new y position of the cursor.
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction
public final void setCursorPos( int x, int y ) throws LuaException
{
@ -75,12 +108,24 @@ public abstract class TermMethods
}
}
/**
* Checks if the cursor is currently blinking.
*
* @return If the cursor is blinking.
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction
public final boolean getCursorBlink() throws LuaException
{
return getTerminal().getCursorBlink();
}
/**
* Sets whether the cursor should be visible (and blinking) at the current {@link #getCursorPos() cursor position}.
*
* @param blink Whether the cursor should blink.
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction
public final void setCursorBlink( boolean blink ) throws LuaException
{
@ -91,6 +136,14 @@ public abstract class TermMethods
}
}
/**
* Get the size of the terminal.
*
* @return The terminal's size.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.treturn number The terminal's width.
* @cc.treturn number The terminal's height.
*/
@LuaFunction
public final Object[] getSize() throws LuaException
{
@ -98,24 +151,49 @@ public abstract class TermMethods
return new Object[] { terminal.getWidth(), terminal.getHeight() };
}
/**
* Clears the terminal, filling it with the {@link #getBackgroundColour() current background colour}.
*
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction
public final void clear() throws LuaException
{
getTerminal().clear();
}
/**
* Clears the line the cursor is currently on, filling it with the {@link #getBackgroundColour() current background
* colour}.
*
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction
public final void clearLine() throws LuaException
{
getTerminal().clearLine();
}
/**
* Return the colour that new text will be written as.
*
* @return The current text colour.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.see colors For a list of colour constants, returned by this function.
*/
@LuaFunction( { "getTextColour", "getTextColor" } )
public final int getTextColour() throws LuaException
{
return encodeColour( getTerminal().getTextColour() );
}
/**
* Set the colour that new text will be written as.
*
* @param colourArg The new text colour.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.see colors For a list of colour constants.
*/
@LuaFunction( { "setTextColour", "setTextColor" } )
public final void setTextColour( int colourArg ) throws LuaException
{
@ -127,12 +205,28 @@ public abstract class TermMethods
}
}
/**
* Return the current background colour. This is used when {@link #write writing text} and {@link #clear clearing}
* the terminal.
*
* @return The current background colour.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.see colors For a list of colour constants, returned by this function.
*/
@LuaFunction( { "getBackgroundColour", "getBackgroundColor" } )
public final int getBackgroundColour() throws LuaException
{
return encodeColour( getTerminal().getBackgroundColour() );
}
/**
* Set the current background colour. This is used when {@link #write writing text} and {@link #clear clearing} the
* terminal.
*
* @param colourArg The new background colour.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.see colors For a list of colour constants.
*/
@LuaFunction( { "setBackgroundColour", "setBackgroundColor" } )
public final void setBackgroundColour( int colourArg ) throws LuaException
{
@ -144,12 +238,41 @@ public abstract class TermMethods
}
}
/**
* Determine if this terminal supports colour.
*
* Terminals which do not support colour will still allow writing coloured text/backgrounds, but it will be
* displayed in greyscale.
*
* @return Whether this terminal supports colour.
* @throws LuaException (hidden) If the terminal cannot be found.
*/
@LuaFunction( { "isColour", "isColor" } )
public final boolean getIsColour() throws LuaException
{
return isColour();
}
/**
* Writes {@code text} to the terminal with the specific foreground and background characters.
*
* As with {@link #write(IArguments)}, the text will be written at the current cursor location, with the cursor
* moving to the end of the text.
*
* {@code textColour} and {@code backgroundColour} must both be strings the same length as {@code text}. All
* characters represent a single hexadecimal digit, which is converted to one of CC's colours. For instance,
* {@code "a"} corresponds to purple.
*
* @param text The text to write.
* @param textColour The corresponding text colours.
* @param backgroundColour The corresponding background colours.
* @throws LuaException If the three inputs are not the same length.
* @cc.see colors For a list of colour constants, and their hexadecimal values.
* @cc.usage Prints "Hello, world!" in rainbow text.
* <pre>{@code
* term.blit("Hello, world!","01234456789ab","0000000000000")
* }</pre>
*/
@LuaFunction
public final void blit( String text, String textColour, String backgroundColour ) throws LuaException
{
@ -166,6 +289,38 @@ public abstract class TermMethods
}
}
/**
* Set the palette for a specific colour.
*
* ComputerCraft's palette system allows you to change how a specific colour should be displayed. For instance, you
* can make @{colors.red} <em>more red</em> by setting its palette to #FF0000. This does now allow you to draw more
* colours - you are still limited to 16 on the screen at one time - but you can change <em>which</em> colours are
* used.
*
* @param args The new palette values.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.tparam [1] number index The colour whose palette should be changed.
* @cc.tparam number colour A 24-bit integer representing the RGB value of the colour. For instance the integer
* `0xFF0000` corresponds to the colour #FF0000.
* @cc.tparam [2] number index The colour whose palette should be changed.
* @cc.tparam number r The intensity of the red channel, between 0 and 1.
* @cc.tparam number g The intensity of the green channel, between 0 and 1.
* @cc.tparam number b The intensity of the blue channel, between 0 and 1.
* @cc.usage Change the @{colors.red|red colour} from the default #CC4C4C to #FF0000.
* <pre>{@code
* term.setPaletteColour(colors.red, 0xFF0000)
* term.setTextColour(colors.red)
* print("Hello, world!")
* }</pre>
* @cc.usage As above, but specifying each colour channel separately.
* <pre>{@code
* term.setPaletteColour(colors.red, 1, 0, 0)
* term.setTextColour(colors.red)
* print("Hello, world!")
* }</pre>
* @cc.see colors.unpackRGB To convert from the 24-bit format to three separate channels.
* @cc.see colors.packRGB To convert from three separate channels to the 24-bit format.
*/
@LuaFunction( { "setPaletteColour", "setPaletteColor" } )
public final void setPaletteColour( IArguments args ) throws LuaException
{
@ -185,20 +340,26 @@ public abstract class TermMethods
}
}
/**
* Get the current palette for a specific colour.
*
* @param colourArg The colour whose palette should be fetched.
* @return The resulting colour.
* @throws LuaException (hidden) If the terminal cannot be found.
* @cc.treturn number The red channel, will be between 0 and 1.
* @cc.treturn number The green channel, will be between 0 and 1.
* @cc.treturn number The blue channel, will be between 0 and 1.
*/
@LuaFunction( { "getPaletteColour", "getPaletteColor" } )
public final Object[] getPaletteColour( int colourArg ) throws LuaException
{
int colour = 15 - parseColour( colourArg );
Terminal terminal = getTerminal();
synchronized( terminal )
{
if( terminal.getPalette() != null )
{
return ArrayUtils.toObject( terminal.getPalette().getColour( colour ) );
}
}
return null;
}
public static int parseColour( int colour ) throws LuaException
{
@ -215,11 +376,8 @@ public abstract class TermMethods
}
public static void setColour( Terminal terminal, int colour, double r, double g, double b )
{
if( terminal.getPalette() != null )
{
terminal.getPalette().setColour( colour, r, g, b );
terminal.setChanged();
}
}
}

60
src/main/java/dan200/computercraft/core/apis/handles/BinaryReadableHandle.java
View File

@ -5,7 +5,6 @@
*/
package dan200.computercraft.core.apis.handles;
import dan200.computercraft.api.lua.IArguments;
import dan200.computercraft.api.lua.LuaException;
import dan200.computercraft.api.lua.LuaFunction;
@ -19,6 +18,12 @@ import java.util.ArrayList;
import java.util.List;
import java.util.Optional;
/**
* A file handle opened with {@link dan200.computercraft.core.apis.FSAPI#open(String, String)} with the {@code "rb"}
* mode.
*
* @cc.module fs.BinaryReadHandle
*/
public class BinaryReadableHandle extends HandleGeneric
{
private static final int BUFFER_SIZE = 8192;
@ -27,7 +32,7 @@ public class BinaryReadableHandle extends HandleGeneric
final SeekableByteChannel seekable;
private final ByteBuffer single = ByteBuffer.allocate( 1 );
protected BinaryReadableHandle( ReadableByteChannel reader, SeekableByteChannel seekable, Closeable closeable )
BinaryReadableHandle( ReadableByteChannel reader, SeekableByteChannel seekable, Closeable closeable )
{
super( closeable );
this.reader = reader;
@ -45,6 +50,18 @@ public class BinaryReadableHandle extends HandleGeneric
return of( channel, channel );
}
/**
* Read a number of bytes from this file.
*
* @param countArg The number of bytes to read. When absent, a single byte will be read <em>as a number</em>. This
* may be 0 to determine we are at the end of the file.
* @return The read bytes.
* @throws LuaException When trying to read a negative number of bytes.
* @throws LuaException If the file has been closed.
* @cc.treturn [1] nil If we are at the end of the file.
* @cc.treturn [2] number The value of the byte read. This is returned when the {@code count} is absent.
* @cc.treturn [3] string The bytes read as a string. This is returned when the {@code count} is given.
*/
@LuaFunction
public final Object[] read( Optional<Integer> countArg ) throws LuaException
{
@ -122,6 +139,13 @@ public class BinaryReadableHandle extends HandleGeneric
}
}
/**
* Read the remainder of the file.
*
* @return The file, or {@code null} if at the end of it.
* @throws LuaException If the file has been closed.
* @cc.treturn string|nil The remaining contents of the file, or {@code nil} if we are at the end.
*/
@LuaFunction
public final Object[] readAll() throws LuaException
{
@ -151,6 +175,14 @@ public class BinaryReadableHandle extends HandleGeneric
}
}
/**
* Read a line from the file.
*
* @param withTrailingArg Whether to include the newline characters with the returned string. Defaults to {@code false}.
* @return The read string.
* @throws LuaException If the file has been closed.
* @cc.treturn string|nil The read line or {@code nil} if at the end of the file.
*/
@LuaFunction
public final Object[] readLine( Optional<Boolean> withTrailingArg ) throws LuaException
{
@ -205,16 +237,34 @@ public class BinaryReadableHandle extends HandleGeneric
public static class Seekable extends BinaryReadableHandle
{
public Seekable( SeekableByteChannel seekable, Closeable closeable )
Seekable( SeekableByteChannel seekable, Closeable closeable )
{
super( seekable, seekable, closeable );
}
/**
* Seek to a new position within the file, changing where bytes are written to. The new position is an offset
* given by {@code offset}, relative to a start position determined by {@code whence}:
*
* - {@code "set"}: {@code offset} is relative to the beginning of the file.
* - {@code "cur"}: Relative to the current position. This is the default.
* - {@code "end"}: Relative to the end of the file.
*
* In case of success, {@code seek} returns the new file position from the beginning of the file.
*
* @param whence Where the offset is relative to.
* @param offset The offset to seek to.
* @return The new position.
* @throws LuaException If the file has been closed.
* @cc.treturn [1] number The new position.
* @cc.treturn [2] nil If seeking failed.
* @cc.treturn string The reason seeking failed.
*/
@LuaFunction
public final Object[] seek( IArguments arguments ) throws LuaException
public final Object[] seek( Optional<String> whence, Optional<Long> offset ) throws LuaException
{
checkOpen();
return handleSeek( seekable, arguments );
return handleSeek( seekable, whence, offset );
}
}
}

42
src/main/java/dan200/computercraft/core/apis/handles/BinaryWritableHandle.java
View File

@ -16,7 +16,14 @@ import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.channels.SeekableByteChannel;
import java.nio.channels.WritableByteChannel;
import java.util.Optional;
/**
* A file handle opened by {@link dan200.computercraft.core.apis.FSAPI#open} using the {@code "wb"} or {@code "ab"}
* modes.
*
* @cc.module fs.BinaryWriteHandle
*/
public class BinaryWritableHandle extends HandleGeneric
{
private final WritableByteChannel writer;
@ -41,6 +48,14 @@ public class BinaryWritableHandle extends HandleGeneric
return of( channel, channel );
}
/**
* Write a string or byte to the file.
*
* @param arguments The value to write.
* @throws LuaException If the file has been closed.
* @cc.tparam [1] number The byte to write.
* @cc.tparam [2] string The string to write.
*/
@LuaFunction
public final void write( IArguments arguments ) throws LuaException
{
@ -72,6 +87,11 @@ public class BinaryWritableHandle extends HandleGeneric
}
}
/**
* Save the current file without closing it.
*
* @throws LuaException If the file has been closed.
*/
@LuaFunction
public final void flush() throws LuaException
{
@ -93,11 +113,29 @@ public class BinaryWritableHandle extends HandleGeneric
super( seekable, seekable, closeable );
}
/**
* Seek to a new position within the file, changing where bytes are written to. The new position is an offset
* given by {@code offset}, relative to a start position determined by {@code whence}:
*
* - {@code "set"}: {@code offset} is relative to the beginning of the file.
* - {@code "cur"}: Relative to the current position. This is the default.
* - {@code "end"}: Relative to the end of the file.
*
* In case of success, {@code seek} returns the new file position from the beginning of the file.
*
* @param whence Where the offset is relative to.
* @param offset The offset to seek to.
* @return The new position.
* @throws LuaException If the file has been closed.
* @cc.treturn [1] number The new position.
* @cc.treturn [2] nil If seeking failed.
* @cc.treturn string The reason seeking failed.
*/
@LuaFunction
public final Object[] seek( IArguments args ) throws LuaException
public final Object[] seek( Optional<String> whence, Optional<Long> offset ) throws LuaException
{
checkOpen();
return handleSeek( seekable, args );
return handleSeek( seekable, whence, offset );
}
}
}

30
src/main/java/dan200/computercraft/core/apis/handles/EncodedReadableHandle.java
View File

@ -20,6 +20,12 @@ import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.util.Optional;
/**
* A file handle opened with {@link dan200.computercraft.core.apis.FSAPI#open(String, String)} with the {@code "r"}
* mode.
*
* @cc.module fs.ReadHandle
*/
public class EncodedReadableHandle extends HandleGeneric
{
private static final int BUFFER_SIZE = 8192;
@ -37,6 +43,14 @@ public class EncodedReadableHandle extends HandleGeneric
this( reader, reader );
}
/**
* Read a line from the file.
*
* @param withTrailingArg Whether to include the newline characters with the returned string. Defaults to {@code false}.
* @return The read string.
* @throws LuaException If the file has been closed.
* @cc.treturn string|nil The read line or {@code nil} if at the end of the file.
*/
@LuaFunction
public final Object[] readLine( Optional<Boolean> withTrailingArg ) throws LuaException
{
@ -62,6 +76,13 @@ public class EncodedReadableHandle extends HandleGeneric
}
}
/**
* Read the remainder of the file.
*
* @return The file, or {@code null} if at the end of it.
* @throws LuaException If the file has been closed.
* @cc.treturn nil|string The remaining contents of the file, or {@code nil} if we are at the end.
*/
@LuaFunction
public final Object[] readAll() throws LuaException
{
@ -87,6 +108,15 @@ public class EncodedReadableHandle extends HandleGeneric
}
}
/**
* Read a number of characters from this file.
*
* @param countA The number of characters to read, defaulting to 1.
* @return The read characters.
* @throws LuaException When trying to read a negative number of characters.
* @throws LuaException If the file has been closed.
* @cc.treturn string|nil The read characters, or {@code nil} if at the of the file.
*/
@LuaFunction
public final Object[] read( Optional<Integer> countA ) throws LuaException
{

24
src/main/java/dan200/computercraft/core/apis/handles/EncodedWritableHandle.java
View File

@ -21,6 +21,11 @@ import java.nio.charset.CharsetEncoder;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
/**
* A file handle opened by {@link dan200.computercraft.core.apis.FSAPI#open} using the {@code "w"} or {@code "a"} modes.
*
* @cc.module fs.WriteHandle
*/
public class EncodedWritableHandle extends HandleGeneric
{
private final BufferedWriter writer;
@ -31,6 +36,13 @@ public class EncodedWritableHandle extends HandleGeneric
this.writer = writer;
}
/**
* Write a string of characters to the file.
*
* @param args The value to write.
* @throws LuaException If the file has been closed.
* @cc.param The value to write to the file.
*/
@LuaFunction
public final void write( IArguments args ) throws LuaException
{
@ -46,6 +58,13 @@ public class EncodedWritableHandle extends HandleGeneric
}
}
/**
* Write a string of characters to the file, follwing them with a new line character.
*
* @param args The value to write.
* @throws LuaException If the file has been closed.
* @cc.param The value to write to the file.
*/
@LuaFunction
public final void writeLine( IArguments args ) throws LuaException
{
@ -62,6 +81,11 @@ public class EncodedWritableHandle extends HandleGeneric
}
}
/**
* Save the current file without closing it.
*
* @throws LuaException If the file has been closed.
*/
@LuaFunction
public final void flush() throws LuaException
{

27
src/main/java/dan200/computercraft/core/apis/handles/HandleGeneric.java
View File

@ -5,7 +5,6 @@
*/
package dan200.computercraft.core.apis.handles;
import dan200.computercraft.api.lua.IArguments;
import dan200.computercraft.api.lua.LuaException;
import dan200.computercraft.api.lua.LuaFunction;
import dan200.computercraft.shared.util.IoUtil;
@ -15,6 +14,7 @@ import java.io.Closeable;
import java.io.IOException;
import java.nio.channels.Channel;
import java.nio.channels.SeekableByteChannel;
import java.util.Optional;
public abstract class HandleGeneric
{
@ -39,6 +39,13 @@ public abstract class HandleGeneric
closable = null;
}
/**
* Close this file, freeing any resources it uses.
*
* Once a file is closed it may no longer be read or written to.
*
* @throws LuaException If the file has already been closed.
*/
@LuaFunction( "close" )
public final void doClose() throws LuaException
{
@ -51,27 +58,27 @@ public abstract class HandleGeneric
* Shared implementation for various file handle types.
*
* @param channel The channel to seek in
* @param args The Lua arguments to process, like Lua's {@code file:seek}.
* @param whence The seeking mode.
* @param offset The offset to seek to.
* @return The new position of the file, or null if some error occurred.
* @throws LuaException If the arguments were invalid
* @see <a href="https://www.lua.org/manual/5.1/manual.html#pdf-file:seek">{@code file:seek} in the Lua manual.</a>
*/
protected static Object[] handleSeek( SeekableByteChannel channel, IArguments args ) throws LuaException
protected static Object[] handleSeek( SeekableByteChannel channel, Optional<String> whence, Optional<Long> offset ) throws LuaException
{
String whence = args.optString( 0, "cur" );
long offset = args.optLong( 1, 0 );
long actualOffset = offset.orElse( 0L );
try
{
switch( whence )
switch( whence.orElse( "cur" ) )
{
case "set":
channel.position( offset );
channel.position( actualOffset );
break;
case "cur":
channel.position( channel.position() + offset );
channel.position( channel.position() + actualOffset );
break;
case "end":
channel.position( channel.size() + offset );
channel.position( channel.size() + actualOffset );
break;
default:
throw new LuaException( "bad argument #1 to 'seek' (invalid option '" + whence + "'" );
@ -81,7 +88,7 @@ public abstract class HandleGeneric
}
catch( IllegalArgumentException e )
{
return new Object[] { false, "Position is negative" };
return new Object[] { null, "Position is negative" };
}
catch( IOException e )
{

37
src/main/java/dan200/computercraft/core/apis/http/request/HttpResponseHandle.java
View File

@ -5,7 +5,11 @@
*/
package dan200.computercraft.core.apis.http.request;
import dan200.computercraft.api.lua.IArguments;
import dan200.computercraft.api.lua.LuaFunction;
import dan200.computercraft.core.apis.HTTPAPI;
import dan200.computercraft.core.apis.handles.BinaryReadableHandle;
import dan200.computercraft.core.apis.handles.EncodedReadableHandle;
import dan200.computercraft.core.apis.handles.HandleGeneric;
import dan200.computercraft.core.asm.ObjectSource;
@ -14,8 +18,12 @@ import java.util.Collections;
import java.util.Map;
/**
* Wraps a {@link dan200.computercraft.core.apis.handles.HandleGeneric} and provides additional methods for
* getting the response code and headers.
* A http response. This provides the same methods as a {@link EncodedReadableHandle file} (or
* {@link BinaryReadableHandle binary file} if the request used binary mode), though provides several request specific
* methods.
*
* @cc.module http.Response
* @see HTTPAPI#request(IArguments) On how to make a http request.
*/
public class HttpResponseHandle implements ObjectSource
{
@ -32,12 +40,37 @@ public class HttpResponseHandle implements ObjectSource
this.responseHeaders = responseHeaders;
}
/**
* Returns the response code and response message returned by the server.
*
* @return The response code and message.
* @cc.treturn number The response code (i.e. 200)
* @cc.treturn string The response message (i.e. "OK")
*/
@LuaFunction
public final Object[] getResponseCode()
{
return new Object[] { responseCode, responseStatus };
}
/**
* Get a table containing the response's headers, in a format similar to that required by {@link HTTPAPI#request}.
* If multiple headers are sent with the same name, they will be combined with a comma.
*
* @return The response's headers.
* @cc.usage Make a request to [example.computercraft.cc](https://example.computercraft.cc), and print the
* returned headers.
* <pre>{@code
* local request = http.get("https://example.computercraft.cc")
* print(textutils.serialize(request.getResponseHeaders()))
* -- => {
* -- [ "Content-Type" ] = "text/plain; charset=utf8",
* -- [ "content-length" ] = 17,
* -- ...
* -- }
* request.close()
* }</pre>
*/
@LuaFunction
public final Map<String, String> getResponseHeaders()
{

10
src/main/java/dan200/computercraft/core/terminal/Terminal.java
View File

@ -10,6 +10,8 @@ import dan200.computercraft.shared.util.Palette;
import net.minecraft.nbt.CompoundNBT;
import net.minecraft.network.PacketBuffer;
import javax.annotation.Nonnull;
public class Terminal
{
private static final String base16 = "0123456789abcdef";
@ -29,7 +31,6 @@ public class Terminal
private final Palette m_palette = new Palette();
private boolean m_changed = false;
private final Runnable onChanged;
public Terminal( int width, int height )
@ -184,6 +185,7 @@ public class Terminal
return m_cursorBackgroundColour;
}
@Nonnull
public Palette getPalette()
{
return m_palette;
@ -305,15 +307,9 @@ public class Terminal
public final void setChanged()
{
m_changed = true;
if( onChanged != null ) onChanged.run();
}
public final void clearChanged()
{
m_changed = false;
}
public synchronized void write( PacketBuffer buffer )
{
buffer.writeInt( m_cursorX );

4
src/main/java/dan200/computercraft/shared/common/ClientTerminal.java
View File

@ -25,10 +25,6 @@ public class ClientTerminal implements ITerminal
{
boolean changed = m_terminalChanged;
m_terminalChanged = false;
Terminal terminal = m_terminal;
if( terminal != null ) terminal.clearChanged();
return changed;
}

3
src/main/java/dan200/computercraft/shared/common/ServerTerminal.java
View File

@ -58,9 +58,6 @@ public class ServerTerminal implements ITerminal
public void update()
{
Terminal terminal = m_terminal;
if( terminal != null ) terminal.clearChanged();
m_terminalChangedLastFrame = m_terminalChanged.getAndSet( false );
}

1
src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
View File

@ -137,6 +137,7 @@ public abstract class WiredModemPeripheral extends ModemPeripheral implements IW
* @param computer The calling computer.
* @param name The peripheral's name.
* @return A list of methods provided by this peripheral, or {@code nil} if it is not present.
* @cc.treturn { string... }|nil A list of methods provided by this peripheral, or {@code nil} if it is not present.
* @see PeripheralAPI#getMethods
*/
@LuaFunction

26
src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
View File

@ -108,6 +108,8 @@ public class TurtleAPI implements ILuaAPI
* Rotate the turtle 90 degress to the left.
*
* @return The turtle command result.
* @cc.treturn boolean Whether the turtle could successfully turn.
* @cc.treturn string|nil The reason the turtle could not turn.
*/
@LuaFunction
public final MethodResult turnLeft()
@ -119,6 +121,8 @@ public class TurtleAPI implements ILuaAPI
* Rotate the turtle 90 degress to the right.
*
* @return The turtle command result.
* @cc.treturn boolean Whether the turtle could successfully turn.
* @cc.treturn string|nil The reason the turtle could not turn.
*/
@LuaFunction
public final MethodResult turnRight()
@ -279,6 +283,7 @@ public class TurtleAPI implements ILuaAPI
* @param slot The slot to select.
* @return The turtle command result.
* @throws LuaException If the slot is out of range.
* @cc.treturn true When the slot has been selected.
* @see #getSelectedSlot
*/
@ -525,18 +530,39 @@ public class TurtleAPI implements ILuaAPI
return trackCommand( new TurtleEquipCommand( TurtleSide.RIGHT ) );
}
/**
* Get information about the block in front of the turtle.
*
* @return The turtle command result.
* @cc.treturn boolean Whether there is a block in front of the turtle.
* @cc.treturn table|string Information about the block in front, or a message explaining that there is no block.
*/
@LuaFunction
public final MethodResult inspect()
{
return trackCommand( new TurtleInspectCommand( InteractDirection.FORWARD ) );
}
/**
* Get information about the block above the turtle.
*
* @return The turtle command result.
* @cc.treturn boolean Whether there is a block above the turtle.
* @cc.treturn table|string Information about the above below, or a message explaining that there is no block.
*/
@LuaFunction
public final MethodResult inspectUp()
{
return trackCommand( new TurtleInspectCommand( InteractDirection.UP ) );
}
/**
* Get information about the block below the turtle.
*
* @return The turtle command result.
* @cc.treturn boolean Whether there is a block below the turtle.
* @cc.treturn table|string Information about the block below, or a message explaining that there is no block.
*/
@LuaFunction
public final MethodResult inspectDown()
{

9
src/main/java/dan200/computercraft/shared/turtle/core/TurtleDetectCommand.java
View File

@ -36,11 +36,8 @@ public class TurtleDetectCommand implements ITurtleCommand
BlockPos oldPosition = turtle.getPosition();
BlockPos newPosition = oldPosition.offset( direction );
if( !WorldUtil.isLiquidBlock( world, newPosition ) && !world.isAirBlock( newPosition ) )
{
return TurtleCommandResult.success();
}
return TurtleCommandResult.failure();
return !WorldUtil.isLiquidBlock( world, newPosition ) && !world.isAirBlock( newPosition )
? TurtleCommandResult.success()
: TurtleCommandResult.failure();
}
}