Copyright | (c) Michael Szvetits 2024 |
---|---|

License | BSD3 (see the file LICENSE) |

Maintainer | typedbyte@qualified.name |

Stability | stable |

Portability | portable |

Safe Haskell | Safe-Inferred |

Language | GHC2021 |

This module exports the types and functions needed to create cells, manipulate their data and wire them up for data propagation.

## Synopsis

- data Network a
- empty :: Network a
- data Error a
- data Propagator a b
- runPropagator :: Propagator a b -> Network a -> Either (Error a) (Network a, b)
- data CellKey
- data Change a
- = Changed a
- | Unchanged a
- | Incompatible

- cell :: a -> (a -> a -> Change a) -> Propagator a CellKey
- readCell :: CellKey -> Propagator a a
- writeCell :: CellKey -> a -> Propagator a ()
- removeCell :: CellKey -> Propagator a ()
- label :: (a -> [b]) -> (b -> a) -> [CellKey] -> Propagator a [[b]]
- data ConnectKey
- data ConnectState
- connect :: ConnectState -> CellKey -> CellKey -> (a -> Maybe a) -> Propagator a ConnectKey
- connect_ :: ConnectState -> CellKey -> CellKey -> (a -> Maybe a) -> Propagator a ()
- sync :: ConnectState -> CellKey -> CellKey -> Propagator a (ConnectKey, ConnectKey)
- sync_ :: ConnectState -> CellKey -> CellKey -> Propagator a ()
- syncWith :: (a -> Maybe a) -> (a -> Maybe a) -> ConnectState -> CellKey -> CellKey -> Propagator a (ConnectKey, ConnectKey)
- syncWith_ :: (a -> Maybe a) -> (a -> Maybe a) -> ConnectState -> CellKey -> CellKey -> Propagator a ()
- combine :: ConnectState -> CellKey -> CellKey -> CellKey -> (a -> a -> Maybe a) -> Propagator a ConnectKey
- combine_ :: ConnectState -> CellKey -> CellKey -> CellKey -> (a -> a -> Maybe a) -> Propagator a ()
- combineMany :: ConnectState -> [CellKey] -> CellKey -> ([a] -> Maybe a) -> Propagator a ConnectKey
- combineMany_ :: ConnectState -> [CellKey] -> CellKey -> ([a] -> Maybe a) -> Propagator a ()
- distribute :: ConnectState -> CellKey -> [CellKey] -> (a -> Maybe a) -> Propagator a ConnectKey
- distribute_ :: ConnectState -> CellKey -> [CellKey] -> (a -> Maybe a) -> Propagator a ()
- manyToMany :: ConnectState -> [CellKey] -> [CellKey] -> ([a] -> Maybe a) -> Propagator a ConnectKey
- manyToMany_ :: ConnectState -> [CellKey] -> [CellKey] -> ([a] -> Maybe a) -> Propagator a ()
- disconnect :: ConnectKey -> Propagator a ()
- plus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
- minus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
- times :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
- timesWith :: Num a => (a -> a -> a) -> ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
- abs :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a ()
- absWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a ()
- negate :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a ()
- signum :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a ()
- signumWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a ()

# Networks

A network consists of cells and connections which propagate data between them.

Represents possible errors that may occur when modifying or using a network.

InvalidCell CellKey | The specified cell could not be found. |

InvalidConnect ConnectKey | The specified connection could not be found. |

NoPropagation ConnectKey | The specified did not produce a value. |

Conflict CellKey a a | The old value of the specified cell is incompatible with a new value propagated to it. |

Cycle CellKey | The specified cell propagated a value to itself (directly or indirectly), leading to a cycle. |

data Propagator a b Source #

Network modifications and data propagations are captured by the `Propagator`

monad.

#### Instances

Applicative (Propagator a) Source # | |

Defined in Data.Propagator pure :: a0 -> Propagator a a0 # (<*>) :: Propagator a (a0 -> b) -> Propagator a a0 -> Propagator a b # liftA2 :: (a0 -> b -> c) -> Propagator a a0 -> Propagator a b -> Propagator a c # (*>) :: Propagator a a0 -> Propagator a b -> Propagator a b # (<*) :: Propagator a a0 -> Propagator a b -> Propagator a a0 # | |

Functor (Propagator a) Source # | |

Defined in Data.Propagator fmap :: (a0 -> b) -> Propagator a a0 -> Propagator a b # (<$) :: a0 -> Propagator a b -> Propagator a a0 # | |

Monad (Propagator a) Source # | |

Defined in Data.Propagator (>>=) :: Propagator a a0 -> (a0 -> Propagator a b) -> Propagator a b # (>>) :: Propagator a a0 -> Propagator a b -> Propagator a b # return :: a0 -> Propagator a a0 # |

