Difference between revisions of "Textutils (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m
m (New CC 1.76 parameter for textutils.serializeJSON())
 
(28 intermediate revisions by 15 users not shown)
Line 1: Line 1:
Text utilities is used to mess around with text easier.
+
The Textutils API is used to format and manipulate strings easily.
  
Its functions include:
+
{{API table|textutils|image=Grid disk.png|2=
{| border="1" cellpadding="2" cellspacing="0"
+
!style="background:#EEE" width="200px"|Method name
+
!style="background:#EEE" width="*"|Description
+
|-
+
|textutils.slowPrint( text )
+
|Slowly prints the text.
+
|-
+
|textutils.slowWrite( text )
+
|Slowly writes the text.
+
|-
+
|textutils.formatTime( time, bTwentyFourHour)
+
|Put a time into it, and it spews it out in a different format. For example:
+
local nTime = os.time()
+
  
print(textutils.formatTime( nTime, false ))
+
{{API table/row
|-
+
|[[textutils.slowWrite]]({{type|string}} text, {{type|number}} rate)
|textutils.tabulate( table, table2, so on)
+
|{{type|nil}}
|Prints tables in an ordered form. Each table is a row, columns' width is auto-adjusted.
+
|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}}
|textutils.pagedTabulate( table, table2, so on)
+
 
|<no description given>
+
{{API table/row
|-
+
|[[textutils.slowPrint]]({{type|string}} text, {{type|number}} rate)
|textutils.serialize( t )
+
|{{type|nil}}
|Returns a string representation of the table t for storage or transmission.
+
|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.
|-
+
|}}
|textutils.unserialize( s )
+
 
|Returns a table reassembled from the string s.
+
{{API table/row
|-
+
|[[textutils.formatTime]]({{type|number}} time, {{type|boolean}} twentyFourHour)
|textutils.urlEncode( str )
+
|{{type|string}} formattedTime
|<no description given>
+
|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}}
 +
 
 +
{{API table/row
 +
|[[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.
 +
|}}
 +
 
 +
{{API table/row
 +
|[[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}}
 +
 
 +
{{API table/row
 +
|[[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>.
 +
|}}
 +
 
 +
{{API table/row
 +
|[[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}}
 +
 
 +
{{API table/row
 +
|[[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.
 +
|}}
 +
 
 +
{{API table/row
 +
|[[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}}
 +
 
 +
{{API table/row
 +
|[[textutils.urlEncode]]({{type|string}} urlUnsafeString)
 +
|{{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.