inst/README.md

In gaborcsardi/ask: Friendly Command Line Interface Tools

Friendly R CLI

ask helps build friendly command line interfaces

Introduction

Command line interfaces don't have to be grey and boring. Just because some ancient terminals do not support color, Unicode glyphs and cursor movement, that does not mean that we can't use them on newer ones.

ask makes use of terminal colors and other advanced properties that are actually supported by 99.9% of the terminals today.

Sadly, some commonly used R IDEs do not emulate a terminal at all, so ask() will look a lot less nice in these (but it will still work fine): R Studio R.app (the default OS X R GUI) RWin (the default Windows R GUI) Emacs ESS

ask was inspired by the Inquirer.js project.

Installation

Once on CRAN, you can install the package with:

install.packages("ask")

Usage

Call the ask() function with all your questions to the user, and the answers are returned in a list. See various question types below.

Typical usage looks like this. (The example is taken from Inquirer.js.)

library(ask)
message("Welcome to R Pizza!")
ask(
  to_be_delivered = confirm("Is it for a delivery?", default = FALSE),
  phone = input("What's your phone number?",
    validate = function(v) {
      good <- grepl("^[- 0-9\\(\\)]+$", v) &&
              nchar(gsub("[^0-9]", "", v)) == 10
      if (good) TRUE else "Please enter a valid phone number"
  }),
  size = choose("What size do you need?", c("Large", "Medium", "Small")),
  quantity = input("How many do you need?", validate = function(v) {
      good <- !is.na(as.integer(v))
      if (good) TRUE else "Please enter a number"
    }, filter = as.integer),
  toppings = choose("What about the topping?",
    c("Peperonni and cheese", "All dressed", "Hawaïan")),
  toppings_extra = checkbox("Extra toppings?",
    c("Peperonni", "Ham", "Extra Cheese", "Olives", "Mushrooms", "Chilis")),
  beverage = choose("You also get a free 2L beverage",
    c("Pepsi", "7up", "Coke")),
  comments = input("Any comments about your purchase experience?",
    default = "Nope, all good!"),
  prize = choose("For leaving a comment, you get a freebie",
    c("Cake", "Fries"), when = function(a) a$comments != "Nope, all good!")
)

The result is the answer list, a named list:

$to_be_delivered
[1] FALSE

$phone
[1] "555-555-5555"

$size
[1] "Medium"

$quantity
[1] 2

$toppings
[1] "Peperonni and cheese"

$beverage
[1] "Pepsi"

$comments
[1] "Nice CLI!"

$prize
[1] "Cake"

The ask() function takes named arguments only: * Each argument corresponds to a question to the user. * The name of the argument is the identifier of the question, the answer will have the same name in the result list. * Each argument is a function call. The name of the function is the type of the question. See question types below. * Questions are asked in the order they are given. See Conditional execution below for more flexible workflows.

Question types

input: one line of text

confirm: a yes-no question

choose: choose one item from a list

checkbox: select multiple values from a list

constant: not a question, defines a constant

This is sometimes useful.

Conditional execution

The when argument to a question can be used for conditional execution of questions. If it is given (and not NULL), then it must be a function. It is called with the answers list up to that point, and it should return TRUE or FALSE. For TRUE, the question is shown to the user and the result is inserted into the answer list. For FALSE, the question is not shown, and the answer list is not chagned.

License

MIT © Gábor Csárdi.

gaborcsardi/ask documentation built on Dec. 27, 2021, 9:56 a.m.