print colorized output to R console

print colorized output to R console

printDebug(
  ...,
  fgText = NULL,
  fgDefault = c("darkorange1", "dodgerblue"),
  bgText = NULL,
  fgTime = "cyan",
  timeStamp = TRUE,
  comment = getOption("jam.comment", TRUE),
  formatNumbers = getOption("jam.formatNumbers", TRUE),
  trim = getOption("jam.trim", TRUE),
  digits = NULL,
  nsmall = 0L,
  justify = "left",
  big.mark = getOption("jam.big.mark", ""),
  small.mark = getOption("jam.small.mark", ""),
  zero.print = NULL,
  width = NULL,
  doColor = NULL,
  splitComments = FALSE,
  collapse = "",
  sep = ",",
  doReset = NULL,
  detectColors = TRUE,
  dex = 2,
  darkFactor = c(1, 1.5),
  sFactor = c(1, 1.5),
  lightMode = checkLightMode(),
  Crange = getOption("jam.Crange"),
  Lrange = getOption("jam.Lrange"),
  removeNA = FALSE,
  replaceNULL = NULL,
  adjustRgb = getOption("jam.adjustRgb"),
  byLine = FALSE,
  verbose = FALSE,
  indent = "",
  keepNA = TRUE,
  file = getOption("jam.file", ""),
  append = getOption("jam.append", TRUE),
  invert = getOption("jam.invert", FALSE),
  htmlOut = getOption("jam.htmlOut", FALSE),
  x
)

Arguments

...

character, factor, numeric or compatible atomic vectors to be printed to the R console. These arguments are recognized as any un-named argument, or any argument whose name does not match the named arguments below.

fgText

one of two formats to define the foreground color for elements in ... being printed. Each element is colored in order, and when multiple vector values are contained in one ... element, the color defined in fgText is extended. The input types recognized:

• NULL when no color is defined, one of two outputs:

  1. When all values in ... represent colors, these colors are used to colorize the output text. When names() are present they are used as the text labels in place of the vector value.

  2. When not all values in ... represent colors, the default color set is used: c("darkorange1", "dodgerblue").

  3. To disable option 1 above, define a specific value for fgText, such as fgText=c("darkorange1", "dodgerblue").

• vector of R compatible colors, recycled to the length of .... When any element of ... is a vector with multiple values, the corresponding color in fgText is shaded slightly lighter and darker, then recycled to the vector length, so that adjacent values have slightly different color. This behavior is controlled by default argument splitComments=TRUE.

• list of vectors of R compatible colors, recycled to the length of ..., then applied to each element in ... in order. When only one color is defined, and multiple values are present in the corresponding list element, the color is shaded slightly lighter and darker, then recycled to the vector length, as described above. This behavior is controlled by default argument splitComments=TRUE. When multiple colors are defined for the list element, these values are recycled to the vector length.

• Note: When invert=TRUE the values for fgText and bgText are reversed, and if the resulting fgText is NULL then its color is defined by setTextContrastColor() in order to define a contrasting text color.

bgText

vector of R colors, or list of vectors, used to define the background color, using the same approach described for fgText. Note that NULL or NA defines the absence of any background color, which is default. When invert=TRUE, which is default for printDebugI(), the values for fgText and bgText are reversed.

fgTime

character R color to colorize the time

timeStamp

logical whether to include a time stamp in output

comment

logical whether to prefix output with '##' as a comment

formatNumbers

logical whether to format numbers using format() which controls the number of digits displayed, and is default. When formatNumbers=FALSE sometimes numeric values that contain integers may be represented as 14.0000000001.

trim, digits, nsmall, justify, big.mark, small.mark, zero.print, width

arguments passed to format().

doColor

logical or NULL indicating whether to colorize output. When doColor is NULL, if the "crayon" package is available, and if crayon detects color is permitted, color is enabled.

splitComments

logical whether to color each element independently without light-dark alternating pattern. The intensity of the adjustment is controlled by dex passed to color2gradient().

