setPrompt: set R prompt with project name and R version

In jmw86069/jamba: Jam Base Methods

set R prompt with project name and R version

Description

set R prompt with project name and R version

Usage

setPrompt(
  projectName = NULL,
  useColor = TRUE,
  projectColor = "yellow",
  bracketColor = "white",
  Rcolors = c("white", "white", "white"),
  PIDcolor = NA,
  promptColor = "white",
  usePid = TRUE,
  resetPrompt = FALSE,
  addEscape = NULL,
  debug = FALSE,
  verbose = FALSE,
  ...
)

Arguments

projectName	character string representing the active project.
useColor	logical whether to define a color prompt if the crayon package is installed.
projectColor, bracketColor, Rcolors, PIDcolor, promptColor	character colors used when useColor==TRUE and the crayon package is installed: projectColor colors the project name; bracketColor colors the curly brackets around the project; Rcolors can be a vector of 3 colors, colorizing "R", the "-" divider, and the R version; PIDcolor colors the PID when usePid=TRUE; and promptColor colors the ">" at the end of the prompt.
usePid	logical whether to include the process ID in the prompt. Including the PID is helpful for the rare occasion when a process is hung and needs to be stopped directly.
resetPrompt	logical whether to revert all changes to the prompt back to the default R prompt, that is, no color and no projectName.
addEscape	logical or NULL indicating whether to wrap color encoding ANSI inside additional escape sequences. This change is helpful for linux-based (readline-based) R consoles, by telling the console not to count ANSI color control characters as visible characters when determining word wrapping on the console. Note that RStudio does not work well with this setting. If you find that the word-wrap is incorrect in the R console, try addEscape=TRUE. Apparently most versions of RStudio will already adjust (and prevent) colorizing the prompt during editing, presumably to sidestep the problem of calculating the correct character length. By default when addEscape is NULL, it checks whether environmental variable RSTUDIO equals "1" (running inside RStudio) then sets addEscape=FALSE; otherwise it defines addEscape=TRUE. In most cases for commandline prompts, addEscape=TRUE is helpful and not problematic.
debug	logical indicating whether to print the ANSI control character output for the full prompt, for visual review.
verbose	logical whether to print verbose output.
...	additional parameters are passed to make_styles() which is only relevant with the argument useColor=TRUE.

Details

This function sets the R prompt including project name, the R version, and the process ID. It is intended to be useful by reinforcing the active project for an R session, particularly when there may be multiple R sessions active. The R version can be useful when running R on different machines, to reinforce which version of R is active on the given machine. The process ID is mainly helpful in the event an R process spins out of control, and it would be useful to know definitively which exact process ID is stuck, so that it can be killed without affecting other R sessions inadvertently.

The prompt is defined in options("prompt").

Note that in some cases, the color encoding of the prompt interferes with word wrapping, the symptom is that when typing text into the R console a long line will begin to word wrap prematurely, before the text reaches the edge of the screen. There are two frequent causes of this issue:

options("width")

is sometimes defined too narrow for the screen, which can happen when resizing the console, or when accessing an R session via GNU screen, or tmux, and the environment variable has not been propagated to the terminal window. Usually this issue is resolved by defining options("width") manually, or by simply resizing the terminal window, which may trigger the appropriate environment variable updates.

The locale

can sometimes be mismatched with the terminal window, usually caused by some terminal emulation layer which is not properly detecting the compatibility of the server. It may happen for example, when using PuTTY on Windows, or when using GNU screen or tmux on linux or Mac OSX. To troubleshoot, check Sys.env("LC_ALL") which may be "C" or another locale such as "en_US.UTF-8". Note that switching locale may have the effect of correcting the word wrap, but may adversely affect display of non-standard unicode characters.

In any event, R uses readline for unix-like systems by default, and issues related to using color prompt are handled at that level. For example, in some Mac OSX consoles, there are alternate color escape sequences which are used to tell readline to ignore an escape sequence when it counts the number of characters being displayed by the prompt.

Value

character string representing the prompt used, returned invisibly.

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(), printDebug(), renameColumn(), rmInfinite(), rmNAs(), rmNA(), rmNULL(), sclass(), sdim()

Examples

## Not run: 
setPrompt("jamba", projectColor="purple");
setPrompt("jamba", usePid=FALSE);

## End(Not run)

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