Utilities to display messages using string_magic interpolation and operations to generate the message.
cat_magic_alias(
.sep = "",
.end = "",
.width = FALSE,
.leader = "",
.vectorize = FALSE,
.delim = c("{", "}"),
.last = NULL,
.collapse = NULL,
.trigger = TRUE,
.check = TRUE,
.namespace = NULL
)
message_magic_alias(
.sep = "",
.end = "\n",
.width = "min(100, .sw)",
.leader = "",
.vectorize = FALSE,
.delim = c("{", "}"),
.last = NULL,
.collapse = NULL,
.trigger = TRUE,
.check = TRUE,
.namespace = NULL
)
cat_magic(
...,
.sep = "",
.end = "",
.width = FALSE,
.leader = "",
.envir = parent.frame(),
.vectorize = FALSE,
.delim = c("{", "}"),
.last = NULL,
.collapse = NULL,
.trigger = TRUE,
.check = TRUE,
.help = NULL,
.namespace = NULL
)
catma(
...,
.sep = "",
.end = "",
.width = FALSE,
.leader = "",
.envir = parent.frame(),
.vectorize = FALSE,
.delim = c("{", "}"),
.last = NULL,
.collapse = NULL,
.trigger = TRUE,
.check = TRUE,
.help = NULL,
.namespace = NULL
)
message_magic(
...,
.sep = "",
.end = "\n",
.width = NULL,
.leader = "",
.envir = parent.frame(),
.vectorize = FALSE,
.delim = c("{", "}"),
.last = NULL,
.collapse = NULL,
.trigger = TRUE,
.check = TRUE,
.help = NULL,
.namespace = NULL
)
mema(
...,
.sep = "",
.end = "\n",
.width = NULL,
.leader = "",
.envir = parent.frame(),
.vectorize = FALSE,
.delim = c("{", "}"),
.last = NULL,
.collapse = NULL,
.trigger = TRUE,
.check = TRUE,
.help = NULL,
.namespace = NULL
)Character scalar, default is the empty string "". It is used to collapse all
the elements in ... before applying any operation.
Character scalar, default is "" (the empty string) for cat_magic,
and "\n" (a newline) for message_magic.
This string will be collated at the end of the message (a common alternative is "\n").
Can be 1) a positive integer, 2) a number in (0;1), 3) FALSE (default
for cat_magic), or 4) NULL (default for message_magic). It represents the target
width of the message on the user console. Newlines will be added between words to fit the
target width.
positive integer: number of characters
number (0;1): fraction of the screen
FALSE: does not add newlines
NULL: the min between 100 characters and 90% of the screen width
Note that you can use the special variable .sw to refer to the screen width. Hence the value
NULL is equivalent to using min(100, 0.9*.sw) (which can be passed as a character string).
Character scalar, default is TRUE. Only used if argument .width is not FALSE.
Whether to add a leading character string right after the extra new lines.
Logical scalar, default is FALSE. If TRUE, Further, elements in ... are
NOT collapsed together, but instead vectorised.
Character vector of length 1 or 2. Default is c("{", "}"). Defines
the opening and the closing delimiters for interpolation.
If of length 1, it must be of the form: 1) the opening delimiter,
2) a single space, 3) the closing delimiter. Ex: ".[ ]" is equivalent to c(".[", "]").
The default value is equivalent to "{ }".
[ ]: R:%20 [", "]: R:%22,%20%22
Character scalar, a function, or NULL (default). If provided and character:
it must be an string_magic chain of operations of the form "'arg1'op1, op2, etc". All these operations
are applied just before returning the vector. If a function,
it will be applied to the resulting vector.
Character scalar, default is NULL. If provided, the character vector
that should be returned is collapsed with the value of this argument. This leads
to return a string of length 1.
Logical, default is TRUE. If FALSE, this function is not run. Can be
useful in debugging situations where we want conditional evaluations.
Logical scalar, default is TRUE. Whether to enable error-handling (i.e.
human readable error messages).
Without error-handling you can save something of the order of 40us. Useful only
in long loops.
Character scalar or NULL (default). Only useful for package developers.
As a regular end-user you shouldn't care! If your package uses string_magic, you should care.
It is useful only if your package uses 'custom' string_magic operations, set with
string_magic_register_fun() or string_magic_register_ops().
Character scalars that will be collapsed with the argument sep. Note that
named arguments are used for substitution.
To interpolate, you can
use "{x}" within each character string to insert the value of x in the string.
You can add string operations in each "{}" instance with the syntax "'arg'op ? x"
(resp. "'arg'op ! x") to apply the operation 'op' with the argument 'arg' to x
(resp. the verbatim of x). Otherwise, what to say? Ah, nesting is enabled, and since
there's over 50 operators, it's a bit complicated to sort you out in this small space.
Use the argument .help = "keyword" (or .help = TRUE) to obtain a selective help
from the main documentation.
Note that in interpolations you have access to the special variables: .now and .date
to get the current time; and the special function .now("format") to
format the time. Ex: .now('%Y-%m %H:%m').
An environment used to evaluate the variables in "{}". By default the variables are
evaluated using the environment from where the function is called or using the named
arguments passed to the function.
Character scalar or TRUE, default is NULL. This argument
is used to generate a dynamic help on the console. If TRUE, the user can select which
topic to read from the main documentation, with the possibility to search for keywords and
navigate the help pages. If a character scalar, then a regex search is perfomed on the main
documentation and any section containining a match is displayed. The user can easily
navigate across matches.
The functions cat_magic() and message_magic() do not return anything, they simply print on the console.
The function cat_magic_alis() returns a function behaving identically to cat_magic() but for which the
default values have been altered.
Same for message_magic_alias().
These functions are base::cat()/message() wrappers aroung string_magic(). There is one notable difference
with respect to cat/message. It's the ability to add newlines after words for
the message to fit a target width. This is controlled with the argument .width. This is
active by default for message_magic (default is .width = NULL which leads to the
minimum betwen 100 characters and 90% of the screen width).
You can very easily change the default values with the alias generators cat_magic_alias and
message_magic_alias.
[Advanced] A note for package developers who would use these functions and
also use custom string_magic operations created with string_magic_register_fun() or
string_magic_register_ops(). To ensure forward compatibility the new operations created
should be defined in the package namespace (see the ad hoc section in string_magic_register_fun() help).
To access these operators in their specific namespaces, you must use an alias with
cat_magic_alias or message_magic_alias with the argument .namespace = "myPackageName"
(to avoid having to provide the .namespace argument repeatedly).
cat_magic_alias(): Create an alias of cat_magic with custom defaults
message_magic_alias(): Create an alias of message_magic with custom defaults
catma(): Alias to cat_magic
message_magic(): Display messages using interpolated strings
mema(): Alias to message_magic
Other tools with aliases:
string_clean_alias(),
string_magic(),
string_magic_alias(),
string_ops_alias(),
string_vec_alias()
start = Sys.time()
Sys.sleep(0.05)
message_magic("This example has run in {difftime ? start}.")
#> This example has run in 66ms.
cat_magic("Let's write a very long message to illustrate how .width work.",
.width = 40)
#> Let's write a very long message to
#> illustrate how .width work.
# Let's add a leader
cat_magic("Let's write a very long message to illustrate how `.width` work.",
"And now we add `.leader`.", .width = 40, .leader = "#> ")
#> #> Let's write a very long message to
#> #> illustrate how `.width` work.And now
#> #> we add `.leader`.
# newlines respect the introductory spaces
cat_magic("Here's a list:",
" + short item",
" + this is a very long item that likely overflows",
.width = 30, .sep = "\n")
#> Here's a list:
#> + short item
#> + this is a very long item
#> that likely overflows
#
# define custom defaults
#
# Unhappy about the default values? Create an alias!
# Here we change the defaults to mimic the printing of a column
cat_column = cat_magic_alias(.sep = "\n", .end = "\n", .vectorize = TRUE,
.last = "fill.center, ' + 'paste.both")
cat_column("code string_magic", "write the docs", "write the vignettes")
#> + code string_magic +
#> + write the docs +
#> + write the vignettes +