|
| 1 | + |
| 2 | +# Crayon - stylish terminal output in R |
| 3 | + |
| 4 | +[](https://travis-ci.org/gaborcsardi/crayon) |
| 5 | +[](https://ci.appveyor.com/project/gaborcsardi/crayon) |
| 6 | +[](http://cran.rstudio.com/web/packages/crayon/index.html) |
| 7 | +[](http://cran.r-project.org/web/packages/crayon/index.html) |
| 8 | + |
| 9 | +With crayon it is easy to add color to terminal output, create styles |
| 10 | +for notes, warnings, errors; and combine styles. |
| 11 | + |
| 12 | +ANSI color support is automatically detected and used. Crayon was largely |
| 13 | +inspired by [chalk](https://github.com/sindresorhus/chalk). |
| 14 | + |
| 15 | +## Installation |
| 16 | + |
| 17 | +```r |
| 18 | +devtools::install_github("gaborcsardi/crayon") |
| 19 | +library(crayon) |
| 20 | +``` |
| 21 | + |
| 22 | +## Styles |
| 23 | + |
| 24 | +Crayon defines several styles, that can be combined. Each style in the list |
| 25 | +has a corresponding function with the same name. |
| 26 | + |
| 27 | +### General styles |
| 28 | + |
| 29 | +* `reset` |
| 30 | +* `bold` |
| 31 | +* `blurred` (usually called `dim`, renamed to avoid name clash) |
| 32 | +* `italic` (not widely supported) |
| 33 | +* `underline` |
| 34 | +* `inverse` |
| 35 | +* `hidden` |
| 36 | +* `strikethrough` (not widely supported) |
| 37 | + |
| 38 | +### Text colors |
| 39 | + |
| 40 | +* `black` |
| 41 | +* `red` |
| 42 | +* `green` |
| 43 | +* `yellow` |
| 44 | +* `blue` |
| 45 | +* `magenta` |
| 46 | +* `cyan` |
| 47 | +* `white` |
| 48 | +* `silver` (usually called `gray`, renamed to avoid name clash) |
| 49 | + |
| 50 | +### Background colors |
| 51 | + |
| 52 | +* `bgBlack` |
| 53 | +* `bgRed` |
| 54 | +* `bgGreen` |
| 55 | +* `bgYellow` |
| 56 | +* `bgBlue` |
| 57 | +* `bgMagenta` |
| 58 | +* `bgCyan` |
| 59 | +* `bgWhite` |
| 60 | + |
| 61 | +### Screenshot on OSX |
| 62 | + |
| 63 | + |
| 64 | + |
| 65 | +## Usage |
| 66 | + |
| 67 | +The styling functions take any number of character vectors as arguments, |
| 68 | +and they concatenate and style them: |
| 69 | + |
| 70 | +```r |
| 71 | +library(crayon) |
| 72 | +cat(blue("Hello", "world!\n")) |
| 73 | +``` |
| 74 | + |
| 75 | +Crayon defines the `%+%` string concatenation operator, to make it easy |
| 76 | +to assemble stings with different styles. |
| 77 | + |
| 78 | +```r |
| 79 | +cat("... to highlight the " %+% red("search term") %+% " in a block of text\n") |
| 80 | +``` |
| 81 | + |
| 82 | +Styles can be combined using the `$` operator: |
| 83 | + |
| 84 | +```r |
| 85 | +cat(yellow$bgMagenta$bold('Hello world!\n')) |
| 86 | +``` |
| 87 | + |
| 88 | +Styles can also be nested, and then inner style takes precedence: |
| 89 | + |
| 90 | +```r |
| 91 | +cat(green( |
| 92 | + 'I am a green line ' %+% |
| 93 | + blue$underline$bold('with a blue substring') %+% |
| 94 | + ' that becomes green again!\n' |
| 95 | +)) |
| 96 | +``` |
| 97 | + |
| 98 | +It is easy to define your own themes: |
| 99 | + |
| 100 | +```r |
| 101 | +error <- red $ bold |
| 102 | +warn <- magenta $ underline |
| 103 | +note <- cyan |
| 104 | +cat(error("Error: subscript out of bounds!\n")) |
| 105 | +cat(warn("Warning: shorter argument was recycled.\n")) |
| 106 | +cat(note("Note: no such directory.\n")) |
| 107 | +``` |
| 108 | + |
| 109 | +## 256 colors |
| 110 | + |
| 111 | +Most modern terminals support the ANSI standard for 256 colors, |
| 112 | +and you can define new styles that make use of them. The `make_style` |
| 113 | +function defines a new style. It can handle R's built in color names |
| 114 | +(see the output of `colors()`), and also RGB specifications, via the |
| 115 | +`rbg()` function. It automatically chooses the ANSI colors that |
| 116 | +are closest to the specified R and RGB colors, and it also has |
| 117 | +a fallback to terminals with 8 ANSI colors only. |
| 118 | + |
| 119 | +```r |
| 120 | +ivory <- make_style("ivory") |
| 121 | +bgMaroon <- make_style("maroon", bg = TRUE) |
| 122 | +fancy <- combine_styles(ivory, bgMaroon) |
| 123 | +cat(fancy("This will have some fancy colors"), "\n") |
| 124 | +``` |
| 125 | + |
| 126 | + |
0 commit comments