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.



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

News

1.0.1

  • New cli_sitrep() function, situation report about UTF-8 and ANSI color support (#53).

  • Fall back to ASCII only characters on non-Windows platforms without UTF-8 support, and also in LaTeX when running knitr (#34).

1.0.0

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.1 by Gábor Csárdi, 2 months 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, utils

Suggests covr, fansi, mockery, testthat, webshot, withr


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

Suggested by checkpoint.


See at CRAN