runPropagator :: Propagator a b -> Network a -> Either (Error a) (Network a, b) Source #

Applies modifications captured by the propagator monad to a network, thus producing a new network if no error occurred.

## Cells

Represents a unique identification of a network cell.

Represents a potential change of a cell value.

Changed a | Indicates that a cell value has been changed to the new value |

Unchanged a | Indicates that a cell value did not change, i.e. needs no propagation. |

Incompatible | Indicates that a new cell value contradicts the one that is already stored in the cell. |

:: a | The initial value of the cell. |

-> (a -> a -> Change a) | A function that describes how to join an existing cell value with a new one that the cell has received via propagation. |

-> Propagator a CellKey | The identification of the newly constructed cell. |

Constructs a new cell with a given initial value and a function which defines how to react if a new value is about to be written to the cell.

readCell :: CellKey -> Propagator a a Source #

Reads the value of a specific cell.

writeCell :: CellKey -> a -> Propagator a () Source #

Writes a new value to a specific cell and starts to propagate potential changes through the network of connected cells.

removeCell :: CellKey -> Propagator a () Source #

Removes a cell from the network. This also removes all connections related to the cell.

label :: (a -> [b]) -> (b -> a) -> [CellKey] -> Propagator a [[b]] Source #

If the content of a cell is an accumulation of multiple values `[b]`

,
and every value `b`

itself can be used as content `a`

for the cell, then we
can write every value `b`

one after another to the cell and check if the
network converges to a successful state.

As a result, we can enumerate all possible combinations of valid values for a given set of cells. This is often used in constraint solving algorithms.

This function does not perform any permanent network modifications.

## Connections

data ConnectKey Source #

Represents a unique identification of a network connection.

#### Instances

Show ConnectKey Source # | |

Defined in Data.Propagator showsPrec :: Int -> ConnectKey -> ShowS # show :: ConnectKey -> String # showList :: [ConnectKey] -> ShowS # | |

Eq ConnectKey Source # | |

Defined in Data.Propagator (==) :: ConnectKey -> ConnectKey -> Bool # (/=) :: ConnectKey -> ConnectKey -> Bool # | |

Ord ConnectKey Source # | |

Defined in Data.Propagator compare :: ConnectKey -> ConnectKey -> Ordering # (<) :: ConnectKey -> ConnectKey -> Bool # (<=) :: ConnectKey -> ConnectKey -> Bool # (>) :: ConnectKey -> ConnectKey -> Bool # (>=) :: ConnectKey -> ConnectKey -> Bool # max :: ConnectKey -> ConnectKey -> ConnectKey # min :: ConnectKey -> ConnectKey -> ConnectKey # |

data ConnectState Source #

When connecting cells, the `ConnectState`

defines the initial behaviour of the connection.

Live | The connection immediately starts to propagate data between the connected cells. |

Idle | The connection is established, but no initial data propagation takes place. |

#### Instances

Show ConnectState Source # | |

Defined in Data.Propagator showsPrec :: Int -> ConnectState -> ShowS # show :: ConnectState -> String # showList :: [ConnectState] -> ShowS # | |

Eq ConnectState Source # | |

Defined in Data.Propagator (==) :: ConnectState -> ConnectState -> Bool # (/=) :: ConnectState -> ConnectState -> Bool # | |

Ord ConnectState Source # | |

Defined in Data.Propagator compare :: ConnectState -> ConnectState -> Ordering # (<) :: ConnectState -> ConnectState -> Bool # (<=) :: ConnectState -> ConnectState -> Bool # (>) :: ConnectState -> ConnectState -> Bool # (>=) :: ConnectState -> ConnectState -> Bool # max :: ConnectState -> ConnectState -> ConnectState # min :: ConnectState -> ConnectState -> ConnectState # |

connect :: ConnectState -> CellKey -> CellKey -> (a -> Maybe a) -> Propagator a ConnectKey Source #

Connects a source cell to a target cell in order to propagate changes
from the source to the target. The returned `ConnectKey`

can be used to
remove the connection via `disconnect`

.

connect_ :: ConnectState -> CellKey -> CellKey -> (a -> Maybe a) -> Propagator a () Source #

Same as `connect`

, but discards the returned `ConnectKey`

.

sync :: ConnectState -> CellKey -> CellKey -> Propagator a (ConnectKey, ConnectKey) Source #

sync_ :: ConnectState -> CellKey -> CellKey -> Propagator a () Source #

Same as `sync`

, but discards the returned `ConnectKey`

s.

