Documentation

A function, that takes an accumulation function as paramater, and returns a function that will have zero or more parameters and returns an accumulated result: @(acc -> next)

A FunctionBuilder acc next f is a function (acc -> next) -> f.

Type parameter:

acc

The final output value that gets build up by the applying the resulting function build by the composed FunctionBuilders. If you were building a printf style library, then acc would probably be String.

next

The next parameter allows composing FunctionBuilders, and the final output will be a function f with zero or more parameters of different type resulting in an acc value. Most FunctionBuilders are parameteric in next and also have next in a in f_make_next. Also note that in (acc -> next) -> f_make_next the next is the output of the continuation acc -> next passed to the FunctionBuilder function, hence this output is actually in input from the perspective of the FunctionBuilder, which makes a FunctionBuilder Contravariant in next.

f_make_next

This is usually a function that returns next or is directly next, this is the resulting - seemingly poly variadic - outout function composed through the composition of FunctionBuilders, and obtained by toFunction.

It is required for the type-class instances allowing the composition as Semigroups or Monoids or even Category.

It is totaly valid to apply it to id, to get f, and behind f typically lies a function of some parameters to next.

At the end of the chain next will be acc and before that the function that takes the next parameters and then returns out.

See toFunction.

Composition comes in two flavours:

1. By using `(.)` to add to the accumulator a value passed to an additional argument of the resulting output function.
2. By using `(<>)` to append a fixed value to the accumulator directly.

For example:

import Data.Monoid (Sum(..))

add :: FunctionBuilder (Sum Int) next (Int -> next)
add = FB $ \k -> \x -> k (Sum x)

Here the next parameter in add is just passed through and is the key to be able to compose FunctionBuilders. add is parametric in next. . And when we are done composing, we pass id to the FunctionBuilder, which forces the the next parameter to match the acc type, and which would the make add function look like this:

addToZero :: FunctionBuilder (Sum Int) (Sum Int) (Int -> Sum Int)
addToZero = add

Turn a FunctionBuilder into the output function that consumes zero or more of parameter and then always return outout.

If passed a FunctionBuilder value of type FunctionBuilder String String (Int -> Double -> Int -> String)

For example:

example :: Int -> Double -> Int -> String
example = toFunction (i . d . i)

s :: String -> FunctionBuilder String a a
s x = FB (\k -> k x)

i :: FunctionBuilder String next (Int -> next)
i = FB (\k x -> k $ show x)

d :: FunctionBuilder String next (Double -> next)
d = FB (\k x -> k $ show x)

Create a FunctionBuilder that appends something to the (monoidal-) output value.

This is a smart constructor for a FunctionBuilder. This functions is probably equal to:

immediate x = FB (\k -> k x)

Example:

When building a String formatting FunctionBuilder the function to append a literal string could be:

s :: String -> FunctionBuilder String a a
s = immediate

c :: Char -> FunctionBuilder String a a
c = immediate . (:[])

example :: String
example = toFunction (s "hello" . c ' ' . s "world")

>>> example
"hello world"

See the example in toFunction.

Create a FunctionBuilder that adds an argument to the output function, and converts that argument to a value that can be accumulated in the resulting monoidal value.

This is a smart constructor for a FunctionBuilder. This functions is probably equal to:

addParameter f = FB (\k x -> k (f x))

Example:

When building a String formatting FunctionBuilder the function to append a parameter that has a show instance could be:

showing :: Show a => FunctionBuilder String r (a -> r)
showing = addParameter show

example :: (Show a, Show b) => a -> b -> String
example = toFunction (showing . showing)

>>> example True 0.33214
"True0.33214"

See the example in toFunction.

Take away a function parameter added with addParameter by pre - applying it to some value. This is equivalent to:

    fillParameter f x = f * pure x

Convert a FunctionBuilder for a function (a -> b) to (Tagged tag a -> b).

Compose to FunctionBuilders such that the second FunctionBuilder may depend on the intermediate result of the first. If you skwirm hard enough you almost see '(>>=)' with m ~ n.

Convert the accumulated (usually monoidal-) value, this allows to change the underlying accumlator type.

Convert the output of a FunctionBuilder value; since most FunctionBuilders are parameteric in r they also have r in a in a, such that a always either is r or is a function returning r eventually.

In order to get from a FunctionBuilder that can accept a continuation returning it an r to a FunctionBuilder that accepts continuations returning an s instead, we need to apply a function s -> r to the return value of the continuation.

Note that a mapNext will not only change the r to an s but probably also the the a, when it is parametric, as in this contrived example:

example :: Int -> x -> Sum Int
example = toFunction (ign add)

add :: FunctionBuilder (Sum Int) next (Int -> next)
add = FB (\k x -> k $ Sum x)

ign :: FunctionBuilder m (x -> r) a -> FunctionBuilder m r a
ign = mapNext const

Here the extra parameter x is pushed down into the a of the add FunctionBuilder.