Package 'colorout' reference manual

Title:	Colorize R Output on Terminal Emulators
Description:	Colorize R output when it is running on a terminal emulator. The functions of this package only work if R is compiled for Unix systems and it is running interactively in a terminal emulator. The terminal must support Select Graphic Rendition (SGR, also known as ANSI escape codes or sequences). The package contains a C library with a function that replaces the default Rstd_WriteConsoleEx which, when enabled, is responsible for printing messages in the Console when R is running in interactive mode. It works with RStudio, but there is no support for Graphical User Interfaces that does not support ANSI colors, such as Windows RGui.
Authors:	Jakson Aquino and Dominique-Laurent Couturier
Maintainer:	Jakson Alves de Aquino <[email protected]>
License:	GPL (>= 2)
Version:	1.3-2
Built:	2024-10-15 01:04:51 UTC
Source:	https://github.com/jalvesaq/colorout

Colorize R output on terminal emulators

Description

Colorize R output when it is running on a Unix terminal emulator. The library also works within RStudio, but there is no support for other Graphical User Interfaces, such as Windows RGui, RKward, JGR, Rcmdr that cannot display ANSI colors. It also did not work with Emacs with ess. The functions of this package only work if R is compiled for Unix systems (e.g., Linux and OS X) and it is running interactively in a terminal emulator. The terminal emulator might have been called by a text editor, such as Vim, Gedit, Kate or Geany.

Homepage: https://github.com/jalvesaq/colorout

Screenshot:

Details

