-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A Propagator Library
--
-- Please see the README on GitHub at
-- https://github.com/typedbyte/propeller#readme
@package propeller
@version 0.2.0.0
-- | This module exports the types and functions needed to create cells,
-- manipulate their data and wire them up for data propagation.
module Data.Propagator
-- | A network consists of cells and connections which propagate data
-- between them.
data Network a
-- | Represents an empty network.
empty :: Network a
-- | Represents possible errors that may occur when modifying or using a
-- network.
data Error a
-- | The specified cell could not be found.
InvalidCell :: CellKey -> Error a
-- | The specified connection could not be found.
InvalidConnect :: ConnectKey -> Error a
-- | The specified did not produce a value.
NoPropagation :: ConnectKey -> Error a
-- | The old value of the specified cell is incompatible with a new value
-- propagated to it.
Conflict :: CellKey -> a -> a -> Error a
-- | The specified cell propagated a value to itself (directly or
-- indirectly), leading to a cycle.
Cycle :: CellKey -> Error a
-- | Network modifications and data propagations are captured by the
-- Propagator monad.
data Propagator a b
-- | Applies modifications captured by the propagator monad to a network,
-- thus producing a new network if no error occurred.
runPropagator :: Propagator a b -> Network a -> Either (Error a) (Network a, b)
-- | Represents a unique identification of a network cell.
data CellKey
-- | Represents a potential change of a cell value.
data Change a
-- | Indicates that a cell value has been changed to the new value
-- a.
Changed :: a -> Change a
-- | Indicates that a cell value did not change, i.e. needs no propagation.
Unchanged :: a -> Change a
-- | Indicates that a new cell value contradicts the one that is already
-- stored in the cell.
Incompatible :: Change a
-- | 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.
cell :: a -> (a -> a -> Change a) -> Propagator a CellKey
-- | Reads the value of a specific cell.
readCell :: CellKey -> Propagator a a
-- | Writes a new value to a specific cell and starts to propagate
-- potential changes through the network of connected cells.
writeCell :: CellKey -> a -> Propagator a ()
-- | Removes a cell from the network. This also removes all connections
-- related to the cell.
removeCell :: CellKey -> Propagator a ()
-- | 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.
label :: (a -> [b]) -> (b -> a) -> [CellKey] -> Propagator a [[b]]
-- | Represents a unique identification of a network connection.
data ConnectKey
-- | When connecting cells, the ConnectState defines the initial
-- behaviour of the connection.
data ConnectState
-- | The connection immediately starts to propagate data between the
-- connected cells.
Live :: ConnectState
-- | The connection is established, but no initial data propagation takes
-- place.
Idle :: ConnectState
-- | 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 ConnectKey
-- | Same as connect, but discards the returned ConnectKey.
connect_ :: ConnectState -> CellKey -> CellKey -> (a -> Maybe a) -> Propagator a ()
-- | Connects and synchronizes two cells, i.e. new values are propagated
-- from the source to the target cell, and vice versa. Short form of
-- syncWith Just Just.
sync :: ConnectState -> CellKey -> CellKey -> Propagator a (ConnectKey, ConnectKey)
-- | Same as sync, but discards the returned ConnectKeys.
sync_ :: ConnectState -> CellKey -> CellKey -> Propagator a ()
-- | 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 (ConnectKey, ConnectKey)
-- | Same as syncWith, but discards the returned ConnectKeys.
syncWith_ :: (a -> Maybe a) -> (a -> Maybe a) -> ConnectState -> CellKey -> CellKey -> Propagator a ()
-- | 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 ConnectKey
-- | Same as combine, but discards the returned ConnectKey.
combine_ :: ConnectState -> CellKey -> CellKey -> CellKey -> (a -> a -> Maybe a) -> Propagator a ()
-- | 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 ConnectKey
-- | Same as combineMany, but discards the returned
-- ConnectKey.
combineMany_ :: ConnectState -> [CellKey] -> CellKey -> ([a] -> Maybe a) -> Propagator a ()
-- | 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 ConnectKey
-- | Same as distribute, but discards the returned
-- ConnectKey.
distribute_ :: ConnectState -> CellKey -> [CellKey] -> (a -> Maybe a) -> Propagator a ()
-- | 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 ConnectKey
-- | Same as manyToMany, but discards the returned
-- ConnectKey.
manyToMany_ :: ConnectState -> [CellKey] -> [CellKey] -> ([a] -> Maybe a) -> Propagator a ()
-- | Removes a connection from the network.
disconnect :: ConnectKey -> Propagator a ()
-- | 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.
--
plus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
-- | 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.
--
minus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
-- | times s a b c connects three cells using the following
-- propagation schema:
--
--
-- - a * b is propagated to c if a or
-- b changes.
--
times :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
-- | 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.
--
timesWith :: Num a => (a -> a -> a) -> ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a ()
-- | abs s a b connects two cells using the following propagation
-- schema:
--
--
-- - |a| is propagated to b if a
-- changes.
--
abs :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a ()
-- | 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.
--
absWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a ()
-- | 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.
--
negate :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a ()
-- | signum s a b connects two cells using the following
-- propagation schema:
--
--
-- - Prelude.signum a is propagated to b if
-- a changes.
--
signum :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a ()
-- | 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.
--
signumWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a ()
instance GHC.Show.Show Data.Propagator.CellKey
instance GHC.Classes.Ord Data.Propagator.CellKey
instance GHC.Classes.Eq Data.Propagator.CellKey
instance GHC.Show.Show Data.Propagator.ConnectKey
instance GHC.Classes.Ord Data.Propagator.ConnectKey
instance GHC.Classes.Eq Data.Propagator.ConnectKey
instance GHC.Show.Show Data.Propagator.ConnectState
instance GHC.Classes.Ord Data.Propagator.ConnectState
instance GHC.Classes.Eq Data.Propagator.ConnectState
instance GHC.Show.Show a => GHC.Show.Show (Data.Propagator.Error a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Propagator.Error a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Propagator.Error a)
instance GHC.Base.Functor (Data.Propagator.Propagator a)
instance GHC.Base.Applicative (Data.Propagator.Propagator a)
instance GHC.Base.Monad (Data.Propagator.Propagator a)
-- | This module exports ST-based types and functions needed to create
-- cells, manipulate their data and wire them up for data propagation.
module Data.Propagator.ST
-- | The result of a propagation which allows to rollback changes and
-- inspect its success.
data Propagation s
-- | An action that reverts all cell changes of a propagation (both direct
-- and transitive ones).
undo :: Propagation s -> ST s ()
-- | True if the propagation was successful (i.e., it did not lead
-- to a cell change that is Incompatible), otherwise False.
--
-- Note that unsuccessful propagations are not automatically reverted.
-- Use undo to do this.
succeeded :: Propagation s -> Bool
-- | The type of a cell holding a value of type a. The type
-- parameter s serves to keep the internal states of different
-- cell networks separate from each other (see ST for details).
data Cell s a
-- | Represents a potential change of a cell value.
data Change a
-- | Indicates that a cell value has been changed to the new value
-- a.
Changed :: a -> Change a
-- | Indicates that a cell value did not change, i.e. needs no propagation.
Unchanged :: a -> Change a
-- | Indicates that a new cell value contradicts the one that is already
-- stored in the cell.
Incompatible :: Change a
-- | 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.
cell :: a -> (a -> a -> Change a) -> ST s (Cell s a)
-- | Reads the value of a specific cell.
readCell :: Cell s a -> ST s a
-- | Writes a new value to a specific cell and starts to propagate
-- potential changes through the network of connected cells.
writeCell :: a -> Cell s a -> ST s (Propagation s)
-- | If the content of a Cell s a 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.
label :: (a -> [b]) -> (b -> a) -> [Cell s a] -> ST s [[b]]
-- | Connects a source cell to a target cell in order to propagate changes
-- from the source to the target.
--
-- Note that newly connected cells do not start to propagate changes
-- immediately after wiring up. Use propagate or
-- propagateMany to do this.
connect :: Cell s a -> Cell s b -> (a -> ST s b) -> ST s ()
-- | Connects and synchronizes two cells, i.e. new values are propagated
-- from the source to the target cell, and vice versa. Short form of
-- syncWith id id.
--
-- Note that newly connected cells do not start to propagate changes
-- immediately after wiring up. Use propagate or
-- propagateMany to do this.
sync :: Cell s a -> Cell s a -> ST s ()
-- | 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.
--
-- Note that newly connected cells do not start to propagate changes
-- immediately after wiring up. Use propagate or
-- propagateMany to do this.
syncWith :: (a -> b) -> (b -> a) -> Cell s a -> Cell s b -> ST s ()
-- | Propagates the value of a specific cell to its connected cells in a
-- transitive manner. The propagation ends if no more cell changes occur
-- or if an Incompatible cell value change is encountered.
propagate :: Cell s a -> ST s (Propagation s)
-- | Propagates the values of specific cells to their connected cells in a
-- transitive manner. The propagation ends if no more cell changes occur
-- or if an Incompatible cell value change is encountered.
propagateMany :: [Cell s a] -> ST s (Propagation s)
-- | plus 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.
--
plus :: Num a => Cell s a -> Cell s a -> Cell s a -> ST s ()
-- | minus 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.
--
minus :: Num a => Cell s a -> Cell s a -> Cell s a -> ST s ()
-- | times a b c connects three cells using the following
-- propagation schema:
--
--
-- - a * b is propagated to c if a or
-- b changes.
--
times :: Num a => Cell s a -> Cell s a -> Cell s a -> ST s ()
-- | timesWith divOp 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.
--
timesWith :: Num a => (a -> a -> a) -> Cell s a -> Cell s a -> Cell s a -> ST s ()
-- | abs a b connects two cells using the following propagation
-- schema:
--
--
-- - |a| is propagated to b if a
-- changes.
--
abs :: Num a => Cell s a -> Cell s a -> ST s ()
-- | absWith inv 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.
--
absWith :: Num a => (a -> a) -> Cell s a -> Cell s a -> ST s ()
-- | negate 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.
--
negate :: Num a => Cell s a -> Cell s a -> ST s ()
-- | signum a b connects two cells using the following propagation
-- schema:
--
--
-- - Prelude.signum a is propagated to b if
-- a changes.
--
signum :: Num a => Cell s a -> Cell s a -> ST s ()
-- | signumWith inv 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.
--
signumWith :: Num a => (a -> a) -> Cell s a -> Cell s a -> ST s ()
instance GHC.Classes.Eq (Data.Propagator.ST.Cell s a)