Difference between revisions of "Textutils (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m (New CC 1.76 parameter for textutils.serializeJSON())
 
(12 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{NeedsWork|Needs <s>5</s> 3 function pages, 1 function descriptions. ''[[User:AfterLifeLochie|AfterLifeLochie]] 02:40, 29 November 2012 (MSK)''}}
+
The Textutils API is used to format and manipulate strings easily.
Text utilities is used to mess around with text easier.
+
  
<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
+
{{API table|textutils|image=Grid disk.png|2=
<tr><td colspan="2" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
+
[[File:Grid_disk.png|24px]]&nbsp;&nbsp;
+
Textutils (API)
+
</td></tr>
+
  
<tr><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>
+
{{API table/row
 +
|[[textutils.slowWrite]]({{type|string}} text, {{type|number}} rate)
 +
|{{type|nil}}
 +
|Writes string <var>text</var> at current cursor position, character-by-character. Number argument <var>rate</var> is optional and is defaulted to 20. The higher the value of <var>rate</var>, the faster <var>text</var> is written (passing a value of 1 writes one character per second).
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.slowPrint|textutils.slowPrint]]([[string (type)|string]] text, [[int (type)|int]] rate)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Slowly prints the text. Only difference is, it leaves a new-line after it.</td></tr>
+
|[[textutils.slowPrint]]({{type|string}} text, {{type|number}} rate)
 +
|{{type|nil}}
 +
|Prints string <var>text</var> at current cursor position, character-by-character. Number argument <var>rate</var> is optional and is defaulted to 20. The higher the value of <var>rate</var>, the faster <var>text</var> is printed (passing a value of 1 prints one character per second). This function also prints a newline.
 +
|}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.slowWrite|textutils.slowWrite]]([[string (type)|string]] text, [[int (type)|int]] rate)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Slowly writes the text.</td></tr>
+
|[[textutils.formatTime]]({{type|number}} time, {{type|boolean}} twentyFourHour)
 +
|{{type|string}} formattedTime
 +
|Takes input <var>time</var> and formats it in a more readable format. If the second value is <var>true</var>, returns time in twenty-four hour format; if the second value is <var>false</var>, returns time in twelve-hour format, with AM or PM. Default for <var>twentyFourHour</var> is <var>false</var>.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.formatTime|textutils.formatTime]]([[int (type)|int]] time, [[boolean (type)|bool]] TwentyFourHour)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Put a time into it, and it spews it out in a different format. Example: print(textutils.formatTime(os.time(), false))</td></tr>
+
|[[textutils.tabulate]]({{type|table}} table/{{type|number}} color, {{type|table}} table2/{{type|number}} color2, ...)
 +
|{{type|nil}}
 +
|Prints tables in an ordered form. Each table is a row, the column width is auto-adjusted. If it encounters a number instead of a table then sets the text color to it.
 +
|}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.tabulate|textutils.tabulate]]([[table (type)|table]] table, [[table (type)|table]] table2, ...)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Prints tables in an ordered form. Each table is a row, columns' width is auto-adjusted.</td></tr>
+
|[[textutils.pagedTabulate]]({{type|table}} table/{{type|number}} color, {{type|table}} table2/{{type|number}} color2, ...)
 +
|{{type|nil}}
 +
|Prints tables in an ordered form, like [[textutils.tabulate]]. However, it waits for confirmation before scrolling down.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.pagedTabulate|textutils.pagedTabulate]]([[table (type)|table]] table, [[table (type)|table]] table2, ...)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">A description is required.</td></tr>
+
|[[textutils.pagedPrint]]({{type|string}} text [, {{type|number}} freeLines])
 +
|{{type|number}} linesPrinted
 +
|Prints string <var>text</var> onto the screen, but waits for confirmation (after at least <var>freeLines</var> have been scrolled) before scrolling down further. Default for <var>freeLines</var> is <var>0</var>.
 +
|}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.pagedPrint|textutils.pagedPrint]]([[string (type)|string]] string, [[string (type)|string]] confirmation_lines)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Prints a string onto the screen, but waits for confirmation before scrolling down.</td></tr>
+
|[[textutils.serialize]]({{type|table}}/{{type|string}}/{{type|number}}/{{type|boolean}}/{{type|nil}} data)
 +
|{{type|string}} serializedData
 +
|Returns a string representation of the data <var>data</var> for storage or transmission. Also exists as textutils.seriali'''s'''e under CC 1.6 or later.
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.serialize|textutils.serialize]]([[table (type)|table]] table)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a string representation of the table t for storage or transmission.</td></tr>
+
|[[textutils.unserialize]]({{type|string}} serializedData)
 +
