textutils

The textutils API provides helpful utilities for formatting and manipulating strings.

slowWrite(sText[, nRate])Slowly writes string text at current cursor position, character-by-character.
slowPrint(sText[, nRate])Slowly prints string text at current cursor position, character-by-character.
formatTime(nTime[, bTwentyFourHour])Takes input time and formats it in a more readable format such as 6:30 PM.
pagedPrint(_sText[, _nFreeLines])Prints a given string to the display.
tabulate(...)Prints tables in a structured form.
pagedTabulate(...)Prints tables in a structured form, stopping and prompting for input should the result not fit on the terminal.
empty_json_arrayA table representing an empty JSON array, in order to distinguish it from an empty JSON object.
json_nullA table representing the JSON null value.
serialize(t)Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.
serialise(t)Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.
unserialize(s)Converts a serialised string back into a reassembled Lua object.
unserialise(s)Converts a serialised string back into a reassembled Lua object.
serializeJSON(t[, bNBTStyle])Returns a JSON representation of the given data.
serialiseJSON(t[, bNBTStyle])Returns a JSON representation of the given data.
unserializeJSON(s[, options])Converts a serialised JSON string back into a reassembled Lua object.
unserialiseJSON(s[, options])Converts a serialised JSON string back into a reassembled Lua object.
urlEncode(str)Replaces certain characters in a string to make it safe for use in URLs or POST data.
complete(sSearchText[, tSearchTable])Provides a list of possible completions for a partial Lua expression.
slowWrite(sText[, nRate])Source

Slowly writes string text at current cursor position, character-by-character.

Like _G.write, this does not insert a newline at the end.

Parameters

  1. sText string The the text to write to the screen
  2. nRate? number The number of characters to write each second, Defaults to 20.

Usage

slowPrint(sText[, nRate])Source

Slowly prints string text at current cursor position, character-by-character.

Like print, this inserts a newline after printing.

Parameters

  1. sText string The the text to write to the screen
  2. nRate? number The number of characters to write each second, Defaults to 20.

Usage

formatTime(nTime[, bTwentyFourHour])Source

Takes input time and formats it in a more readable format such as 6:30 PM.

Parameters

  1. nTime number The time to format, as provided by os.time.
  2. bTwentyFourHour? boolean Whether to format this as a 24-hour clock (18:30) rather than a 12-hour one (6:30 AM)

Returns

  1. string The formatted time

Usage

pagedPrint(_sText[, _nFreeLines])Source

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 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.

Parameters

  1. _sText string The text to print to the screen.
  2. _nFreeLines? number The number of lines which will be automatically scrolled before the first prompt appears (meaning _nFreeLines + 1 lines will be printed). This can be set to the terminal's height - 2 to always try to fill the screen. Defaults to 0, meaning only one line is displayed before prompting.

Returns

  1. number The number of lines printed.

Usage

  • local width, height = term.getSize()

    textutils.pagedPrint(("This is a rather verbose dose of repetition.\n"):rep(30), height - 2)
tabulate(...)Source

Prints tables in a structured form.

This accepts multiple arguments, either a table or a number. When encountering a table, this will be treated as a table row, with each column width being auto-adjusted.

When encountering a number, this sets the text color of the subsequent rows to it.

Parameters

  1. ... { string... } | number The rows and text colors to display.

Usage

pagedTabulate(...)Source

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 input should the whole output not fit on the display.

Parameters

  1. ... { string... } | number The rows and text colors to display.

Usage

See also

empty_json_arraySource

A table representing an empty JSON array, in order to distinguish it from an empty JSON object.

The contents of this table should not be modified.

Usage

See also

json_nullSource

A table representing the JSON null value.

The contents of this table should not be modified.

Usage

See also

serialize(t)Source

Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.

Parameters

  1. t The object to serialise

Returns

  1. string The serialised representation

Throws

  • If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times.

serialise(t)Source

Convert a Lua object into a textual representation, suitable for saving in a file or pretty-printing.

Parameters

  1. t The object to serialise

Returns

  1. string The serialised representation

Throws

  • If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times.

unserialize(s)Source

Converts a serialised string back into a reassembled Lua object.

This is mainly used together with textutils.serialize.

Parameters

  1. s string The serialised string to deserialise.

Returns

  1. The deserialised object

Or

  1. nil If the object could not be deserialised.
unserialise(s)Source

Converts a serialised string back into a reassembled Lua object.

This is mainly used together with textutils.serialize.

Parameters

  1. s string The serialised string to deserialise.

Returns

  1. The deserialised object

Or

  1. nil If the object could not be deserialised.
serializeJSON(t[, bNBTStyle])Source

Returns a JSON representation of the given data.

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.

This is largely intended for interacting with various functions from the commands API, though may also be used in making http requests.

Parameters

  1. t The value to serialise. Like textutils.serialise, this should not contain recursive tables or functions.
  2. bNBTStyle? boolean Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON.

Returns

  1. string The JSON representation of the input.

Throws

  • If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times.

Usage

serialiseJSON(t[, bNBTStyle])Source

Returns a JSON representation of the given data.

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.

This is largely intended for interacting with various functions from the commands API, though may also be used in making http requests.

Parameters

  1. t The value to serialise. Like textutils.serialise, this should not contain recursive tables or functions.
  2. bNBTStyle? boolean Whether to produce NBT-style JSON (non-quoted keys) instead of standard JSON.

Returns

  1. string The JSON representation of the input.

Throws

  • If the object contains a value which cannot be serialised. This includes functions and tables which appear multiple times.

Usage

unserializeJSON(s[, options])Source

Converts a serialised JSON string back into a reassembled Lua object.

This may be used with textutils.serializeJSON, or when communicating with command blocks or web APIs.

Parameters

  1. s string The serialised string to deserialise.
  2. options? { nbt_style? = boolean, parse_null? = boolean }

    Options which control how this JSON object is parsed.

    • nbt_style: When true, this will accept stringified NBT strings, as produced by many commands.
    • parse_null: When true, null will be parsed as json_null, rather than nil.

Returns

  1. The deserialised object

Or

  1. nil If the object could not be deserialised.
  2. string A message describing why the JSON string is invalid.
unserialiseJSON(s[, options])Source

Converts a serialised JSON string back into a reassembled Lua object.

This may be used with textutils.serializeJSON, or when communicating with command blocks or web APIs.

Parameters

  1. s string The serialised string to deserialise.
  2. options? { nbt_style? = boolean, parse_null? = boolean }

    Options which control how this JSON object is parsed.

    • nbt_style: When true, this will accept stringified NBT strings, as produced by many commands.
    • parse_null: When true, null will be parsed as json_null, rather than nil.

Returns

  1. The deserialised object

Or

  1. nil If the object could not be deserialised.
  2. string A message describing why the JSON string is invalid.
urlEncode(str)Source

Replaces certain characters in a string to make it safe for use in URLs or POST data.

Parameters

  1. str string The string to encode

Returns

  1. string The encoded string.

Usage

complete(sSearchText[, tSearchTable])Source

Provides a list of possible completions for a partial Lua expression.

If the completed element is a table, suggestions will have . appended to them. Similarly, functions have ( appended to them.

Parameters

  1. sSearchText string The partial expression to complete, such as a variable name or table index.
  2. tSearchTable? table The table to find variables in, defaulting to the global environment (_G). The function also searches the "parent" environment via the __index metatable field.

Returns

  1. { string... } The (possibly empty) list of completions.

Usage

See also