string_magic_alias {stringmagic}

Create string_magic aliases with custom defaults

Description

Utility to easily create string_magic aliases with custom default

Usage

string_magic_alias(
  .sep = "",
  .vectorize = FALSE,
  .delim = c("{", "}"),
  .last = NULL,
  .post = NULL,
  .default = NULL,
  .nest = FALSE,
  .invisible = FALSE,
  .local_ops = NULL,
  .collapse = NULL,
  .check = TRUE,
  .class = 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.

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

.post

Function or NULL (default). If not NULL, this function will be applied after all the processing, just before returning the object. This function can have extra arguments which will be caught directly in the ... argument of string_magic. For example if .post = head, you can directly pass the argument n = 3 to string_magic's arguments.

.default

Character scalar or NULL (default). If provided, it must be a sequence of string_magic operations. It will be applied as a default to any interpolation. Ex: if x = 1:2, then string_magic("x = {x}", .default = "enum") leads to "x = 1 and 2", and is equivalent to string_magic("x = {enum?x}"). Note that this default operations does not apply to nested expressions. That is string_magic("{!x{1:2}}", .default = "enum") leads to c("x1", "x2") and NOT "x1 and 2".

.nest

Logical, default is FALSE. If TRUE, it will nest the original string within interpolation delimiters, so that you can apply operations directly on the string. Example: string_magic("upper ! hello") returns "upper ! hello", while string_magic("upper ! hello", .nest = TRUE) returns "HELLO".

.invisible

Logical scalar, default is FALSE. Whether the object returned should be invisible (i.e. not printed on the console).

.local_ops

Named list or NULL (default). If provided, it must be a list of the form list(alias1 = ops1, alias2 = ops2) where alias is the name of the newly defined operator an ops is a character scalar representing the associated string_magic operations. Ex: list(add = "' + 'collapse") creates the operation add which collapses the string with pluses. All operations created here are only available to the generated function.

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

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

.class

Character vector representing the class to give to the object returned. By default it is NULL. Note that the class string_magic has a specific print method, usually nicer for small vectors (it base::cat()s the elements).

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

Details

Use this function if you want to change string_magic default values. For example, if you want the interpolation to be done with "{{}}" (instead of {}) or if you want the default separation to be the space (instead of the empty string). See the example.

Value

This function returns a function which will behave in the same way as string_magic()

Writing a package using string_magic

If you want to use string_magic in your package and want to make use of custom operations:

• place any string_magic_register_fun and string_magic_register_ops in your .onLoad function (see help("onLoad")). The .onLoad function is run whenever the package is loaded for the first time. It's a function that you can place anywhere in your ⁠R/*⁠ files and which looks like this:

.onLoad = function(libname, pkgname){
  # string_magic custom operations
  string_magic_register_ops("'80|-'fill", "h1")

  invisible()
}

• if you don't want to place the ⁠string_magic_register_*⁠ functions in the .onLoad function, you can, but then you must provide the argument namespace:

string_magic_register_ops("'80|-'fill", "h1", namespace = "myPackageName")

• you must create an string_magic_alias() to create an alias to string_magic() and use the argument .namespace = "myPackageName". Use this opportunity to change the defaults if you wish. You can even override the string_magic function:

# creating an alias with the same name + changing the delimiter
string_magic = stringmagic::string_magic_alias(.namespace = "myPackageName", .delim = "{{ }}")

Author(s)

Laurent Berge

See Also

Other related to string_magic: string_magic_register_fun()

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

Examples

# we create the function sma2 with different defaults
sma2 = string_magic_alias(.delim = ".[ ]", .sep = " ", .class = "string_magic")

person = "john doe"
sma2("Hello", ".[title ? person]")

# you can use the arguments whose default has been changed
sma2("Hello", ".[title ? person]", .sep = ": ")