cat_magic_alias {stringmagic}

Display messages using interpolated strings

Description

Utilities to display messages using string_magic interpolation and operations to generate the message.

Usage

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 = FALSE,
  .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
)

Arguments

.sep

Character scalar, default is the empty string "". It is used to collapse all the elements in ... before applying any operation.

.end

Character scalar, default is "" (the empty string). This string will be collated at the end of the message (a common alternative is "\n").

.width

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.

1. positive integer: number of characters

2. number (0;1): fraction of the screen

3. FALSE: does not add newlines

4. NULL: the min between 120 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(120, 0.9*.sw).

.leader

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.

.vectorize

Logical scalar, default is FALSE. If TRUE, Further, elements in ... are NOT collapsed together, but instead vectorised.

.delim

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

.last

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.

.collapse

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.

.trigger

Logical, default is TRUE. If FALSE, this function is not run. Can be useful in debugging situations where we want conditional evaluations.

.check

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.

.namespace

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').

.envir

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.

.help

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.

Details

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 120 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).

Value

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().

Functions

• 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

See Also

Other tools with aliases: string_clean_alias(), string_magic(), string_magic_alias(), string_ops_alias(), string_vec_alias()

Examples

start = Sys.time()
Sys.sleep(0.05)
message_magic("This example has run in {difftime ? start}.")

cat_magic("Let's write a very long message to illustrate how .width work.", 
          .width = 40)

# 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 = "#> ")

# 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")

#
# 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")