Helpers for Developing Command Line Interfaces

A suite of tools to build attractive command line interfaces ('CLIs'), from semantic elements: headings, lists, alerts, paragraphs, etc. Supports custom themes via a 'CSS'-like language. It also contains a number of lower level 'CLI' elements: rules, boxes, trees, and 'Unicode' symbols with 'ASCII' alternatives. It integrates with the 'crayon' package to support 'ANSI' terminal colors.

It integrates well with crayon for coloring the boxes or their content, It can draw rules and boxes to make headers or footers in console output, and tree structures. It includes a set of Unicode characters, with fallbacks on systems that do not support them.

• Installation
• Usage
  • Unicode characters
  • Spinners
  • Rules
  • Boxes
  • Trees
• License

Install the stable version from CRAN:

install.packages("cli")

Install the development version from GitHub:

source("https://install-github.me/r-lib/cli")

Usage

library(cli)

Unicode characters

Inspired by (and mostly copied from) the figures JavaScript project.

#> ✔    tick                      ☐ checkbox_off           
#> ✖    cross                     ⓧ checkbox_circle_on     
#> ★    star                      Ⓘ checkbox_circle_off    
#> ▇    square                    ❓ fancy_question_mark    
#> ◻    square_small              ≠ neq                    
#> ◼    square_small_filled       ≥ geq                    
#> ◯    circle                    ≤ leq                    
#> ◉    circle_filled             × times                  
#> ◌    circle_dotted             ▔ upper_block_1          
#> ◎    circle_double             ▀ upper_block_4          
#> ⓞ    circle_circle             ▁ lower_block_1          
#> ⓧ    circle_cross              ▂ lower_block_2          
#> Ⓘ    circle_pipe               ▃ lower_block_3          
#> ?⃝   circle_question_mark      ▄ lower_block_4          
#> ●    bullet                    ▅ lower_block_5          
#> ․    dot                       ▆ lower_block_6          
#> ─    line                      ▇ lower_block_7          
#> ═    double_line               █ lower_block_8          
#> …    ellipsis                  █ full_block             
#> …    continue                  ⁰ sup_0                  
#> ❯    pointer                   ¹ sup_1                  
#> ℹ    info                      ² sup_2                  
#> ⚠    warning                   ³ sup_3                  
#> ☰    menu                      ⁴ sup_4                  
#> ☺    smiley                    ⁵ sup_5                  
#> ෴    mustache                  ⁶ sup_6                  
#> ♥    heart                     ⁷ sup_7                  
#> ↑    arrow_up                  ⁸ sup_8                  
#> ↓    arrow_down                ⁹ sup_9                  
#> ←    arrow_left                ⁻ sup_minus              
#> →    arrow_right               ⁺ sup_plus               
#> ◉    radio_on                  ▶ play                   
#> ◯    radio_off                 ■ stop                   
#> ☒    checkbox_on               ● record

Spinners

See list_spinners() and get_spinner(). From the awesome cli-spinners project.

Rules

Simple rule

rule()

Double rule

rule(line = 2)

Bars

rule(line = "bar2")

rule(line = "bar5")

Left label

rule(left = "Results")

Centered label

rule(center = " * RESULTS * ")

Colored labels

rule(center = crayon::red(" * RESULTS * "))

Colored label and line

rule(center = " * RESULTS * ", col = "red")

Colored line

rule(center = " * RESULTS * ", line_col = "red")

Custom line

rule(center = "TITLE", line = "~")

More custom line

rule(center = "TITLE", line = "~-", line_col = "blue")

Even more custom line

rule(center = crayon::bgRed(" ", symbol$star, "TITLE", symbol$star, " "),
  line = "\u2582", line_col = "orange")

Boxes

Default box

boxx("Hello there!")

Change border style

boxx("Hello there!", border_style = "double")

Multiple lines

boxx(c("Hello", "there!"), padding = 1)

Padding

boxx("Hello there!", padding = 1)

boxx("Hello there!", padding = c(1, 5, 1, 5))

Margin

boxx("Hello there!", margin = 1)

boxx("Hello there!", margin = c(1, 5, 1, 5))

boxx("Hello there!", padding = 1, margin = c(1, 5, 1, 5))

Floating

boxx("Hello there!", padding = 1, float = "center")

boxx("Hello there!", padding = 1, float = "right")

Text color

boxx(crayon::cyan("Hello there!"), padding = 1, float = "center")

Backgorund color

boxx("Hello there!", padding = 1, background_col = "brown")

boxx("Hello there!", padding = 1, background_col = crayon::bgRed)

Border color

boxx("Hello there!", padding = 1, border_col = "green")

boxx("Hello there!", padding = 1, border_col = crayon::red)

Label alignment

boxx(c("Hi", "there", "you!"), padding = 1, align = "left")

boxx(c("Hi", "there", "you!"), padding = 1, align = "center")

boxx(c("Hi", "there", "you!"), padding = 1, align = "right")

A very customized box

star <- symbol$star
label <- c(paste(star, "Hello", star), "  there!")
boxx(
  crayon::white(label),
  border_style="round",
  padding = 1,
  float = "center",
  border_col = "tomato3",
  background_col="darkolivegreen"
)

Trees

You can specify the tree with a two column data frame, containing the node ids/labels, and the list of their children.

data <- data.frame(
  stringsAsFactors = FALSE,
  package = c("processx", "backports", "assertthat", "Matrix",
    "magrittr", "rprojroot", "clisymbols", "prettyunits", "withr",
    "desc", "igraph", "R6", "crayon", "debugme", "digest", "irlba",
    "rcmdcheck", "callr", "pkgconfig", "lattice"),
  dependencies = I(list(
    c("assertthat", "crayon", "debugme", "R6"), character(0),
    character(0), "lattice", character(0), "backports", character(0),
    c("magrittr", "assertthat"), character(0),
    c("assertthat", "R6", "crayon", "rprojroot"),
    c("irlba", "magrittr", "Matrix", "pkgconfig"), character(0),
    character(0), "crayon", character(0), "Matrix",
    c("callr", "clisymbols", "crayon", "desc", "digest", "prettyunits",
      "R6", "rprojroot", "withr"),
    c("processx", "R6"), character(0), character(0)
  ))
)
tree(data, root = "rcmdcheck")

An optional third column may contain custom labels. These can be colored as well:

data$label <- paste(data$package,
  crayon::blurred(paste0("(", c("2.0.0.1", "1.1.1", "0.2.0", "1.2-11",
    "1.5", "1.2", "1.2.0", "1.0.2", "2.0.0", "1.1.1.9000", "1.1.2",
    "2.2.2", "1.3.4", "1.0.2", "0.6.12", "2.2.1", "1.2.1.9002",
    "1.0.0.9000", "2.0.1", "0.20-35"), ")"))
  )
roots <- ! data$package %in% unlist(data$dependencies)
data$label[roots] <- crayon::cyan(crayon::italic(data$label[roots]))
tree(data, root = "rcmdcheck")

License

MIT © RStudio