mirrors
/
CC-Tweaked
mirror of https://github.com/SquidDev-CC/CC-Tweaked
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #1570 from cc-tweaked/feature/new-md-syntax 

Change the syntax of several markdown extensions
This commit is contained in:
Jonathan Coates 2023-08-24 16:26:41 +01:00 committed by GitHub
parent 12ee47ff19 52b78f92cd
commit 053751b190
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
90 changed files with 631 additions and 670 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/events/alarm.md
View File

@ -9,11 +9,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{alarm} event is fired when an alarm started with @{os.setAlarm} completes.
The [`alarm`] event is fired when an alarm started with [`os.setAlarm`] completes.
## Return Values
1. @{string}: The event name.
2. @{number}: The ID of the alarm that finished.
1. [`string`]: The event name.
2. [`number`]: The ID of the alarm that finished.
## Example
Starts a timer and then waits for it to complete.

10
doc/events/char.md
View File

@ -9,15 +9,15 @@
SPDX-License-Identifier: LicenseRef-CCPL
-->
The @{char} event is fired when a character is typed on the keyboard.
The [`char`] event is fired when a character is typed on the keyboard.
The @{char} event is different to a key press. Sometimes multiple key presses may result in one character being
The [`char`] event is different to a key press. Sometimes multiple key presses may result in one character being
typed (for instance, on some European keyboards). Similarly, some keys (e.g. <kbd>Ctrl</kbd>) do not have any
corresponding character. The @{key} should be used if you want to listen to key presses themselves.
corresponding character. The [`key`] should be used if you want to listen to key presses themselves.
## Return values
1. @{string}: The event name.
2. @{string}: The string representing the character that was pressed.
1. [`string`]: The event name.
2. [`string`]: The string representing the character that was pressed.
## Example

6
doc/events/computer_command.md
View File

@ -8,11 +8,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{computer_command} event is fired when the `/computercraft queue` command is run for the current computer.
The [`computer_command`] event is fired when the `/computercraft queue` command is run for the current computer.
## Return Values
1. @{string}: The event name.
2. @{string}<abbr title="Variable number of arguments">&hellip;</abbr>: The arguments passed to the command.
1. [`string`]: The event name.
2. [`string`]<abbr title="Variable number of arguments">&hellip;</abbr>: The arguments passed to the command.
## Example
Prints the contents of messages sent:

6
doc/events/disk.md
View File

@ -9,11 +9,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{disk} event is fired when a disk is inserted into an adjacent or networked disk drive.
The [`disk`] event is fired when a disk is inserted into an adjacent or networked disk drive.
## Return Values
1. @{string}: The event name.
2. @{string}: The side of the disk drive that had a disk inserted.
1. [`string`]: The event name.
2. [`string`]: The side of the disk drive that had a disk inserted.
## Example
Prints a message when a disk is inserted:

6
doc/events/disk_eject.md
View File

@ -9,11 +9,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{disk_eject} event is fired when a disk is removed from an adjacent or networked disk drive.
The [`disk_eject`] event is fired when a disk is removed from an adjacent or networked disk drive.
## Return Values
1. @{string}: The event name.
2. @{string}: The side of the disk drive that had a disk removed.
1. [`string`]: The event name.
2. [`string`]: The side of the disk drive that had a disk removed.
## Example
Prints a message when a disk is removed:

12
doc/events/file_transfer.md
View File

@ -9,15 +9,15 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{file_transfer} event is queued when a user drags-and-drops a file on an open computer.
The [`file_transfer`] event is queued when a user drags-and-drops a file on an open computer.
This event contains a single argument of type @{TransferredFiles}, which can be used to @{TransferredFiles.getFiles|get
the files to be transferred}. Each file returned is a @{fs.BinaryReadHandle|binary file handle} with an additional
@{TransferredFile.getName|getName} method.
This event contains a single argument of type [`TransferredFiles`], which can be used to [get the files to be
transferred][`TransferredFiles.getFiles`]. Each file returned is a [binary file handle][`fs.BinaryReadHandle`] with an
additional [getName][`TransferredFile.getName`] method.
## Return values
1. @{string}: The event name
2. @{TransferredFiles}: The list of transferred files.
1. [`string`]: The event name
2. [`TransferredFiles`]: The list of transferred files.
## Example
Waits for a user to drop files on top of the computer, then prints the list of files and the size of each file.

12
doc/events/http_check.md
View File

@ -9,12 +9,12 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{http_check} event is fired when a URL check finishes.
The [`http_check`] event is fired when a URL check finishes.
This event is normally handled inside @{http.checkURL}, but it can still be seen when using @{http.checkURLAsync}.
This event is normally handled inside [`http.checkURL`], but it can still be seen when using [`http.checkURLAsync`].
## Return Values
1. @{string}: The event name.
2. @{string}: The URL requested to be checked.
3. @{boolean}: Whether the check succeeded.
4. <span class="type">@{string}|@{nil}</span>: If the check failed, a reason explaining why the check failed.
1. [`string`]: The event name.
2. [`string`]: The URL requested to be checked.
3. [`boolean`]: Whether the check succeeded.
4. <span class="type">[`string`]|[`nil`]</span>: If the check failed, a reason explaining why the check failed.

12
doc/events/http_failure.md
View File

@ -9,15 +9,15 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{http_failure} event is fired when an HTTP request fails.
The [`http_failure`] event is fired when an HTTP request fails.
This event is normally handled inside @{http.get} and @{http.post}, but it can still be seen when using @{http.request}.
This event is normally handled inside [`http.get`] and [`http.post`], but it can still be seen when using [`http.request`].
## Return Values
1. @{string}: The event name.
2. @{string}: The URL of the site requested.
3. @{string}: An error describing the failure.
4. <span class="type">@{http.Response}|@{nil}</span>: A response handle if the connection succeeded, but the server's
1. [`string`]: The event name.
2. [`string`]: The URL of the site requested.
3. [`string`]: An error describing the failure.
4. <span class="type">[`http.Response`]|[`nil`]</span>: A response handle if the connection succeeded, but the server's
response indicated failure.
## Example

10
doc/events/http_success.md
View File

@ -9,14 +9,14 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{http_success} event is fired when an HTTP request returns successfully.
The [`http_success`] event is fired when an HTTP request returns successfully.
This event is normally handled inside @{http.get} and @{http.post}, but it can still be seen when using @{http.request}.
This event is normally handled inside [`http.get`] and [`http.post`], but it can still be seen when using [`http.request`].
## Return Values
1. @{string}: The event name.
2. @{string}: The URL of the site requested.
3. @{http.Response}: The successful HTTP response.
1. [`string`]: The event name.
2. [`string`]: The URL of the site requested.
3. [`http.Response`]: The successful HTTP response.
## Example
Prints the content of a website (this may fail if the request fails):

12
doc/events/key.md
View File

@ -11,15 +11,15 @@
This event is fired when any key is pressed while the terminal is focused.
This event returns a numerical "key code" (for instance, <kbd>F1</kbd> is 290). This value may vary between versions and
so it is recommended to use the constants in the @{keys} API rather than hard coding numeric values.
so it is recommended to use the constants in the [`keys`] API rather than hard coding numeric values.
If the button pressed represented a printable character, then the @{key} event will be followed immediately by a @{char}
event. If you are consuming text input, use a @{char} event instead!
If the button pressed represented a printable character, then the [`key`] event will be followed immediately by a [`char`]
event. If you are consuming text input, use a [`char`] event instead!
## Return values
1. @{string}: The event name.
2. @{number}: The numerical key value of the key pressed.
3. @{boolean}: Whether the key event was generated while holding the key (@{true}), rather than pressing it the first time (@{false}).
1. [`string`]: The event name.
2. [`number`]: The numerical key value of the key pressed.
3. [`boolean`]: Whether the key event was generated while holding the key ([`true`]), rather than pressing it the first time ([`false`]).
## Example
Prints each key when the user presses it, and if the key is being held.

8
doc/events/key_up.md
View File

@ -12,14 +12,14 @@
Fired whenever a key is released (or the terminal is closed while a key was being pressed).
This event returns a numerical "key code" (for instance, <kbd>F1</kbd> is 290). This value may vary between versions and
so it is recommended to use the constants in the @{keys} API rather than hard coding numeric values.
so it is recommended to use the constants in the [`keys`] API rather than hard coding numeric values.
## Return values
1. @{string}: The event name.
2. @{number}: The numerical key value of the key pressed.
1. [`string`]: The event name.
2. [`number`]: The numerical key value of the key pressed.
## Example
Prints each key released on the keyboard whenever a @{key_up} event is fired.
Prints each key released on the keyboard whenever a [`key_up`] event is fired.
```lua
while true do

16
doc/events/modem_message.md
View File

@ -8,18 +8,18 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{modem_message} event is fired when a message is received on an open channel on any @{modem}.
The [`modem_message`] event is fired when a message is received on an open channel on any [`modem`].
## Return Values
1. @{string}: The event name.
2. @{string}: The side of the modem that received the message.
3. @{number}: The channel that the message was sent on.
4. @{number}: The reply channel set by the sender.
5. @{any}: The message as sent by the sender.
6. <span class="type">@{number}|@{nil}</span>: The distance between the sender and the receiver in blocks, or @{nil} if the message was sent between dimensions.
1. [`string`]: The event name.
2. [`string`]: The side of the modem that received the message.
3. [`number`]: The channel that the message was sent on.
4. [`number`]: The reply channel set by the sender.
5. [`any`]: The message as sent by the sender.
6. <span class="type">[`number`]|[`nil`]</span>: The distance between the sender and the receiver in blocks, or [`nil`] if the message was sent between dimensions.
## Example
Wraps a @{modem} peripheral, opens channel 0 for listening, and prints all received messages.
Wraps a [`modem`] peripheral, opens channel 0 for listening, and prints all received messages.
```lua
local modem = peripheral.find("modem") or error("No modem attached", 0)

6
doc/events/monitor_resize.md
View File

@ -8,11 +8,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{monitor_resize} event is fired when an adjacent or networked monitor's size is changed.
The [`monitor_resize`] event is fired when an adjacent or networked monitor's size is changed.
## Return Values
1. @{string}: The event name.
2. @{string}: The side or network ID of the monitor that was resized.
1. [`string`]: The event name.
2. [`string`]: The side or network ID of the monitor that was resized.
## Example
Prints a message when a monitor is resized:

10
doc/events/monitor_touch.md
View File

@ -8,13 +8,13 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{monitor_touch} event is fired when an adjacent or networked Advanced Monitor is right-clicked.
The [`monitor_touch`] event is fired when an adjacent or networked Advanced Monitor is right-clicked.
## Return Values
1. @{string}: The event name.
2. @{string}: The side or network ID of the monitor that was touched.
3. @{number}: The X coordinate of the touch, in characters.
4. @{number}: The Y coordinate of the touch, in characters.
1. [`string`]: The event name.
2. [`string`]: The side or network ID of the monitor that was touched.
3. [`number`]: The X coordinate of the touch, in characters.
4. [`number`]: The Y coordinate of the touch, in characters.
## Example
Prints a message when a monitor is touched:

10
doc/events/mouse_click.md
View File

@ -12,13 +12,13 @@
advanced turtles and pocket computers).
## Return values
1. @{string}: The event name.
2. @{number}: The mouse button that was clicked.
3. @{number}: The X-coordinate of the click.
4. @{number}: The Y-coordinate of the click.
1. [`string`]: The event name.
2. [`number`]: The mouse button that was clicked.
3. [`number`]: The X-coordinate of the click.
4. [`number`]: The Y-coordinate of the click.
## Mouse buttons
Several mouse events (@{mouse_click}, @{mouse_up}, @{mouse_scroll}) contain a "mouse button" code. This takes a
Several mouse events ([`mouse_click`], [`mouse_up`], [`mouse_scroll`]) contain a "mouse button" code. This takes a
numerical value depending on which button on your mouse was last pressed when this event occurred.
| Button Code | Mouse Button |

8
doc/events/mouse_drag.md
View File