collapse

character collapse string used to separate list items, by default "" so text separation is expected in the input data.

sep

character separator used to separate vector elements, when a list items contains a vector.

doReset

logical or NULL, indicating whether to apply crayon::reset() to the delimiter sep. When doReset=TRUE the style on the delimiter is forced to reset, using crayon::reset(), or to remove pre-existing style with crayon::strip_style(). When doReset=NULL and sep contains ANSI escape characters, they are left as-is; when doReset=NULL and sep does not contain ANSI escape characters, sep becomes crayon::reset(sep) which forces the style to be reset between printed values.

detectColors

logical whether to detect and potentially try to correct console color capabilities.

dex

numeric passed to color2gradient() to split a color into a lighter,darker alternating pattern. Until version 0.0.83.900, this process used gradientWtFactor=1 and was not adjustable. Note that when splitComments=TRUE the input values in ... are flattened to a single vector, and colors in fgText are applied directly without adjustment.

darkFactor, sFactor

numeric arguments deprecated.

lightMode

logical or NULL, indicating whether the text background color is light, where lightMode=TRUE indicates the background is white or light enough to require darker text, imposing a maximum brightness for colors displayed. When NULL it calls checkLightMode(), which uses:

• getOption("jam.lightMode") if defined

• otherwise attempts to detect whether the session is running inside RStudio, by checking for environmental variable "RSTUDIO", under the assumption that default RStudio uses a light background, therefore lightMode=TRUE.

• if steps above fail, it uses lightMode=FALSE.

• to force a specific lightMode for all uses, use options: options(jam.lightMode=TRUE) or options(jam.lightMode=FALSE).

Crange, Lrange

numeric range of chroma and luminance values between 0 and 100. When NULL, default values are assigned by setCLranges(). The intent is to restrict the range relative to the console background color, also controlled by lightMode.

removeNA

logical whether to remove NA values and not print to the console.

replaceNULL

character or NULL, optionally replace NULL elements with non-NULL character value, otherwise NULL elements are ignored.

adjustRgb

numeric value adjustment used during the conversion of RGB colors to ANSI colors, which is inherently lossy. If not defined, it uses the default returned by setCLranges() which itself uses getOption("jam.adjustRgb") with default=0. In order to boost color contrast, an alternate value of -0.1 is suggested.

byLine

logical whether to delimit lists by line instead of using collapse to combine them onto one line.

verbose

logical whether to print verbose output

indent

character optional characters used as a prefix to indent output. When numeric it is rounded to integer, then this many character spaces " " are concatenated together to define the indent width. Note that the indent text is not colorized.

file

argument passed to cat() to send output to a file or compatible output of cat().

append

logical whether to append output, passed to cat() when file is defined.

invert

logical indicating whether foreground and background colors should be switched, as is default for printDebugI(). Note when the resulting fgText is NULL, its color is defined by setTextContrastColor() to define a contrasting text color relative to the background color in bgText.

htmlOut

logical indicating whether to print HTML span output, using format <span style="color:fg;background-color:bg">text</span>. This argument is not yet implemented, more testing is required to determine the best mechanism to use for things like RMarkdown rendering, and R-shiny app rendering.

Value

This function is called for the by-product of printing debug output, it returns invisible(NULL), no output.

Details

This function prints colorized output to the R console, with some rules for colorizing the output to help visually distinguish items.

The main intent is to use this function to print pretty debug messages, because color helps identify.

By default, output has the following configurable properties:

• each line begins with a comment '#' characters with argument comment=TRUE or options("jam.comment"=TRUE) so that the output can be copied and pasted and without causing new commands to be run.

• each line includes time and date stamp (timeStamp=TRUE)

• each line formats numeric values (formatNumbers=TRUE or options("jam.formatNumbers"=TRUE))

• each list is printed with its own foreground color (fgText) and background color (bgText), recycled to accommodate all list arguments to be printed; within each list, the color brightness is adjusted for slightly lighter and darker color to delineate each item in the vector. The lightness effect is used to help visualize multiple values.

