From eead8b575569be841f535cc2e44c9f9f2e671c18 Mon Sep 17 00:00:00 2001 From: SquidDev Date: Sat, 18 Apr 2020 21:42:59 +0100 Subject: [PATCH] A small amount of Lua documentation I'd forgotten how tedious this was. I can't say any of these docs are especially good, but it's something. --- doc/stub/http.lua | 22 +- doc/stub/turtle.lua | 226 ++++++++++++++++-- .../computercraft/lua/rom/apis/peripheral.lua | 6 +- .../lua/rom/apis/turtle/turtle.lua | 2 +- .../computercraft/lua/rom/apis/window.lua | 95 +++++--- 5 files changed, 297 insertions(+), 54 deletions(-) diff --git a/doc/stub/http.lua b/doc/stub/http.lua index 8e7df608f..8e8a24c08 100644 --- a/doc/stub/http.lua +++ b/doc/stub/http.lua @@ -199,8 +199,6 @@ function websocket(url, headers) end -- of the initial websocket connection. function websocketAsync(url, headers) end - - --- A websocket, which can be used to send an receive messages with a web -- server. -- @@ -208,6 +206,24 @@ function websocketAsync(url, headers) end -- @see http.websocket On how to open a websocket. local Websocket = {} +--- Send a websocket message to the connected server. +-- +-- @tparam string message The message to send. +-- @tparam[opt] boolean binary Whether this message should be treated as a +-- binary string, rather than encoded text. +-- @throws If the websocket has been closed. function Websocket.send(message, binary) end -function Websocket.receive() end + +--- Wait for a message from the server. +-- +-- @tparam[opt] number timeout The number of seconds to wait if no message is +-- received. +-- @treturn[1] string The received message. +-- @treturn boolean If this was a binary message. +-- @treturn[2] nil If the websocket was closed while waiting, or if we timed out. +-- @throws If the websocket has been closed. +function Websocket.receive(timeout) end + +--- Close this websocket. This will terminate the connection, meaning messages +-- can no longer be sent or received along it. function Websocket.close() end diff --git a/doc/stub/turtle.lua b/doc/stub/turtle.lua index 0baa4c6fa..7fabd2a8a 100644 --- a/doc/stub/turtle.lua +++ b/doc/stub/turtle.lua @@ -1,42 +1,230 @@ +--- Move the turtle forward one block. +-- @treturn boolean Whether the turtle could successfully move. +-- @treturn string|nil The reason the turtle could not move. function forward() end + +--- Move the turtle backwards one block. +-- @treturn boolean Whether the turtle could successfully move. +-- @treturn string|nil The reason the turtle could not move. function back() end + +--- Move the turtle up one block. +-- @treturn boolean Whether the turtle could successfully move. +-- @treturn string|nil The reason the turtle could not move. function up() end + +--- Move the turtle down one block. +-- @treturn boolean Whether the turtle could successfully move. +-- @treturn string|nil The reason the turtle could not move. function down() end + +--- Rotate the turtle 90 degress to the left. function turnLeft() end + +--- Rotate the turtle 90 degress to the right. function turnRight() end + +--- Attempt to break the block in front of the turtle. +-- +-- This requires a turtle tool capable of breaking the block. Diamond pickaxes +-- (mining turtles) can break any vanilla block, but other tools (such as axes) +-- are more limited. +-- +-- @tparam[opt] "left"|"right" side The specific tool to use. +-- @treturn boolean Whether a block was broken. +-- @treturn string|nil The reason no block was broken. function dig(side) end + +--- Attempt to break the block above the turtle. See @{dig} for full details. +-- +-- @tparam[opt] "left"|"right" side The specific tool to use. +-- @treturn boolean Whether a block was broken. +-- @treturn string|nil The reason no block was broken. function digUp(side) end + +--- Attempt to break the block below the turtle. See @{dig} for full details. +-- +-- @tparam[opt] "left"|"right" side The specific tool to use. +-- @treturn boolean Whether a block was broken. +-- @treturn string|nil The reason no block was broken. function digDown(side) end + +--- Attack the entity in front of the turtle. +-- +-- @tparam[opt] "left"|"right" side The specific tool to use. +-- @treturn boolean Whether an entity was attacked. +-- @treturn string|nil The reason nothing was attacked. +function attack(side) end + +--- Attack the entity above the turtle. +-- +-- @tparam[opt] "left"|"right" side The specific tool to use. +-- @treturn boolean Whether an entity was attacked. +-- @treturn string|nil The reason nothing was attacked. +function attackUp(side) end + +--- Attack the entity below the turtle. +-- +-- @tparam[opt] "left"|"right" side The specific tool to use. +-- @treturn boolean Whether an entity was attacked. +-- @treturn string|nil The reason nothing was attacked. +function attackDown(side) end + +--- Place a block or item into the world in front of the turtle. +-- +-- @treturn boolean Whether the block could be placed. +-- @treturn string|nil The reason the block was not placed. function place() end + +--- Place a block or item into the world above the turtle. +-- +-- @treturn boolean Whether the block could be placed. +-- @treturn string|nil The reason the block was not placed. function placeUp() end + +--- Place a block or item into the world below the turtle. +-- +-- @treturn boolean Whether the block could be placed. +-- @treturn string|nil The reason the block was not placed. function placeDown() end + +--- Drop the currently selected stack into the inventory in front of the turtle, +-- or as an item into the world if there is no inventory. +-- +-- @tparam[opt] number count The number of items to drop. If not given, the +-- entire stack will be dropped. +-- @treturn boolean Whether items were dropped. +-- @treturn string|nil The reason the no items were dropped. +-- @see select function drop(count) end -function select(slot) end -function getItemCount(slot) end -function getItemSpace(slot) end + +--- Drop the currently selected stack into the inventory above the turtle, or as +-- an item into the world if there is no inventory. +-- +-- @tparam[opt] number count The number of items to drop. If not given, the +-- entire stack will be dropped. +-- @treturn boolean Whether items were dropped. +-- @treturn string|nil The reason the no items were dropped. +-- @see select +function dropUp(count) end + +--- Drop the currently selected stack into the inventory below the turtle, or as +-- an item into the world if there is no inventory. +-- +-- @tparam[opt] number count The number of items to drop. If not given, the +-- entire stack will be dropped. +-- @treturn boolean Whether items were dropped. +-- @treturn string|nil The reason the no items were dropped. +-- @see select +function dropDown(count) end + +--- Suck an item from the inventory in front of the turtle, or from an item +-- floating in the world. +-- +-- This will pull items into the first acceptable slot, starting at the +-- @{select|currently selected} one. +-- +-- @tparam[opt] number count The number of items to suck. If not given, up to a +-- stack of items will be picked up. +-- @treturn boolean Whether items were picked up. +-- @treturn string|nil The reason the no items were picked up. +function suck(count) end + +--- Suck an item from the inventory above the turtle, or from an item floating +-- in the world. +-- +-- @tparam[opt] number count The number of items to suck. If not given, up to a +-- stack of items will be picked up. +-- @treturn boolean Whether items were picked up. +-- @treturn string|nil The reason the no items were picked up. +function suckUp(count) end + +--- Suck an item from the inventory below the turtle, or from an item floating +-- in the world. +-- +-- @tparam[opt] number count The number of items to suck. If not given, up to a +-- stack of items will be picked up. +-- @treturn boolean Whether items were picked up. +-- @treturn string|nil The reason the no items were picked up. +function suckDown(count) end + +--- Check if there is a solid block in front of the turtle. In this case, solid +-- refers to any non-air or liquid block. +-- +-- @treturn boolean If there is a solid block in front. function detect() end + +--- Check if there is a solid block above the turtle. +-- +-- @treturn boolean If there is a solid block above. function detectUp() end + +--- Check if there is a solid block below the turtle. +-- +-- @treturn boolean If there is a solid block below. function detectDown() end + function compare() end function compareUp() end function compareDown() end -function attack(side) end -function attackUp(side) end -function attackDown(side) end -function dropUp(count) end -function dropDown(count) end -function suck(count) end -function suckUp(count) end -function suckDown(count) end -function getFuelLevel() end -function refuel(count) end -function compareTo(slot) end -function transferTo(slot, count) end -function getSelectedSlot() end -function getFuelLimit() end -function equipLeft() end -function equipRight() end + function inspect() end function inspectUp() end function inspectDown() end + + +--- Change the currently selected slot. +-- +-- The selected slot is determines what slot actions like @{drop} or +-- @{getItemCount} act on. +-- +-- @tparam number slot The slot to select. +-- @see getSelectedSlot +function select(slot) end + +--- Get the currently selected slot. +-- +-- @treturn number The current slot. +-- @see select +function getSelectedSlot() end + +--- Get the number of items in the given slot. +-- +-- @tparam[opt] number slot The slot we wish to check. Defaults to the @{turtle.select|selected slot}. +-- @treturn number The number of items in this slot. +function getItemCount(slot) end + +--- Get the remaining number of items which may be stored in this stack. +-- +-- For instance, if a slot contains 13 blocks of dirt, it has room for another 51. +-- +-- @tparam[opt] number slot The slot we wish to check. Defaults to the @{turtle.select|selected slot}. +-- @treturn number The space left in this slot. +function getItemSpace(slot) end + + +--- Get detailed information about the items in the given slot. +-- +-- @tparam[opt] number slot The slot to get information about. Defaults to the @{turtle.select|selected slot}. +-- @treturn nil|table Information about the given slot, or @{nil} if it is empty. +-- @usage Print the current slot, assuming it contains 13 dirt. +-- +-- print(textutils.serialize(turtle.getItemDetail())) +-- -- => { +-- -- name = "minecraft:dirt", +-- -- damage = 0, +-- -- count = 13, +-- -- } function getItemDetail(slot) end + +function getFuelLevel() end + +function refuel(count) end +function compareTo(slot) end +function transferTo(slot, count) end + +function getFuelLimit() end +function equipLeft() end +function equipRight() end + +function craft(limit) end diff --git a/src/main/resources/assets/computercraft/lua/rom/apis/peripheral.lua b/src/main/resources/assets/computercraft/lua/rom/apis/peripheral.lua index c3c71ff65..b9039a52f 100644 --- a/src/main/resources/assets/computercraft/lua/rom/apis/peripheral.lua +++ b/src/main/resources/assets/computercraft/lua/rom/apis/peripheral.lua @@ -105,14 +105,16 @@ function getMethods(name) return nil end ---- Call a method on a peripheral with a given name +--- Call a method on the peripheral with the given name. -- -- @tparam string name The name of the peripheral to invoke the method on. -- @tparam string method The name of the method -- @param ... Additional arguments to pass to the method -- @return The return values of the peripheral method. -- --- @usage peripheral.call("top", "open", 1) +-- @usage Open the modem on the top of this computer. +-- +-- peripheral.call("top", "open", 1) function call(name, method, ...) expect(1, name, "string") expect(2, method, "string") diff --git a/src/main/resources/assets/computercraft/lua/rom/apis/turtle/turtle.lua b/src/main/resources/assets/computercraft/lua/rom/apis/turtle/turtle.lua index f52645524..32852f718 100644 --- a/src/main/resources/assets/computercraft/lua/rom/apis/turtle/turtle.lua +++ b/src/main/resources/assets/computercraft/lua/rom/apis/turtle/turtle.lua @@ -5,7 +5,7 @@ if not turtle then error("Cannot load turtle API on computer", 2) end -native = turtle.native or turtle +native = turtle.native or turtle --- @local local function addCraftMethod(object) if peripheral.getType("left") == "workbench" then diff --git a/src/main/resources/assets/computercraft/lua/rom/apis/window.lua b/src/main/resources/assets/computercraft/lua/rom/apis/window.lua index aa6e5aab6..57bd70c54 100644 --- a/src/main/resources/assets/computercraft/lua/rom/apis/window.lua +++ b/src/main/resources/assets/computercraft/lua/rom/apis/window.lua @@ -68,7 +68,7 @@ local string_sub = string.sub -- @tparam number nWidth The width of this window -- @tparam number nHeight The height of this window -- @tparam[opt] boolean bStartVisible Whether this window is visible by --- default. Defaults to `true`. +-- default. Defaults to `true`. -- @treturn Window The constructed window function create(parent, nX, nY, nWidth, nHeight, bStartVisible) expect(1, parent, "table") @@ -229,9 +229,11 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible) end end - --- Terminal implementation + --- The window object. Refer to the @{window|module's documentation} for + -- a full description. -- -- @type Window + -- @see term.Redirect local window = {} function window.write(sText) @@ -437,6 +439,13 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible) return nBackgroundColor end + --- Get the buffered contents of a line in this window. + --- + -- @tparam number y The y position of the line to get. + -- @treturn string The textual content of this line. + -- @treturn string The text colours of this line, suitable for use with @{term.blit}. + -- @treturn string The background colours of this line, suitable for use with @{term.blit}. + -- @throws If `y` is a valid line. function window.getLine(y) if type(y) ~= "number" then expect(1, y, "number") end @@ -448,16 +457,26 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible) end -- Other functions - function window.setVisible(bVis) - if type(bVis) ~= "boolean" then expect(1, bVis, "boolean") end - if bVisible ~= bVis then - bVisible = bVis + + --- Set whether this window is visible. Invisible windows will not be drawn + -- to the screen until they are made visible again. + -- + -- Making an invisible window visible will immediately draw it. + -- + -- @tparam boolean visible Whether this window is visible. + function window.setVisible(visible) + if type(visible) ~= "boolean" then expect(1, visible, "boolean") end + if bVisible ~= visible then + bVisible = visible if bVisible then window.redraw() end end end + --- Draw this window. This does nothing if the window is not visible. + -- + -- @see Window:setVisible function window.redraw() if bVisible then redraw() @@ -468,6 +487,8 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible) end end + --- Set the current terminal's cursor to where this window's cursor is. This + -- does nothing if the window is not visible. function window.restoreCursor() if bVisible then updateCursorBlink() @@ -476,31 +497,47 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible) end end + --- Get the position of the top left corner of this window. + -- + -- @treturn number The x position of this window. + -- @treturn number The y position of this window. function window.getPosition() return nX, nY end - function window.reposition(nNewX, nNewY, nNewWidth, nNewHeight, newParent) - if type(nNewX) ~= "number" then expect(1, nNewX, "number") end - if type(nNewY) ~= "number" then expect(2, nNewY, "number") end - if nNewWidth ~= nil or nNewHeight ~= nil then - expect(3, nNewWidth, "number") - expect(4, nNewHeight, "number") + --- Reposition or resize the given window. + -- + -- This function also accepts arguments to change the size of this window. + -- It is recommended that you fire a `term_resize` event after changing a + -- window's, to allow programs to adjust their sizing. + -- + -- @tparam number new_x The new x position of this window. + -- @tparam number new_y The new y position of this window. + -- @tparam[opt] number new_width The new width of this window. + -- @tparam number new_height The new height of this window. + -- @tparam[opt] term.Redirect new_parent The new redirect object this + -- window should draw to. + function window.reposition(new_x, new_y, new_width, new_height, new_parent) + if type(new_x) ~= "number" then expect(1, new_x, "number") end + if type(new_y) ~= "number" then expect(2, new_y, "number") end + if new_width ~= nil or new_height ~= nil then + expect(3, new_width, "number") + expect(4, new_height, "number") end - if newParent ~= nil and type(newParent) ~= "table" then expect(5, newParent, "table") end + if new_parent ~= nil and type(new_parent) ~= "table" then expect(5, new_parent, "table") end - nX = nNewX - nY = nNewY + nX = new_x + nY = new_y - if newParent then parent = newParent end + if new_parent then parent = new_parent end - if nNewWidth and nNewHeight then + if new_width and new_height then local tNewLines = {} - createEmptyLines(nNewWidth) + createEmptyLines(new_width) local sEmptyText = sEmptySpaceLine local sEmptyTextColor = tEmptyColorLines[nTextColor] local sEmptyBackgroundColor = tEmptyColorLines[nBackgroundColor] - for y = 1, nNewHeight do + for y = 1, new_height do if y > nHeight then tNewLines[y] = { text = sEmptyText, @@ -509,25 +546,25 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible) } else local tOldLine = tLines[y] - if nNewWidth == nWidth then + if new_width == nWidth then tNewLines[y] = tOldLine - elseif nNewWidth < nWidth then + elseif new_width < nWidth then tNewLines[y] = { - text = string_sub(tOldLine.text, 1, nNewWidth), - textColor = string_sub(tOldLine.textColor, 1, nNewWidth), - backgroundColor = string_sub(tOldLine.backgroundColor, 1, nNewWidth), + text = string_sub(tOldLine.text, 1, new_width), + textColor = string_sub(tOldLine.textColor, 1, new_width), + backgroundColor = string_sub(tOldLine.backgroundColor, 1, new_width), } else tNewLines[y] = { - text = tOldLine.text .. string_sub(sEmptyText, nWidth + 1, nNewWidth), - textColor = tOldLine.textColor .. string_sub(sEmptyTextColor, nWidth + 1, nNewWidth), - backgroundColor = tOldLine.backgroundColor .. string_sub(sEmptyBackgroundColor, nWidth + 1, nNewWidth), + text = tOldLine.text .. string_sub(sEmptyText, nWidth + 1, new_width), + textColor = tOldLine.textColor .. string_sub(sEmptyTextColor, nWidth + 1, new_width), + backgroundColor = tOldLine.backgroundColor .. string_sub(sEmptyBackgroundColor, nWidth + 1, new_width), } end end end - nWidth = nNewWidth - nHeight = nNewHeight + nWidth = new_width + nHeight = new_height tLines = tNewLines end if bVisible then