@ -12,10 +12,10 @@
This event is fired every time the mouse is moved while a mouse button is being held.
## Return values
1. @{string}: The event name.
2. @{number}: The [mouse button](mouse_click.html#Mouse_buttons) that is being pressed.
3. @{number}: The X-coordinate of the mouse.
4. @{number}: The Y-coordinate of the mouse.
1. [`string`]: The event name.
2. [`number`]: The [mouse button](mouse_click.html#Mouse_buttons) that is being pressed.
3. [`number`]: The X-coordinate of the mouse.
4. [`number`]: The Y-coordinate of the mouse.
## Example
Print the button and the coordinates whenever the mouse is dragged.

8
doc/events/mouse_scroll.md
View File

@ -11,10 +11,10 @@
This event is fired when a mouse wheel is scrolled in the terminal.
## Return values
1. @{string}: The event name.
2. @{number}: The direction of the scroll. (-1 = up, 1 = down)
3. @{number}: The X-coordinate of the mouse when scrolling.
4. @{number}: The Y-coordinate of the mouse when scrolling.
1. [`string`]: The event name.
2. [`number`]: The direction of the scroll. (-1 = up, 1 = down)
3. [`number`]: The X-coordinate of the mouse when scrolling.
4. [`number`]: The Y-coordinate of the mouse when scrolling.
## Example
Prints the direction of each scroll, and the position of the mouse at the time.

8
doc/events/mouse_up.md
View File

@ -11,10 +11,10 @@
This event is fired when a mouse button is released or a held mouse leaves the computer's terminal.
## Return values
1. @{string}: The event name.
2. @{number}: The [mouse button](mouse_click.html#Mouse_buttons) that was released.
3. @{number}: The X-coordinate of the mouse.
4. @{number}: The Y-coordinate of the mouse.
1. [`string`]: The event name.
2. [`number`]: The [mouse button](mouse_click.html#Mouse_buttons) that was released.
3. [`number`]: The X-coordinate of the mouse.
4. [`number`]: The Y-coordinate of the mouse.
## Example
Prints the coordinates and button number whenever the mouse is released.

6
doc/events/paste.md
View File

@ -8,11 +8,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{paste} event is fired when text is pasted into the computer through Ctrl-V (or ⌘V on Mac).
The [`paste`] event is fired when text is pasted into the computer through Ctrl-V (or ⌘V on Mac).
## Return values
1. @{string}: The event name.
2. @{string} The text that was pasted.
1. [`string`]: The event name.
2. [`string`] The text that was pasted.
## Example
Prints pasted text:

6
doc/events/peripheral.md
View File

@ -9,11 +9,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{peripheral} event is fired when a peripheral is attached on a side or to a modem.
The [`peripheral`] event is fired when a peripheral is attached on a side or to a modem.
## Return Values
1. @{string}: The event name.
2. @{string}: The side the peripheral was attached to.
1. [`string`]: The event name.
2. [`string`]: The side the peripheral was attached to.
## Example
Prints a message when a peripheral is attached:

6
doc/events/peripheral_detach.md
View File

@ -9,11 +9,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{peripheral_detach} event is fired when a peripheral is detached from a side or from a modem.
The [`peripheral_detach`] event is fired when a peripheral is detached from a side or from a modem.
## Return Values
1. @{string}: The event name.
2. @{string}: The side the peripheral was detached from.
1. [`string`]: The event name.
2. [`string`]: The side the peripheral was detached from.
## Example
Prints a message when a peripheral is detached:

14
doc/events/rednet_message.md
View File

@ -10,17 +10,17 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{rednet_message} event is fired when a message is sent over Rednet.
The [`rednet_message`] event is fired when a message is sent over Rednet.
This event is usually handled by @{rednet.receive}, but it can also be pulled manually.
This event is usually handled by [`rednet.receive`], but it can also be pulled manually.
@{rednet_message} events are sent by @{rednet.run} in the top-level coroutine in response to @{modem_message} events. A @{rednet_message} event is always preceded by a @{modem_message} event. They are generated inside CraftOS rather than being sent by the ComputerCraft machine.
[`rednet_message`] events are sent by [`rednet.run`] in the top-level coroutine in response to [`modem_message`] events. A [`rednet_message`] event is always preceded by a [`modem_message`] event. They are generated inside CraftOS rather than being sent by the ComputerCraft machine.
## Return Values
1. @{string}: The event name.
2. @{number}: The ID of the sending computer.
3. @{any}: The message sent.
4. <span class="type">@{string}|@{nil}</span>: The protocol of the message, if provided.
1. [`string`]: The event name.
2. [`number`]: The ID of the sending computer.
3. [`any`]: The message sent.
4. <span class="type">[`string`]|[`nil`]</span>: The protocol of the message, if provided.
## Example
Prints a message when one is sent:

4
doc/events/redstone.md
View File

@ -8,10 +8,10 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{event!redstone} event is fired whenever any redstone inputs on the computer change.
The [`event!redstone`] event is fired whenever any redstone inputs on the computer change.
## Return values
1. @{string}: The event name.
1. [`string`]: The event name.
## Example
Prints a message when a redstone input changes:

8
doc/events/speaker_audio_empty.md
View File

@ -10,13 +10,13 @@
-->
## Return Values
1. @{string}: The event name.
2. @{string}: The name of the speaker which is available to play more audio.
1. [`string`]: The event name.
2. [`string`]: The name of the speaker which is available to play more audio.
## Example
This uses @{io.lines} to read audio data in blocks of 16KiB from "example_song.dfpwm", and then attempts to play it
using @{speaker.playAudio}. If the speaker's buffer is full, it waits for an event and tries again.
This uses [`io.lines`] to read audio data in blocks of 16KiB from "example_song.dfpwm", and then attempts to play it
using [`speaker.playAudio`]. If the speaker's buffer is full, it waits for an event and tries again.
```lua {data-peripheral=speaker}
local dfpwm = require("cc.audio.dfpwm")

10
doc/events/task_complete.md
View File

@ -9,13 +9,13 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{task_complete} event is fired when an asynchronous task completes. This is usually handled inside the function call that queued the task; however, functions such as @{commands.execAsync} return immediately so the user can wait for completion.
The [`task_complete`] event is fired when an asynchronous task completes. This is usually handled inside the function call that queued the task; however, functions such as [`commands.execAsync`] return immediately so the user can wait for completion.
## Return Values
1. @{string}: The event name.
2. @{number}: The ID of the task that completed.
3. @{boolean}: Whether the command succeeded.
4. @{string}: If the command failed, an error message explaining the failure. (This is not present if the command succeeded.)
1. [`string`]: The event name.
2. [`number`]: The ID of the task that completed.
3. [`boolean`]: Whether the command succeeded.
4. [`string`]: If the command failed, an error message explaining the failure. (This is not present if the command succeeded.)
5. <abbr title="Variable number of arguments">&hellip;</abbr>: Any parameters returned from the command.
## Example

8
doc/events/term_resize.md
View File

@ -8,15 +8,15 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{term_resize} event is fired when the main terminal is resized. For instance:
- When a the tab bar is shown or hidden in @{multishell}.
The [`term_resize`] event is fired when the main terminal is resized. For instance:
- When a the tab bar is shown or hidden in [`multishell`].
- When the terminal is redirected to a monitor via the "monitor" program and the monitor is resized.
When this event fires, some parts of the terminal may have been moved or deleted. Simple terminal programs (those
not using @{term.setCursorPos}) can ignore this event, but more complex GUI programs should redraw the entire screen.
not using [`term.setCursorPos`]) can ignore this event, but more complex GUI programs should redraw the entire screen.
## Return values
1. @{string}: The event name.
1. [`string`]: The event name.
## Example
Print a message each time the terminal is resized.

8
doc/events/terminate.md
View File

@ -8,14 +8,14 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{terminate} event is fired when <kbd>Ctrl-T</kbd> is held down.
The [`terminate`] event is fired when <kbd>Ctrl-T</kbd> is held down.
This event is normally handled by @{os.pullEvent}, and will not be returned. However, @{os.pullEventRaw} will return this event when fired.
This event is normally handled by [`os.pullEvent`], and will not be returned. However, [`os.pullEventRaw`] will return this event when fired.
@{terminate} will be sent even when a filter is provided to @{os.pullEventRaw}. When using @{os.pullEventRaw} with a filter, make sure to check that the event is not @{terminate}.
[`terminate`] will be sent even when a filter is provided to [`os.pullEventRaw`]. When using [`os.pullEventRaw`] with a filter, make sure to check that the event is not [`terminate`].
## Return values
1. @{string}: The event name.
1. [`string`]: The event name.
## Example
Prints a message when Ctrl-T is held:

6
doc/events/timer.md
View File

@ -9,11 +9,11 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{timer} event is fired when a timer started with @{os.startTimer} completes.
The [`timer`] event is fired when a timer started with [`os.startTimer`] completes.
## Return Values
1. @{string}: The event name.
2. @{number}: The ID of the timer that finished.
1. [`string`]: The event name.
2. [`number`]: The ID of the timer that finished.
## Example
Start and wait for a timer to finish.

4
doc/events/turtle_inventory.md
View File

@ -8,10 +8,10 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{turtle_inventory} event is fired when a turtle's inventory is changed.
The [`turtle_inventory`] event is fired when a turtle's inventory is changed.
## Return values
1. @{string}: The event name.
1. [`string`]: The event name.
## Example
Prints a message when the inventory is changed:

14
doc/events/websocket_closed.md
View File

@ -8,16 +8,16 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{websocket_closed} event is fired when an open WebSocket connection is closed.
The [`websocket_closed`] event is fired when an open WebSocket connection is closed.
## Return Values
1. @{string}: The event name.
2. @{string}: The URL of the WebSocket that was closed.
3. <span class="type">@{string}|@{nil}</span>: The [server-provided reason][close_reason]
the websocket was closed. This will be @{nil} if the connection was closed
1. [`string`]: The event name.
2. [`string`]: The URL of the WebSocket that was closed.
3. <span class="type">[`string`]|[`nil`]</span>: The [server-provided reason][close_reason]
the websocket was closed. This will be [`nil`] if the connection was closed
abnormally.
4. <span class="type">@{number}|@{nil}</span>: The [connection close code][close_code],
indicating why the socket was closed. This will be @{nil} if the connection
4. <span class="type">[`number`]|[`nil`]</span>: The [connection close code][close_code],
indicating why the socket was closed. This will be [`nil`] if the connection
was closed abnormally.
[close_reason]: https://www.rfc-editor.org/rfc/rfc6455.html#section-7.1.6 "The WebSocket Connection Close Reason, RFC 6455"

10
doc/events/websocket_failure.md
View File

@ -9,14 +9,14 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{websocket_failure} event is fired when a WebSocket connection request fails.
The [`websocket_failure`] event is fired when a WebSocket connection request fails.
This event is normally handled inside @{http.websocket}, but it can still be seen when using @{http.websocketAsync}.
This event is normally handled inside [`http.websocket`], but it can still be seen when using [`http.websocketAsync`].
## Return Values
1. @{string}: The event name.
2. @{string}: The URL of the site requested.
3. @{string}: An error describing the failure.
1. [`string`]: The event name.
2. [`string`]: The URL of the site requested.
3. [`string`]: An error describing the failure.
## Example
Prints an error why the website cannot be contacted:

12
doc/events/websocket_message.md
View File

@ -8,15 +8,15 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{websocket_message} event is fired when a message is received on an open WebSocket connection.
The [`websocket_message`] event is fired when a message is received on an open WebSocket connection.
This event is normally handled by @{http.Websocket.receive}, but it can also be pulled manually.
This event is normally handled by [`http.Websocket.receive`], but it can also be pulled manually.
## Return Values
1. @{string}: The event name.
2. @{string}: The URL of the WebSocket.
3. @{string}: The contents of the message.
4. @{boolean}: Whether this is a binary message.
1. [`string`]: The event name.
2. [`string`]: The URL of the WebSocket.
3. [`string`]: The contents of the message.
4. [`boolean`]: Whether this is a binary message.
## Example
Prints a message sent by a WebSocket:

10
doc/events/websocket_success.md
View File

@ -9,14 +9,14 @@
SPDX-License-Identifier: MPL-2.0
-->
The @{websocket_success} event is fired when a WebSocket connection request returns successfully.
The [`websocket_success`] event is fired when a WebSocket connection request returns successfully.
This event is normally handled inside @{http.websocket}, but it can still be seen when using @{http.websocketAsync}.
This event is normally handled inside [`http.websocket`], but it can still be seen when using [`http.websocketAsync`].
## Return Values
1. @{string}: The event name.
2. @{string}: The URL of the site.
3. @{http.Websocket}: The handle for the WebSocket.
1. [`string`]: The event name.
2. [`string`]: The URL of the site.
3. [`http.Websocket`]: The handle for the WebSocket.
## Example
Prints the content of a website (this may fail if the request fails):

43
doc/guides/gps_setup.md
View File

@ -9,7 +9,7 @@
-->
# Setting up GPS
The @{gps} API allows computers and turtles to find their current position using wireless modems.
The [`gps`] API allows computers and turtles to find their current position using wireless modems.
In order to use GPS, you'll need to set up multiple *GPS hosts*. These are computers running the special `gps host`
program, which tell other computers the host's position. Several hosts running together are known as a *GPS
@ -25,16 +25,15 @@ ## Building a GPS constellation
modems or 4 ender modems. Try not to mix ender and wireless modems together as you might get some odd behavior when your
requesting computers are out of range.
:::tip Ender modems vs wireless modems
Ender modems have a very large range, which makes them very useful for setting up GPS hosts. If you do this then you
will likely only need one GPS constellation for the whole dimension (such as the Overworld or Nether).
If you do use wireless modems then you may find that you need multiple GPS constellations to cover your needs.
A computer needs a wireless or ender modem and to be in range of a GPS constellation that is in the same dimension as it
to use the GPS API. The reason for this is that ComputerCraft mimics real-life GPS by making use of the distance
parameter of @{modem_message|modem messages} and some maths.
:::
> [Ender modems vs wireless modems][!TIP]
> Ender modems have a very large range, which makes them very useful for setting up GPS hosts. If you do this then you
> will likely only need one GPS constellation for the whole dimension (such as the Overworld or Nether).
>
> If you do use wireless modems then you may find that you need multiple GPS constellations to cover your needs.
>
> A computer needs a wireless or ender modem and to be in range of a GPS constellation that is in the same dimension as
> it to use the GPS API. The reason for this is that ComputerCraft mimics real-life GPS by making use of the distance
> parameter of [modem messages][`modem_message`] and some maths.
Locate where you want to place your GPS constellation. You will need an area at least 6 blocks high, 6 blocks wide, and
6 blocks deep (6x6x6). If you are using wireless modems then you may want to build your constellation as high as you can
@ -79,18 +78,16 @@ ## Configuring the constellation
Create similar startup files for the other computers in your constellation, making sure to input the each computer's own
coordinates.
:::caution Modem messages come from the computer's position, not the modem's
Wireless modems transmit from the block that they are attached to *not* the block space that they occupy, the
coordinates that you input into your GPS host should be the position of the computer and not the position of the modem.
:::
> [Modem messages come from the computer's position, not the modem's][!WARNING]
> Wireless modems transmit from the block that they are attached to *not* the block space that they occupy, the
> coordinates that you input into your GPS host should be the position of the computer and not the position of the modem.
Congratulations, your constellation is now fully set up! You can test it by placing another computer close by, placing a
wireless modem on it, and running the `gps locate` program (or calling the @{gps.locate} function).
wireless modem on it, and running the `gps locate` program (or calling the [`gps.locate`] function).
:::info Why use Minecraft's coordinates?
CC doesn't care if you use Minecraft's coordinate system, so long as all of the GPS hosts with overlapping ranges use
the same reference point (requesting computers will get confused if hosts have different reference points). However,
using MC's coordinate system does provide a nice standard to adopt server-wide. It also is consistent with how command
computers get their location, they use MC's command system to get their block which returns that in MC's coordinate
system.
:::
> [Why use Minecraft's coordinates?][!INFO]
> CC doesn't care if you use Minecraft's coordinate system, so long as all of the GPS hosts with overlapping ranges use
> the same reference point (requesting computers will get confused if hosts have different reference points). However,
> using MC's coordinate system does provide a nice standard to adopt server-wide. It also is consistent with how command
> computers get their location, they use MC's command system to get their block which returns that in MC's coordinate
> system.

31
doc/guides/speaker_audio.md
View File

@ -11,7 +11,7 @@
-->
# Playing audio with speakers
CC: Tweaked's speaker peripheral provides a powerful way to play any audio you like with the @{speaker.playAudio}
CC: Tweaked's speaker peripheral provides a powerful way to play any audio you like with the [`speaker.playAudio`]
method. However, for people unfamiliar with digital audio, it's not the most intuitive thing to use. This guide provides
an introduction to digital audio, demonstrates how to play music with CC: Tweaked's speakers, and then briefly discusses
the more complex topic of audio processing.
@ -60,7 +60,7 @@ ## Streaming audio
up very quickly, and these tables take up more and more memory.
Instead of building our entire song (well, sine wave) in one go, we can produce it in small batches, each of which get
passed off to @{speaker.playAudio} when the time is right. This allows us to build a _stream_ of audio, where we read
passed off to [`speaker.playAudio`] when the time is right. This allows us to build a _stream_ of audio, where we read
chunks of audio one at a time (either from a file or a tone generator like above), do some optional processing to each
one, and then play them.
@ -84,15 +84,15 @@ ## Streaming audio
```
It looks pretty similar to before, aside from we've wrapped the generation and playing code in a while loop, and added a
rather odd loop with @{speaker.playAudio} and @{os.pullEvent}.
rather odd loop with [`speaker.playAudio`] and [`os.pullEvent`].
Let's talk about this loop, why do we need to keep calling @{speaker.playAudio}? Remember that what we're trying to do
Let's talk about this loop, why do we need to keep calling [`speaker.playAudio`]? Remember that what we're trying to do
here is avoid keeping too much audio in memory at once. However, if we're generating audio quicker than the speakers can
play it, we're not helping at all - all this audio is still hanging around waiting to be played!
In order to avoid this, the speaker rejects any new chunks of audio if its backlog is too large. When this happens,
@{speaker.playAudio} returns false. Once enough audio has played, and the backlog has been reduced, a
@{speaker_audio_empty} event is queued, and we can try to play our chunk once more.
[`speaker.playAudio`] returns false. Once enough audio has played, and the backlog has been reduced, a
[`speaker_audio_empty`] event is queued, and we can try to play our chunk once more.
## Storing audio
PCM is a fantastic way of representing audio when we want to manipulate it, but it's not very efficient when we want to
@ -106,7 +106,7 @@ ## Storing audio
DFPWM (Dynamic Filter Pulse Width Modulation) is the de facto standard audio format of the ComputerCraft (and
OpenComputers) world. Originally popularised by the addon mod [Computronics], CC:T now has built-in support for it with
the @{cc.audio.dfpwm} module. This allows you to read DFPWM files from disk, decode them to PCM, and then play them
the [`cc.audio.dfpwm`] module. This allows you to read DFPWM files from disk, decode them to PCM, and then play them
using the speaker.
Let's dive in with an example, and we'll explain things afterwards:
@ -125,16 +125,16 @@ ## Storing audio
end
```
Once again, we see the @{speaker.playAudio}/@{speaker_audio_empty} loop. However, the rest of the program is a little
Once again, we see the [`speaker.playAudio`]/[`speaker_audio_empty`] loop. However, the rest of the program is a little
different.
First, we require the dfpwm module and call @{cc.audio.dfpwm.make_decoder} to construct a new decoder. This decoder
First, we require the dfpwm module and call [`cc.audio.dfpwm.make_decoder`] to construct a new decoder. This decoder
accepts blocks of DFPWM data and converts it to a list of 8-bit amplitudes, which we can then play with our speaker.
As mentioned above, @{speaker.playAudio} accepts at most 128×1024 samples in one go. DFPMW uses a single bit for each
As mentioned above, [`speaker.playAudio`] accepts at most 128×1024 samples in one go. DFPMW uses a single bit for each
sample, which means we want to process our audio in chunks of 16×1024 bytes (16KiB). In order to do this, we use
@{io.lines}, which provides a nice way to loop over chunks of a file. You can of course just use @{fs.open} and
@{fs.BinaryReadHandle.read} if you prefer.
[`io.lines`], which provides a nice way to loop over chunks of a file. You can of course just use [`fs.open`] and
[`fs.BinaryReadHandle.read`] if you prefer.
## Processing audio
As mentioned near the beginning of this guide, PCM audio is pretty easy to work with as it's just a list of amplitudes.
@ -189,10 +189,9 @@ ## Processing audio
end
```
:::note Confused?
Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't
cover. That said, don't be afraid to ask on [GitHub Discussions] or [IRC] either!
:::
> [Confused?][!NOTE]
> Don't worry if you don't understand this example. It's quite advanced, and does use some ideas that this guide doesn't
> cover. That said, don't be afraid to ask on [GitHub Discussions] or [IRC] either!
It's worth noting that the examples of audio processing we've mentioned here are about manipulating the _amplitude_ of
the wave. If you wanted to modify the _frequency_ (for instance, shifting the pitch), things get rather more complex.

20
doc/guides/using_require.md
View File

@ -13,7 +13,7 @@ # Reusing code with require
might want to create a library because you have some functions which are used in multiple programs, or just to split
your program into multiple more modular files.
Let's say we want to create a small library to make working with the @{term|terminal} a little easier. We'll provide two
Let's say we want to create a small library to make working with the [terminal][`term`] a little easier. We'll provide two
functions: `reset`, which clears the terminal and sets the cursor to (1, 1), and `write_center`, which prints some text
in the middle of the screen.
@ -48,32 +48,32 @@ # Reusing code with require
When run, this'll clear the screen and print some text in the middle of the first line.
## require in depth
While the previous section is a good introduction to how @{require} operates, there are a couple of remaining points
While the previous section is a good introduction to how [`require`] operates, there are a couple of remaining points
which are worth mentioning for more advanced usage.
### Libraries can return anything
In our above example, we return a table containing the functions we want to expose. However, it's worth pointing out
that you can return ''anything'' from your library - a table, a function or even just a string! @{require} treats them
that you can return ''anything'' from your library - a table, a function or even just a string! [`require`] treats them
all the same, and just returns whatever your library provides.
### Module resolution and the package path
In the above examples, we defined our library in a file, and @{require} read from it. While this is what you'll do most
of the time, it is possible to make @{require} look elsewhere for your library, such as downloading from a website or
In the above examples, we defined our library in a file, and [`require`] read from it. While this is what you'll do most
of the time, it is possible to make [`require`] look elsewhere for your library, such as downloading from a website or
loading from an in-memory library store.
As a result, the *module name* you pass to @{require} doesn't correspond to a file path. One common mistake is to load
As a result, the *module name* you pass to [`require`] doesn't correspond to a file path. One common mistake is to load
code from a sub-directory using `require("folder/library")` or even `require("folder/library.lua")`, neither of which
will do quite what you expect.
When loading libraries (also referred to as *modules*) from files, @{require} searches along the *@{package.path|module
path}*. By default, this looks something like:
When loading libraries (also referred to as *modules*) from files, [`require`] searches along the [*module
path*][`package.path`]. By default, this looks something like:
* `?.lua`
* `?/init.lua`
* `/rom/modules/main/?.lua`
* etc...
When you call `require("my_library")`, @{require} replaces the `?` in each element of the path with your module name, and
When you call `require("my_library")`, [`require`] replaces the `?` in each element of the path with your module name, and
checks if the file exists. In this case, we'd look for `my_library.lua`, `my_library/init.lua`,
`/rom/modules/main/my_library.lua` and so on. Note that this works *relative to the current program*, so if your
program is actually called `folder/program`, then we'll look for `folder/my_library.lua`, etc...
@ -86,4 +86,4 @@ ## External links
There are several external resources which go into require in a little more detail:
- The [Lua Module tutorial](http://lua-users.org/wiki/ModulesTutorial) on the Lua wiki.
- [Lua's manual section on @{require}](https://www.lua.org/manual/5.1/manual.html#pdf-require).
- [Lua's manual section on `require`](https://www.lua.org/manual/5.1/manual.html#pdf-require).

26
doc/stub/global.lua
View File

@ -13,22 +13,20 @@ include standard Lua functions.
As it waits for a fixed amount of world ticks, `time` will automatically be
rounded up to the nearest multiple of 0.05 seconds. If you are using coroutines
or the @{parallel|parallel API}, it will only pause execution of the current
or the [parallel API][`parallel`], it will only pause execution of the current
thread, not the whole program.
:::tip
Because sleep internally uses timers, it is a function that yields. This means
that you can use it to prevent "Too long without yielding" errors. However, as
the minimum sleep time is 0.05 seconds, it will slow your program down.
:::
> [!TIP]
> Because sleep internally uses timers, it is a function that yields. This means
> that you can use it to prevent "Too long without yielding" errors. However, as
> the minimum sleep time is 0.05 seconds, it will slow your program down.
:::caution
Internally, this function queues and waits for a timer event (using
@{os.startTimer}), however it does not listen for any other events. This means
that any event that occurs while sleeping will be entirely discarded. If you
need to receive events while sleeping, consider using @{os.startTimer|timers},
or the @{parallel|parallel API}.
:::
> [!WARNING]
> Internally, this function queues and waits for a timer event (using
> [`os.startTimer`]), however it does not listen for any other events. This means
> that any event that occurs while sleeping will be entirely discarded. If you
> need to receive events while sleeping, consider using [timers][`os.startTimer`],
> or the [parallel API][`parallel`].
@tparam number time The number of seconds to sleep for, rounded up to the
nearest multiple of 0.05.
@ -116,7 +114,7 @@ function read(replaceChar, history, completeFn, default) end
--- Stores the current ComputerCraft and Minecraft versions.
--
-- Outside of Minecraft (for instance, in an emulator) @{_HOST} will contain the
-- Outside of Minecraft (for instance, in an emulator) [`_HOST`] will contain the
-- emulator's version instead.
--
-- For example, `ComputerCraft 1.93.0 (Minecraft 1.15.2)`.

20
doc/stub/os.lua
View File

@ -15,27 +15,27 @@ variables and functions exported by it will by available through the use of
@deprecated When possible it's best to avoid using this function. It pollutes
the global table and can mask errors.
@{require} should be used to load libraries instead.
[`require`] should be used to load libraries instead.
]]
function loadAPI(path) end
--- Unloads an API which was loaded by @{os.loadAPI}.
--- Unloads an API which was loaded by [`os.loadAPI`].
--
-- This effectively removes the specified table from `_G`.
--
-- @tparam string name The name of the API to unload.
-- @since 1.2
-- @deprecated See @{os.loadAPI} for why.
-- @deprecated See [`os.loadAPI`] for why.
function unloadAPI(name) end
--[[- Pause execution of the current thread and waits for any events matching
`filter`.
This function @{coroutine.yield|yields} the current process and waits for it
This function [yields][`coroutine.yield`] the current process and waits for it
to be resumed with a vararg list where the first element matches `filter`.
If no `filter` is supplied, this will match all events.
Unlike @{os.pullEventRaw}, it will stop the application upon a "terminate"
Unlike [`os.pullEventRaw`], it will stop the application upon a "terminate"
event, printing the error "Terminated".
@tparam[opt] string filter Event to filter for.
@ -69,7 +69,7 @@ function pullEvent(filter) end
--[[- Pause execution of the current thread and waits for events, including the
`terminate` event.
This behaves almost the same as @{os.pullEvent}, except it allows you to handle
This behaves almost the same as [`os.pullEvent`], except it allows you to handle
the `terminate` event yourself - the program will not stop execution when
<kbd>Ctrl+T</kbd> is pressed.
@ -89,7 +89,7 @@ the `terminate` event yourself - the program will not stop execution when
]]
function pullEventRaw(filter) end
--- Pauses execution for the specified number of seconds, alias of @{_G.sleep}.
--- Pauses execution for the specified number of seconds, alias of [`_G.sleep`].
--
-- @tparam number time The number of seconds to sleep for, rounded up to the
-- nearest multiple of 0.05.
@ -109,12 +109,12 @@ arguments.
This function does not resolve program names like the shell does. This means
that, for example, `os.run("edit")` will not work. As well as this, it does not
provide access to the @{shell} API in the environment. For this behaviour, use
@{shell.run} instead.
provide access to the [`shell`] API in the environment. For this behaviour, use
[`shell.run`] instead.
If the program cannot be found, or failed to run, it will print the error and
return `false`. If you want to handle this more gracefully, use an alternative
such as @{loadfile}.
such as [`loadfile`].
@tparam table env The environment to run the program with.
@tparam string path The exact path of the program to run.

4
gradle/libs.versions.toml
View File

@ -49,7 +49,7 @@ jqwik = "1.7.2"
junit = "5.9.2"
# Build tools
cctJavadoc = "1.7.0"
cctJavadoc = "1.8.0"
checkstyle = "10.3.4"
curseForgeGradle = "1.0.14"
errorProne-core = "2.18.0"
@ -58,7 +58,7 @@ fabric-loom = "1.3.7"
forgeGradle = "6.0.8"
githubRelease = "2.2.12"
ideaExt = "1.1.6"
illuaminate = "0.1.0-38-gfe61ad4/"
illuaminate = "0.1.0-40-g975cbc3"
librarian = "1.+"
minotaur = "2.+"
mixinGradle = "0.7.+"

3
illuaminate.sexp
View File

@ -12,7 +12,6 @@
/projects/core/src/test/resources/test-rom
/projects/web/src/mount)
(doc
; Also defined in projects/web/build.gradle.kts
(destination /projects/web/build/illuaminate)
@ -50,6 +49,8 @@
(at /
(linters
syntax:string-index
doc:docusaurus-admonition
doc:ldoc-reference
;; It'd be nice to avoid this, but right now there's a lot of instances of
;; it.

4
projects/common/src/main/java/dan200/computercraft/shared/computer/apis/CommandAPI.java
View File

@ -168,7 +168,7 @@ public final Object[] getBlockPosition() {
/**
* Get information about a range of blocks.
* <p>
* This returns the same information as @{getBlockInfo}, just for multiple
* This returns the same information as [`getBlockInfo`], just for multiple
* blocks at once.
* <p>
* Blocks are traversed by ascending y level, followed by z and x - the returned
@ -225,7 +225,7 @@ public final Object[] getBlockPosition() {
* Get some basic information about a block.
* <p>
* The returned table contains the current name, metadata and block state (as
* with @{turtle.inspect}). If there is a tile entity for that block, its NBT
* with [`turtle.inspect`]). If there is a tile entity for that block, its NBT
* will also be returned.
*
* @param x The x position of the block to query.

18
projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/ModemPeripheral.java
View File

@ -21,10 +21,9 @@
/**
* Modems allow you to send messages between computers over long distances.
* <p>
* :::tip
* Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The
* {@literal @}{rednet} API is built on top of modems, and provides a more user-friendly interface.
* :::
* > [!TIP]
* > Modems provide a fairly basic set of methods, which makes them very flexible but often hard to work with. The
* > [`rednet`] API is built on top of modems, and provides a more user-friendly interface.
* <p>
* ## Sending and receiving messages
* Modems operate on a series of channels, a bit like frequencies on a radio. Any modem can send a message on a
@ -32,11 +31,11 @@
* messages.
* <p>
* Channels are represented as an integer between 0 and 65535 inclusive. These channels don't have any defined meaning,
* though some APIs or programs will assign a meaning to them. For instance, the @{gps} module sends all its messages on
* channel 65534 (@{gps.CHANNEL_GPS}), while @{rednet} uses channels equal to the computer's ID.
* though some APIs or programs will assign a meaning to them. For instance, the [`gps`] module sends all its messages on
* channel 65534 ([`gps.CHANNEL_GPS`]), while [`rednet`] uses channels equal to the computer's ID.
* <p>
* - Sending messages is done with the {@link #transmit(int, int, Object)} message.
* - Receiving messages is done by listening to the @{modem_message} event.
* - Receiving messages is done by listening to the [`modem_message`] event.
* <p>
* ## Types of modem
* CC: Tweaked comes with three kinds of modem, with different capabilities.
@ -198,9 +197,8 @@ public final void closeAll() {
* Sends a modem message on a certain channel. Modems listening on the channel will queue a {@code modem_message}
* event on adjacent computers.
* <p>
* :::note
* The channel does not need be open to send a message.
* :::
* > [!NOTE]
* > The channel does not need be open to send a message.
*
* @param channel The channel to send messages on.
* @param replyChannel The channel that responses to this message should be sent on. This can be the same as

35
projects/common/src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemPeripheral.java
View File

@ -80,9 +80,8 @@ public Set<String> getAdditionalTypes() {
* If this computer is attached to the network, it _will not_ be included in
* this list.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @return Remote peripheral names on the network.
@ -96,9 +95,8 @@ public final Collection<String> getNamesRemote(IComputerAccess computer) {
/**
* Determine if a peripheral is available on this wired network.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@ -113,9 +111,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) {
/**
* Get the type of a peripheral is available on this wired network.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@ -133,9 +130,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) {
/**
* Check a peripheral is of a particular type.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@ -154,9 +150,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) {
/**
* Get all available methods for the remote peripheral with the given name.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param name The peripheral's name.
@ -175,9 +170,8 @@ public final boolean isPresentRemote(IComputerAccess computer, String name) {
/**
* Call a method on a peripheral on this wired network.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @param computer The calling computer.
* @param context The Lua context we're executing in.
@ -205,9 +199,8 @@ public final MethodResult callRemote(IComputerAccess computer, ILuaContext conte
* may be used by other computers on the network to wrap this computer as a
* peripheral.
* <p>
* :::note
* This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
* :::
* > [!NOTE]
* > This function only appears on wired modems. Check {@link #isWireless} returns false before calling it.
*
* @return The current computer's name.
* @cc.treturn string|nil The current computer's name on the wired network.

2
projects/common/src/main/java/dan200/computercraft/shared/peripheral/monitor/MonitorPeripheral.java
View File

@ -18,7 +18,7 @@
* Monitors are a block which act as a terminal, displaying information on one side. This allows them to be read and
* interacted with in-world without opening a GUI.
* <p>
* Monitors act as @{term.Redirect|terminal redirects} and so expose the same methods, as well as several additional
* Monitors act as [terminal redirects][`term.Redirect`] and so expose the same methods, as well as several additional
* ones, which are documented below.
* <p>
* Like computers, monitors come in both normal (no colour) and advanced (colour) varieties.

17
projects/common/src/main/java/dan200/computercraft/shared/peripheral/speaker/SpeakerPeripheral.java
View File

@ -272,16 +272,15 @@ public final boolean playSound(ILuaContext context, String name, Optional<Double
* <p>
* This accepts a list of audio samples as amplitudes between -128 and 127. These are stored in an internal buffer
* and played back at 48kHz. If this buffer is full, this function will return {@literal false}. You should wait for
* a @{speaker_audio_empty} event before trying again.
* a [`speaker_audio_empty`] event before trying again.
* <p>
* :::note
* The speaker only buffers a single call to {@link #playAudio} at once. This means if you try to play a small
* number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible
* (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or
* computer is lagging.
* :::
* > [!NOTE]
* > The speaker only buffers a single call to {@link #playAudio} at once. This means if you try to play a small
* > number of samples, you'll have a lot of stutter. You should try to play as many samples in one call as possible
* > (up to 128×1024), as this reduces the chances of audio stuttering or halting, especially when the server or
* > computer is lagging.
* <p>
* {@literal @}{speaker_audio} provides a more complete guide to using speakers
* [`speaker_audio`] provides a more complete guide to using speakers
*
* @param context The Lua context.
* @param audio The audio data to play.
@ -292,7 +291,7 @@ public final boolean playSound(ILuaContext context, String name, Optional<Double
* @cc.tparam [opt] number volume The volume to play this audio at. If not given, defaults to the previous volume
* given to {@link #playAudio}.
* @cc.since 1.100
* @cc.usage Read an audio file, decode it using @{cc.audio.dfpwm}, and play it using the speaker.
* @cc.usage Read an audio file, decode it using [`cc.audio.dfpwm`], and play it using the speaker.
*
* <pre data-peripheral="speaker">{@code
* local dfpwm = require("cc.audio.dfpwm")

42
projects/common/src/main/java/dan200/computercraft/shared/turtle/apis/TurtleAPI.java
View File

@ -23,40 +23,38 @@
* Turtles are capable of moving through the world. As turtles are blocks themselves, they are confined to Minecraft's
* grid, moving a single block at a time.
* <p>
* {@literal @}{turtle.forward} and @{turtle.back} move the turtle in the direction it is facing, while @{turtle.up} and
* {@literal @}{turtle.down} move it up and down (as one might expect!). In order to move left or right, you first need
* to turn the turtle using @{turtle.turnLeft}/@{turtle.turnRight} and then move forward or backwards.
* [`turtle.forward`] and [`turtle.back`] move the turtle in the direction it is facing, while [`turtle.up`] and
* [`turtle.down`] move it up and down (as one might expect!). In order to move left or right, you first need
* to turn the turtle using [`turtle.turnLeft`]/[`turtle.turnRight`] and then move forward or backwards.
* <p>
* :::info
* The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd move
* a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
* :::
* > [!INFO]
* > The name "turtle" comes from [Turtle graphics], which originated from the Logo programming language. Here you'd
* > move a turtle with various commands like "move 10" and "turn left", much like ComputerCraft's turtles!
* <p>
* Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any @{turtle.refuel|fuel}, it
* won't move, and the movement functions will return @{false}. If your turtle isn't going anywhere, the first thing to
* Moving a turtle (though not turning it) consumes *fuel*. If a turtle does not have any [fuel][`turtle.refuel`], it
* won't move, and the movement functions will return [`false`]. If your turtle isn't going anywhere, the first thing to
* check is if you've fuelled your turtle.
* <p>
* :::tip Handling errors
* Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a block
* there. Instead of erroring, functions which can fail either return @{true} if they succeed, or @{false} and some
* error message if they fail.
* <p>
* Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
* functions, or wrap them in @{assert} (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
* so the program doesn't misbehave.
* :::
* > [Handling errors][!TIP]
* > Many turtle functions can fail in various ways. For instance, a turtle cannot move forward if there's already a
* > block there. Instead of erroring, functions which can fail either return [`true`] if they succeed, or [`false`] and
* > some error message if they fail.
* >
* > Unexpected failures can often lead to strange behaviour. It's often a good idea to check the return values of these
* > functions, or wrap them in [`assert`] (for instance, use `assert(turtle.forward())` rather than `turtle.forward()`),
* > so the program doesn't misbehave.
* <p>
* ## Turtle upgrades
* While a normal turtle can move about the world and place blocks, its functionality is limited. Thankfully, turtles
* can be upgraded with *tools* and @{peripheral|peripherals}. Turtles have two upgrade slots, one on the left and right
* sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the @{turtle.equipLeft}/@{turtle.equipRight}
* can be upgraded with *tools* and [peripherals][`peripheral`]. Turtles have two upgrade slots, one on the left and right
* sides. Upgrades can be equipped by crafting a turtle with the upgrade, or calling the [`turtle.equipLeft`]/[`turtle.equipRight`]
* functions.
* <p>
* Turtle tools allow you to break blocks (@{turtle.dig}) and attack entities (@{turtle.attack}). Some tools are more
* Turtle tools allow you to break blocks ([`turtle.dig`]) and attack entities ([`turtle.attack`]). Some tools are more
* suitable to a task than others. For instance, a diamond pickaxe can break every block, while a sword does more
* damage. Other tools have more niche use-cases, for instance hoes can til dirt.
* <p>
* Peripherals (such as the @{modem|wireless modem} or @{speaker}) can also be equipped as upgrades. These are then
* Peripherals (such as the [wireless modem][`modem`] or [`speaker`]) can also be equipped as upgrades. These are then
* accessible by accessing the `"left"` or `"right"` peripheral.
* <p>
* [Turtle Graphics]: https://en.wikipedia.org/wiki/Turtle_graphics "Turtle graphics"

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

@ -37,10 +37,9 @@
* {@link #copy} and {@link #delete}.</li>
* </ul>
* <p>
* :::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.
* :::
* > [!NOTE]
* > All functions in the API work on absolute paths, and do not take the [current directory][`shell.dir`] into account.
* > You can use [`shell.resolve`] to convert a relative path into an absolute one.
* <p>
* ## Mounts
* While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For
@ -333,7 +332,7 @@ public final void delete(String path) throws LuaException {
*
* print(contents)
* }</pre>
* @cc.usage Open a file and read all lines into a table. @{io.lines} offers an alternative way to do this.
* @cc.usage Open a file and read all lines into a table. [`io.lines`] offers an alternative way to do this.
* <pre>{@code
* local file = fs.open("/rom/motd.txt", "r")
* local lines = {}

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

@ -146,7 +146,7 @@ public final void queueEvent(String name, IArguments args) throws LuaException {
* the timer fires, a {@code timer} event will be added to the queue with
* the ID returned from this function as the first parameter.
* <p>
* As with @{os.sleep|sleep}, {@code timer} will automatically be rounded up
* As with [sleep][`os.sleep`], {@code timer} will automatically be rounded up
* to the nearest multiple of 0.05 seconds, as it waits for a fixed amount
* of world ticks.
*
@ -353,13 +353,12 @@ public final int day(Optional<String> args) throws LuaException {
* * If called with {@code local}, returns the number of milliseconds since 1
* January 1970 in the server's local timezone.
* <p>
* :::info
* The {@code ingame} time zone assumes that one Minecraft day consists of 86,400,000
* milliseconds. Since one in-game day is much faster than a real day (20 minutes), this
* will change quicker than real time - one real second is equal to 72000 in-game
* milliseconds. If you wish to convert this value to real time, divide by 72000; to
* convert to ticks (where a day is 24000 ticks), divide by 3600.
* :::
* > [!INFO]
* > The {@code ingame} time zone assumes that one Minecraft day consists of 86,400,000
* > milliseconds. Since one in-game day is much faster than a real day (20 minutes), this
* > will change quicker than real time - one real second is equal to 72000 in-game
* > milliseconds. If you wish to convert this value to real time, divide by 72000; to
* > convert to ticks (where a day is 24000 ticks), divide by 3600.
*
* @param args The locale to get the milliseconds for. Defaults to {@code ingame} if not set.
* @return The milliseconds since the epoch depending on the selected locale.

6
projects/core/src/main/java/dan200/computercraft/core/apis/RedstoneAPI.java
View File

@ -21,9 +21,9 @@
* strength of the redstone wired, from 0 to 15.
* - Bundled cables ({@link #setBundledOutput}/{@link #getBundledInput}): These interact with "bundled" cables, such
* as those from Project:Red. These allow you to send 16 separate on/off signals. Each channel corresponds to a
* colour, with the first being @{colors.white} and the last @{colors.black}.
* colour, with the first being [`colors.white`] and the last [`colors.black`].
* <p>
* Whenever a redstone input changes, a @{event!redstone} event will be fired. This may be used instead of repeativly
* Whenever a redstone input changes, a [`event!redstone`] event will be fired. This may be used instead of repeativly
* polling.
* <p>
* This module may also be referred to as {@code rs}. For example, one may call {@code rs.getSides()} instead of
@ -192,7 +192,7 @@ public final int getBundledInput(ComputerSide side) {
* @param side The side to test.
* @param mask The mask to test.
* @return If the colours are on.
* @cc.usage Check if @{colors.white} and @{colors.black} are on above the computer.
* @cc.usage Check if [`colors.white`] and [`colors.black`] are on above the computer.
* <pre>{@code
* print(redstone.testBundledInput("top", colors.combine(colors.white, colors.black)))
* }</pre>

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

@ -267,7 +267,7 @@ public final void blit(ByteBuffer text, ByteBuffer textColour, ByteBuffer backgr
* Set the palette for a specific colour.
* <p>
* 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
* 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.
*
@ -280,7 +280,7 @@ public final void blit(ByteBuffer text, ByteBuffer textColour, ByteBuffer backgr
* @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.
* @cc.usage Change the [red colour][`colors.red`] from the default #CC4C4C to #FF0000.
* <pre>{@code
* term.setPaletteColour(colors.red, 0xFF0000)
* term.setTextColour(colors.red)

66
projects/core/src/main/resources/data/computercraft/lua/rom/apis/colors.lua
View File

@ -3,20 +3,20 @@
-- SPDX-License-Identifier: LicenseRef-CCPL
--[[- Constants and functions for colour values, suitable for working with
@{term} and @{redstone}.
[`term`] and [`redstone`].
This is useful in conjunction with @{redstone.setBundledOutput|Bundled Cables}
from mods like Project Red, and @{term.setTextColour|colors on Advanced
Computers and Advanced Monitors}.
This is useful in conjunction with [Bundled Cables][`redstone.setBundledOutput`]
from mods like Project Red, and [colors on Advanced Computers and Advanced
Monitors][`term.setTextColour`].
For the non-American English version just replace @{colors} with @{colours}.
For the non-American English version just replace [`colors`] with [`colours`].
This alternative API is exactly the same, except the colours use British English
(e.g. @{colors.gray} is spelt @{colours.grey}).
(e.g. [`colors.gray`] is spelt [`colours.grey`]).
On basic terminals (such as the Computer and Monitor), all the colors are
converted to grayscale. This means you can still use all 16 colors on the
screen, but they will appear as the nearest tint of gray. You can check if a
terminal supports color by using the function @{term.isColor}.
terminal supports color by using the function [`term.isColor`].
Grayscale colors are calculated by taking the average of the three components,
i.e. `(red + green + blue) / 3`.
@ -140,67 +140,67 @@ i.e. `(red + green + blue) / 3`.
local expect = dofile("rom/modules/main/cc/expect.lua").expect
--- White: Written as `0` in paint files and @{term.blit}, has a default
--- White: Written as `0` in paint files and [`term.blit`], has a default
-- terminal colour of #F0F0F0.
white = 0x1
--- Orange: Written as `1` in paint files and @{term.blit}, has a
--- Orange: Written as `1` in paint files and [`term.blit`], has a
-- default terminal colour of #F2B233.
orange = 0x2
--- Magenta: Written as `2` in paint files and @{term.blit}, has a
--- Magenta: Written as `2` in paint files and [`term.blit`], has a
-- default terminal colour of #E57FD8.
magenta = 0x4
--- Light blue: Written as `3` in paint files and @{term.blit}, has a
--- Light blue: Written as `3` in paint files and [`term.blit`], has a
-- default terminal colour of #99B2F2.
lightBlue = 0x8
--- Yellow: Written as `4` in paint files and @{term.blit}, has a
--- Yellow: Written as `4` in paint files and [`term.blit`], has a
-- default terminal colour of #DEDE6C.
yellow = 0x10
--- Lime: Written as `5` in paint files and @{term.blit}, has a default
--- Lime: Written as `5` in paint files and [`term.blit`], has a default
-- terminal colour of #7FCC19.
lime = 0x20
--- Pink: Written as `6` in paint files and @{term.blit}, has a default
--- Pink: Written as `6` in paint files and [`term.blit`], has a default
-- terminal colour of #F2B2CC.
pink = 0x40
--- Gray: Written as `7` in paint files and @{term.blit}, has a default
--- Gray: Written as `7` in paint files and [`term.blit`], has a default
-- terminal colour of #4C4C4C.
gray = 0x80
--- Light gray: Written as `8` in paint files and @{term.blit}, has a
--- Light gray: Written as `8` in paint files and [`term.blit`], has a
-- default terminal colour of #999999.
lightGray = 0x100
--- Cyan: Written as `9` in paint files and @{term.blit}, has a default
--- Cyan: Written as `9` in paint files and [`term.blit`], has a default
-- terminal colour of #4C99B2.
cyan = 0x200
--- Purple: Written as `a` in paint files and @{term.blit}, has a
--- Purple: Written as `a` in paint files and [`term.blit`], has a
-- default terminal colour of #B266E5.
purple = 0x400
--- Blue: Written as `b` in paint files and @{term.blit}, has a default
--- Blue: Written as `b` in paint files and [`term.blit`], has a default
-- terminal colour of #3366CC.
blue = 0x800
--- Brown: Written as `c` in paint files and @{term.blit}, has a default
--- Brown: Written as `c` in paint files and [`term.blit`], has a default
-- terminal colour of #7F664C.
brown = 0x1000
--- Green: Written as `d` in paint files and @{term.blit}, has a default
--- Green: Written as `d` in paint files and [`term.blit`], has a default
-- terminal colour of #57A64E.
green = 0x2000
--- Red: Written as `e` in paint files and @{term.blit}, has a default
--- Red: Written as `e` in paint files and [`term.blit`], has a default
-- terminal colour of #CC4C4C.
red = 0x4000
--- Black: Written as `f` in paint files and @{term.blit}, has a default
--- Black: Written as `f` in paint files and [`term.blit`], has a default
-- terminal colour of #111111.
black = 0x8000
@ -313,18 +313,18 @@ function unpackRGB(rgb)
bit32.band(rgb, 0xFF) / 255
end
--- Either calls @{colors.packRGB} or @{colors.unpackRGB}, depending on how many
--- Either calls [`colors.packRGB`] or [`colors.unpackRGB`], depending on how many
-- arguments it receives.
--
-- @tparam[1] number r The red channel, as an argument to @{colors.packRGB}.
-- @tparam[1] number g The green channel, as an argument to @{colors.packRGB}.
-- @tparam[1] number b The blue channel, as an argument to @{colors.packRGB}.
-- @tparam[2] number rgb The combined hexadecimal color, as an argument to @{colors.unpackRGB}.
-- @treturn[1] number The combined hexadecimal colour, as returned by @{colors.packRGB}.
-- @treturn[2] number The red channel, as returned by @{colors.unpackRGB}
-- @treturn[2] number The green channel, as returned by @{colors.unpackRGB}
-- @treturn[2] number The blue channel, as returned by @{colors.unpackRGB}
-- @deprecated Use @{packRGB} or @{unpackRGB} directly.
-- @tparam[1] number r The red channel, as an argument to [`colors.packRGB`].
-- @tparam[1] number g The green channel, as an argument to [`colors.packRGB`].
-- @tparam[1] number b The blue channel, as an argument to [`colors.packRGB`].
-- @tparam[2] number rgb The combined hexadecimal color, as an argument to [`colors.unpackRGB`].
-- @treturn[1] number The combined hexadecimal colour, as returned by [`colors.packRGB`].
-- @treturn[2] number The red channel, as returned by [`colors.unpackRGB`]
-- @treturn[2] number The green channel, as returned by [`colors.unpackRGB`]
-- @treturn[2] number The blue channel, as returned by [`colors.unpackRGB`]
-- @deprecated Use [`packRGB`] or [`unpackRGB`] directly.
-- @usage
-- ```lua
-- colors.rgb8(0xb23399)

6
projects/core/src/main/resources/data/computercraft/lua/rom/apis/colours.lua
View File

@ -2,7 +2,7 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
--- An alternative version of @{colors} for lovers of British spelling.
--- An alternative version of [`colors`] for lovers of British spelling.
--
-- @see colors
-- @module colours
@ -13,14 +13,14 @@ for k, v in pairs(colors) do
colours[k] = v
end
--- Grey. Written as `7` in paint files and @{term.blit}, has a default
--- Grey. Written as `7` in paint files and [`term.blit`], has a default
-- terminal colour of #4C4C4C.
--
-- @see colors.gray
colours.grey = colors.gray
colours.gray = nil --- @local
--- Light grey. Written as `8` in paint files and @{term.blit}, has a
--- Light grey. Written as `8` in paint files and [`term.blit`], has a
-- default terminal colour of #999999.
--
-- @see colors.lightGray

15
projects/core/src/main/resources/data/computercraft/lua/rom/apis/command/commands.lua
View File

@ -5,16 +5,15 @@
--[[- Execute [Minecraft commands][mc] and gather data from the results from
a command computer.
:::note
This API is only available on Command computers. It is not accessible to normal
players.
:::
> [!NOTE]
> This API is only available on Command computers. It is not accessible to normal
> players.
While one may use @{commands.exec} directly to execute a command, the
While one may use [`commands.exec`] directly to execute a command, the
commands API also provides helper methods to execute every command. For
instance, `commands.say("Hi!")` is equivalent to `commands.exec("say Hi!")`.
@{commands.async} provides a similar interface to execute asynchronous
[`commands.async`] provides a similar interface to execute asynchronous
commands. `commands.async.say("Hi!")` is equivalent to
`commands.execAsync("say Hi!")`.
@ -31,7 +30,7 @@ end
--- The builtin commands API, without any generated command helper functions
--
-- This may be useful if a built-in function (such as @{commands.list}) has been
-- This may be useful if a built-in function (such as [`commands.list`]) has been
-- overwritten by a command.
local native = commands.native or commands
@ -112,7 +111,7 @@ end
--- A table containing asynchronous wrappers for all commands.
--
-- As with @{commands.execAsync}, this returns the "task id" of the enqueued
-- As with [`commands.execAsync`], this returns the "task id" of the enqueued
-- command.
-- @see execAsync
-- @usage Asynchronously sets the block above the computer to stone.

19
projects/core/src/main/resources/data/computercraft/lua/rom/apis/disk.lua
View File

@ -9,10 +9,9 @@ locally attached drive, specify “side” as one of the six sides (e.g. `left`)
use a remote disk drive, specify its name as printed when enabling its modem
(e.g. `drive_0`).
:::tip
All computers (except command computers), turtles and pocket computers can be
placed within a disk drive to access it's internal storage like a disk.
:::
> [!TIP]
> All computers (except command computers), turtles and pocket computers can be
> placed within a disk drive to access it's internal storage like a disk.
@module disk
@since 1.2
@ -95,7 +94,7 @@ end
--- Whether the current disk is a [music disk][disk] as opposed to a floppy disk
-- or other item.
--
-- If this returns true, you will can @{disk.playAudio|play} the record.
-- If this returns true, you will can [play][`disk.playAudio`] the record.
--
-- [disk]: https://minecraft.gamepedia.com/Music_Disc
--
@ -110,10 +109,10 @@ end
--- Get the title of the audio track from the music record in the drive.
--
-- This generally returns the same as @{disk.getLabel} for records.
-- This generally returns the same as [`disk.getLabel`] for records.
--
-- @tparam string name The name of the disk drive.
-- @treturn string|false|nil The track title, @{false} if there is not a music
-- @treturn string|false|nil The track title, [`false`] if there is not a music
-- record in the drive or `nil` if no drive is present.
function getAudioTitle(name)
if isDrive(name) then
@ -126,7 +125,7 @@ end
--
-- If any record is already playing on any disk drive, it stops before the
-- target drive starts playing. The record stops when it reaches the end of the
-- track, when it is removed from the drive, when @{disk.stopAudio} is called, or
-- track, when it is removed from the drive, when [`disk.stopAudio`] is called, or
-- when another record is started.
--
-- @tparam string name The name of the disk drive.
@ -138,7 +137,7 @@ function playAudio(name)
end
--- Stops the music record in the drive from playing, if it was started with
-- @{disk.playAudio}.
-- [`disk.playAudio`].
--
-- @tparam string name The name o the disk drive.
function stopAudio(name)
@ -165,7 +164,7 @@ end
--- Returns a number which uniquely identifies the disk in the drive.
--
-- Note, unlike @{disk.getLabel}, this does not return anything for other media,
-- Note, unlike [`disk.getLabel`], this does not return anything for other media,
-- such as computers or turtles.
--
-- @tparam string name The name of the disk drive.

8
projects/core/src/main/resources/data/computercraft/lua/rom/apis/fs.lua
View File

@ -13,19 +13,19 @@ local fs = _ENV
for k, v in pairs(native) do fs[k] = v end
--[[- Provides completion for a file or directory name, suitable for use with
@{_G.read}.
[`_G.read`].
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
completion candidate). `include_dirs` can be set to [`false`] to only include
those with a trailing slash.
@tparam[1] string path The path to complete.
@tparam[1] string location The location where paths are resolved from.
@tparam[1,opt=true] boolean include_files When @{false}, only directories will
@tparam[1,opt=true] boolean include_files When [`false`], only directories will
be included in the returned list.
@tparam[1,opt=true] boolean include_dirs When @{false}, "raw" directories will
@tparam[1,opt=true] boolean include_dirs When [`false`], "raw" directories will
not be included in the returned list.
@tparam[2] string path The path to complete.

13
projects/core/src/main/resources/data/computercraft/lua/rom/apis/gps.lua
View File

@ -2,21 +2,20 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
--[[- Use @{modem|modems} to locate the position of the current turtle or
--[[- Use [modems][`modem`] to locate the position of the current turtle or
computers.
It broadcasts a PING message over @{rednet} and wait for responses. In order for
It broadcasts a PING message over [`rednet`] and wait for responses. In order for
this system to work, there must be at least 4 computers used as gps hosts which
will respond and allow trilateration. Three of these hosts should be in a plane,
and the fourth should be either above or below the other three. The three in a
plane should not be in a line with each other. You can set up hosts using the
gps program.
:::note
When entering in the coordinates for the host you need to put in the `x`, `y`,
and `z` coordinates of the block that the modem is connected to, not the modem.
All modem distances are measured from the block that the modem is placed on.
:::
> [!NOTE]
> When entering in the coordinates for the host you need to put in the `x`, `y`,
> and `z` coordinates of the block that the modem is connected to, not the modem.
> All modem distances are measured from the block that the modem is placed on.
Also note that you may choose which axes x, y, or z refers to - so long as your
systems have the same definition as any GPS servers that're in range, it works

16
projects/core/src/main/resources/data/computercraft/lua/rom/apis/http/http.lua
View File

@ -74,7 +74,7 @@ decoded.
url = string, headers? = { [string] = string },
binary? = boolean, method? = string, redirect? = boolean,
timeout? = number,
} request Options for the request. See @{http.request} for details on how
} request Options for the request. See [`http.request`] for details on how
these options behave.
@treturn Response The resulting http response, which can be read from.
@ -126,7 +126,7 @@ decoded.
url = string, body? = string, headers? = { [string] = string },
binary? = boolean, method? = string, redirect? = boolean,
timeout? = number,
} request Options for the request. See @{http.request} for details on how
} request Options for the request. See [`http.request`] for details on how
these options behave.
@treturn Response The resulting http response, which can be read from.
@ -158,7 +158,7 @@ end
--[[- Asynchronously make a HTTP request to the given url.
This returns immediately, a @{http_success} or @{http_failure} will be queued
This returns immediately, a [`http_success`] or [`http_failure`] will be queued
once the request has completed.
@tparam string url The url to request
@ -221,7 +221,7 @@ local nativeCheckURL = native.checkURL
--[[- Asynchronously determine whether a URL can be requested.
If this returns `true`, one should also listen for @{http_check} which will
If this returns `true`, one should also listen for [`http_check`] which will
container further information about whether the URL is allowed or not.
@tparam string url The URL to check.
@ -237,11 +237,11 @@ checkURLAsync = nativeCheckURL
--[[- Determine whether a URL can be requested.
If this returns `true`, one should also listen for @{http_check} which will
If this returns `true`, one should also listen for [`http_check`] which will
container further information about whether the URL is allowed or not.
@tparam string url The URL to check.
@treturn true When this url is valid and can be requested via @{http.request}.
@treturn true When this url is valid and can be requested via [`http.request`].
@treturn[2] false When this url is invalid.
@treturn string A reason why this URL is not valid (for instance, if it is
malformed, or blocked).
@ -280,7 +280,7 @@ end
--[[- Asynchronously open a websocket.
This returns immediately, a @{websocket_success} or @{websocket_failure}
This returns immediately, a [`websocket_success`] or [`websocket_failure`]
will be queued once the request has completed.
@tparam[1] string url The websocket url to connect to. This should have the
@ -290,7 +290,7 @@ of the initial websocket connection.
@tparam[2] {
url = string, headers? = { [string] = string }, timeout ?= number,
} request Options for the websocket. See @{http.websocket} for details on how
} request Options for the websocket. See [`http.websocket`] for details on how
these options behave.
@since 1.80pr1.3

22
projects/core/src/main/resources/data/computercraft/lua/rom/apis/io.lua
View File

@ -74,10 +74,10 @@ handleMetatable = {
This can be used in a for loop to iterate over all lines of a file
Once the end of the file has been reached, @{nil} will be returned. The file is
Once the end of the file has been reached, [`nil`] will be returned. The file is
*not* automatically closed.
@param ... The argument to pass to @{Handle:read} for each line.
@param ... The argument to pass to [`Handle:read`] for each line.
@treturn function():string|nil The line iterator.
@throws If the file cannot be opened for reading
@since 1.3
@ -324,14 +324,14 @@ each time it is called, returns a new line from the file.
This can be used in a for loop to iterate over all lines of a file
Once the end of the file has been reached, @{nil} will be returned. The file is
Once the end of the file has been reached, [`nil`] will be returned. The file is
automatically closed.
If no file name is given, the @{io.input|current input} will be used instead.
If no file name is given, the [current input][`io.input`] will be used instead.
In this case, the handle is not used.
@tparam[opt] string filename The name of the file to extract lines from
@param ... The argument to pass to @{Handle:read} for each line.
@param ... The argument to pass to [`Handle:read`] for each line.
@treturn function():string|nil The line iterator.
@throws If the file cannot be opened for reading
@ -362,7 +362,7 @@ function lines(filename, ...)
end
--- Open a file with the given mode, either returning a new file handle
-- or @{nil}, plus an error message.
-- or [`nil`], plus an error message.
--
-- The `mode` string can be any of the following:
-- - **"r"**: Read mode
@ -410,11 +410,11 @@ end
--- Read from the currently opened input file.
--
-- This is equivalent to `io.input():read(...)`. See @{Handle:read|the
-- documentation} there for full details.
-- This is equivalent to `io.input():read(...)`. See [the documentation][`Handle:read`]
-- there for full details.
--
-- @tparam string ... The formats to read, defaulting to a whole line.
-- @treturn (string|nil)... The data read, or @{nil} if nothing can be read.
-- @treturn (string|nil)... The data read, or [`nil`] if nothing can be read.
function read(...)
return currentInput:read(...)
end
@ -438,8 +438,8 @@ end
--- Write to the currently opened output file.
--
-- This is equivalent to `io.output():write(...)`. See @{Handle:write|the
-- documentation} there for full details.
-- This is equivalent to `io.output():write(...)`. See [the documentation][`Handle:write`]
-- there for full details.
--
-- @tparam string ... The strings to write
-- @changed 1.81.0 Multiple arguments are now allowed.

2
projects/core/src/main/resources/data/computercraft/lua/rom/apis/keys.lua
View File

@ -2,7 +2,7 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
--- Constants for all keyboard "key codes", as queued by the @{key} event.
--- Constants for all keyboard "key codes", as queued by the [`key`] event.
--
-- These values are not guaranteed to remain the same between versions. It is
-- recommended that you use the constants provided by this file, rather than

14
projects/core/src/main/resources/data/computercraft/lua/rom/apis/paintutils.lua
View File

@ -51,7 +51,7 @@ end
--
-- @tparam string image The string containing the raw-image data.
-- @treturn table The parsed image data, suitable for use with
-- @{paintutils.drawImage}.
-- [`paintutils.drawImage`].
-- @since 1.80pr1
function parseImage(image)
expect(1, image, "string")
@ -69,7 +69,7 @@ end
-- @tparam string path The file to load.
--
-- @treturn table|nil The parsed image data, suitable for use with
-- @{paintutils.drawImage}, or `nil` if the file does not exist.
-- [`paintutils.drawImage`], or `nil` if the file does not exist.
-- @usage Load an image and draw it.
--
-- local image = paintutils.loadImage("data/example.nfp")
@ -93,7 +93,7 @@ end
--
-- @tparam number xPos The x position to draw at, where 1 is the far left.
-- @tparam number yPos The y position to draw at, where 1 is the very top.
-- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
function drawPixel(xPos, yPos, colour)
expect(1, xPos, "number")
@ -115,7 +115,7 @@ end
-- @tparam number startY The starting y position of the line.
-- @tparam number endX The end x position of the line.
-- @tparam number endY The end y position of the line.
-- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
-- @usage paintutils.drawLine(2, 3, 30, 7, colors.red)
function drawLine(startX, startY, endX, endY, colour)
@ -189,7 +189,7 @@ end
-- @tparam number startY The starting y position of the line.
-- @tparam number endX The end x position of the line.
-- @tparam number endY The end y position of the line.
-- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
-- @usage paintutils.drawBox(2, 3, 30, 7, colors.red)
function drawBox(startX, startY, endX, endY, nColour)
@ -242,7 +242,7 @@ end
-- @tparam number startY The starting y position of the line.
-- @tparam number endX The end x position of the line.
-- @tparam number endY The end y position of the line.
-- @tparam[opt] number colour The @{colors|color} of this pixel. This will be
-- @tparam[opt] number colour The [color][`colors`] of this pixel. This will be
-- the current background colour if not specified.
-- @usage paintutils.drawFilledBox(2, 3, 30, 7, colors.red)
function drawFilledBox(startX, startY, endX, endY, nColour)
@ -278,7 +278,7 @@ function drawFilledBox(startX, startY, endX, endY, nColour)
end
end
--- Draw an image loaded by @{paintutils.parseImage} or @{paintutils.loadImage}.
--- Draw an image loaded by [`paintutils.parseImage`] or [`paintutils.loadImage`].
--
-- @tparam table image The parsed image data.
-- @tparam number xPos The x position to start drawing at.

44
projects/core/src/main/resources/data/computercraft/lua/rom/apis/parallel.lua
View File

@ -6,36 +6,34 @@
Functions are not actually executed simultaneously, but rather this API will
automatically switch between them whenever they yield (e.g. whenever they call
@{coroutine.yield}, or functions that call that - such as @{os.pullEvent} - or
[`coroutine.yield`], or functions that call that - such as [`os.pullEvent`] - or
functions that call that, etc - basically, anything that causes the function
to "pause").
Each function executed in "parallel" gets its own copy of the event queue,
and so "event consuming" functions (again, mostly anything that causes the
script to pause - eg @{os.sleep}, @{rednet.receive}, most of the @{turtle} API,
script to pause - eg [`os.sleep`], [`rednet.receive`], most of the [`turtle`] API,
etc) can safely be used in one without affecting the event queue accessed by
the other.
:::caution
When using this API, be careful to pass the functions you want to run in
parallel, and _not_ the result of calling those functions.
For instance, the following is correct:
```lua
local function do_sleep() sleep(1) end
parallel.waitForAny(do_sleep, rednet.receive)
```
but the following is **NOT**:
```lua
local function do_sleep() sleep(1) end
parallel.waitForAny(do_sleep(), rednet.receive)
```
:::
> [!WARNING]
> When using this API, be careful to pass the functions you want to run in
> parallel, and _not_ the result of calling those functions.
>
> For instance, the following is correct:
>
> ```lua
> local function do_sleep() sleep(1) end
> parallel.waitForAny(do_sleep, rednet.receive)
> ```
>
> but the following is **NOT**:
>
> ```lua
> local function do_sleep() sleep(1) end
> parallel.waitForAny(do_sleep(), rednet.receive)
> ```
@module parallel
@since 1.2
@ -100,7 +98,7 @@ end
--[[- Switches between execution of the functions, until any of them
finishes. If any of the functions errors, the message is propagated upwards
from the @{parallel.waitForAny} call.
from the [`parallel.waitForAny`] call.
@tparam function ... The functions this task will run
@usage Print a message every second until the `q` key is pressed.
@ -128,7 +126,7 @@ end
--[[- Switches between execution of the functions, until all of them are
finished. If any of the functions errors, the message is propagated upwards
from the @{parallel.waitForAll} call.
from the [`parallel.waitForAll`] call.
@tparam function ... The functions this task will run
@usage Start off two timers and wait for them both to run.

39
projects/core/src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua
View File

@ -5,8 +5,8 @@
--[[- Find and control peripherals attached to this computer.
Peripherals are blocks (or turtle and pocket computer upgrades) which can
be controlled by a computer. For instance, the @{speaker} peripheral allows a
computer to play music and the @{monitor} peripheral allows you to display text
be controlled by a computer. For instance, the [`speaker`] peripheral allows a
computer to play music and the [`monitor`] peripheral allows you to display text
in the world.
## Referencing peripherals
@ -18,10 +18,10 @@ computer will be called `"bottom"` in your Lua code, one to the left called
`"right"`, `"front"`, `"back"`).
You can list the names of all peripherals with the `peripherals` program, or the
@{peripheral.getNames} function.
[`peripheral.getNames`] function.
It's also possible to use peripherals which are further away from your computer
through the use of @{modem|Wired Modems}. Place one modem against your computer
through the use of [Wired Modems][`modem`]. Place one modem against your computer
(you may need to sneak and right click), run Networking Cable to your
peripheral, and then place another modem against that block. You can then right
click the modem to use (or *attach*) the peripheral. This will print a
@ -32,24 +32,23 @@ clipboard.
## Using peripherals
Once you have the name of a peripheral, you can call functions on it using the
@{peripheral.call} function. This takes the name of our peripheral, the name of
[`peripheral.call`] function. This takes the name of our peripheral, the name of
the function we want to call, and then its arguments.
:::info
Some bits of the peripheral API call peripheral functions *methods* instead
(for example, the @{peripheral.getMethods} function). Don't worry, they're the
same thing!
:::
> [!INFO]
> Some bits of the peripheral API call peripheral functions *methods* instead
> (for example, the [`peripheral.getMethods`] function). Don't worry, they're the
> same thing!
Let's say we have a monitor above our computer (and so "top") and want to
@{monitor.write|write some text to it}. We'd write the following:
[write some text to it][`monitor.write`]. We'd write the following:
```lua
peripheral.call("top", "write", "This is displayed on a monitor!")
```
Once you start calling making a couple of peripheral calls this can get very
repetitive, and so we can @{peripheral.wrap|wrap} a peripheral. This builds a
repetitive, and so we can [wrap][`peripheral.wrap`] a peripheral. This builds a
table of all the peripheral's functions so you can use it like an API or module.
For instance, we could have written the above example as follows:
@ -66,7 +65,7 @@ called, you just need to know it's there. For instance, if you're writing a
music player, you just need a speaker - it doesn't matter if it's above or below
the computer.
Thankfully there's a quick way to do this: @{peripheral.find}. This takes a
Thankfully there's a quick way to do this: [`peripheral.find`]. This takes a
*peripheral type* and returns all the attached peripherals which are of this
type.
@ -76,10 +75,10 @@ are just called `"speaker"`, and monitors `"monitor"`. Some peripherals might
have more than one type - a Minecraft chest is both a `"minecraft:chest"` and
`"inventory"`.
You can get all the types a peripheral has with @{peripheral.getType}, and check
a peripheral is a specific type with @{peripheral.hasType}.
You can get all the types a peripheral has with [`peripheral.getType`], and check
a peripheral is a specific type with [`peripheral.hasType`].
To return to our original example, let's use @{peripheral.find} to find an
To return to our original example, let's use [`peripheral.find`] to find an
attached speaker:
```lua
@ -229,7 +228,7 @@ function getMethods(name)
return nil
end
--- Get the name of a peripheral wrapped with @{peripheral.wrap}.
--- Get the name of a peripheral wrapped with [`peripheral.wrap`].
--
-- @tparam table peripheral The peripheral to get the name of.
-- @treturn string The name of the given peripheral.
@ -270,7 +269,7 @@ function call(name, method, ...)
end
--- Get a table containing all functions available on a peripheral. These can
-- then be called instead of using @{peripheral.call} every time.
-- then be called instead of using [`peripheral.call`] every time.
--
-- @tparam string name The name of the peripheral to wrap.
-- @treturn table|nil The table containing the peripheral's methods, or `nil` if
@ -305,7 +304,7 @@ function wrap(name)
end
--[[- Find all peripherals of a specific type, and return the
@{peripheral.wrap|wrapped} peripherals.
[wrapped][`peripheral.wrap`] peripherals.
@tparam string ty The type of peripheral to look for.
@tparam[opt] function(name:string, wrapped:table):boolean filter A
@ -325,7 +324,7 @@ and returns if it should be included in the result.
return modem.isWireless() -- Check this modem is wireless.
end) }
@usage This abuses the `filter` argument to call @{rednet.open} on every modem.
@usage This abuses the `filter` argument to call [`rednet.open`] on every modem.
peripheral.find("modem", rednet.open)
@since 1.6

79
projects/core/src/main/resources/data/computercraft/lua/rom/apis/rednet.lua
View File

@ -2,42 +2,41 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
--[[- Communicate with other computers by using @{modem|modems}. @{rednet}
provides a layer of abstraction on top of the main @{modem} peripheral, making
--[[- Communicate with other computers by using [modems][`modem`]. [`rednet`]
provides a layer of abstraction on top of the main [`modem`] peripheral, making
it slightly easier to use.
## Basic usage
In order to send a message between two computers, each computer must have a
modem on one of its sides (or in the case of pocket computers and turtles, the
modem must be equipped as an upgrade). The two computers should then call
@{rednet.open}, which sets up the modems ready to send and receive messages.
[`rednet.open`], which sets up the modems ready to send and receive messages.
Once rednet is opened, you can send messages using @{rednet.send} and receive
them using @{rednet.receive}. It's also possible to send a message to _every_
rednet-using computer using @{rednet.broadcast}.
Once rednet is opened, you can send messages using [`rednet.send`] and receive
them using [`rednet.receive`]. It's also possible to send a message to _every_
rednet-using computer using [`rednet.broadcast`].
:::caution Network security
While rednet provides a friendly way to send messages to specific computers, it
doesn't provide any guarantees about security. Other computers could be
listening in to your messages, or even pretending to send messages from other computers!
If you're playing on a multi-player server (or at least one where you don't
trust other players), it's worth encrypting or signing your rednet messages.
:::
> [Network security][!WARNING]
>
> While rednet provides a friendly way to send messages to specific computers, it
> doesn't provide any guarantees about security. Other computers could be
> listening in to your messages, or even pretending to send messages from other computers!
>
> If you're playing on a multi-player server (or at least one where you don't
> trust other players), it's worth encrypting or signing your rednet messages.
## Protocols and hostnames
Several rednet messages accept "protocol"s - simple string names describing what
a message is about. When sending messages using @{rednet.send} and
@{rednet.broadcast}, you can optionally specify a protocol for the message. This
same protocol can then be given to @{rednet.receive}, to ignore all messages not
a message is about. When sending messages using [`rednet.send`] and
[`rednet.broadcast`], you can optionally specify a protocol for the message. This
same protocol can then be given to [`rednet.receive`], to ignore all messages not
using this protocol.
It's also possible to look-up computers based on protocols, providing a basic
system for service discovery and [DNS]. A computer can advertise that it
supports a particular protocol with @{rednet.host}, also providing a friendly
supports a particular protocol with [`rednet.host`], also providing a friendly
"hostname". Other computers may then find all computers which support this
protocol using @{rednet.lookup}.
protocol using [`rednet.lookup`].
[DNS]: https://en.wikipedia.org/wiki/Domain_Name_System "Domain Name System"
@ -50,7 +49,7 @@ bare-bones but flexible interface.
local expect = dofile("rom/modules/main/cc/expect.lua").expect
--- The channel used by the Rednet API to @{broadcast} messages.
--- The channel used by the Rednet API to [`broadcast`] messages.
CHANNEL_BROADCAST = 65535
--- The channel used by the Rednet API to repeat messages.
@ -68,12 +67,12 @@ local function id_as_channel(id)
return (id or os.getComputerID()) % MAX_ID_CHANNELS
end
--[[- Opens a modem with the given @{peripheral} name, allowing it to send and
--[[- Opens a modem with the given [`peripheral`] name, allowing it to send and
receive messages over rednet.
This will open the modem on two channels: one which has the same
@{os.getComputerID|ID} as the computer, and another on
@{CHANNEL_BROADCAST|the broadcast channel}.
[ID][`os.getComputerID`] as the computer, and another on
[the broadcast channel][`CHANNEL_BROADCAST`].
@tparam string modem The name of the modem to open.
@throws If there is no such modem with the given name
@ -83,7 +82,7 @@ rednet messages using it.
rednet.open("back")
@usage Open rednet on all attached modems. This abuses the "filter" argument to
@{peripheral.find}.
[`peripheral.find`].
peripheral.find("modem", rednet.open)
@see rednet.close
@ -98,7 +97,7 @@ function open(modem)
peripheral.call(modem, "open", CHANNEL_BROADCAST)
end
--- Close a modem with the given @{peripheral} name, meaning it can no longer
--- Close a modem with the given [`peripheral`] name, meaning it can no longer
-- send and receive rednet messages.
--
-- @tparam[opt] string modem The side the modem exists on. If not given, all
@ -151,21 +150,21 @@ end
--[[- Allows a computer or turtle with an attached modem to send a message
intended for a sycomputer with a specific ID. At least one such modem must first
be @{rednet.open|opened} before sending is possible.
be [opened][`rednet.open`] before sending is possible.
Assuming the target was in range and also had a correctly opened modem, the
target computer may then use @{rednet.receive} to collect the message.
target computer may then use [`rednet.receive`] to collect the message.
@tparam number recipient The ID of the receiving computer.
@param message The message to send. Like with @{modem.transmit}, this can
@param message The message to send. Like with [`modem.transmit`], this can
contain any primitive type (numbers, booleans and strings) as well as
tables. Other types (like functions), as well as metatables, will not be
transmitted.
@tparam[opt] string protocol The "protocol" to send this message under. When
using @{rednet.receive} one can filter to only receive messages sent under a
using [`rednet.receive`] one can filter to only receive messages sent under a
particular protocol.
@treturn boolean If this message was successfully sent (i.e. if rednet is
currently @{rednet.open|open}). Note, this does not guarantee the message was
currently [open][`rednet.open`]). Note, this does not guarantee the message was
actually _received_.
@changed 1.6 Added protocol parameter.
@changed 1.82.0 Now returns whether the message was successfully sent.
@ -217,13 +216,13 @@ function send(recipient, message, protocol)
return sent
end
--[[- Broadcasts a string message over the predefined @{CHANNEL_BROADCAST}
--[[- Broadcasts a string message over the predefined [`CHANNEL_BROADCAST`]
channel. The message will be received by every device listening to rednet.
@param message The message to send. This should not contain coroutines or
functions, as they will be converted to @{nil}.
functions, as they will be converted to [`nil`].
@tparam[opt] string protocol The "protocol" to send this message under. When
using @{rednet.receive} one can filter to only receive messages sent under a
using [`rednet.receive`] one can filter to only receive messages sent under a
particular protocol.
@see rednet.receive
@changed 1.6 Added protocol parameter.
@ -311,7 +310,7 @@ function receive(protocol_filter, timeout)
end
--[[- Register the system as "hosting" the desired protocol under the specified
name. If a rednet @{rednet.lookup|lookup} is performed for that protocol (and
name. If a rednet [lookup][`rednet.lookup`] is performed for that protocol (and
maybe name) on the same network, the registered system will automatically
respond via a background process, hence providing the system performing the
lookup with its ID number.
@ -343,8 +342,8 @@ function host(protocol, hostname)
end
end
--- Stop @{rednet.host|hosting} a specific protocol, meaning it will no longer
-- respond to @{rednet.lookup} requests.
--- Stop [hosting][`rednet.host`] a specific protocol, meaning it will no longer
-- respond to [`rednet.lookup`] requests.
--
-- @tparam string protocol The protocol to unregister your self from.
-- @since 1.6
@ -353,7 +352,7 @@ function unhost(protocol)
hostnames[protocol] = nil
end
--[[- Search the local rednet network for systems @{rednet.host|hosting} the
--[[- Search the local rednet network for systems [hosting][`rednet.host`] the
desired protocol and returns any computer IDs that respond as "registered"
against it.
@ -365,7 +364,7 @@ match is found).
@treturn[1] number... A list of computer IDs hosting the given protocol.
@treturn[2] number|nil The computer ID with the provided hostname and protocol,
or @{nil} if none exists.
or [`nil`] if none exists.
@since 1.6
@usage Find all computers which are hosting the `"chat"` protocol.
@ -450,7 +449,7 @@ end
local started = false
--- Listen for modem messages and converts them into rednet messages, which may
-- then be @{receive|received}.
-- then be [received][`receive`].
--
-- This is automatically started in the background on computer startup, and
-- should not be called manually.

36
projects/core/src/main/resources/data/computercraft/lua/rom/apis/settings.lua
View File

@ -5,13 +5,12 @@
--[[- Read and write configuration options for CraftOS and your programs.
When a computer starts, it reads the current value of settings from the
`/.settings` file. These values then may be @{settings.get|read} or
@{settings.set|modified}.
`/.settings` file. These values then may be [read][`settings.get`] or
[modified][`settings.set`].
:::caution
Calling @{settings.set} does _not_ update the settings file by default. You
_must_ call @{settings.save} to persist values.
:::
> [!WARNING]
> Calling [`settings.set`] does _not_ update the settings file by default. You
> _must_ call [`settings.save`] to persist values.
@module settings
@since 1.78
@ -59,9 +58,9 @@ for _, v in ipairs(valid_types) do valid_types[v] = true end
-- Options for this setting. This table accepts the following fields:
--
-- - `description`: A description which may be printed when running the `set` program.
-- - `default`: A default value, which is returned by @{settings.get} if the
-- - `default`: A default value, which is returned by [`settings.get`] if the
-- setting has not been changed.
-- - `type`: Require values to be of this type. @{set|Setting} the value to another type
-- - `type`: Require values to be of this type. [Setting][`set`] the value to another type
-- will error.
-- @since 1.87.0
function define(name, options)
@ -85,9 +84,9 @@ function define(name, options)
details[name] = options
end
--- Remove a @{define|definition} of a setting.
--- Remove a [definition][`define`] of a setting.
--
-- If a setting has been changed, this does not remove its value. Use @{settings.unset}
-- If a setting has been changed, this does not remove its value. Use [`settings.unset`]
-- for that.
--
-- @tparam string name The name of this option
@ -113,14 +112,13 @@ end
--[[- Set the value of a setting.
:::caution
Calling @{settings.set} does _not_ update the settings file by default. You
_must_ call @{settings.save} to persist values.
:::
> [!WARNING]
> Calling [`settings.set`] does _not_ update the settings file by default. You
> _must_ call [`settings.save`] to persist values.
@tparam string name The name of the setting to set
@param value The setting's value. This cannot be `nil`, and must be
serialisable by @{textutils.serialize}.
serialisable by [`textutils.serialize`].
@throws If this value cannot be serialised
@see settings.unset
]]
@ -159,7 +157,7 @@ end
--
-- @tparam string name The name of the setting to get.
-- @treturn { description? = string, default? = any, type? = string, value? = any }
-- Information about this setting. This includes all information from @{settings.define},
-- Information about this setting. This includes all information from [`settings.define`],
-- as well as this setting's value.
-- @since 1.87.0
function getDetails(name)
@ -173,8 +171,8 @@ end
--- Remove the value of a setting, setting it to the default.
--
-- @{settings.get} will return the default value until the setting's value is
-- @{settings.set|set}, or the computer is rebooted.
-- [`settings.get`] will return the default value until the setting's value is
-- [set][`settings.set`], or the computer is rebooted.
--
-- @tparam string name The name of the setting to unset.
-- @see settings.set
@ -184,7 +182,7 @@ function unset(name)
set_value(name, nil)
end
--- Resets the value of all settings. Equivalent to calling @{settings.unset}
--- Resets the value of all settings. Equivalent to calling [`settings.unset`]
--- on every setting.
--
-- @see settings.unset

12
projects/core/src/main/resources/data/computercraft/lua/rom/apis/term.lua
View File

@ -17,9 +17,9 @@ end
local term = _ENV
--- Redirects terminal output to a monitor, a @{window}, or any other custom
--- Redirects terminal output to a monitor, a [`window`], or any other custom
-- terminal object. Once the redirect is performed, any calls to a "term"
-- function - or to a function that makes use of a term function, as @{print} -
-- function - or to a function that makes use of a term function, as [`print`] -
-- will instead operate with the new terminal object.
--
-- A "terminal object" is simply a table that contains functions with the same
@ -29,9 +29,9 @@ local term = _ENV
-- The redirect can be undone by pointing back to the previous terminal object
-- (which this function returns whenever you switch).
--
-- @tparam Redirect target The terminal redirect the @{term} API will draw to.
-- @tparam Redirect target The terminal redirect the [`term`] API will draw to.
-- @treturn Redirect The previous redirect object, as returned by
-- @{term.current}.
-- [`term.current`].
-- @since 1.31
-- @usage
-- Redirect to a monitor on the right of the computer.
@ -60,7 +60,7 @@ end
-- @treturn Redirect The current terminal redirect
-- @since 1.6
-- @usage
-- Create a new @{window} which draws to the current redirect target.
-- Create a new [`window`] which draws to the current redirect target.
--
-- window.create(term.current(), 1, 1, 10, 10)
term.current = function()
@ -70,7 +70,7 @@ end
--- Get the native terminal object of the current computer.
--
-- It is recommended you do not use this function unless you absolutely have
-- to. In a multitasked environment, @{term.native} will _not_ be the current
-- to. In a multitasked environment, [`term.native`] will _not_ be the current
-- terminal object, and so drawing may interfere with other programs.
--
-- @treturn Redirect The native terminal redirect.

34
projects/core/src/main/resources/data/computercraft/lua/rom/apis/textutils.lua
View File

@ -14,7 +14,7 @@ local wrap = dofile("rom/modules/main/cc/strings.lua").wrap
--- Slowly writes string text at current cursor position,
-- character-by-character.
--
-- Like @{_G.write}, this does not insert a newline at the end.
-- Like [`_G.write`], this does not insert a newline at the end.
--
-- @tparam string text The the text to write to the screen
-- @tparam[opt] number rate The number of characters to write each second,
@ -42,7 +42,7 @@ end
--- Slowly prints string text at current cursor position,
-- character-by-character.
--
-- Like @{print}, this inserts a newline after printing.
-- Like [`print`], this inserts a newline after printing.
--
-- @tparam string sText The the text to write to the screen
-- @tparam[opt] number nRate The number of characters to write each second,
@ -56,7 +56,7 @@ end
--- Takes input time and formats it in a more readable format such as `6:30 PM`.
--
-- @tparam number nTime The time to format, as provided by @{os.time}.
-- @tparam number nTime The time to format, as provided by [`os.time`].
-- @tparam[opt] boolean bTwentyFourHour Whether to format this as a 24-hour
-- clock (`18:30`) rather than a 12-hour one (`6:30 AM`)
-- @treturn string The formatted time
@ -114,7 +114,7 @@ end
--[[- Prints a given string to the display.
If the action can be completed without scrolling, it acts much the same as
@{print}; otherwise, it will throw up a "Press any key to continue" prompt at
[`print`]; otherwise, it will throw up a "Press any key to continue" prompt at
the bottom of the display. Each press will cause it to scroll down and write a
single line more before prompting again, if need be.
@ -253,7 +253,7 @@ end
--[[- Prints tables in a structured form, stopping and prompting for input should
the result not fit on the terminal.
This functions identically to @{textutils.tabulate}, but will prompt for user
This functions identically to [`textutils.tabulate`], but will prompt for user
input should the whole output not fit on the display.
@tparam {string...}|number ... The rows and text colors to display.
@ -702,13 +702,13 @@ do
--[[- Converts a serialised JSON string back into a reassembled Lua object.
This may be used with @{textutils.serializeJSON}, or when communicating
This may be used with [`textutils.serializeJSON`], or when communicating
with command blocks or web APIs.
If a `null` value is encountered, it is converted into `nil`. It can be converted
into @{textutils.json_null} with the `parse_null` option.
into [`textutils.json_null`] with the `parse_null` option.
If an empty array is encountered, it is converted into @{textutils.empty_json_array}.
If an empty array is encountered, it is converted into [`textutils.empty_json_array`].
It can be converted into a new empty table with the `parse_empty_array` option.
@tparam string s The serialised string to deserialise.
@ -717,10 +717,10 @@ do
- `nbt_style`: When true, this will accept [stringified NBT][nbt] strings,
as produced by many commands.
- `parse_null`: When true, `null` will be parsed as @{json_null}, rather than
- `parse_null`: When true, `null` will be parsed as [`json_null`], rather than
`nil`.
- `parse_empty_array`: When false, empty arrays will be parsed as a new table.
By default (or when this value is true), they are parsed as @{empty_json_array}.
By default (or when this value is true), they are parsed as [`empty_json_array`].
[nbt]: https://minecraft.gamepedia.com/NBT_format
@return[1] The deserialised object
@ -734,7 +734,7 @@ do
textutils.unserialiseJSON('{"name": "Steve", "age": null}')
@usage Unserialise a basic JSON object, returning null values as @{json_null}.
@usage Unserialise a basic JSON object, returning null values as [`json_null`].
textutils.unserialiseJSON('{"name": "Steve", "age": null}', { parse_null = true })
]]
@ -813,7 +813,7 @@ serialise = serialize -- GB version
--- Converts a serialised string back into a reassembled Lua object.
--
-- This is mainly used together with @{textutils.serialise}.
-- This is mainly used together with [`textutils.serialise`].
--
-- @tparam string s The serialised string to deserialise.
-- @return[1] The deserialised object
@ -837,19 +837,19 @@ unserialise = unserialize -- GB version
This function attempts to guess whether a table is a JSON array or
object. However, empty tables are assumed to be empty objects - use
@{textutils.empty_json_array} to mark an empty array.
[`textutils.empty_json_array`] to mark an empty array.
This is largely intended for interacting with various functions from the
@{commands} API, though may also be used in making @{http} requests.
[`commands`] API, though may also be used in making [`http`] requests.
@param[1] t The value to serialise. Like @{textutils.serialise}, this should not
@param[1] t The value to serialise. Like [`textutils.serialise`], this should not
contain recursive tables or functions.
@tparam[1,opt] { nbt_style? = boolean, unicode_strings? = boolean } options Options for serialisation.
- `nbt_style`: Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON.
- `unicode_strings`: Whether to treat strings as containing UTF-8 characters instead of
using the default 8-bit character set.
@param[2] t The value to serialise. Like @{textutils.serialise}, this should not
@param[2] t The value to serialise. Like [`textutils.serialise`], this should not
contain recursive tables or functions.
@tparam[2] boolean bNBTStyle Whether to produce NBT-style JSON (non-quoted keys)
instead of standard JSON.
@ -929,7 +929,7 @@ local tEmpty = {}
-- variable name or table index.
--
-- @tparam[opt] table tSearchTable The table to find variables in, defaulting to
-- the global environment (@{_G}). The function also searches the "parent"
-- the global environment ([`_G`]). The function also searches the "parent"
-- environment via the `__index` metatable field.
--
-- @treturn { string... } The (possibly empty) list of completions.

4
projects/core/src/main/resources/data/computercraft/lua/rom/apis/vector.lua
View File

@ -4,7 +4,7 @@
--- A basic 3D vector type and some common vector operations. This may be useful
-- when working with coordinates in Minecraft's world (such as those from the
-- @{gps} API).
-- [`gps`] API).
--
-- An introduction to vectors can be found on [Wikipedia][wiki].
--
@ -180,7 +180,7 @@ local vmetatable = {
__eq = vector.equals,
}
--- Construct a new @{Vector} with the given coordinates.
--- Construct a new [`Vector`] with the given coordinates.
--
-- @tparam number x The X coordinate or direction of the vector.
-- @tparam number y The Y coordinate or direction of the vector.

16
projects/core/src/main/resources/data/computercraft/lua/rom/apis/window.lua
View File

@ -2,10 +2,10 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
--[[- A @{term.Redirect|terminal redirect} occupying a smaller area of an
--[[- A [terminal redirect][`term.Redirect`] occupying a smaller area of an
existing terminal. This allows for easy definition of spaces within the display
that can be written/drawn to, then later redrawn/repositioned/etc as need
be. The API itself contains only one function, @{window.create}, which returns
be. The API itself contains only one function, [`window.create`], which returns
the windows themselves.
Windows are considered terminal objects - as such, they have access to nearly
@ -60,11 +60,11 @@ local string_sub = string.sub
--[[- Returns a terminal object that is a space within the specified parent
terminal object. This can then be used (or even redirected to) in the same
manner as eg a wrapped monitor. Refer to @{term|the term API} for a list of
manner as eg a wrapped monitor. Refer to [the term API][`term`] for a list of
functions available to it.
@{term} itself may not be passed as the parent, though @{term.native} is
acceptable. Generally, @{term.current} or a wrapped monitor will be most
[`term`] itself may not be passed as the parent, though [`term.native`] is
acceptable. Generally, [`term.current`] or a wrapped monitor will be most
suitable, though windows may even have other windows assigned as their
parents.
@ -247,7 +247,7 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
end
end
--- The window object. Refer to the @{window|module's documentation} for
--- The window object. Refer to the [module's documentation][`window`] for
-- a full description.
--
-- @type Window
@ -454,8 +454,8 @@ function create(parent, nX, nY, nWidth, nHeight, bStartVisible)
--
-- @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}.
-- @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 not between 1 and this window's height.
-- @since 1.84.0
function window.getLine(y)

24
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/audio/dfpwm.lua
View File

@ -9,11 +9,11 @@ DFPWM (Dynamic Filter Pulse Width Modulation) is an audio codec designed by Grea
format compared to raw PCM data, only using 1 bit per sample, but is simple enough to simple enough to encode and decode
in real time.
Typically DFPWM audio is read from @{fs.BinaryReadHandle|the filesystem} or a @{http.Response|a web request} as a
string, and converted a format suitable for @{speaker.playAudio}.
Typically DFPWM audio is read from [the filesystem][`fs.BinaryReadHandle`] or a [a web request][`http.Response`] as a
string, and converted a format suitable for [`speaker.playAudio`].
## Encoding and decoding files
This modules exposes two key functions, @{make_decoder} and @{make_encoder}, which construct a new decoder or encoder.
This modules exposes two key functions, [`make_decoder`] and [`make_encoder`], which construct a new decoder or encoder.
The returned encoder/decoder is itself a function, which converts between the two kinds of data.
These encoders and decoders have lots of hidden state, so you should be careful to use the same encoder or decoder for
@ -95,10 +95,9 @@ end
The returned encoder is itself a function. This function accepts a table of amplitude data between -128 and 127 and
returns the encoded DFPWM data.
:::caution Reusing encoders
Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple
streams, or use different encoders for the same stream, the resulting audio may not sound correct.
:::
> [Reusing encoders][!WARNING]
> Encoders have lots of internal state which tracks the state of the current stream. If you reuse an encoder for multiple
> streams, or use different encoders for the same stream, the resulting audio may not sound correct.
@treturn function(pcm: { number... }):string The encoder function
@see encode A helper function for encoding an entire file of audio at once.
@ -138,10 +137,9 @@ end
The returned decoder is itself a function. This function accepts a string and returns a table of amplitudes, each value
between -128 and 127.
:::caution Reusing decoders
Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for multiple
streams, or use different decoders for the same stream, the resulting audio may not sound correct.
:::
> [Reusing decoders][!WARNING]
> Decoders have lots of internal state which tracks the state of the current stream. If you reuse an decoder for
> multiple streams, or use different decoders for the same stream, the resulting audio may not sound correct.
@treturn function(dfpwm: string):{ number... } The encoder function
@see decode A helper function for decoding an entire file of audio at once.
@ -200,7 +198,7 @@ end
--[[- A convenience function for decoding a complete file of audio at once.
This should only be used for short files. For larger files, one should read the file in chunks and process it using
@{make_decoder}.
[`make_decoder`].
@tparam string input The DFPWM data to convert.
@treturn { number... } The produced amplitude data.
@ -214,7 +212,7 @@ end
--[[- A convenience function for encoding a complete file of audio at once.
This should only be used for complete pieces of audio. If you are writing writing multiple chunks to the same place,
you should use an encoder returned by @{make_encoder} instead.
you should use an encoder returned by [`make_encoder`] instead.
@tparam { number... } input The table of amplitude data.
@treturn string The encoded DFPWM data.

10
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/completion.lua
View File

@ -3,11 +3,11 @@
-- SPDX-License-Identifier: LicenseRef-CCPL
--- A collection of helper methods for working with input completion, such
-- as that require by @{_G.read}.
-- as that require by [`_G.read`].
--
-- @module cc.completion
-- @see cc.shell.completion For additional helpers to use with
-- @{shell.setCompletionFunction}.
-- [`shell.setCompletionFunction`].
-- @since 1.85.0
local expect = require "cc.expect".expect
@ -34,7 +34,7 @@ end
-- @tparam { string... } choices The list of choices to complete from.
-- @tparam[opt] boolean add_space Whether to add a space after the completed item.
-- @treturn { string... } A list of suffixes of matching strings.
-- @usage Call @{_G.read}, completing the names of various animals.
-- @usage Call [`_G.read`], completing the names of various animals.
--
-- local completion = require "cc.completion"
-- local animals = { "dog", "cat", "lion", "unicorn" }
@ -76,7 +76,7 @@ local function side(text, add_space)
return choice_impl(text, sides, add_space)
end
--- Complete a @{settings|setting}.
--- Complete a [setting][`settings`].
--
-- @tparam string text The input string to complete.
-- @tparam[opt] boolean add_space Whether to add a space after the completed settings.
@ -92,7 +92,7 @@ end
local command_list
--- Complete the name of a Minecraft @{commands|command}.
--- Complete the name of a Minecraft [command][`commands`].
--
-- @tparam string text The input string to complete.
-- @tparam[opt] boolean add_space Whether to add a space after the completed command.

2
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/expect.lua
View File

@ -2,7 +2,7 @@
--
-- SPDX-License-Identifier: MPL-2.0
--[[- The @{cc.expect} library provides helper functions for verifying that
--[[- The [`cc.expect`] library provides helper functions for verifying that
function arguments are well-formed and of the correct type.
@module cc.expect

4
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/image/nft.lua
View File

@ -5,7 +5,7 @@
--- Read and draw nft ("Nitrogen Fingers Text") images.
--
-- nft ("Nitrogen Fingers Text") is a file format for drawing basic images.
-- Unlike the images that @{paintutils.parseImage} uses, nft supports coloured
-- Unlike the images that [`paintutils.parseImage`] uses, nft supports coloured
-- text as well as simple coloured pixels.
--
-- @module cc.image.nft
@ -87,7 +87,7 @@ end
--- Draw an nft image to the screen.
--
-- @tparam table image An image, as returned from @{load} or @{parse}.
-- @tparam table image An image, as returned from [`load`] or [`parse`].
-- @tparam number xPos The x position to start drawing at.
-- @tparam number xPos The y position to start drawing at.
-- @tparam[opt] term.Redirect target The terminal redirect to draw to. Defaults to the

9
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/error_printer.lua
View File

@ -4,10 +4,9 @@
--[[- A pretty-printer for Lua errors.
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
This consumes a list of messages and "annotations" and displays the error to the
terminal.
@ -100,7 +99,7 @@ local code_accent = pretty.text("\x95", colours.cyan)
over the underlying source, exposing the following functions:
- `get_pos`: Get the line and column of an opaque position.
- `get_line`: Get the source code for an opaque position.
@tparam table message The message to display, as produced by @{cc.internal.syntax.errors}.
@tparam table message The message to display, as produced by [`cc.internal.syntax.errors`].
]]
return function(context, message)
expect(1, context, "table")

7
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/exception.lua
View File

@ -4,10 +4,9 @@
--[[- Internal tools for working with errors.
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
@local
]]

9
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/import.lua
View File

@ -2,12 +2,11 @@
--
-- SPDX-License-Identifier: MPL-2.0
--[[- Upload a list of files, as received by the @{event!file_transfer} event.
--[[- Upload a list of files, as received by the [`event!file_transfer`] event.
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
@local
]]

13
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/errors.lua
View File

@ -4,14 +4,13 @@
--[[- The error messages reported by our lexer and parser.
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
This provides a list of factory methods which take source positions and produce
appropriate error messages targeting that location. These error messages can
then be displayed to the user via @{cc.internal.error_printer}.
then be displayed to the user via [`cc.internal.error_printer`].
@local
]]
@ -121,7 +120,7 @@ function errors.unfinished_string(start_pos, end_pos, quote)
end
--[[- A string which ends with an escape sequence (so a literal `"foo\`). This
is slightly different from @{unfinished_string}, as we don't want to suggest
is slightly different from [`unfinished_string`], as we don't want to suggest
adding a quote.
@tparam number start_pos The start position of the string.
@ -467,7 +466,7 @@ function errors.standalone_name(pos)
}
end
--[[- A statement of the form `x.y`. This is similar to @{standalone_name}, but
--[[- A statement of the form `x.y`. This is similar to [`standalone_name`], but
when the next token is on another line.
@tparam number pos The position right after this name.

7
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/init.lua
View File

@ -4,10 +4,9 @@
--[[- The main entrypoint to our Lua parser
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
@local
]]

15
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/lexer.lua
View File

@ -4,17 +4,16 @@
--[[- A lexer for Lua source code.
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
This module provides utilities for lexing Lua code, returning tokens compatible
with @{cc.internal.syntax.parser}. While all lexers are roughly the same, there
with [`cc.internal.syntax.parser`]. While all lexers are roughly the same, there
are some design choices worth drawing attention to:
- The lexer uses Lua patterns (i.e. @{string.find}) as much as possible,
trying to avoid @{string.sub} loops except when needed. This allows us to
- The lexer uses Lua patterns (i.e. [`string.find`]) as much as possible,
trying to avoid [`string.sub`] loops except when needed. This allows us to
move string processing to native code, which ends up being much faster.
- We try to avoid allocating where possible. There are some cases we need to
@ -178,7 +177,7 @@ end
-- @tparam number start The start position, after the input boundary.
-- @tparam number len The expected length of the boundary. Equal to 1 + the
-- number of `=`.
-- @treturn number|nil The end position, or @{nil} if this is not terminated.
-- @treturn number|nil The end position, or [`nil`] if this is not terminated.
local function lex_long_str(context, str, start, len)
local pos = start
while true do

7
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/internal/syntax/parser.lua
View File

@ -4,10 +4,9 @@
--[[- A parser for Lua programs and expressions.
:::warning
This is an internal module and SHOULD NOT be used in your own code. It may
be removed or changed at any time.
:::
> [!DANGER]
> This is an internal module and SHOULD NOT be used in your own code. It may
> be removed or changed at any time.
Most of the code in this module is automatically generated from the Lua grammar,
hence being mostly unreadable!

18
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/pretty.lua
View File

@ -5,12 +5,12 @@
--[[- A pretty printer for rendering data structures in an aesthetically
pleasing manner.
In order to display something using @{cc.pretty}, you build up a series of
@{Doc|documents}. These behave a little bit like strings; you can concatenate
In order to display something using [`cc.pretty`], you build up a series of
[documents][`Doc`]. These behave a little bit like strings; you can concatenate
them together and then print them to the screen.
However, documents also allow you to control how they should be printed. There
are several functions (such as @{nest} and @{group}) which allow you to control
are several functions (such as [`nest`] and [`group`]) which allow you to control
the "layout" of the document. When you come to display the document, the 'best'
(most compact) layout is used.
@ -37,7 +37,7 @@ local expect, field = expect.expect, expect.field
local type, getmetatable, setmetatable, colours, str_write, tostring = type, getmetatable, setmetatable, colours, write, tostring
local debug_info, debug_local = debug.getinfo, debug.getlocal
--- @{table.insert} alternative, but with the length stored inline.
--- [`table.insert`] alternative, but with the length stored inline.
local function append(out, value)
local n = out.n + 1
out[n], out.n = value, n
@ -59,10 +59,10 @@ local empty = mk_doc({ tag = "nil" })
--- A document with a single space in it.
local space = mk_doc({ tag = "text", text = " " })
--- A line break. When collapsed with @{group}, this will be replaced with @{empty}.
--- A line break. When collapsed with [`group`], this will be replaced with [`empty`].
local line = mk_doc({ tag = "line", flat = empty })
--- A line break. When collapsed with @{group}, this will be replaced with @{space}.
--- A line break. When collapsed with [`group`], this will be replaced with [`space`].
local space_line = mk_doc({ tag = "line", flat = space })
local text_cache = { [""] = empty, [" "] = space, ["\n"] = space_line }
@ -73,7 +73,7 @@ end
--- Create a new document from a string.
--
-- If your string contains multiple lines, @{group} will flatten the string
-- If your string contains multiple lines, [`group`] will flatten the string
-- into a single line, with spaces between each line.
--
-- @tparam string text The string to construct a new document with.
@ -453,7 +453,7 @@ end
--- Pretty-print an arbitrary object, converting it into a document.
--
-- This can then be rendered with @{write} or @{print}.
-- This can then be rendered with [`write`] or [`print`].
--
-- @param obj The object to pretty-print.
-- @tparam[opt] { function_args = boolean, function_source = boolean } options
@ -479,7 +479,7 @@ local function pretty(obj, options)
return pretty_impl(obj, actual_options, {})
end
--[[- A shortcut for calling @{pretty} and @{print} together.
--[[- A shortcut for calling [`pretty`] and [`print`] together.
@param obj The object to pretty-print.
@tparam[opt] { function_args = boolean, function_source = boolean } options

12
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/require.lua
View File

@ -2,8 +2,8 @@
--
-- SPDX-License-Identifier: LicenseRef-CCPL
--[[- A pure Lua implementation of the builtin @{require} function and
@{package} library.
--[[- A pure Lua implementation of the builtin [`require`] function and
[`package`] library.
Generally you do not need to use this module - it is injected into the every
program's environment. However, it may be useful when building a custom shell or
@ -11,7 +11,7 @@ when running programs yourself.
@module cc.require
@since 1.88.0
@see using_require For an introduction on how to use @{require}.
@see using_require For an introduction on how to use [`require`].
@usage Construct the package and require function, and insert them into a
custom environment.
@ -110,13 +110,13 @@ local function make_require(package)
end
end
--- Build an implementation of Lua's @{package} library, and a @{require}
--- Build an implementation of Lua's [`package`] library, and a [`require`]
-- function to load modules within it.
--
-- @tparam table env The environment to load packages into.
-- @tparam string dir The directory that relative packages are loaded from.
-- @treturn function The new @{require} function.
-- @treturn table The new @{package} library.
-- @treturn function The new [`require`] function.
-- @treturn table The new [`package`] library.
local function make_package(env, dir)
expect(1, env, "table")
expect(2, dir, "string")

26
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/shell/completion.lua
View File

@ -4,16 +4,16 @@
--[[- A collection of helper methods for working with shell completion.
Most programs may be completed using the @{build} helper method, rather than
Most programs may be completed using the [`build`] helper method, rather than
manually switching on the argument index.
Note, the helper functions within this module do not accept an argument index,
and so are not directly usable with the @{shell.setCompletionFunction}. Instead,
wrap them using @{build}, or your own custom function.
and so are not directly usable with the [`shell.setCompletionFunction`]. Instead,
wrap them using [`build`], or your own custom function.
@module cc.shell.completion
@since 1.85.0
@see cc.completion For more general helpers, suitable for use with @{_G.read}.
@see cc.completion For more general helpers, suitable for use with [`_G.read`].
@see shell.setCompletionFunction
@usage Register a completion handler for example.lua which prompts for a
@ -135,15 +135,15 @@ end
--[[- A helper function for building shell completion arguments.
This accepts a series of single-argument completion functions, and combines
them into a function suitable for use with @{shell.setCompletionFunction}.
them into a function suitable for use with [`shell.setCompletionFunction`].
@tparam nil|table|function ... Every argument to @{build} represents an argument
@tparam nil|table|function ... Every argument to [`build`] represents an argument
to the program you wish to complete. Each argument can be one of three types:
- `nil`: This argument will not be completed.
- A function: This argument will be completed with the given function. It is
called with the @{shell} object, the string to complete and the arguments
called with the [`shell`] object, the string to complete and the arguments
before this one.
- A table: This acts as a more powerful version of the function case. The table
@ -197,12 +197,12 @@ return {
programWithArgs = programWithArgs,
-- Re-export various other functions
help = wrap(help.completeTopic), --- Wraps @{help.completeTopic} as a @{build} compatible function.
choice = wrap(completion.choice), --- Wraps @{cc.completion.choice} as a @{build} compatible function.
peripheral = wrap(completion.peripheral), --- Wraps @{cc.completion.peripheral} as a @{build} compatible function.
side = wrap(completion.side), --- Wraps @{cc.completion.side} as a @{build} compatible function.
setting = wrap(completion.setting), --- Wraps @{cc.completion.setting} as a @{build} compatible function.
command = wrap(completion.command), --- Wraps @{cc.completion.command} as a @{build} compatible function.
help = wrap(help.completeTopic), --- Wraps [`help.completeTopic`] as a [`build`] compatible function.
choice = wrap(completion.choice), --- Wraps [`cc.completion.choice`] as a [`build`] compatible function.
peripheral = wrap(completion.peripheral), --- Wraps [`cc.completion.peripheral`] as a [`build`] compatible function.
side = wrap(completion.side), --- Wraps [`cc.completion.side`] as a [`build`] compatible function.
setting = wrap(completion.setting), --- Wraps [`cc.completion.setting`] as a [`build`] compatible function.
command = wrap(completion.command), --- Wraps [`cc.completion.command`] as a [`build`] compatible function.
build = build,
}

2
projects/core/src/main/resources/data/computercraft/lua/rom/modules/main/cc/strings.lua
View File

@ -13,7 +13,7 @@ local expect = (require and require("cc.expect") or dofile("rom/modules/main/cc/
--[[- Wraps a block of text, so that each line fits within the given width.
This may be useful if you want to wrap text before displaying it to a
@{monitor} or @{printer} without using @{_G.print|print}.
[`monitor`] or [`printer`] without using [print][`_G.print`].
@tparam string text The string to wrap.
@tparam[opt] number width The width to constrain to, defaults to the width of

16
projects/core/src/main/resources/data/computercraft/lua/rom/programs/advanced/multishell.lua
View File

@ -6,17 +6,17 @@
--
-- When multiple programs are running, it displays a tab bar at the top of the
-- screen, which allows you to switch between programs. New programs can be
-- launched using the `fg` or `bg` programs, or using the @{shell.openTab} and
-- @{multishell.launch} functions.
-- launched using the `fg` or `bg` programs, or using the [`shell.openTab`] and
-- [`multishell.launch`] functions.
--
-- Each process is identified by its ID, which corresponds to its position in
-- the tab list. As tabs may be opened and closed, this ID is _not_ constant
-- over a program's run. As such, be careful not to use stale IDs.
--
-- As with @{shell}, @{multishell} is not a "true" API. Instead, it is a
-- As with [`shell`], [`multishell`] is not a "true" API. Instead, it is a
-- standard program, which launches a shell and injects its API into the shell's
-- environment. This API is not available in the global environment, and so is
-- not available to @{os.loadAPI|APIs}.
-- not available to [APIs][`os.loadAPI`].
--
-- @module[module] multishell
-- @since 1.6
@ -222,7 +222,7 @@ local multishell = {} --- @export
--- Get the currently visible process. This will be the one selected on
-- the tab bar.
--
-- Note, this is different to @{getCurrent}, which returns the process which is
-- Note, this is different to [`getCurrent`], which returns the process which is
-- currently executing.
--
-- @treturn number The currently visible process's index.
@ -235,7 +235,7 @@ end
--
-- @tparam number n The process index to switch to.
-- @treturn boolean If the process was changed successfully. This will
-- return @{false} if there is no process with this id.
-- return [`false`] if there is no process with this id.
-- @see getFocus
function multishell.setFocus(n)
expect(1, n, "number")
@ -250,9 +250,9 @@ end
--- Get the title of the given tab.
--
-- This starts as the name of the program, but may be changed using
-- @{multishell.setTitle}.
-- [`multishell.setTitle`].
-- @tparam number n The process index.
-- @treturn string|nil The current process title, or @{nil} if the
-- @treturn string|nil The current process title, or [`nil`] if the
-- process doesn't exist.
function multishell.getTitle(n)
expect(1, n, "number")

44
projects/core/src/main/resources/data/computercraft/lua/rom/programs/shell.lua
View File

@ -4,26 +4,26 @@
--[[- The shell API provides access to CraftOS's command line interface.
It allows you to @{run|start programs}, @{setCompletionFunction|add completion
for a program}, and much more.
It allows you to [start programs][`run`], [add completion for a
program][`setCompletionFunction`], and much more.
@{shell} is not a "true" API. Instead, it is a standard program, which injects
[`shell`] is not a "true" API. Instead, it is a standard program, which injects
its API into the programs that it launches. This allows for multiple shells to
run at the same time, but means that the API is not available in the global
environment, and so is unavailable to other @{os.loadAPI|APIs}.
environment, and so is unavailable to other [APIs][`os.loadAPI`].
## Programs and the program path
When you run a command with the shell, either from the prompt or
@{shell.run|from Lua code}, the shell API performs several steps to work out
[from Lua code][`shell.run`], the shell API performs several steps to work out
which program to run:
1. Firstly, the shell attempts to resolve @{shell.aliases|aliases}. This allows
1. Firstly, the shell attempts to resolve [aliases][`shell.aliases`]. This allows
us to use multiple names for a single command. For example, the `list`
program has two aliases: `ls` and `dir`. When you write `ls /rom`, that's
expanded to `list /rom`.
2. Next, the shell attempts to find where the program actually is. For this, it
uses the @{shell.path|program path}. This is a colon separated list of
uses the [program path][`shell.path`]. This is a colon separated list of
directories, each of which is checked to see if it contains the program.
`list` or `list.lua` doesn't exist in `.` (the current directory), so the
@ -192,7 +192,7 @@ end
--- Run a program with the supplied arguments.
--
-- Unlike @{shell.run}, each argument is passed to the program verbatim. While
-- Unlike [`shell.run`], each argument is passed to the program verbatim. While
-- `shell.run("echo", "b c")` runs `echo` with `b` and `c`,
-- `shell.execute("echo", "b c")` runs `echo` with a single argument `b c`.
--
@ -276,7 +276,7 @@ function shell.exit()
end
--- Return the current working directory. This is what is displayed before the
-- `> ` of the shell prompt, and is used by @{shell.resolve} to handle relative
-- `> ` of the shell prompt, and is used by [`shell.resolve`] to handle relative
-- paths.
--
-- @treturn string The current working directory.
@ -313,10 +313,10 @@ function shell.path()
return sPath
end
--- Set the @{path|current program path}.
--- Set the [current program path][`path`].
--
-- Be careful to prefix directories with a `/`. Otherwise they will be searched
-- for from the @{shell.dir|current directory}, rather than the computer's root.
-- for from the [current directory][`shell.dir`], rather than the computer's root.
--
-- @tparam string path The new program path.
-- @since 1.2
@ -327,8 +327,8 @@ end
--- Resolve a relative path to an absolute path.
--
-- The @{fs} and @{io} APIs work using absolute paths, and so we must convert
-- any paths relative to the @{dir|current directory} to absolute ones. This
-- The [`fs`] and [`io`] APIs work using absolute paths, and so we must convert
-- any paths relative to the [current directory][`dir`] to absolute ones. This
-- does nothing when the path starts with `/`.
--
-- @tparam string path The path to resolve.
@ -357,10 +357,10 @@ local function pathWithExtension(_sPath, _sExt)
return _sPath .. "." .. _sExt
end
--- Resolve a program, using the @{path|program path} and list of @{aliases|aliases}.
--- Resolve a program, using the [program path][`path`] and list of [aliases][`aliases`].
--
-- @tparam string command The name of the program
-- @treturn string|nil The absolute path to the program, or @{nil} if it could
-- @treturn string|nil The absolute path to the program, or [`nil`] if it could
-- not be found.
-- @since 1.2
-- @changed 1.80pr1 Now searches for files with and without the `.lua` extension.
@ -406,7 +406,7 @@ function shell.resolveProgram(command)
return nil
end
--- Return a list of all programs on the @{shell.path|path}.
--- Return a list of all programs on the [path][`shell.path`].
--
-- @tparam[opt] boolean include_hidden Include hidden files. Namely, any which
-- start with `.`.
@ -518,7 +518,7 @@ end
-- completed to `ls rom/`.
--
-- Completion handlers for your program may be registered with
-- @{shell.setCompletionFunction}.
-- [`shell.setCompletionFunction`].
--
-- @tparam string sLine The input to complete.
-- @treturn { string }|nil The list of possible completions.
@ -614,7 +614,7 @@ end
--- Get a table containing all completion functions.
--
-- This should only be needed when building custom shells. Use
-- @{setCompletionFunction} to add a completion function.
-- [`setCompletionFunction`] to add a completion function.
--
-- @treturn { [string] = { fnComplete = function } } A table mapping the
-- absolute path of programs, to their completion functions.
@ -676,12 +676,12 @@ function shell.aliases()
end
if multishell then
--- Open a new @{multishell} tab running a command.
--- Open a new [`multishell`] tab running a command.
--
-- This behaves similarly to @{shell.run}, but instead returns the process
-- This behaves similarly to [`shell.run`], but instead returns the process
-- index.
--
-- This function is only available if the @{multishell} API is.
-- This function is only available if the [`multishell`] API is.
--
-- @tparam string ... The command line to run.
-- @see shell.run
@ -706,7 +706,7 @@ if multishell then
end
end
--- Switch to the @{multishell} tab with the given index.
--- Switch to the [`multishell`] tab with the given index.
--
-- @tparam number id The tab to switch to.
-- @see multishell.setFocus

2
projects/core/src/test/resources/test-rom/mcfly.lua
View File

@ -55,7 +55,7 @@ local function default_stub() end
-- @tparam string key The variable to stub
-- @param[opt] value The value to stub it with. If this is a function, one can
-- use the various stub expectation methods to determine what it was called
-- with. Defaults to an empty function - pass @{nil} in explicitly to set the
-- with. Defaults to an empty function - pass [`nil`] in explicitly to set the
-- value to nil.
-- @treturn Stub The resulting stub
local function stub(tbl, key, ...)

2
projects/core/src/test/resources/test-rom/spec/modules/cc/internal/syntax/syntax_helpers.lua
View File

@ -27,7 +27,7 @@ end
--[[- Run a parser on an input string, capturing its output.
This uses a simplified method of displaying errors (compared with
@{cc.internal.error_printer}), which is suitable for printing to a file.
[`cc.internal.error_printer`]), which is suitable for printing to a file.
@tparam string input The input string to parse.
@tparam[opt=false] boolean print_tokens Whether to print each token as its parsed.

7
projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/EnergyMethods.java
View File

@ -15,10 +15,9 @@
* <p>
* This works with energy storage blocks, as well as generators and machines which consume energy.
* <p>
* :::note
* Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
* used/generated per tick).
* :::
* > [!NOTE]
* > Due to limitations with Forge's energy API, it is not possible to measure throughput (i.e. RF
* > used/generated per tick).
*
* @cc.module energy_storage
* @cc.since 1.94.0

8
projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/FluidMethods.java
View File

@ -75,13 +75,13 @@ public String id() {
*
* @param from Container to move fluid from.
* @param computer The current computer.
* @param toName The name of the peripheral/container to push to. This is the string given to @{peripheral.wrap},
* @param toName The name of the peripheral/container to push to. This is the string given to [`peripheral.wrap`],
* and displayed by the wired modem.
* @param limit The maximum amount of fluid to move.
* @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen.
* @return The amount of moved fluid.
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container.
* @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
*/
@LuaFunction(mainThread = true)
public static int pushFluid(
@ -115,13 +115,13 @@ public static int pushFluid(
*
* @param to Container to move fluid to.
* @param computer The current computer.
* @param fromName The name of the peripheral/container to push to. This is the string given to @{peripheral.wrap},
* @param fromName The name of the peripheral/container to push to. This is the string given to [`peripheral.wrap`],
* and displayed by the wired modem.
* @param limit The maximum amount of fluid to move.
* @param fluidName The fluid to move. If not given, an arbitrary fluid will be chosen.
* @return The amount of moved fluid.
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an fluid container.
* @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
*/
@LuaFunction(mainThread = true)
public static int pullFluid(

21
projects/forge/src/main/java/dan200/computercraft/shared/peripheral/generic/methods/InventoryMethods.java
View File

@ -99,15 +99,14 @@ public static int size(IItemHandler inventory) {
* (`displayName`), and item and item durability (`damage`, `maxDamage`, `durability`).
* <p>
* Some items include more information (such as enchantments) - it is
* recommended to print it out using @{textutils.serialize} or in the Lua
* recommended to print it out using [`textutils.serialize`] or in the Lua
* REPL, to explore what is available.
* <p>
* :::info Deprecated fields
* Older versions of CC: Tweaked exposed an {@code itemGroups} field, listing the
* creative tabs an item was available under. This information is no longer available on
* more recent versions of the game, and so this field will always be empty. Do not use this
* field in new code!
* :::
* > [Deprecated fields][!INFO]
* > Older versions of CC: Tweaked exposed an {@code itemGroups} field, listing the
* > creative tabs an item was available under. This information is no longer available on
* > more recent versions of the game, and so this field will always be empty. Do not use this
* > field in new code!
*
* @param inventory The current inventory.
* @param slot The slot to get information about.
@ -173,7 +172,7 @@ public static int getItemLimit(IItemHandler inventory, int slot) throws LuaExcep
*
* @param from Inventory to move items from.
* @param computer The current computer.
* @param toName The name of the peripheral/inventory to push to. This is the string given to @{peripheral.wrap},
* @param toName The name of the peripheral/inventory to push to. This is the string given to [`peripheral.wrap`],
* and displayed by the wired modem.
* @param fromSlot The slot in the current inventory to move items to.
* @param limit The maximum number of items to move. Defaults to the current stack limit.
@ -181,7 +180,7 @@ public static int getItemLimit(IItemHandler inventory, int slot) throws LuaExcep
* @return The number of transferred items.
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory.
* @throws LuaException If either source or destination slot is out of range.
* @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
* @cc.usage Wrap two chests, and push an item from one to another.
* <pre>{@code
* local chest_a = peripheral.wrap("minecraft:chest_0")
@ -219,7 +218,7 @@ public static int pushItems(
*
* @param to Inventory to move items to.
* @param computer The current computer.
* @param fromName The name of the peripheral/inventory to pull from. This is the string given to @{peripheral.wrap},
* @param fromName The name of the peripheral/inventory to pull from. This is the string given to [`peripheral.wrap`],
* and displayed by the wired modem.
* @param fromSlot The slot in the source inventory to move items from.
* @param limit The maximum number of items to move. Defaults to the current stack limit.
@ -227,7 +226,7 @@ public static int pushItems(
* @return The number of transferred items.
* @throws LuaException If the peripheral to transfer to doesn't exist or isn't an inventory.
* @throws LuaException If either source or destination slot is out of range.
* @cc.see peripheral.getName Allows you to get the name of a @{peripheral.wrap|wrapped} peripheral.
* @cc.see peripheral.getName Allows you to get the name of a [wrapped][`peripheral.wrap`] peripheral.
* @cc.usage Wrap two chests, and push an item from one to another.
* <pre>{@code
* local chest_a = peripheral.wrap("minecraft:chest_0")