Module ftext
ftext functions to format and print text, and the objects which use them
Info:
- Copyright: 2020 Damian Monogue,2021 Damian Monogue,2022 Damian Monogue
- License: MIT, see LICENSE.lua
- Author: Damian Monogue
Functions
wordWrap(str, limit) | Performs wordwrapping on a string, given a length limit. |
xwrap(text, limit, type) | Performs wordwrapping on a string, while ignoring color tags of a given type. |
fText(str, opts) | The main course, this function returns a formatted string, based on a table of options |
Class ftext.TextFormatter
TextFormatter:setType(typeToSet) | Set's the formatting type whether it's for cecho, decho, or hecho |
TextFormatter:setWrap(shouldWrap) | Sets whether or not we should do word wrapping. |
TextFormatter:setWidth(width) | Sets the width we should format for |
TextFormatter:setCap(cap) | Sets the cap for the formatter |
TextFormatter:setCapColor(capColor) | Sets the color for the format cap |
TextFormatter:setSpacerColor(spacerColor) | Sets the color for spacing character |
TextFormatter:setTextColor(textColor) | Sets the color for formatted text |
TextFormatter:setSpacer(spacer) | Sets the spacing character to use. |
TextFormatter:setAlignment(alignment) | Set the alignment to format for |
TextFormatter:setInside(spacerInside) | Set whether the the spacer should go inside the the cap or outside of it |
TextFormatter:setMirror(shouldMirror) | Set whether we should mirror/reverse the caps. |
TextFormatter:setNoGap(noGap) | Set whether we should remove the gap spaces between the text and spacer characters. |
TextFormatter:enableTruncate() | Enables truncation (cutting to length). |
TextFormatter:disableTruncate() | Disables truncation (cutting to length). |
TextFormatter:format(str) | Format a string based on the stored options |
TextFormatter:new(options) | Creates and returns a new TextFormatter. |
Class ftext.TableMaker
TableMaker:getColumn(position) | Get the TextFormatter which defines the format of a specific column |
TableMaker:addColumn(options, position) | Adds a column definition for the table. |
TableMaker:deleteColumn(position) | Deletes a column at the given position |
TableMaker:replaceColumn(options, position) | Replaces a column at a specific position with the newly provided formatting |
TableMaker:getRow(position) | Gets the row of output at a specific position |
TableMaker:addRow(columnEntries, position) | Adds a row of output to the table |
TableMaker:deleteRow(position) | Deletes the row at the given position |
TableMaker:replaceRow(columnEntries, position) | Replaces a row of output in the table |
TableMaker:getCell(row, column) | Get the contents and formatter for a specific cell |
TableMaker:setCell(row, column, entry) | Sets a specific cell's display information |
TableMaker:setTitle(title) | set the title of the table |
TableMaker:setRowSeparator(char) | set the rowSeparator for the table |
TableMaker:setEdgeCharacter(char) | set the edgeCharacter for the table |
TableMaker:setFootCharacter(char) | set the foot character for the table |
TableMaker:setHeadCharacter(char) | set the head character for the table |
TableMaker:setSeparator(char) | set the column separator character for the table |
TableMaker:setTitleColor(color) | set the title color for the table |
TableMaker:setSeparatorColor(color) | set the title color for the table |
TableMaker:setFrameColor(color) | set the title color for the table |
TableMaker:enableForceHeaderSeparator() | Force a separator between the header and first row, even if the row separator is disabled for the overall table |
TableMaker:disableForceHeaderSeparator() | Do not force a separator between the header and first row, even if the row separator is disabled for the overall table |
TableMaker:enableHeaderTitle() | Enable using the title separator for the column headers as well |
TableMaker:disableHeaderTitle() | Disable using the title separator for the column headers as well |
TableMaker:enablePrintTitle() | enable printing the title of the table |
TableMaker:disablePrintTitle() | disable printing the title of the table |
TableMaker:enablePrintHeaders() | enable printing of the column headers |
TableMaker:disablePrintHeaders() | disable printing of the column headers |
TableMaker:enableRowSeparator() | enable printing the separator line between rows |
TableMaker:disableRowSeparator() | enable printing the separator line between rows |
TableMaker:enablePopups() | enables making cells which incorporate insertLink/insertPopup |
TableMaker:enableAutoEcho() | enables autoEcho so that when assemble is called it echos automatically |
TableMaker:disableAutoEcho() | disables autoecho. |
TableMaker:enableAutoClear() | Enables automatically clearing the miniconsole we echo to |
TableMaker:disableAutoClear() | Disables automatically clearing the miniconsole we echo to |
TableMaker:setAutoEchoConsole(console) | Set the miniconsole to echo to |
TableMaker:assemble() | Assemble the table. |
TableMaker:new(options) | Creates and returns a new TableMaker. |
Functions
- wordWrap(str, limit) line 17
-
Performs wordwrapping on a string, given a length limit. Does not understand colour tags and will count them as characters in the string
Parameters:
- str string the string to wordwrap
- limit number the line length to wrap at
- xwrap(text, limit, type) line 36
-
Performs wordwrapping on a string, while ignoring color tags of a given type.
Parameters:
- fText(str, opts) line 203
-
The main course, this function returns a formatted string, based on a table of options
Parameters:
- str string the string to format
- opts
table
the table of options which control the formatting
Table of optionsoption name description default wrap Should it wordwrap to multiple lines? true formatType Determines how it formats for color. 'c' for cecho, 'd' for decho, 'h' for hecho, and anything else for no colors "" width How wide should we format the text? 80 cap what characters to use for the endcap. "" capColor what color to make the endcap? the correct 'white' for your formatType spacer What character to use for empty space. Must be a single character " " spacerColor what color should the spacer be? the correct 'white' for your formatType textColor what color should the text itself be? the correct 'white' for your formatType alignment How should the text be aligned within the width. "center", "left", or "right" "center" nogap Should we put a literal space between the spacer character and the text? false inside Put the spacers inside the caps? false mirror Should the endcap be reversed on the right? IE [[ becomes ]] true truncate Cut the string to width. Is superceded by wrap being true. false
Class ftext.TextFormatter
Stand alone text formatter object. Remembers the options you set and can be adjusted as needed
- TextFormatter:setType(typeToSet) line 512
-
Set's the formatting type whether it's for cecho, decho, or hecho
Parameters:
- typeToSet string What type of formatter is this? Valid options are { 'd', 'dec', 'decimal', 'h', 'hex', 'hexidecimal', 'c', 'color', 'colour', 'col', 'name'}
- TextFormatter:setWrap(shouldWrap) line 546
-
Sets whether or not we should do word wrapping.
Parameters:
- shouldWrap boolean should we do wordwrapping?
- TextFormatter:setWidth(width) line 558
-
Sets the width we should format for
Parameters:
- width number the width we should format for
- TextFormatter:setCap(cap) line 571
-
Sets the cap for the formatter
Parameters:
- cap string the string to use for capping the formatted string.
- TextFormatter:setCapColor(capColor) line 582
-
Sets the color for the format cap
Parameters:
- capColor string Color which can be formatted via Geyser.Color.parse()
- TextFormatter:setSpacerColor(spacerColor) line 593
-
Sets the color for spacing character
Parameters:
- spacerColor string Color which can be formatted via Geyser.Color.parse()
- TextFormatter:setTextColor(textColor) line 604
-
Sets the color for formatted text
Parameters:
- textColor string Color which can be formatted via Geyser.Color.parse()
- TextFormatter:setSpacer(spacer) line 615
-
Sets the spacing character to use. Should be a single character
Parameters:
- spacer string the character to use for spacing
- TextFormatter:setAlignment(alignment) line 626
-
Set the alignment to format for
Parameters:
- alignment string How to align the formatted string. Valid options are 'left', 'right', or 'center'
- TextFormatter:setInside(spacerInside) line 637
-
Set whether the the spacer should go inside the the cap or outside of it
Parameters:
- spacerInside boolean
- TextFormatter:setMirror(shouldMirror) line 648
-
Set whether we should mirror/reverse the caps. IE << becomes >> if set to true
Parameters:
- shouldMirror boolean
- TextFormatter:setNoGap(noGap) line 659
-
Set whether we should remove the gap spaces between the text and spacer characters. "===some text===" if set to true, "== some text ==" if set to false
Parameters:
- noGap boolean
- TextFormatter:enableTruncate() line 669
- Enables truncation (cutting to length). You still need to ensure wrap is disabled, as it supercedes.
- TextFormatter:disableTruncate() line 674
- Disables truncation (cutting to length). You still need to ensure wrap is enabled if you want it to wrap.
- TextFormatter:format(str) line 680
-
Format a string based on the stored options
Parameters:
- str string The string to format
- TextFormatter:new(options) line 773
-
Creates and returns a new TextFormatter.
Parameters:
- options
table
the options for the text formatter to use when running format()
Table of optionsoption name description default wrap Should it wordwrap to multiple lines? true formatType Determines how it formats for color. 'c' for cecho, 'd' for decho, 'h' for hecho, and anything else for no colors "c" width How wide should we format the text? 80 cap what characters to use for the endcap. "" capColor what color to make the endcap? the correct 'white' for your formatType spacer What character to use for empty space. Must be a single character " " spacerColor what color should the spacer be? the correct 'white' for your formatType textColor what color should the text itself be? the correct 'white' for your formatType alignment How should the text be aligned within the width. "center", "left", or "right" "center" nogap Should we put a literal space between the spacer character and the text? false inside Put the spacers inside the caps? false mirror Should the endcap be reversed on the right? IE [[ becomes ]] true truncate Cut the string to width. Is superceded by wrap being true. false
Usage:
local TextFormatter = require("MDK.ftext").TextFormatter myFormatter = TextFormatter:new( { width = 40, cap = "[CAP]", capColor = "<orange>", textColor = "<light_blue>" }) myMessage = "This is a test of the emergency broadcasting system. This is only a test" cecho(myFormatter:format(myMessage))
- options
table
the options for the text formatter to use when running format()
Class ftext.TableMaker
Easy formatting for text tables
- TableMaker:getColumn(position) line 839
-
Get the TextFormatter which defines the format of a specific column
Parameters:
- position number The position of the column you're getting, counting from the left. If not provided will return the last column.
- TableMaker:addColumn(options, position) line 848
-
Adds a column definition for the table.
Parameters:
- options table Table of options suitable for a TextFormatter object. See https://github.com/demonnic/fText/wiki/fText
- position number The position of the column you're adding, counting from the left. If not provided will add it as the last column
- TableMaker:deleteColumn(position) line 865
-
Deletes a column at the given position
Parameters:
- position number the column you wish to delete
- TableMaker:replaceColumn(options, position) line 882
-
Replaces a column at a specific position with the newly provided formatting
Parameters:
- options table table of options suitable for a TextFormatter object. See https://github.com/demonnic/fText/wiki/fText
- position number which column you are replacing, counting from the left.
- TableMaker:getRow(position) line 904
-
Gets the row of output at a specific position
Parameters:
- position number The position of the row you want to get, coutning from the top down. If not provided defaults to the last row in the table
Returns:
-
table of entries in the specified row
- TableMaker:addRow(columnEntries, position) line 913
-
Adds a row of output to the table
Parameters:
- columnEntries table This indexed table contains an entry for each column in the table. Entries in the table must be strings, a table of options for insertPopup or insertLink, or a function which returns one of these things
- position number position for the row you want to add, counting from the top down. If not provided defaults to the last line in the table.
- TableMaker:deleteRow(position) line 936
-
Deletes the row at the given position
Parameters:
- position number the row to delete
- TableMaker:replaceRow(columnEntries, position) line 951
-
Replaces a row of output in the table
Parameters:
- columnEntries table This indexed table contains an entry for each column in the table. Entries in the table must be strings, a table of options for insertPopup or insertLink, or a function which returns one of these things
- position number position for the row you want to add, counting from the top down.
- TableMaker:getCell(row, column) line 1006
-
Get the contents and formatter for a specific cell
Parameters:
- row number the row number of the cell, counted top down.
- column number the column number of the cell, counted from the left.
Returns:
-
the base text and TextFormatter for the cell at the specific row and column number
- TableMaker:setCell(row, column, entry) line 1038
-
Sets a specific cell's display information
Parameters:
- row number the row number of the cell, counted from the top down
- column number the column number of the cell, counted from the left
- entry What to set the entry to. Must be a string, or a table of options for insertLink/insertPopup if allowPopups is set. Or a function which returns one of these things
- TableMaker:setTitle(title) line 1282
-
set the title of the table
Parameters:
- title string The title of the table.
- TableMaker:setRowSeparator(char) line 1289
-
set the rowSeparator for the table
Parameters:
- char string The row separator to use
- TableMaker:setEdgeCharacter(char) line 1296
-
set the edgeCharacter for the table
Parameters:
- char string The edge character to use
- TableMaker:setFootCharacter(char) line 1303
-
set the foot character for the table
Parameters:
- char string The foot character to use
- TableMaker:setHeadCharacter(char) line 1310
-
set the head character for the table
Parameters:
- char string The head character to use
- TableMaker:setSeparator(char) line 1317
-
set the column separator character for the table
Parameters:
- char string The separator character to use
- TableMaker:setTitleColor(color) line 1324
-
set the title color for the table
Parameters:
- color string The title color to use. Should match the color type of the tablemaker (cecho by default)
- TableMaker:setSeparatorColor(color) line 1331
-
set the title color for the table
Parameters:
- color string The separator color to use. Should match the color type of the tablemaker (cecho by default)
- TableMaker:setFrameColor(color) line 1338
-
set the title color for the table
Parameters:
- color string The frame color to use. Should match the color type of the tablemaker (cecho by default)
- TableMaker:enableForceHeaderSeparator() line 1344
- Force a separator between the header and first row, even if the row separator is disabled for the overall table
- TableMaker:disableForceHeaderSeparator() line 1350
- Do not force a separator between the header and first row, even if the row separator is disabled for the overall table
- TableMaker:enableHeaderTitle() line 1356
- Enable using the title separator for the column headers as well
- TableMaker:disableHeaderTitle() line 1362
- Disable using the title separator for the column headers as well
- TableMaker:enablePrintTitle() line 1368
- enable printing the title of the table
- TableMaker:disablePrintTitle() line 1374
- disable printing the title of the table
- TableMaker:enablePrintHeaders() line 1380
- enable printing of the column headers
- TableMaker:disablePrintHeaders() line 1386
- disable printing of the column headers
- TableMaker:enableRowSeparator() line 1392
- enable printing the separator line between rows
- TableMaker:disableRowSeparator() line 1398
- enable printing the separator line between rows
- TableMaker:enablePopups() line 1404
- enables making cells which incorporate insertLink/insertPopup
- TableMaker:enableAutoEcho() line 1411
- enables autoEcho so that when assemble is called it echos automatically
- TableMaker:disableAutoEcho() line 1417
- disables autoecho. Cannot be used if allowPopups is set
- TableMaker:enableAutoClear() line 1426
- Enables automatically clearing the miniconsole we echo to
- TableMaker:disableAutoClear() line 1432
- Disables automatically clearing the miniconsole we echo to
- TableMaker:setAutoEchoConsole(console) line 1438
-
Set the miniconsole to echo to
Parameters:
- console The miniconsole to autoecho to. Set to "main" or do not pass the parameter to autoecho to the main console. Can be a string name of the console, or a Geyser MiniConsole
- TableMaker:assemble() line 1455
- Assemble the table. If autoEcho is enabled/set to true, will automatically echo. Otherwise, returns the formatted string to echo the table
- TableMaker:new(options) line 1619
-
Creates and returns a new TableMaker.
see https://github.com/demonnic/MDK/wiki/fText%3A-TableMaker%3A-Examples for usage
Parameters:
- options
table
table of options for the TableMaker object
Table of new optionsoption name description default formatType Determines how it formats for color. 'c' for cecho, 'd' for decho, 'h' for hecho, and anything else for no colors c printHeaders print top row as header true headCharacter The character used to construct the very top of the table. A solid line of these characters is used "*" footCharacter The character used to construct the very bottom of the table. A solid line of these characters is used "*" edgeCharacter the character used to form the left and right edges of the table. There is one on either side of every line "*" frameColor The color to use for the frame. The frame is the border around the outside edge of the table (headCharacter, footCharacter, and edgeCharacters will all be this color). the correct 'white' for your formatType rowSeparator the character used to form the lines between rows of text "-" separator Character used between columns. "|" separatorColor the color used for the separators, the things which divide the rows and columns internally. (separator and rowSeparator will be this color) frameColor autoEcho echo the table automatically in addition to returning the string representation? false autoEchoConsole MiniConsole to autoEcho to "main" autoClear If autoEchoing, and not echoing to the main console, should we clear the console before outputting? false allowPopups setting this to true allows you to make cells in the table clickable, as well as give them right-click menus.
Please see Clickable Tables HEREfalse separateRows When false, will not print the separator line between rows true title The overall title of the table. Displayed at the top "" titleColor What color to use for the title text formatColor printTitle Should we print the title of the table at the very tip-top? false headerTitle Use the same separator for the column headers as the title/top, rather than the row separator formatColor forceHeaderSeparator Force a separator between the column headers and the first row, even if rowSeparator is false. false
- options
table
table of options for the TableMaker object