alert_help: Console-Based User Dialog
In j-martineau/uj: Utilities by JAM
alert_help R Documentation
Console-Based User Dialog
Description
All functions collapse ... args into a d-delimited prompt. Each posts an alert to the console, posts the prompt (if any), and follows up with a specific action.
Usage
alert_help()
alert(
...,
title = "alert",
sub = "",
ps = "",
def = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
acknowledge(
...,
sub = "",
ps = "",
ft = "r|w|b",
fs = "k|y|p",
fp = "k|y|i",
d = " ",
clear = FALSE
)
choose1(opts, ..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
chooseN(
opts,
...,
n = NULL,
min = NULL,
max = NULL,
all = base::is.null(c(n, max)),
none = FALSE,
ft = "r|w|b",
fs = "k|y|p",
d = " ",
clear = FALSE
)
NO(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
YES(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
OK(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
CANCEL(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
ask(
...,
Default = "",
sub = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
ask_new(
old,
type = "replacement values",
u = TRUE,
sub = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = "|",
clear = FALSE
)
choose_dir(
dir.type = "directory",
sub = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
choose_doc(
doc.type = "document",
sub = "",
ft = "r|w|b",
fs = "",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
Arguments
...
An arbitrary, optional number of arguments which are atomized into a character scalar message to be posted to the console.
title
A title for the alert (type = 'error' results in stopping execution after posting the alert). Should be short to avoid formatting problems.
sub
A character scalar alert subtitle to post to the console on the line following the title. Should be short to avoid formatting problems.
ps
A character scalar suffix to post to the console on the line following the alert message contained in ....
def
A character scalar containing a default message if atomizing and collapsing ... to a character scalar results in a blank string ("").
ft, fs, fm, fp
Formatting values consistent with the description in the specifying formats section giving formatting instructions for, respectively, the title (in title), subtitle (in sub), message (in ...), and postscript (in ps).
d
A character scalar delimiter for collapsing ... args into a character scalar.
clear
A non-NA logical scalar indicating whether to clear the console before each interaction with the user.
opts
An atomic vector listing opts to choose from.
n
An optional complete positive numeric whole-number scalar (?cmp_psw_scl) indicating the number of opts that must be selected. Must be contained in 1:length(opts).
min
An optional complete positive numeric whole-number scalar indicating the minimum number of opts that may be selected. Must be NULL when n is non-NULL.
max
An optional complete positive numeric whole-number scalar indicating the maximum number of opts that may be selected. Must be NULL when n is non-NULL.
all
Scalar TRUE or FALSE indicating whether to add an { ALL } value to opts.
none
Scalar TRUE or FALSE indicating whether to add a { NONE } value to opts (implying that it is valid to select none).
old
A character vec of unique values to be replaced.
type
A character scalar describing the type of replacement values to be entered.
u
Scalar TRUE or FALSE indicating whether replacement values must be unique.
Details
The following give templates for what the user sees, where any value derived from arguments will be absent if it is a blank string or resolves to a blank string.
alert
CONDITION VALUE
g(d, title) != "" formatted title from title.
g(d, sub) != "" formatted subtitle from sub.
g(d, ...) != "" formatted message from ....
< blank line >
g(d, ps) != "" formatted postscript from ps.
all other templates incorporate a call to alert(.) with components as shown below.
acknowledge
COMPONENT VALUE
Title 'ACKNOWLEDGMENT REQUIRED'
Subtitle '< g(d, sub) >'
Message '< g(d, ...) >'
< blank line >
Postscript 'press [return] or [enter] to continue:'
choose1
COMPONENT VALUE
title 'RESPONSE REQUIRED'
Subtitle '< g(d, sub) >'
Message '< g(d, ...) >'
< blank line >
Postscript 'choose an option - Select one'
< blank line >
CANCEL.Option 'X: { CANCEL }'
Option.1 '1: < opts[1] >'
Option.2 '2: < opts[2] >'
... ...
Option.N '< N >: < opts[n] >'
Prompt 'Selection:'
chooseN
COMPONENT VALUE
Title 'RESPONSE REQUIRED'
Subtitle '< g(d, sub) >'
Message '< g(d, ...) >'
< blank line >
Postscript 'choose < n | between n1 and n2 > opts - Select one or more'
< blank line >
CANCEL.Option 'X: { CANCEL }'
Option.1 '1: < opts[1] >'
Option.2 '2: < opts[2] >'
... ...
Option.N '< N >: < opts[n] >'
ALL.option 'A: { ALL }'
NONE.option 'N: { NONE }'
Prompt 'Enter one or more numbers separated by spaces and then ENTER, or 0 to cancel'
NO and YES
COMPONENT VALUE
Title 'RESPONSE REQUIRED'
Subtitle '< g(d, sub) >'
Message '< g(d, ...) >'
< blank line >
Postscript 'choose an option - Select one'
< blank line >
CANCEL.Option '1: { CANCEL }'
YES.option '2: { YES }'
NO.option '3: { NO }'
Prompt 'Selection:'
OK and CANCEL
COMPONENT VALUE
Title 'RESPONSE REQUIRED'
Subtitle '< g(d, sub) >'
Message '< g(d, ...) >'
< blank line >
Postscript 'choose an option - Select one'
< blank line >
CANCEL.Option '1: { CANCEL }'
OK.option '2: { OK }'
Prompt 'Selection: '
ask
COMPONENT VALUE
Title 'RESPONSE REQUIRED'
Subtitle '< g(d, sub) >'
Message '< g(d, ...) >'
< blank line >
Postscript 'enter your response: '
ask_new
COMPONENT VALUE
Title 'RESPONSE REQUIRED'
Subtitle '< g(d, sub) >'
Message 'Enter a pipe-separated list of < N(opts) > replacement values
for the following pipe-separated original values: '
< blank line >
Old.Values '< paste0(old, collapse = " | ") >'
< blank line >
Postscript 'enter your response: '
choose_dir
COMPONENT VALUE
Title 'ACKNOWLEDGMENT REQUIRED'
Subtitle '< g(d, sub) >'
Message 'In the next dialog box, select a < dir.type >.'
choose_doc
COMPONENT VALUE
Title 'ACKNOWLEDGMENT REQUIRED'
Subtitle '< g(d, sub) >'
Message 'In the next dialog box, select a < doc.type >.'
Value
The NULL object
acknowledge, alert
A character scalar
choose_dir (a directory path)
choose_doc (a document path)
ask
A character vector
ask_new
An atomic vector
chooseN
An atomic scalar
choose1
A logical scalar
CANCEL, YES, NO, OK
Functions
-
alert(): Collapses ... into an alert message using d as a delimiter and issues the alert to the console with the specified title, subtitle, postscript and style/color formatting. Clears the console first if clear = TRUE.
-
acknowledge(): Posts an alert message with the title ACKNOWLEDGMENT REQUIRED and waits for the user to press the [return] or [enter] key.
-
choose1(): Posts an alert message and prompts the user to select one of the options in opts.
-
chooseN(): Posts an alert message and prompts the user to select from 0 to N of the N options in opts. The minimum and maximum number of options to be selected are controlled by the arguments n, min, max, all, and none.
-
NO(): Posts an alert message and prompts the user to choose either yes or no as a response. Returns TRUE when the user chooses yes. Returns FALSE when the user chooses no.
-
YES(): Posts an alert message and prompts the user to choose either yes or no as a response. Returns TRUE when the user chooses no. Returns FALSE when the user chooses yes.
-
OK(): Posts an alert message and prompts the user to choose either ok or cancel as a response. Returns TRUE when the user chooses ok. Returns FALSE when the user chooses cancel.
-
CANCEL(): Posts an alert message and prompts the user to choose either ok or cancel as a response. Returns TRUE when the user chooses cancel. Returns FALSE when the user chooses ok.
-
ask(): Posts an alert question and prompts the user to answer the question via entering text and hitting return or enter. Returns the entered text.
-
ask_new(): Posts an alert message describing multiple values and prompts the user to enter new/replacement values. Returns a vector of new/replacement values.
-
choose_dir(): Posts an alert message notifying the user that a dialog box will open and prompting the user to choose a directory/folder. Returns the path to the selected directory/folder.
-
choose_doc(): Posts an alert message notifying the user that a dialog box will open and prompting the user to choose a file/document. Returns the path to the selected file/document.
Specifying formats
When formatting arguments (ft, fs, fm, and fp) take the special value "", the corresponding alert elements (title, sub, ..., and ps, respectively) are posted to the console without special formatting.
Otherwise, formatting arguments must be complete string vecs that when atomized and split along pipes results in a three-element character vector, the first element of which is used to specify text background color and must be a value from bg_vals(), the second element of which is used to specify text foreground color and must be a value from fg_vals(), and the last of which specifies text style and must be a value from st_vals().
Examples
## Not run:
egAlert <- function() {
partA <- "two-part"
partB <- "message"
fmtT <- base::c("yellow", "red", "plain")
fmtS <- base::c("blk|wht", "und")
fmtM <- "b|y|i"
title <- "Title"
sub <- "Subtitle"
opts <- base::paste("option", letters[1:10])
mssg1 <- "Do you want to continue?"
mssg2 <- "Why do you want to continue?"
uj::alert(partA, partB, d = " ")
uj::alert(partA, partB, title = title, d = " ")
uj::alert(partA, partB, sub = sub, d = " ")
uj::alert(partA, partB, title = title, sub = sub, d = " ")
uj::alert(partA, partB, title = title, sub = sub, d = " ", fm = fmtM)
uj::alert(partA, partB, title = title, sub = sub, d = " ", fs = fmtS)
uj::alert(partA, partB, title = title, sub = sub, d = " ", ft = fmtT)
uj::alert(partA, partB, title = title, sub = sub, d = " ", ft = fmtT, fs = fmtS, fm = fmtM)
uj::alert(title = title, sub = sub, ft = fmtT, fs = fmtS)
uj::alert(title = title, sub = sub)
uj::alert(sub = sub, fs = fmtS)
uj::acknowledge(partA, partB)
ch1 <- uj::choose1(opts)
ch2 <- uj::chooseN(opts)
ch3 <- uj::chooseN(opts, all = T, none = F, min = 6, max = 10)
no <- uj::NO(mssg1)
ok <- uj::OK(mssg2)
yes <- uj::YES(mssg1)
can <- uj::CANCEL(mssg1)
ASK <- uj::ask(mssg2)
NEW <- uj::ask_new(opts)
dir <- uj::choose_dir(dir.type = "directory for R scripts")
doc <- uj::choose_doc(doc.type = "document to read")
base::list(ch1 = ch1, ch2 = ch2, ch3 = ch3, no = no , ok = ok, yes = yes,
can = can, ASK = ASK, NEW = NEW, dir = dir, doc = doc)
}
egAlert()
## End(Not run)
j-martineau/uj documentation built on Sept. 14, 2024, 4:40 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| alert_help | R Documentation |
Console-Based User Dialog
Description
All functions collapse ... args into a d-delimited prompt. Each posts an alert to the console, posts the prompt (if any), and follows up with a specific action.
Usage
alert_help()
alert(
...,
title = "alert",
sub = "",
ps = "",
def = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
acknowledge(
...,
sub = "",
ps = "",
ft = "r|w|b",
fs = "k|y|p",
fp = "k|y|i",
d = " ",
clear = FALSE
)
choose1(opts, ..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
chooseN(
opts,
...,
n = NULL,
min = NULL,
max = NULL,
all = base::is.null(c(n, max)),
none = FALSE,
ft = "r|w|b",
fs = "k|y|p",
d = " ",
clear = FALSE
)
NO(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
YES(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
OK(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
CANCEL(..., ft = "r|w|b", fs = "k|y|p", d = " ", clear = FALSE)
ask(
...,
Default = "",
sub = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
ask_new(
old,
type = "replacement values",
u = TRUE,
sub = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = "|",
clear = FALSE
)
choose_dir(
dir.type = "directory",
sub = "",
ft = "r|w|b",
fs = "k|y|p",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
choose_doc(
doc.type = "document",
sub = "",
ft = "r|w|b",
fs = "",
fm = "",
fp = "k|y|i",
d = " ",
clear = FALSE
)
Arguments
... |
An arbitrary, optional number of arguments which are atomized into a character scalar message to be posted to the console. |
title |
A title for the alert ( |
sub |
A character scalar alert subtitle to post to the console on the line following the title. Should be short to avoid formatting problems. |
ps |
A character scalar suffix to post to the console on the line following the alert message contained in |
def |
A character scalar containing a default message if atomizing and collapsing |
ft, fs, fm, fp |
Formatting values consistent with the description in the specifying formats section giving formatting instructions for, respectively, the title (in |
d |
A character scalar delimiter for collapsing |
clear |
A non- |
opts |
An atomic vector listing opts to choose from. |
n |
An optional complete positive numeric whole-number scalar (?cmp_psw_scl) indicating the number of opts that must be selected. Must be contained in |
min |
An optional complete positive numeric whole-number scalar indicating the minimum number of opts that may be selected. Must be |
max |
An optional complete positive numeric whole-number scalar indicating the maximum number of opts that may be selected. Must be |
all |
Scalar |
none |
Scalar |
old |
A character vec of unique values to be replaced. |
type |
A character scalar describing the type of replacement values to be entered. |
u |
Scalar |
Details
The following give templates for what the user sees, where any value derived from arguments will be absent if it is a blank string or resolves to a blank string.
alert
| CONDITION | VALUE | ||
g(d, title) != "" | formatted title from title. |
||
g(d, sub) != "" | formatted subtitle from sub. |
||
g(d, ...) != "" | formatted message from .... |
||
< blank line > |
|||
g(d, ps) != "" | formatted postscript from ps. |
all other templates incorporate a call to alert(.) with components as shown below.
acknowledge
| COMPONENT | VALUE | ||
| Title | 'ACKNOWLEDGMENT REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | '< g(d, ...) >' |
||
< blank line > |
|||
| Postscript | 'press [return] or [enter] to continue:' |
choose1
| COMPONENT | VALUE | ||
| title | 'RESPONSE REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | '< g(d, ...) >' |
||
< blank line > |
|||
| Postscript | 'choose an option - Select one' |
||
< blank line > |
|||
| CANCEL.Option | 'X: { CANCEL }' |
||
| Option.1 | '1: < opts[1] >' |
||
| Option.2 | '2: < opts[2] >' |
||
| ... | ... | ||
| Option.N | '< N >: < opts[n] >' |
||
| Prompt | 'Selection:' |
chooseN
| COMPONENT | VALUE | ||
| Title | 'RESPONSE REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | '< g(d, ...) >' |
||
< blank line > |
|||
| Postscript | 'choose < n | between n1 and n2 > opts - Select one or more' |
||
< blank line > |
|||
| CANCEL.Option | 'X: { CANCEL }' |
||
| Option.1 | '1: < opts[1] >' |
||
| Option.2 | '2: < opts[2] >' |
||
| ... | ... | ||
| Option.N | '< N >: < opts[n] >' |
||
| ALL.option | 'A: { ALL }' |
||
| NONE.option | 'N: { NONE }' |
||
| Prompt | 'Enter one or more numbers separated by spaces and then ENTER, or 0 to cancel' |
NO and YES
| COMPONENT | VALUE | ||
| Title | 'RESPONSE REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | '< g(d, ...) >' |
||
< blank line > |
|||
| Postscript | 'choose an option - Select one' |
||
< blank line > |
|||
| CANCEL.Option | '1: { CANCEL }' |
||
| YES.option | '2: { YES }' |
||
| NO.option | '3: { NO }' |
||
| Prompt | 'Selection:' |
OK and CANCEL
| COMPONENT | VALUE | ||
| Title | 'RESPONSE REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | '< g(d, ...) >' |
||
< blank line > |
|||
| Postscript | 'choose an option - Select one' |
||
< blank line > |
|||
| CANCEL.Option | '1: { CANCEL }' |
||
| OK.option | '2: { OK }' |
||
| Prompt | 'Selection: ' |
ask
| COMPONENT | VALUE | ||
| Title | 'RESPONSE REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | '< g(d, ...) >' |
||
< blank line > |
|||
| Postscript | 'enter your response: ' |
ask_new
| COMPONENT | VALUE | ||
| Title | 'RESPONSE REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | 'Enter a pipe-separated list of < N(opts) > replacement values |
||
for the following pipe-separated original values: ' |
|||
< blank line > |
|||
| Old.Values | '< paste0(old, collapse = " | ") >' |
||
< blank line > |
|||
| Postscript | 'enter your response: ' |
choose_dir
| COMPONENT | VALUE | ||
| Title | 'ACKNOWLEDGMENT REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | 'In the next dialog box, select a < dir.type >.' |
choose_doc
| COMPONENT | VALUE | ||
| Title | 'ACKNOWLEDGMENT REQUIRED' |
||
| Subtitle | '< g(d, sub) >' |
||
| Message | 'In the next dialog box, select a < doc.type >.' |
Value
The NULL object
acknowledge, alert
A character scalar
choose_dir (a directory path)
choose_doc (a document path)
ask
A character vector
ask_new
An atomic vector
chooseN
An atomic scalar
choose1
A logical scalar
CANCEL, YES, NO, OK
Functions
-
alert(): Collapses...into an alert message usingdas a delimiter and issues the alert to the console with the specified title, subtitle, postscript and style/color formatting. Clears the console first ifclear = TRUE. -
acknowledge(): Posts an alert message with the titleACKNOWLEDGMENT REQUIREDand waits for the user to press the[return]or[enter]key. -
choose1(): Posts an alert message and prompts the user to select one of the options inopts. -
chooseN(): Posts an alert message and prompts the user to select from0toNof theNoptions inopts. The minimum and maximum number of options to be selected are controlled by the argumentsn,min,max,all, andnone. -
NO(): Posts an alert message and prompts the user to choose eitheryesornoas a response. ReturnsTRUEwhen the user choosesyes. ReturnsFALSEwhen the user choosesno. -
YES(): Posts an alert message and prompts the user to choose eitheryesornoas a response. ReturnsTRUEwhen the user choosesno. ReturnsFALSEwhen the user choosesyes. -
OK(): Posts an alert message and prompts the user to choose eitherokorcancelas a response. ReturnsTRUEwhen the user choosesok. ReturnsFALSEwhen the user choosescancel. -
CANCEL(): Posts an alert message and prompts the user to choose eitherokorcancelas a response. ReturnsTRUEwhen the user choosescancel. ReturnsFALSEwhen the user choosesok. -
ask(): Posts an alert question and prompts the user to answer the question via entering text and hitting return or enter. Returns the entered text. -
ask_new(): Posts an alert message describing multiple values and prompts the user to enter new/replacement values. Returns a vector of new/replacement values. -
choose_dir(): Posts an alert message notifying the user that a dialog box will open and prompting the user to choose a directory/folder. Returns the path to the selected directory/folder. -
choose_doc(): Posts an alert message notifying the user that a dialog box will open and prompting the user to choose a file/document. Returns the path to the selected file/document.
Specifying formats
When formatting arguments (ft, fs, fm, and fp) take the special value "", the corresponding alert elements (title, sub, ..., and ps, respectively) are posted to the console without special formatting.
Otherwise, formatting arguments must be complete string vecs that when atomized and split along pipes results in a three-element character vector, the first element of which is used to specify text background color and must be a value from bg_vals(), the second element of which is used to specify text foreground color and must be a value from fg_vals(), and the last of which specifies text style and must be a value from st_vals().
Examples
## Not run:
egAlert <- function() {
partA <- "two-part"
partB <- "message"
fmtT <- base::c("yellow", "red", "plain")
fmtS <- base::c("blk|wht", "und")
fmtM <- "b|y|i"
title <- "Title"
sub <- "Subtitle"
opts <- base::paste("option", letters[1:10])
mssg1 <- "Do you want to continue?"
mssg2 <- "Why do you want to continue?"
uj::alert(partA, partB, d = " ")
uj::alert(partA, partB, title = title, d = " ")
uj::alert(partA, partB, sub = sub, d = " ")
uj::alert(partA, partB, title = title, sub = sub, d = " ")
uj::alert(partA, partB, title = title, sub = sub, d = " ", fm = fmtM)
uj::alert(partA, partB, title = title, sub = sub, d = " ", fs = fmtS)
uj::alert(partA, partB, title = title, sub = sub, d = " ", ft = fmtT)
uj::alert(partA, partB, title = title, sub = sub, d = " ", ft = fmtT, fs = fmtS, fm = fmtM)
uj::alert(title = title, sub = sub, ft = fmtT, fs = fmtS)
uj::alert(title = title, sub = sub)
uj::alert(sub = sub, fs = fmtS)
uj::acknowledge(partA, partB)
ch1 <- uj::choose1(opts)
ch2 <- uj::chooseN(opts)
ch3 <- uj::chooseN(opts, all = T, none = F, min = 6, max = 10)
no <- uj::NO(mssg1)
ok <- uj::OK(mssg2)
yes <- uj::YES(mssg1)
can <- uj::CANCEL(mssg1)
ASK <- uj::ask(mssg2)
NEW <- uj::ask_new(opts)
dir <- uj::choose_dir(dir.type = "directory for R scripts")
doc <- uj::choose_doc(doc.type = "document to read")
base::list(ch1 = ch1, ch2 = ch2, ch3 = ch3, no = no , ok = ok, yes = yes,
can = can, ASK = ASK, NEW = NEW, dir = dir, doc = doc)
}
egAlert()
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.