Get started with {rui}

The verb API

The 19 verbs currently implemented in {rui} are tell, entitle, inform, approve, dissapprove, begin, proceed, clear, succeed, fail, give, suggest, ask, alert, warn, error, display, expose and inspect.

Plain text messages

For plain text messages, you can use rui::tell():

rui::tell("A message without any particular prefix.")
#> A message without any particular prefix.

In most of the verbs, {glue} strings and {cli} styles are supported, so you can for instance do things like:

rui::tell("With {.fun nrow} you can see that the {.code cars} data frame has {nrow(cars)} rows.")
#> With `nrow()` you can see that the `cars` data frame has 50 rows.
rui::tell("The {.strong first 5 letters} of the alphabet are {.strong {letters[1:5]}}.")
#> The first 5 letters of the alphabet are a, b, c, d, and e.

Multi-line user feedback

For more advanced, multi-line user feedback, make use of rui::entitle(), rui::inform(), rui::approve() and rui::dissapprove():

rui::entitle("A markdown-like title")
#> # A markdown-like title
rui::inform("Provide some information to the user")
#> i Provide some information to the user
rui::approve("Approve something")
#> v Approve something
rui::disapprove("Disapprove something")
#> x Disapprove something

Single-line user feedback

With long-running tasks, it may be interesting to indicate the user that R is busy doing something. The single-line user feedback verbs rui::begin() and rui::proceed() can be used for this purpose, where rui::clear(), rui::succeed() and rui::fail() resolve the status message by removing it, or indicating success or failure respectively:

rui::begin("Analysing something")
rui::proceed("Analysing the next thing")
rui::succeed()
#> v Analysing the next thing ... done
rui::begin("Something that will fail")
rui::fail()
#> x Something that will fail ... failed
rui::begin("A message that can be cleared from the console")
rui::clear()

Note that ongoing task messages from rui::begin() or rui::proceed() are not displayed here, only the final messages that would remain visible in the console/terminal are retained. Hence, the last message is not shown at all.

User interaction

To provide the user with a piece of code to use, you can use rui::give():

rui::give("nrow(cars)")
#>  nrow(cars)

To suggest the user to do something, use rui::suggest():

rui::suggest("Restart R")
#> * Restart R

To pose a yes/no question to the user, use rui::ask():

rui::ask("Can we install this additional dependency for you?", .demo = TRUE)
#> ? Can we install this additional dependency for you?
#> 
#> 1: Yes please.
#> 2: No thanks.
#> 

Note the .demo argument is only set here to demonstrate what the message would look like, without actually waiting for a response.

Conditions

Functions rui::warn() and rui::error() are drop-in replacements for base::warning() and base::stop(). They don’t support ANSI colours however. Instead, rui::alert() can be used, and arguments warn and error can be set to TRUE if the corresponding conditions should be signalled as well:

rui::warn("Something may be wrong")
#> Something may be wrong
#> Warning: NA
rui::error("Something did go wrong", .demo = TRUE)
#> Something did go wrong
#> Error: NA
rui::alert("Something important")
#> ! Something important

Note the .demo argument is again used here to demonstrate how the error message would be printed, without actually signalling an error.

Object inspection

Finally, the verbs rui::display() and rui::expose() can be used for designing custom object print functions, where the idea is that rui::display() displays the bare contents of the object, while rui::expose() can dig deeper into an hierarchical object:

rui::display("Bare contents")
#> . Bare contents
rui::expose("Level one contents")
#> $ Level one contents
rui::expose("Level two contents", level = 2)
#> $.$ Level two contents
rui::expose("Level three contents", level = 3)
#> $.$.$ Level three contents

Both are used within rui::inspect(), which tries to provide object printing consistent with the rest of the {rui} functionality:

rui::inspect(cars)
#> # object of class "data.frame" type "list" [50x2]
#> $ speed: <dbl> 4 4 7 7 8 ...
#> $ dist : <dbl> 2 10 4 22 16 ...

The rui::console() API

The rui::console() API currently just maps prefixes to the corresponding verbs, as follows:

Prefix	Verb	Comment
	rui::tell()
#	rui::entitle()
i	rui::inform()
v	rui::approve()
x	rui::disapprove()
~	rui::begin()	Same as rui::proceed()
~	rui::proceed()	Same as rui::begin()
c	rui::clear()	Single character “c”
v	rui::succeed()	Single character “v”
x	rui::fail()	Single character “x”
=	rui::give()
*	rui::suggest()
?	rui::ask()
!	rui::alert()
w	rui::warn()
e	rui::error()
.	rui::display()
$	rui::expose()

This means that rui::console("# title") will be equivalent to rui::entitle("title"), etc. Only for object inspection, we need to use the object argument instead, to achieve the same as rui::inspect(cars):

rui::console(object = cars)
#> # object of class "data.frame" type "list" [50x2]
#> $ speed: <dbl> 4 4 7 7 8 ...
#> $ dist : <dbl> 2 10 4 22 16 ...