The terminal must support Select Graphic Rendition (SGR, also known as ANSI escape codes or sequences), otherwise you may see garbage like this:

    > rnorm(5)
    [32m[ [33m1 [32m] [0m [32m  [33m0.07574585 [32m [0m [32m
    [33m0.88167822 [32m [0m [32m  [33m0.60788656 [32m [0m [32m
    [33m1.13590951 [32m [0m [32m  [33m1.07758879 [32m [0m [32m [0m

The package contains a C library with a function that replaces the default Rstd_WriteConsoleEx which, when enabled, is responsible for printing messages in the Console when R is running in interactive mode. R should be built against libreadline since libedit may cause issues.

The function that enables the colorization of R output is ColorOut, and it is called automatically when the package is loaded. However, it will do nothing if Sys.getenv("TERM") returns either "" or "dumb". The output will not be colorized also if the result of either interactive() or isatty(stdout()) is FALSE. You can change this behavior by putting in your ‘⁠~/.Rprofile⁠’ one or more of the following options:

    options(colorout.verbose = 0)
    options(colorout.anyterm = TRUE)
    options(colorout.dumb = TRUE)
    options(colorout.noninteractive = TRUE)
    options(colorout.notatty = TRUE)

With colorout.anyterm == TRUE, the package will not check the ‘⁠TERM⁠’ environment variable, and it will also not test whether R is running interactively. If your terminal emulator is capable of displaying ANSI colors but is not being recognized you may put the following in your ‘⁠~/.Rprofile⁠’:

    if(interactive()){
        options(colorout.anyterm = TRUE)
        library(colorout)
    }

And of course, you can use any arbitrary condition to decide whether to load colorout or not. For instance:

    if(isatty(stdout())){
        options(colorout.anyterm = TRUE)
        library(colorout)
    }

If colorout.verbose > 0, the package will display a warning if the output is not going to be colorized.

A 256 color scheme is used by default. If your terminal emulator only supports 8 colors, you will have to set your own color scheme. Please, see the example at setOutputColors.

Author(s)

Jakson Alves de Aquino [email protected] and Dominique-Laurent Couturier [email protected].

Add custom pattern to be colorized

Description

Enable colorizing of custom patterns.

Usage

addPattern(pattern, color)
addPattern(pattern, color)

Arguments

`pattern`	String representing the pattern to be colorized. The patterns are literal strings. The only two types of regular expression accepted are (1) a range of ASCII characters surrounded by square brackets and separated by a hyphen and (2) either an ASCII character or a range of ASCII characters followed by an asterisk (see section Examples below).
`color`	Formating and color of the pattern (see the Details section in `setOutputColors`).

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Examples

# Slash separated date (YYYY-MM-DD):
addPattern("[1-2][0-9][0-9][0-9]/[0-1][0-9]/[0-3][0-9]", 179)

# Date in Year-quarter format:
addPattern("[1-2][0-9][0-9][0-9] Q[0-4]", 179)

# Date in "Month Year" format (Not perfect; it will wrongly colorize strings
# such as"Not 2019"):
addPattern("[A-S][a-u][b-z] [1-2][0-9][0-9][0-9]", 179)

# If all columns in a data.frame start with the letter 'q' followed by a
# number end, in some cases, by other letters, colorize them:
addPattern("q[0-9]*", 123)
addPattern("q[0-9]*[a-z]*", 123)
# Slash separated date (YYYY-MM-DD):
addPattern("[1-2][0-9][0-9][0-9]/[0-1][0-9]/[0-3][0-9]", 179)

# Date in Year-quarter format:
addPattern("[1-2][0-9][0-9][0-9] Q[0-4]", 179)

# Date in "Month Year" format (Not perfect; it will wrongly colorize strings
# such as"Not 2019"):
addPattern("[A-S][a-u][b-z] [1-2][0-9][0-9][0-9]", 179)

# If all columns in a data.frame start with the letter 'q' followed by a
# number end, in some cases, by other letters, colorize them:
addPattern("q[0-9]*", 123)
addPattern("q[0-9]*[a-z]*", 123)

Colorize R output in terminal emulator

Description

Colorize output of R running in a terminal emulator. The function is called automatically when the package is loaded.

Usage

ColorOut()
ColorOut()

Details

The library works within RStudio, but there is no support for Graphical User Interfaces, that does not support ANSI colors. If running in a terminal emulator, it must support ANSI escape codes. Please, read colorout-package for more details.

Emacs/ESS users should read colorout-package to know how to enable and use the package.

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Delete custom pattern that was being colorized

Description

Do not colorize previously defined string pattern.

Usage

deletePattern(pattern)
deletePattern(pattern)

Arguments

pattern

String representing the pattern to be colorized. The patterns are literal strings.

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Examples

# Slash separated date (YYYY-MM-DD):
deletePattern("[1-2][0-9][0-9][0-9]/[0-1][0-9]/[0-3][0-9]")

# Delete all user defined patterns:
deletePattern(listPatterns())
# Slash separated date (YYYY-MM-DD):
deletePattern("[1-2][0-9][0-9][0-9]/[0-1][0-9]/[0-3][0-9]")

# Delete all user defined patterns:
deletePattern(listPatterns())

Check if colorizing of R output is enabled

Description

Function to check if colorizing of R output is enabled.

Usage

isColorOut()
isColorOut()

Value

TRUE if the colorizing of R output is enabled and FALSE otherwise.

Author(s)

Neal Fultz and Jakson Aquino [email protected]

List custom defined patterns that are colorized

Description

List patterns defined by users in their colors.

Usage

listPatterns()
listPatterns()

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Stop colorizing R output

Description

Stop colorizing R output.

Usage

noColorOut()
noColorOut()

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Set the Colors to Be Used on R Output

Description

Set the output colors to be used if R is running in a terminal emulator. The terminal must be capable of displaying 256 colors. See a screenshot at colorout-package.

Usage

setOutputColors(normal = 40, negnum = 209, zero = 226,
                number = 214, date = 179, string = 85,
                const = 35, false = 203, true = 78,
                infinite = 39, index = 30, stderror = 213,
                warn = c(1, 16, 196), error = c(160, 231),
                verbose = TRUE, zero.limit = NA)
setOutputColors(normal = 40, negnum = 209, zero = 226,
                number = 214, date = 179, string = 85,
                const = 35, false = 203, true = 78,
                infinite = 39, index = 30, stderror = 213,
                warn = c(1, 16, 196), error = c(160, 231),
                verbose = TRUE, zero.limit = NA)

Arguments

`normal`	Formating and color of normal text.
`negnum`	Formating and color of negative numbers.
`zero`	Formating and color of values being close to 0.
`number`	Formating and color of positive numbers.
`date`	Formating and color of dates and hours. For dates, the output format should be ‘⁠YYYYxMMxDD⁠’ or ‘⁠DDxMMxYYYY⁠’, where the separator x may equal '-' or '/'. For hours, the output format should be ‘⁠HH:MM:SS⁠’.
`string`	Formating and color of quoted text.
`const`	Formating and color of `NULL`, `NA` and `NaN`.
`false`	Formating and color of `FALSE`.
`true`	Formating and color of `TRUE`.
`infinite`	Formating and color of `Inf` and `-Inf`.
`index`	Formating and color of vector indexes.
`stderror`	Formating and color of text sent to stderr.
`warn`	Formating and color of warnings.
`error`	Formating and color of errors.
`verbose`	Logical value indicating whether to print colored words showing the result of the setup.
`zero.limit`	The limit below which a value is considered close to 0. If set, the colorizing of zero and values near zero is enabled. You can also use the function `setZero` to set this value at any time and `unsetZero` to disable the colorizing of values near zero.

Details

The function takes numeric vectors of at most three elements each. The three numbers indicate, respectively, formating, background color and foreground color. If a vector has only one element, the number will be used to set the foreground color; if it has two elements, they will be used to set the background and foreground colors.

If you pass a string as a color, it will be used as is. Thus, you should pass valid strings (please, see the true color example below). The string must have at most 63 characters.

The table below shows valid formating values (some formating codes do not work properly in some terminal emulators):

Value	Formating
0	No formating
1	Bold or bright
2	Faint
3	Italic or inverse
4	Underline
5	Blink slowly
6	Blink quickly
7	Invert

The values of ANSI escape codes for 256 colors are different than the ones used in the function setOutputColors. Run show256Colors to to get a table of the 256 colors and their codes.

Messages are colored as errors and warnings if they start with "Error" or "Warning" (or their translations, if not running in an English locale).

If the ‘⁠TERM⁠’ environment variable is "fbterm", fbterm escape codes will be used instead of the ANSI ones and the format values will be ignored.

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Examples

# Color scheme for terminal emulator with only 8 colors:
setOutputColors(normal = 2, negnum = 3, zero = 3, number = 3,
                date = 3, string = 6, const = 5, false = 5,
                true = 2, infinite = 5, index = 2, stderror = 4,
                warn = c(1, 0, 1), error = c(1, 7),
                verbose = TRUE, zero.limit = NA)

# Color scheme for white background:
setOutputColors(normal = c(0, 0, 18), number = c(0, 0, 90),
                negnum = c(0, 0, 88), date = c(0, 0, 53),
                string = c(0, 0, 22), const = c(0, 0, 94), stderror = 52)

# Color schemes for black background:
setOutputColors(normal = 39, negnum = 183, zero = 114, number = 51,
                date = 43, string = 79, const = 75, zero.limit = 0.1)
setOutputColors(normal = 202, number = 214, zero = 220, negnum = 209,
                date = 184, string = 172, const = 179, zero.limit = 0.01)
setOutputColors(normal = 202, number = 214, zero = NA, negnum = 209,
                date = 184, string = 172, const = 179, zero.limit = 0.01)

# True color example:
# The color code starts with "\x1b[" and ends with "m"
# 38;2 means "foreground"
# 48;2 means "background"
# valid values for red, green, and blue are integers between 0 and 255
setOutputColors(normal   = "\x1b[38;2;0;200;0m",     # red = 0; green = 200; blue = 0
                negnum   = "\x1b[38;2;255;200;0m",
                zero     = "\x1b[38;2;255;255;0m",
                number   = "\x1b[38;2;200;255;75m",
                date     = "\x1b[38;2;155;155;255m",
                string   = "\x1b[38;2;0;255;175m",
                const    = "\x1b[38;2;0;255;255m",
                false    = "\x1b[38;2;255;125;125m",
                true     = "\x1b[38;2;125;255;125m",
                infinite = "\x1b[38;2;75;75;255m",
                index    = "\x1b[38;2;00;150;80m",
                stderror = "\x1b[38;2;255;0;255m",
                warn     = "\x1b[38;2;255;0;0m",
                error    = "\x1b[38;2;255;255;255;48;2;255;0;0m",
                zero.limit = 0.01)
# Color scheme for terminal emulator with only 8 colors:
setOutputColors(normal = 2, negnum = 3, zero = 3, number = 3,
                date = 3, string = 6, const = 5, false = 5,
                true = 2, infinite = 5, index = 2, stderror = 4,
                warn = c(1, 0, 1), error = c(1, 7),
                verbose = TRUE, zero.limit = NA)

# Color scheme for white background:
setOutputColors(normal = c(0, 0, 18), number = c(0, 0, 90),
                negnum = c(0, 0, 88), date = c(0, 0, 53),
                string = c(0, 0, 22), const = c(0, 0, 94), stderror = 52)

# Color schemes for black background:
setOutputColors(normal = 39, negnum = 183, zero = 114, number = 51,
                date = 43, string = 79, const = 75, zero.limit = 0.1)
setOutputColors(normal = 202, number = 214, zero = 220, negnum = 209,
                date = 184, string = 172, const = 179, zero.limit = 0.01)
setOutputColors(normal = 202, number = 214, zero = NA, negnum = 209,
                date = 184, string = 172, const = 179, zero.limit = 0.01)

# True color example:
# The color code starts with "\x1b[" and ends with "m"
# 38;2 means "foreground"
# 48;2 means "background"
# valid values for red, green, and blue are integers between 0 and 255
setOutputColors(normal   = "\x1b[38;2;0;200;0m",     # red = 0; green = 200; blue = 0
                negnum   = "\x1b[38;2;255;200;0m",
                zero     = "\x1b[38;2;255;255;0m",
                number   = "\x1b[38;2;200;255;75m",
                date     = "\x1b[38;2;155;155;255m",
                string   = "\x1b[38;2;0;255;175m",
                const    = "\x1b[38;2;0;255;255m",
                false    = "\x1b[38;2;255;125;125m",
                true     = "\x1b[38;2;125;255;125m",
                infinite = "\x1b[38;2;75;75;255m",
                index    = "\x1b[38;2;00;150;80m",
                stderror = "\x1b[38;2;255;0;255m",
                warn     = "\x1b[38;2;255;0;0m",
                error    = "\x1b[38;2;255;255;255;48;2;255;0;0m",
                zero.limit = 0.01)

Deprecated Function

Description

This function is deprecated. Use setOutputColors instead.

Usage

setOutputColors256(...)
setOutputColors256(...)

Arguments

...

Arguments to be passed to setOutputColors.

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Enable colorizing of numbers near zero

Description

Enable colorizing of numbers near zero

Usage

setZero(z = 1e-12)
setZero(z = 1e-12)

Arguments

`z`	The limit below which a value is considered close to 0.

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Create and show a table with 256 colors

Description

Create and show a table with 256 colors and their ANSI escape codes. The table should be displayed in your browser. You have to hover the mouse over the colors to see their codes.

Usage

show256Colors(outfile = "/tmp/table256.html")
show256Colors(outfile = "/tmp/table256.html")

Arguments

outfile

String. Path to file where the table will be saved.

Value

NULL.

Author(s)

Jakson A. Aquino [email protected], based on code from Todd Larason (‘⁠256colors.pl⁠’) and Ben Fritz (‘⁠2html.vim⁠’).

Stop colorizing numbers near zero

Description

Stop colorizing numbers near zero

Usage

unsetZero()
unsetZero()

Value

NULL.

Author(s)

Jakson A. Aquino [email protected]

Package 'colorout'

Help Index

Colorize R output on terminal emulators

Description

Details

Author(s)

See Also

Add custom pattern to be colorized

Description

Usage

Arguments

Value

Author(s)

Examples

Colorize R output in terminal emulator

Description

Usage

Details

Value

Author(s)

Delete custom pattern that was being colorized

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Check if colorizing of R output is enabled

Description

Usage

Value

Author(s)

List custom defined patterns that are colorized

Description

Usage

Value

Author(s)

Stop colorizing R output

Description

Usage

Value

Author(s)

Set the Colors to Be Used on R Output

Description

Usage

Arguments

Details

Value

Author(s)

Examples

Deprecated Function

Description

Usage

Arguments

Value

Author(s)

Enable colorizing of numbers near zero

Description

Usage

Arguments

Value

Author(s)

See Also

Create and show a table with 256 colors

Description

Usage

Arguments

Value

Author(s)

Stop colorizing numbers near zero

Description

Usage

Value

Author(s)

See Also