Control.Provenience

The Provenience system lets you execute a function on particular input data while automatically recording the intermediate results together with a graph of the data flow. It is inspired by the Javelin software of the 80s which pre-dates Excel spreadsheets.

Intermediate results are stored in Variables, which decorate the data with a description. Instead of binding data to a Haskell identifier, you bind data to a Variable and provide a description of what the data is. Instead of applying a logical part to intermediate data, you apply the logical part to intermediate variables. So instead of writing code like

workflow x y z = let
    a = f x y
    b = g a z
    in h b

with Provenience you write

workflow x y z = do
    x' <- input x
    y' <- input y
    z' <- input z
    a <- var f <%> x' <%> y'
    b <- var g <%> a z'
    return (var h <%> b)

In addition to the above you should provide decoration for the variables which is used when rendering the data dependency graph. See <? and named. If and how the value of the variable is rendered is controlled with the render family functions and the DefaultRender class.

The ProvenienceT transformer has an additional type parameter for a machine-readable representation of a value. If you don't care about this, just use the unit type () here as in the Provenience type. Otherwise, all calls to render must be done on Variables of types which have a Representation in the chosen alternative type. After running the ProvenienceT computation you can extract the graph containing the alternative representations using graphAltReps. If the target representation is a spreadsheet, use renderSheet to obtain a spreadsheet where Variables are blocks of rows separated by blank rows.

Variables

data Variable a

Every Variable has an identifier in the data flow graph.

Constructors

Variable

Fields

• identifier :: Node
• value :: a

Instances

Functor Variable

Defined in Control.Provenience

Methods

fmap :: (a -> b) -> Variable a -> Variable b

(<$) :: a -> Variable b -> Variable a

Show a => Show (Variable a)

Defined in Control.Provenience

Methods

showsPrec :: Int -> Variable a -> ShowS

show :: Variable a -> String

showList :: [Variable a] -> ShowS

data VariableStore alt

Variables are internally numbered by Node = Int and have an alternative value Representation alt. Futher each variable has a Pandoc description (set by <?) and optionally a shortname set by named which is a String to be used in hyperlinks.

var :: Monad m => a -> ProvenienceT alt m a

Register a new variable in the VariableStore. This variable has neither description, shortname nor valueRendering.

var = varM . pure 

varM :: Monad m => m a -> ProvenienceT alt m a

Register a new variable with content from a monadic action in the VariableStore. This variable has neither description, shortname nor valueRendering.

input :: (Monad m, Representation a alt, DefaultRender a) => a -> ProvenienceT alt m a

Register a static input variable which is immediately rendered.

inputM :: (Monad m, Representation a alt, DefaultRender a) => m a -> ProvenienceT alt m a

Register a static input variable with content from a monad action which is immediately rendered.

func :: (Monad m, Default alt) => a -> Block -> ProvenienceT alt m a

Combination of var and <? that can be used for immediate function application, e.g.

x  <- input 1
y  <- input 2
xy <- func (*) (renderDefault "*") <%> x <%> y

Modifiers

type StoreUpdate = forall m alt. Monad m => StateT (VariableStore alt) m ()

Action on the VariableStore

(<?) :: Variable a -> Block -> StoreUpdate infixl 3

The what is this?-operator. Changes the description of the computation's result.

>>> v <- var 99
>>> v <? renderDefault "bottles of beer on the wall"

named :: Variable a -> String -> StoreUpdate

Provides a shortname symbol for the Variable, for use in hyperlinks and other references.

>>> v <- var 99
>>> v `named` "beer"

Rendering

linkto :: Monad m => Variable a -> StateT (VariableStore alt) m Inline

Render a hyperlink to a Variable, to be used e.g. in descriptions of downstream variables. Make sure to provide a short name via named before calling linkto.

render :: (Representation a alt, Monad m, DefaultRender a) => Variable a -> StateT (VariableStore alt) m ()

render = renderWith renderDefault. You can use this function without providing a DefaultRender instance by using a conversion function to a type that is member of DefaultRender:

\f -> render . fmap f

renderWith :: (Representation a alt, Monad m) => (a -> Block) -> Variable a -> StateT (VariableStore alt) m ()

Supply the valueRendering and altRep for the variable.

renderShow :: Show a => a -> Block

Use the show method to render a value as Plain text.

class DefaultRender a where

Class of types with a default rendering method. For the basic types renderDefault equals renderShow.

Methods

renderDefault :: a -> Block

Instances

DefaultRender Char

Defined in Control.Provenience

Methods

renderDefault :: Char -> Block

DefaultRender Double

Defined in Control.Provenience

Methods

renderDefault :: Double -> Block

