Utility to easily create string_magic aliases with custom default
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
)Character scalar, default is the empty string "". It is used to collapse all
the elements in ... before applying any operation.
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.
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.
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".
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".
Logical scalar, default is FALSE. Whether the object returned should be
invisible (i.e. not printed on the console).
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.
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 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 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).
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().
This function returns a function which will behave in the same way as string_magic()
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.
string_magicIf 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 = "{{ }}")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()
# we create the function sma2 with different defaults
sma2 = string_magic_alias(.delim = ".[ ]", .sep = " ", .class = "string_magic")
person = "john doe"
sma2("Hello", ".[title ? person]")
#> [1] "Hello John Doe"
#> attr(,"class")
#> [1] "string_magic" "character"
# you can use the arguments whose default has been changed
sma2("Hello", ".[title ? person]", .sep = ": ")
#> [1] "Hello: John Doe"
#> attr(,"class")
#> [1] "string_magic" "character"