The Maybe monad

library(chronicler)
library(maybe)
#> 
#> Attaching package: 'maybe'
#> The following objects are masked _by_ '.GlobalEnv':
#> 
#>     bind, fmap

{chronicler} uses the {maybe} package under the hood; {maybe} implements the Maybe monad which provides an elegant solution to situations where functions fail. As an example, let’s consider the sqrt() function decorated using maybe():

m_sqrt <- maybe(sqrt)

m_sqrt(16)
#> Just
#> [1] 4

m_sqrt(16) succeeds and returns Just 4. But what happens if it fails?

m_sqrt("10")
#> Nothing

m_sqrt("10") returns Nothing because sqrt("10") would return an error. Using maybe() allows you to build safe functions that never fail; you can explicitely handle Nothing values instead of having the program crash and stop.

When a computation fails, functions decorated using record() also return Nothing:

r_sqrt <- record(sqrt)

r_sqrt("16")
#> NOK! Value computed unsuccessfully:
#> ---------------
#> Nothing
#> 
#> ---------------
#> This is an object of type `chronicle`.
#> Retrieve the value of this object with pick(.c, "value").
#> To read the log of this object, call read_log(.c).

and when computations succeed, Just values are also returned:

r_sqrt <- record(sqrt)

r_sqrt(16)
#> OK! Value computed successfully:
#> ---------------
#> Just
#> [1] 4
#> 
#> ---------------
#> This is an object of type `chronicle`.
#> Retrieve the value of this object with pick(.c, "value").
#> To read the log of this object, call read_log(.c).

If Nothing is passed to a function decorated by record(), Nothing gets immediately returned.

Users of {chronicle} do not need to be familiar with the {maybe} package to use it, as conversion to and from maybe objects is handled automatically.

To recuperate the value from a chronicler object, users can use pick():

pick(r_sqrt(16), "value")
#> [1] 4

pick() converts the value from the maybe type to the underlying type of the object. Compare to:

(r_sqrt(16))$value
#> Just
#> [1] 4

which returns the Just object. To learn more about {maybe}, read the package’s readme which provides a nice introduction.