printDebug: print colorized output to R console
In jmw86069/jamba: Jam Base Methods

printDebug

R Documentation

print colorized output to R console

Description

print colorized output to R console

print colorized output to R console, inverted

print colorized output to HTML

Usage

printDebug(
  ...,
  fgText = NULL,
  fgDefault = getOption("jam.fgDefault", c("darkorange1", "dodgerblue")),
  bgText = NULL,
  fgTime = getOption("jam.fgTime", "cyan2"),
  timeStamp = getOption("jam.timeStamp", TRUE),
  comment = getOption("jam.comment", !htmlOut),
  formatNumbers = getOption("jam.formatNumbers", TRUE),
  trim = getOption("jam.trim", TRUE),
  digits = getOption("jam.digits"),
  nsmall = getOption("jam.nsmall", 0L),
  justify = "left",
  big.mark = getOption("jam.big.mark", ","),
  small.mark = getOption("jam.small.mark", "."),
  zero.print = NULL,
  width = NULL,
  doColor = getOption("jam.doColor"),
  splitComments = FALSE,
  collapse = getOption("jam.collapse", ""),
  sep = getOption("jam.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)
)

printDebugI(..., invert = TRUE)

printDebugHtml(..., htmlOut = TRUE, comment = FALSE)

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: 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. When not all values in `...` represent colors, the default color set is used: `c("darkorange1", "dodgerblue")`. 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, or `character` string used as a prefix.
`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.

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, controlled by default comment=getOption("jam.comment", TRUE) which by default uses "##", but which can be defined to use a different prefix, or FALSE for no prefix at all.
each line includes time and date stamp controlled by timeStamp=getOption("jam.timeStamp", TRUE) which by default includes the current time and date.
each line formats numeric values, controlled by formatNumbers=getOption("jam.formatNumbers", TRUE), which determines whether to apply arguments big.mark and small.mark to make numeric values more readable.
each entry in ... is printed with its own foreground color fgText, background color bgText, with a slight lighter/darker dithering effect to add minor visual distinction for multiple values.
Values in each vector are concatenated by sep="," by default.
Each list is concatenated by collapse="" by default.

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).

This function prints colorized output to the R console, using the same logic as printDebug except by default the color is inverted so the default fgText colors are applied to the background.

This function prints colorized output in HTML form, using the same logic as printDebug except by default the output is HTML. The intended use is for RMarkdown with chunk option results='asis', which causes the HTML code to be interpreted directly as HTML.

This function internally calls printDebug() which then calls make_html_styles(). The text is surrounded by ⁠<span color='#FFFFFF'>⁠ HTML formatting.

Value

NULL invisibly, this function is called for the side effect of printing output using cat().

Examples

printDebug("Testing ", "default ", "printDebug().");
printDebug("List of vectors:", c("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"));
# To add a space " " between elements, use collapse
printDebug("List of vectors:", c("one", "two", "three"),
   c("four", "five", "six"), collapse=" ");

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

# when a vector entirely contains recognized colors,
# the colors are used in the output
printDebug(c("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);

# Remember the sister function that inverses the colors
printDebugI(color_vector);

printDebug(1:10, fgText="blue", dex=2);
printDebug(1:10, bgText="blue", dex=2);
printDebug(1:10, fgText="orange", dex=2);

jmw86069/jamba documentation built on Oct. 9, 2024, 10:52 a.m.