string_magic_register_fun {stringmagic}

Register custom operations to apply them in string_magic

Description

Extends the capabilities of string_magic() by adding any custom operation

Usage

string_magic_register_fun(fun, alias, valid_options = NULL, namespace = NULL)

string_magic_register_ops(ops, alias, namespace = NULL)

Arguments

fun

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.

alias

Character scalar, the name of the operation.

valid_options

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.

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

ops

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.

Details

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.

Value

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

Functions

• string_magic_register_ops(): Create new combinations of string_magic operations

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

See Also

Other related to string_magic: string_magic_alias()

Examples

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

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

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

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