|{{type|any}} unserializedData
 +
|Returns the data reassembled from string <var>serializedData</var>. Used mainly together with [[textutils.serialize]](). Also exists as textutils.unseriali'''s'''e under CC 1.6 or later.
 +
|}}
  
<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.unserialize|textutils.unserialize]]([[string (type)|string]] text)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns a table reassembled from the string s.</td></tr>
+
|[[textutils.serializeJSON]]({{type|table}}/{{type|string}}/{{type|number}}/{{type|boolean}} data [, {{type|boolean}} unquote keys])
 +
|{{type|string}} serializedData
 +
|Returns a JSON representation of the data <var>data</var> in a form of a {{type|string}}, mainly for [[Commands (API)|command usage]]. Also exists as textutils.seriali'''s'''eJSON. ''Requires CC 1.7 or later.''
 +
|odd}}
  
<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[textutils.urlEncode|textutils.urlEncode]]([[string (type)|string]] text)</td>
+
{{API table/row
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Makes a string safe to encode into a url. Spaces are replaced with +s. Unsafe characters such as '\', '£' and '}' are translated into ASCII code and preceded with a % for transmission. For reference visit: [http://www.blooberry.com/indexdot/html/topics/urlencoding.htm].</td></tr>
+
|[[textutils.urlEncode]]({{type|string}} urlUnsafeString)
</table>
+
|{{type|string}} urlSafeString
 +
|Makes a string safe to encode into a url. Spaces are replaced with <var>+</var>s. Unsafe characters such as '\', '£' and '}' are translated into ASCII code and preceded with a % for transmission. For reference visit: [http://www.blooberry.com/indexdot/html/topics/urlencoding.htm].
 +
|}}
  
 +
{{API table/row|[[textutils.complete]]({{Type|string}} partial name [, {{Type|table}} environment])
 +
|{{type|table}} matches
 +
|Returns a list of strings that could be combined with the provided name to produce valid entries in the specified environment. ''Requires version 1.74 or later.''
 +
|odd}}
 +
 +
}}
  
 
[[Category:APIs]]
 
[[Category:APIs]]

Latest revision as of 02:07, 26 December 2015

The Textutils API is used to format and manipulate strings easily.

Grid disk.png  textutils (API)
Function Return values Description
textutils.slowWrite(string text, number rate) nil Writes string text at current cursor position, character-by-character. Number argument rate is optional and is defaulted to 20. The higher the value of rate, the faster text is written (passing a value of 1 writes one character per second).
textutils.slowPrint(string text, number rate) nil Prints string text at current cursor position, character-by-character. Number argument rate is optional and is defaulted to 20. The higher the value of rate, the faster text is printed (passing a value of 1 prints one character per second). This function also prints a newline.
textutils.formatTime(number time, boolean twentyFourHour) string formattedTime Takes input time and formats it in a more readable format. If the second value is true, returns time in twenty-four hour format; if the second value is false, returns time in twelve-hour format, with AM or PM. Default for twentyFourHour is false.
textutils.tabulate(table table/number color, table table2/number color2, ...) nil Prints tables in an ordered form. Each table is a row, the column width is auto-adjusted. If it encounters a number instead of a table then sets the text color to it.
textutils.pagedTabulate(table table/number color, table table2/number color2, ...) nil Prints tables in an ordered form, like textutils.tabulate. However, it waits for confirmation before scrolling down.
textutils.pagedPrint(string text [, number freeLines]) number linesPrinted Prints string text onto the screen, but waits for confirmation (after at least freeLines have been scrolled) before scrolling down further. Default for freeLines is 0.
textutils.serialize(table/string/number/boolean/nil data) string serializedData Returns a string representation of the data data for storage or transmission. Also exists as textutils.serialise under CC 1.6 or later.
textutils.unserialize(string serializedData) any unserializedData Returns the data reassembled from string serializedData. Used mainly together with textutils.serialize(). Also exists as textutils.unserialise under CC 1.6 or later.
textutils.serializeJSON(table/string/number/boolean data [, boolean unquote keys]) string serializedData Returns a JSON representation of the data data in a form of a string, mainly for command usage. Also exists as textutils.serialiseJSON. Requires CC 1.7 or later.
textutils.urlEncode(string urlUnsafeString) string urlSafeString Makes a string safe to encode into a url. Spaces are replaced with +s. Unsafe characters such as '\', '£' and '}' are translated into ASCII code and preceded with a % for transmission. For reference visit: [1].
textutils.complete(string partial name [, table environment]) table matches Returns a list of strings that could be combined with the provided name to produce valid entries in the specified environment. Requires version 1.74 or later.