unitizer (version 1.4.9)

unitizer_prompt: Interactively Retrieve User Input

Description

Different functions used in different contexts to capture user input. unitizer_prompt, navigate_prompt, and review_prompt are more advanced and allow evaluation of arbitrary expressions, in addition to searching for specific commands such as "Y", "N", etc. simple_prompt only matches along specified values.

Usage

unitizer_prompt(text, browse.env = baseenv(), help = character(),
  help.opts = character(), valid.opts, hist.con = NULL,
  exit.condition = function(exp, env) FALSE, global, ...)

navigate_prompt(x, curr.id, text, browse.env1 = globalenv(), browse.env2 = globalenv(), help = character(), help.opts = character(), valid.opts)

review_prompt(x, nav.env)

simple_prompt(message, values = c("Y", "N"), prompt = "unitizer> ", attempts = 5L, case.sensitive = FALSE)

exit_fun(y, env, valid.vals)

read_line(prompt = "")

read_line_set_vals(vals)

interactive_mode()

Arguments

text

the prompt text to display

browse.env

the environment to evaluate user expressions in; typically this will contain interesting objects (use ls() to review)

help

a character vector with help suggestions: the first value in the vector is word_cat output, the rest normal cat

help.opts

a character vector of help options

valid.opts

the special letters user can type to get a special action, typically a character vector where the names are one letter (though they don't actually have to be) and are looked for as user typed input; note that the quit and help options will always be appended to this

hist.con

connection to save history to

exit.condition

function used to evaluate whether user input should cause the prompt loop to exit; this function should accept two parameters:

  • expression typed in by the user

  • environment the environment user expressions get evaluated in

The function can then decide to exit or not based on either the literal expression or evaluate the expression and decide based on the result. This is implemented this way because eval_user_exp will print to screen which may not be desirable. Function should return a value which will then be returned by unitizer_prompt, unless this value is FALSE in which case unitizer_prompt will continue with normal evaluation.

global

unitizerGlobal or NULL, if the global state tracking object; will be used to record state after evaluating user expressions

...

additional arguments for exit.condition

x

a unitizerBrowse object

curr.id

which id we are currently browsing

browse.env1

environment to have user review tests, run commands, etc

browse.env2

navigation environment

nav.env

an environment

message

character ask the user a question

values

character valid responses

prompt
attempts

how many times to try before erroring

case.sensitive

whether to care about case sensitivity when matching user input

Value

  • unitizer_prompt: mixed allowable user input

  • navigate_prompt: a unitizerBrowse object, or allowable user input

  • review_prompt: a unitizerBrowse object, or "Q" if the user chose to quit

  • simple_prompt: one of values as selected by user

Details

The set-up is intended to replicate something similar to what happens when code hits a browse() statement. User expressions are evaluated and output to screen, and special expressions as described above cause the evaluation loop to terminate.

navigate_prompt is just a wrapper around unitizer_prompt that provides the special shortcuts to navigate to other tests in the unitizer.

review_prompt is also a wrapper, but used only when at the menu that presents available test items to navigate to.

simple_prompt simpler prompting function used to allow user to select from pre-specified values.

exit_fun is used as a generic function to pass to the exit.condition argument of unitizer_prompt.

read_line and read_line_set_vals are utility functions that are used to implement a version of readline that can be automated for testing.

interactive_mode returns interactive status, accounting for whether we are in faux-interactive mode as set by read_line_set_vals

See Also

browse_unitizer_items