string_magic
R/string_magic_main.R
string_magic_register_fun.Rd
Extends the capabilities of string_magic()
by adding any custom operation
string_magic_register_fun(fun, alias, valid_options = NULL, namespace = NULL)
string_magic_register_ops(ops, alias, namespace = NULL)
A function which must have at least the arguments 'x' and '...'.
Additionnaly, it can have the arguments: 'argument', 'options', 'group', 'group_flag'.
This function must return a vector.
This function will be internally called by string_magic
in the form
fun(x, argument, options, group, group_flag)
.x
: the value to which the
operation applies. argument
: the quoted string_magic
argument (always character).
options
: a character vector of string_magic
options. The two last arguments are of use
only in group-wise operations if fun
changes the lengths of vectors. group
: an index of
the group to which belongs each observation (integer). group_flag
: value between 0
and 2; 0: no grouping operation requested; 1: keep track of groups; 2: apply grouping.
Character scalar, the name of the operation.
A character vector or NULL (default). Represents a list of valid options for the operation. This is used: a) to enable auto-completion, b) for error-handling purposes.
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.
If the function string_magic_register_*
is located in the onLoad
function (see help("onLoad")
),
there is nothing to do. Otherwise, pass the name of your package in this argument to
make all the new operation definitions scoped (i.e. only your package can access it and
it can't be messed up by end users).
Character scalar representing a valid chain of string_magic
operations. It should
be of the form "op1, 'arg'op2, etc"
. For example "'80|-'fill"
fills the line
with dashes up to 80 characters.
These function do not return anything. They register new operations to be used in the
string_magic
family of functions by placing them in the options (later fetched by
string_magic()
at run-time).
We try to strongly check the new operations since it's always better to find out problems sooner than later. This means that when the function is defined, it is also tested.
If you pass a function, note that it should work for non-character arguments in x
.
string_magic_register_ops()
: Create new combinations of string_magic
operations
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 = "{{ }}")
Other related to string_magic:
string_magic_alias()
# let's create an operation that adds markdown emphasis
# to elements of a vector
# A) define the function
fun_emph = function(x, ...) paste0("*", x, "*")
# B) register it
string_magic_register_fun(fun_emph, "emph")
# C) use it
x = string_vec("right, now")
string_magic("Take heed, {emph, c? x}.")
#> [1] "Take heed, *right* *now*."
#
# now let's add the option "strong"
fun_emph = function(x, options, ...) {
if("strong" %in% options){
paste0("***", x, "***")
} else {
paste0("*", x, "*")
}
}
string_magic_register_fun(fun_emph, "emph", "strong")
x = string_vec("right, now")
string_magic("Take heed, {emph.strong, c? x}.")
#> [1] "Take heed, ***right*** ***now***."
#
# now let's add an argument
fun_emph = function(x, argument, options, ...){
arg = argument
if(nchar(arg) == 0) arg = "*"
if("strong" %in% options){
arg = paste0(rep(arg, 3), collapse = "")
}
paste0(arg, x, arg)
}
string_magic_register_fun(fun_emph, "emph", "strong")
x = string_vec("right, now")
string_magic("Take heed, {'_'emph.s, c? x}.")
#> [1] "Take heed, ___right___ ___now___."
#
# using string_magic_register_ops
#
# create a 'header' maker
string_magic_register_ops("tws, '# 'paste, ' 'paste.right, '40|-'fill", "h1")
cat_magic("{h1 ! My title}\n my content")
#> # My title -----------------------------
#> my content