Additional convenience rules:

• For convenience, when the last ... argument is a character vector of colors, it is assumed to be fgText.

• When the only entry in ... is a character vector of R colors, the names are printed using the color vector for fgText, or if no names exist the colors are printed using the color vector for fgText.

• For printDebugI() or invert=TRUE, colors typically assigned to fgText are instead assigned to bgText.

• For very specific color assignments, fgText and/or bgText can be defined as a list of character vectors of R colors, in which case the list overall is recycled to the length ... to be printed, and within each vector of ... printed the corresponding color vector is recycled to the length of that vector.

For use inside Rmarkdown .Rmd documents, current recommendation is to define the R output with results='asis' like this:

\`\`\`{r block_name, results='asis'}
# some R code here
\`\`\`

Then define a global option to turn off the comment prefix in printDebug(): options("jam.comment"=FALSE)

For colorized text, it may require "html_output" rendering of the .Rmd Rmarkdown file, as well as this option to enable HTML formatting by printDebug(): options("jam.htmlOut"=TRUE).

See also

Other jam practical functions: breakDensity(), checkLightMode(), check_pkg_installed(), colNum2excelName(), color_dither(), diff_functions(), exp2signed(), fileInfo(), fixYellow(), getAxisLabel(), handleArgsText(), heads(), isFALSEV(), isTRUEV(), jamba, jargs(), kable_coloring(), lldf(), log2signed(), make_html_styles(), make_styles(), match_unique(), mergeAllXY(), middle(), minorLogTicks(), newestFile(), printDebugI(), renameColumn(), rmInfinite(), rmNAs(), rmNA(), rmNULL(), sclass(), sdim(), setPrompt()

Examples

printDebug("Testing ", "default ", "printDebug().");
#> ##  (19:07:45) 10Aug2023:   Testing default printDebug(). 
printDebug("List of vectors:", c("one", "two", "three"));
#> ##  (19:07:45) 10Aug2023:   List of vectors:one,two,three 

# By default, there is no space between separate elements in `...`
printDebug("List of vectors:", c("one", "two", "three"),
   c("four", "five", "six"));
#> ##  (19:07:45) 10Aug2023:   List of vectors:one,two,threefour,five,six 
# To add a space " " between elements, use collapse
printDebug("List of vectors:", c("one", "two", "three"),
   c("four", "five", "six"), collapse=" ");
#> ##  (19:07:46) 10Aug2023:   List of vectors: one, two, three four, five, six 

# slightly different style, one entry per line, indented:
printDebug("List of vectors:", c("one", "two", "three"),
   c("four", "five", "six"), collapse="\n   ");
#> ##  (19:07:46) 10Aug2023:   List of vectors:
#>    one,
#>    two,
#>    three
#>    four,
#>    five,
#>    six 

# when a vector entirely contains recognized colors,
# the colors are used in the output
printDebug(c("red", "blue", "yellow"));
#> ##  (19:07:46) 10Aug2023:      red,blue,yellow 

# When the vector contains colors, the names are used as the label
color_vector <- jamba::nameVector(c("red", "blue", "green","orange"),
   c("group_A", "group_B", "group_C", "group_D"));
printDebug(color_vector);
#> ##  (19:07:46) 10Aug2023:      group_A,group_B,group_C,group_D 

# Remember the sister function that inverses the colors
printDebugI(color_vector);
#> ##  (19:07:46) 10Aug2023:      group_A,group_B,group_C,group_D 

printDebug(1:10, fgText="blue", dex=2);
#> ##  (19:07:46) 10Aug2023:   1,2,3,4,5,6,7,8,9,10 
printDebug(1:10, bgText="blue", dex=2);
#> ##  (19:07:46) 10Aug2023:   1,2,3,4,5,6,7,8,9,10 
printDebug(1:10, fgText="orange", dex=2);
#> ##  (19:07:46) 10Aug2023:   1,2,3,4,5,6,7,8,9,10