Formalism and API reboot

[moodymudskipper]

• see https://github.com/moodymudskipper/tags/issues/14 for notes from Advanced R
• see https://github.com/moodymudskipper/tags/issues/4 for previous discussion
• this doesn't reflect the current implementation!
• what we now call tag is what we previously refered to as an adverb factory
• what was called tag or adverb before is now called a tag_adverb, the class adverb is discarded so we won't be in the awkward situation to say that purrr::safely is an adverb but not an adverb (meaning it doesn't have the "adverb" class attribute).

---

1) Redefining everything

We take the existing definition and tweak them to make them more rigorous, enrich them, and then define our own terms.

• A function factory is a function that makes functions, its input can be anything or nothing, but its output will ALWAYS be a function. Function factories will often, but not always, return functions with the same body, but with an enclosing environment containing different variables/ values. Strictly speaking they include function operators but when mentioned side by side, function factory often means standard function factory

• A standard function factory is a function factory that is NOT a function operator

• A function operator is a function that takes one (or more) functions as input and returns a function as output. They are a subcategory of function factories. It can be useful to see them as adverbs and some of them can be conveniently named as such.

• A functional is a function that takes a function as an input (not necessarily the first!) and returns a vector as output, it includes the purrr::map family, the base::apply family, but also functions like base::Filter

• A standard function is a function that is none of those, meaning it doesn't take any systematic function input, and it doesn't systematically return a function.

In this package :

• A standard function operator is a function operator that is NOT a tag_adverb and NOT a tag

• A tag_adverb is a function operator that was given a class "tag_adverb". It is generally created by a tag as an intermediate object, but can be created by using as_tag_adverb on a standard function operator. This class allows the use of $.tag_adverb helps keep the focus and IDE highlighting on the input function, avoid bracket overload, push the tag_adverb's arguments at the back of the function call, and keep the autocomplete that is lost when using standard function operators.

• A tagged function is a manufactured function, output of a call to a tag_adverb, $.tag_adverb or directly $.tag, it has a class "tagged_function" to enable print.tagged_function which will print the function's code AND the values of the variables contained in the enclosing environment.

• A tag is a function operator which returns a tag_adverb. It essentially allows a friendlier syntax and more flexibility than a tag_adverb. It is given a class "tag" to enables $.tag

---

2) Examples :

converting to tag_adverb

The advantage of converting an adverb/ function operator to a tag_adverb is that it keeps it original behaviour and gains the advantage of being able to use $.tag_adverb, so fun <- as_tag_adverb(fun) shouldn't break any code. We can even use set_as_adverb on packaged function to make them compatible with $.tag_adverb.

library(purrr)
safely2 <- as_tag_adverb(safely)
safely(log, otherwise = NA_real_)(100, 10)
safely2(log, otherwise = NA_real_)(100, 10)
safely2$log(100, 10, otherwise = NA_real_)
as_tag_adverb(safely)$log(100, 10, otherwise = NA_real_)
set_as_adverb(safely)
safely(log, otherwise = NA_real_)(100, 10) # still works
safely$log(100, 10, otherwise = NA_real_)

## output for all :
#> $result
#> [1] 2
#> 
#> $error
#> NULL

class(safely2)
#> [1] "tag_adverb" "function"
f1 <- safely2(log, otherwise = NA_real_)
class(f1)
#> [1] "tagged_function" "function"
f2 <- safely2$log
class(f2)
#> [1] "tagged_function" "function"

converting to tag

safely3 <- as_tag(safely)
safely3(otherwise = NA_real_)$log(100, 10)
safely3()$log(100, 10, otherwise = NA_real_)
safely3$log(100, 10, otherwise = NA_real_)
as_tag(safely)$log(100, 10, otherwise = NA_real_)

## output for all :
#> $result
#> [1] 2
#> 
#> $error
#> NULL

class(safely3)
#> [1] "tag" "function"
g1 <- safely3(otherwise = NA_real_)
class(g1)
#> [1] "tag_adverb" "function"
g2 <- safely3(otherwise = NA_real_)$log
class(g2)
#> [1] "tagged_function" "function"
g3 <- safely3()$log
class(g3)
#> [1] "tagged_function" "function"
g4 <- safely3$log
class(g3)
#> [1] "tagged_function" "function"

We recommend using adverb or adjective names for tags and tag_adverbs. Strict guidelines appear to be hard to follow in practice with functional operators but we suggest the following :

• If you can, find a fitting adverb or adjective name that describes how differently the tagged function will behave from the input function, the suffix ly and the prefix with_ are commonly used and will make a function recognisable as not standard.
• for tag, using present participle forms (ing suffix) can work well, especially if the tag is designed to be mainly used with the bracket form:

# bracket form
using(iris)$plot(Petal.Length, Petal.Width)
grouping_by("Species")$summarize_all(mean)

# dollar form, looks less good but is less likely to be used for those :
using$plot(Petal.Length, Petal.Width, .with = iris)
grouping_by$summarize_all(mean, .by = "Species")

• In other cases, names can be used, and be read as an "annotation" to the function
• Verbs are better avoided to easily pick tags and tag_adverbs apart from standard functions

[moodymudskipper]

archived