DefaultRender Int

Defined in Control.Provenience

Methods

renderDefault :: Int -> Block

DefaultRender Integer

Defined in Control.Provenience

Methods

renderDefault :: Integer -> Block

DefaultRender String

render Strings as plain text.

Defined in Control.Provenience

Methods

renderDefault :: String -> Block

DefaultRender Text

Defined in Control.Provenience

Methods

renderDefault :: Text -> Block

DefaultRender Block

Defined in Control.Provenience

Methods

renderDefault :: Block -> Block

DefaultRender (Ratio Integer)

Defined in Control.Provenience

Methods

renderDefault :: Ratio Integer -> Block

data Proveniencei18n

Internationalization of the keywords used in renderStore.

Constructors

Proveniencei18n

Fields

• i18n_construction :: Inline

  keyword for the edge labels

• i18n_incoming :: Inline

  keyword for the nodes upstream

• i18n_outgoing :: Inline

  keyword for the nodes downstream

Instances

Show Proveniencei18n

Defined in Control.Provenience

Methods

showsPrec :: Int -> Proveniencei18n -> ShowS

show :: Proveniencei18n -> String

showList :: [Proveniencei18n] -> ShowS

Default Proveniencei18n

default is enProveniencei18n

Defined in Control.Provenience

Methods

def :: Proveniencei18n

enProveniencei18n :: Proveniencei18n

English version

deProveniencei18n :: Proveniencei18n

German version

renderStore :: Proveniencei18n -> VariableStore alt -> Block

Render the store with Pandoc. For each Variable the following data is written:

1. The variable name given with named,
2. The variables linking to this one (if any),
3. The edge labels linking to this variable,
4. The variables depending on this one (if any),
5. The description provided with <?,
6. A rendering of the value as provided by one of the render family functions.

renderSheet :: forall row sheet. (ToSheet row sheet, ToRow StaticCellValue row) => Proveniencei18n -> VariableStore (Seq row) -> sheet

When the alternative representation is in terms of spreadsheet rows, we can assemble the VariableStore into a spreadheet. This is analogous to renderStore but only places the data underneath the shortname, thus omitting any formatted descriptions.

graphAltReps :: VariableStore alt -> Gr alt Block

Obtain a graph of all the Variables alternative representations

graphShortnames :: VariableStore alt -> Gr String Block

Obtain a graph of all the Variables short names

The Provenience monad

type ProvenienceT alt m a = StateT (VariableStore alt) m (Variable a)

A Monad transformer that keeps track of data dependencies

type Provenience a = State (VariableStore ()) (Variable a)

Provenience = ProvenienceT () Identity

(<%>) :: Monad m => ProvenienceT alt m (a -> b) -> Variable a -> ProvenienceT alt m b infixl 4

Applicative-style application operator. Replaces the function Variable with its (partial) application and creates an edge from the argument to the result Variable that is labeled with the function description.

f <- func succ (renderDefault "successor")
x <- input (5 :: Int)
y <- pure f <%> x
x <? renderDefault "input data"
y <? renderDefault "The successor of 5"
render y

The above creates the following graph.

"input data"  "successor"  "The successor of 5"
     5        ----------->        6

If you want to re-use a function in several applications then bind f to the Provenience action rather the Variable like below.

let f = func succ (renderDefault "successor")
x <- input (5 :: Int)
y <- f <%> x
z <- f <%> y

(<%%>) :: Monad m => ProvenienceT alt m (a -> m b) -> Variable a -> ProvenienceT alt m b infixl 4

Like above but permit side-effects in the base monad.

runProvenienceT :: Monad m => ProvenienceT alt m a -> Node -> m ((a, VariableStore alt), Node)

Run the Provenience monad and return the value of the result variable together with the VariableStore and its next unused Node. Initialize the VariableStore with an empty graph and start with the given Node identifier.

execProvenienceT :: Monad m => ProvenienceT alt m a -> Node -> m (VariableStore alt, Node)

run the Provenience monad and return the data dependency graph

execProvenience :: Provenience a -> Node -> (VariableStore (), Node)

run the Provenience monad and return the data dependency graph

evalProvenienceT :: Monad m => ProvenienceT alt m a -> m a

run the Provenience monad and return the resulting value.

evalProvenience :: Provenience a -> a

run the Provenience monad and return the resulting value.

sequenceProvenienceT :: (Traversable t, Monad m) => t (ProvenienceT alt m a) -> m (t (a, VariableStore alt))

Run multiple ProvenienceT actions using the same pool of Nodes but returning seperate VariableStores. This is useful when several data flow graphs get embedded into the same document, where hyperlink targets must be unique.