print colorized output to R console
print colorized output to R console, inverted
print colorized output to HTML
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)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.
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.
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.
character R color to colorize the time
logical whether to include a time stamp in output
logical whether to prefix output with '## ' as a comment,
or character string used as a prefix.
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.
arguments passed to format().
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.
logical whether to color each element independently
without light-dark alternating pattern. The intensity of the
adjustment is controlled by dex passed to color2gradient().
character collapse string used to separate list items,
by default "" so text separation is expected in the input data.
character separator used to separate vector elements, when
a list items contains a vector.
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.
logical whether to detect and potentially try to
correct console color capabilities.
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.
numeric arguments deprecated.
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).
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.
logical whether to remove NA values and not print to
the console.
character or NULL, optionally replace NULL elements
with non-NULL character value, otherwise NULL elements are ignored.
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.
logical whether to delimit lists by line instead of
using collapse to combine them onto one line.
logical whether to print verbose output
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.
argument passed to cat() to send output to a file or
compatible output of cat().
logical whether to append output, passed to cat()
when file is defined.
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.
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.
NULL invisibly, this function is called for the side effect
of printing output using cat().
NULL invisibly, this function is called for the side effect
of printing output using cat().
NULL invisibly, this function is called for the side effect
of printing output using cat().
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:
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.
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(),
renameColumn(),
rmInfinite(),
rmNAs(),
rmNA(),
rmNULL(),
sclass(),
sdim(),
setPrompt()
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(),
renameColumn(),
rmInfinite(),
rmNAs(),
rmNA(),
rmNULL(),
sclass(),
sdim(),
setPrompt()
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(),
renameColumn(),
rmInfinite(),
rmNAs(),
rmNA(),
rmNULL(),
sclass(),
sdim(),
setPrompt()
printDebug("Testing ", "default ", "printDebug().");
#> ## (13:43:43) 10Jun2024: Testing default printDebug().
printDebug("List of vectors:", c("one", "two", "three"));
#> ## (13:43:43) 10Jun2024: 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"));
#> ## (13:43:43) 10Jun2024: 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=" ");
#> ## (13:43:43) 10Jun2024: 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 ");
#> ## (13:43:43) 10Jun2024: 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"));
#> ## (13:43:43) 10Jun2024: 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);
#> ## (13:43:43) 10Jun2024: group_A,group_B,group_C,group_D
# Remember the sister function that inverses the colors
printDebugI(color_vector);
#> ## (13:43:43) 10Jun2024: group_A,group_B,group_C,group_D
printDebug(1:10, fgText="blue", dex=2);
#> ## (13:43:43) 10Jun2024: 1,2,3,4,5,6,7,8,9,10
printDebug(1:10, bgText="blue", dex=2);
#> ## (13:43:43) 10Jun2024: 1,2,3,4,5,6,7,8,9,10
printDebug(1:10, fgText="orange", dex=2);
#> ## (13:43:43) 10Jun2024: 1,2,3,4,5,6,7,8,9,10