Helpers for Developing Command Line Interfaces

A suite of tools designed to build attractive command line interfaces ('CLIs'). Includes tools for drawing rules, boxes, trees, and 'Unicode' symbols with 'ASCII' alternatives.


Linux Build Status Windows Build status CRAN RStudio mirror downloads Coverage Status

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

devtools::install_github("r-lib/cli")

Usage

library(cli)

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

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

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

News

0.0.0.9000

First public release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("cli")

1.0.0 by Gábor Csárdi, a year ago


https://github.com/r-lib/cli#readme


Report a bug at https://github.com/r-lib/cli/issues


Browse source code at https://github.com/cran/cli


Authors: Gábor Csárdi [aut, cre], Hadley Wickham [ctb], Kirill Müller [ctb]


Documentation:   PDF Manual  


MIT + file LICENSE license


Imports assertthat, crayon, methods

Suggests covr, mockery, testthat, withr


Imported by CrossClustering, GA, RxODE, available, blorr, diceR, eplusr, furniture, jsonstat, jtools, ncodeR, nlmixr, olsrr, openVA, pillar, pkgdown, psychReport, psychmeta, rcmdcheck, sars, sinew, skimr, styler, testthat, tibble, tidyhydat, tidymodels, tidyverse.

Suggested by checkpoint.


See at CRAN