ask
ask copied to clipboard
Friendly CLI interaction in R
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.