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:

  • text string the string you are wordwrapping
  • limit number the line length to wrap at
  • type string What type of color codes to ignore. 'c' for cecho, 'd' for decho, 'h' for hecho, and anything else or nil to pass the string on to wordWrap
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 options
    option 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 options
    option 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))

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 options
    option 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 HERE
    false
    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
generated by LDoc 1.5.0 Last updated 2023-05-29 18:41:27