syncWith :: (a -> Maybe a) -> (a -> Maybe a) -> ConnectState -> CellKey -> CellKey -> Propagator a (ConnectKey, ConnectKey) Source #

Connects and synchronizes two cells using two translation functions `f`

and `g`

, i.e. new values are propagated from the source to the target cell
using `f`

, and vice versa using `g`

.

syncWith_ :: (a -> Maybe a) -> (a -> Maybe a) -> ConnectState -> CellKey -> CellKey -> Propagator a () Source #

Same as `syncWith`

, but discards the returned `ConnectKey`

s.

combine :: ConnectState -> CellKey -> CellKey -> CellKey -> (a -> a -> Maybe a) -> Propagator a ConnectKey Source #

Connects two source cells to a target cell in order to propagate changes
from the sources to the target. The returned `ConnectKey`

can be used to
remove the connection via `disconnect`

.

combine_ :: ConnectState -> CellKey -> CellKey -> CellKey -> (a -> a -> Maybe a) -> Propagator a () Source #

Same as `combine`

, but discards the returned `ConnectKey`

.

combineMany :: ConnectState -> [CellKey] -> CellKey -> ([a] -> Maybe a) -> Propagator a ConnectKey Source #

Connects several source cells to a target cell in order to propagate changes
from the sources to the target. The returned `ConnectKey`

can be used to
remove the connection via `disconnect`

.

combineMany_ :: ConnectState -> [CellKey] -> CellKey -> ([a] -> Maybe a) -> Propagator a () Source #

Same as `combineMany`

, but discards the returned `ConnectKey`

.

distribute :: ConnectState -> CellKey -> [CellKey] -> (a -> Maybe a) -> Propagator a ConnectKey Source #

Connects a source cells to several target cells in order to propagate changes
from the source to the targets. The returned `ConnectKey`

can be used to
remove the connection via `disconnect`

.

distribute_ :: ConnectState -> CellKey -> [CellKey] -> (a -> Maybe a) -> Propagator a () Source #

Same as `distribute`

, but discards the returned `ConnectKey`

.

manyToMany :: ConnectState -> [CellKey] -> [CellKey] -> ([a] -> Maybe a) -> Propagator a ConnectKey Source #

Connects several source cells to several target cells in order to propagate changes
from the sources to the targets. The returned `ConnectKey`

can be used to
remove the connection via `disconnect`

.

manyToMany_ :: ConnectState -> [CellKey] -> [CellKey] -> ([a] -> Maybe a) -> Propagator a () Source #

Same as `manyToMany`

, but discards the returned `ConnectKey`

.

disconnect :: ConnectKey -> Propagator a () Source #

Removes a connection from the network.

### Numeric

plus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () Source #

`plus s a b c`

connects three cells using the following propagation schema:

`a + b`

is propagated to`c`

if`a`

or`b`

changes.`c - b`

is propagated to`a`

if`b`

or`c`

changes.`c - a`

is propagated to`b`

if`a`

or`c`

changes.

minus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () Source #

`minus s a b c`

connects three cells using the following propagation schema:

`a - b`

is propagated to`c`

if`a`

or`b`

changes.`b + c`

is propagated to`a`

if`b`

or`c`

changes.`a - c`

is propagated to`b`

if`a`

or`c`

changes.

times :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () Source #

`times s a b c`

connects three cells using the following propagation schema:

`a * b`

is propagated to`c`

if`a`

or`b`

changes.

timesWith :: Num a => (a -> a -> a) -> ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () Source #

`timesWith divOp s a b c`

connects three cells using the following propagation schema:

`a * b`

is propagated to`c`

if`a`

or`b`

changes.`divOp c b`

is propagated to`a`

if`b`

or`c`

changes.`divOp c a`

is propagated to`b`

if`a`

or`c`

changes.

abs :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a () Source #

`abs s a b`

connects two cells using the following propagation schema:

`|a|`

is propagated to`b`

if`a`

changes.

absWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a () Source #

`absWith inv s a b`

connects two cells using the following propagation schema:

`|a|`

is propagated to`b`

if`a`

changes.`inv b`

is propagated to`a`

if`b`

changes.

negate :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a () Source #

`negate s a b`

connects two cells using the following propagation schema:

`-a`

is propagated to`b`

if`a`

changes.`-b`

is propagated to`a`

if`b`

changes.

signum :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a () Source #

`signum s a b`

connects two cells using the following propagation schema:

`Prelude.signum a`

is propagated to`b`

if`a`

changes.

signumWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a () Source #

`signumWith inv s a b`

connects two cells using the following propagation schema:

`Prelude.signum a`

is propagated to`b`

if`a`

changes.`inv b`

is propagated to`a`

if`b`

changes.