Documentation

A tricky newtype wrapper around a function that carries out a computation resulting in a monoidal output value that is passed to a continuation.

Type parameters:

acc

Type of monoidal value that is build from the parameters of the function returned by toFunction. For example: In a printf style formatting library acc could be String.

next

The trick- parameter that allows composing FunctionBuilders. Also note that FunctionBuilders are contravarient in this parameter; next is the output of the continuation acc -> next, hence this is an input from the perspective of the FunctionBuilder.

f_make_next

This is usually a function type that returns next, this is the type of the output function returned by toFunction.

A FunctionBuilder acc next f is a newtype wrapper around functions of type (acc -> next) -> f.

The immediate return value of the function is usually a function type, that takes zero or more arguments: a_0 -> .. -> a_N -> next.

The FunctionBuilders that deferred returns are polymorphic in next. And next is the key for composition.

For example:

fb1 :: FunctionBuilder MyMonoid next (Int -> next)
fb1 = deferred undefined

fb2 :: FunctionBuilder MyMonoid next (String -> next)
fb2 = deferred undefined

newtype MyMonoid = MyMonoid () deriving (Semigroup, Monoid)

When we desugar with ghci:

>>> :t (runFunctionBuilder fb1)
(runFunctionBuilder fb1) :: (MyMonoid -> next) -> Int -> next

>>> :t (runFunctionBuilder fb2)
(runFunctionBuilder fb2) :: (MyMonoid -> next) -> String -> next

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 (see example below).
2. By using <> to append a fixed value to the accumulator directly.

When composing fb1 and fb2 using . we get:

>>> :t (fb1 . fb2)
(fb1 . fb2) :: FunctionBuilder MyMonoid a (Int -> String -> a)

And desugared:

>>> :t runFunctionBuilder (fb1 . fb2)
runFunctionBuilder (fb1 . fb2) :: (MyMonoid -> next) -> Int -> String -> next

What happened during composition was that the next in fb1 was used to insert into Int -> next the String -> other_next from fb2; such that this results in Int -> (String -> other_next). (Note: For clarity I renamed the type local type parameter next to other_next from fb2)

Also, there is the StaticContent type class for types that have function builders.

NOTE: FunctionBuilder w a b is actually Cokleisli ((->) w) a b When w is a Monoid then, ((->) w) is a Comonad instance. The reason why this library does not use the comonad library under the hood is currently only the missing Semigroup and Monoid instances; and to avoid orphan instances a newtype wrapper would be required, and that does not justify the additional dependency and the pollution of this library with scary Cokleislies and Comonads.

Get the composed output function of a FunctionBuilder.

The FunctionBuilder passed to this function must match this signature:

FunctionBuilder m m (arg0 -> .. -> m)

This means that the result of the generated function arg0 -> .. -> m MUST be m, the underlying Monoid.

The FunctionBuilders generated by deferred and immediate are parametric in the second type parameter and match the type signature required by this function.

Example 1:

fb :: FunctionBuilder String String (Int -> Double -> Int -> String)
fb = undefined

example :: Int -> Double -> Int -> String
example = toFunction  fb

Example 2:

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)

A smart constructor for a FunctionBuilder with that will build a function with a parameter, and when the generated function is applied at that parameter the function given here will be applied to the argument and the resulting monoidal value will be appended to the result.

The generated builder can be passed to toFunction since it is parametric in its second type parameter.

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 = deferred show

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

>>> example True 0.33214
"True0.33214"

See the example in toFunction.

Since: 0.3.0.0

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)

The generated builder can be passed to toFunction since it is parametric in its second type parameter.

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.

Types a that can be turned into FunctionBuilders for a base monoid m.

This is the abstract version of StaticContent and DynamicContent

Since: 0.1.2.0

Types a that can be turned into FunctionBuilders for a base monoid m.

These type can provide a function to work on the internal monoid,

They can be constructed using immediate.

Of course they can incorporate information statically known at compile time or via type class dictionaries (through singletons for instance).

For example:

instance forall s . (KnownSymbol s) => StaticContent String (Proxy s) where
  addStaticContent = immediate (symbolVal (Proxy @s))

Since: 0.2.0.0

Types that have a FunctionBuilder with a runtime parameter for a base monoid m.

For example: If an instance adds an Int parameter, it will define this family instance:

instance DynamicContent String (Proxy "%i") Int where
   addParameter _ = deferred

Since: 0.2.0.0

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

For example:

intArg :: FunctionBuilder MyMonoid a (Int -> a)
intArg = deferred undefined

stringArg :: FunctionBuilder MyMonoid a (String -> a)
stringArg = deferred undefined

twoInt :: FunctionBuilder MyMonoid a (Int -> String -> a)
twoInt = intArg . stringArg

example :: FunctionBuilder MyMonoid a (String -> a)
example = fillParameter twoInt 42

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. Similar to a monadic bind >>= but more flexible sind the underlying Monoid may change too, for example:

intText :: FunctionBuilder Text next (Int -> next)
intText = deferred undefined

unpackB :: Text -> FunctionBuilder String next next
unpackB = immediate . unpack

intStr :: FunctionBuilder String next (Int -> next)
intStr = intText `bind` unpackB

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.