Chalk-Lua

A Lua port of the open source JS terminal string styling library Chalk.

---

Installation

Add this package to your [dependencies] in your rotriever.toml.
``
Chalk = "github.com/roblox/chalk-lua@0.2.0"
`

Run rotrieve install to install the package.

Require it at the top of your file.
`lua
local chalk = require(Packages.Chalk)
`

---

API

chalk.style(string) to style a string (or tostring-able object) with any of the following modifiers, colors or color models.

$3

* reset - Resets the current color chain.
* bold - Make text bold.
* dim - Emitting only a small amount of light.
italic - Make text italic. (Not widely supported)*
underline - Make text underline. (Not widely supported)*
* inverse- Inverse background and foreground colors.
* hidden - Prints the text, but makes it invisible.
strikethrough - Puts a horizontal line through the center of the text. (Not widely supported)*

$3

* black
* red
* green
* yellow
* blue
* magenta
* cyan
* white
* blackBright (alias: gray, grey)
* redBright
* greenBright
* yellowBright
* blueBright
* magentaBright
* cyanBright
* whiteBright

$3

* bgBlack
* bgRed
* bgGreen
* bgYellow
* bgBlue
* bgMagenta
* bgCyan
* bgWhite
* bgBlackBright (alias: bgGray, bgGrey)
* bgRedBright
* bgGreenBright
* bgYellowBright
* bgBlueBright
* bgMagentaBright
* bgCyanBright
* bgWhiteBright

Styles can be nested to apply multiple styles at the same time.
`lua
chalk.red(chalk.bold('red and bold'))
`
Later styles take precedence in case of a conflict (multiple nested styles of the same type). For example, chalk.red(chalk.blue(chalk.green('green'))) will output green text.

Styles can be concatenated with .. to be composed and stored.
`lua
local errorMessage = chalk.red..chalk.bold
errorMessage('red and bold')
`

The following color models can also be used:
`lua
-- accepts ANSI16 color codes
chalk.ansi(31)('red') -- valid values: 30-37, 90-97
chalk.bgAnsi(41)('bgRed') -- valid values: 40-47, 100-107

-- accepts ANSI256 color codes
chalk.ansi256(196)('#ff0000') -- valid values: 0-255
chalk.bgAnsi256(196)('#ff0000') -- valid values: 0-255

-- downsamples to a valid ANSI256 color
chalk.rgb(255, 0, 0)('#ff0000')
chalk.bgRgb(255, 0, 0)('#ff0000')

chalk.hex('#ff0000')('red')
chalk.bgHex('#ff0000')('red')
`

chalk.level specifies the level of color support. This can be set by setting chalk.level to a different value, for example, chalk.level = 0 to disable color support. Note that this will affect all uses of chalk throughout the entire module. The default value is 2. The flag NOCOLOR can be set with --lua.globals=NOCOLOR=true to set the default value to 0.
| Level | Description |
| :---: | :--- |
| 0 | All colors disabled |
| 2 | 256 color support |

---

Unsupported features

* chalk.level - only suppors either level 2 or level 0
* No automatic detection of terminal color support
* Level 3 isn't supported so rgb and hex will downsample to the closest ANSI256 color
* Level 1 isn't supported so color models with ANSI256 support (ansi256, rgb, hex) will never downsample to ANSI16
* The following color models:
* chalk.keyword
* chalk.hsl
* chalk.hsv
* chalk.hwb
* Can't method chain styles together like JS chalk, prefer to nest them instead. If they need to be composed together to be stored, use the concatenation (..) operator.
`lua
-- chalk.red.bold('foo')
chalk.red(chalk.bold('foo'))

-- const errorMessage = chalk.red.bold
local errorMessage = chalk.red..chalk.bold
`
* Can't nest styles of the same "type" (foreground or background color), prefer to split them up. Styles of different types can be nested, however, still prefer to split them up for consistency.
`lua
-- chalk.blue('blue' + chalk.red('red') + 'blue')
chalk.blue('blue' .. chalk.red('red') .. 'not blue')
chalk.blue('blue') .. chalk.red('red') .. chalk.blue('blue')
``