-- 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.4.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 connection 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 -- | 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. -- -- Such an identification should not be constructed manually, or else -- InvalidCell errors are possible. The raw identification is -- exposed for situations where cells should be managed externally, like -- in an IntMap. newtype CellKey CellKey :: Int -> CellKey [rawCellKey] :: CellKey -> Int -- | 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 :: (CellKey -> 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 :: a -> CellKey -> 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. -- -- Such an identification should not be constructed manually, or else -- InvalidConnect errors are possible. The raw identification is -- exposed for situations where connections should be managed externally, -- like in an IntMap. newtype ConnectKey ConnectKey :: Int -> ConnectKey [rawConnectKey] :: ConnectKey -> Int -- | 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: -- -- plus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () -- | minus s a b c connects three cells using the following -- propagation schema: -- -- minus :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () -- | times s a b c connects three cells using the following -- propagation schema: -- -- times :: Num a => ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () -- | timesWith divOp s a b c connects three cells using the -- following propagation schema: -- -- timesWith :: Num a => (a -> a -> a) -> ConnectState -> CellKey -> CellKey -> CellKey -> Propagator a () -- | abs s a b connects two cells using the following propagation -- schema: -- -- abs :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a () -- | absWith inv s a b connects two cells using the following -- propagation schema: -- -- absWith :: Num a => (a -> a) -> ConnectState -> CellKey -> CellKey -> Propagator a () -- | negate s a b connects two cells using the following -- propagation schema: -- -- negate :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a () -- | signum s a b connects two cells using the following -- propagation schema: -- -- signum :: Num a => ConnectState -> CellKey -> CellKey -> Propagator a () -- | signumWith inv s a b connects two cells using the following -- propagation schema: -- -- 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 the types and functions needed to create cells of -- heterogeneous types, manipulate their data and wire them up for data -- propagation. module Data.Propagator.Hetero -- | A network consists of cells and connections which propagate data -- between them. data Network -- | Represents an empty network. empty :: Network -- | Represents possible errors that may occur when modifying or using a -- network. data Error -- | The specified cell could not be found. InvalidCell :: Some CellKey -> Error -- | The specified connection could not be found. InvalidConnect :: ConnectKey -> Error -- | The specified connection did not produce a value. NoPropagation :: ConnectKey -> Error -- | The old value of the specified cell is incompatible with a new value -- propagated to it. Conflict :: Some CellKey -> Error -- | Network modifications and data propagations are captured by the -- Propagator monad. data Propagator a -- | Applies modifications captured by the propagator monad to a network, -- thus producing a new network if no error occurred. runPropagator :: Propagator a -> Network -> Either Error (Network, a) -- | Represents a unique identification of a network cell. -- -- Such an identification should not be constructed manually, or else -- InvalidCell errors are possible. The raw identification is -- exposed for situations where cells should be managed externally, like -- in an IntMap. newtype CellKey (a :: Type) CellKey :: Int -> CellKey (a :: Type) [rawCellKey] :: CellKey (a :: Type) -> Int -- | Represents a list of cell identifications of heterogeneous types. data CellKeys ts [KNil] :: CellKeys '[] [KCons] :: CellKey a -> CellKeys ts -> CellKeys (a ': ts) infixr 3 `KCons` -- | Represents a list of cell values of heterogeneous types. data CellValues ts [VNil] :: CellValues '[] [VCons] :: a -> CellValues ts -> CellValues (a ': ts) infixr 3 `VCons` -- | 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 :: (CellKey a -> a) -> (a -> a -> Change a) -> Propagator (CellKey a) -- | Reads the value of a specific cell. readCell :: CellKey a -> Propagator a -- | Writes a new value to a specific cell and starts to propagate -- potential changes through the network of connected cells. writeCell :: a -> CellKey a -> Propagator () -- | Removes a cell from the network. This also removes all connections -- related to the cell. removeCell :: CellKey a -> Propagator () -- | 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 a] -> Propagator [[b]] -- | Represents a unique identification of a network connection. -- -- Such an identification should not be constructed manually, or else -- InvalidConnect errors are possible. The raw identification is -- exposed for situations where connections should be managed externally, -- like in an IntMap. newtype ConnectKey ConnectKey :: Int -> ConnectKey [rawConnectKey] :: ConnectKey -> Int -- | 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 a -> CellKey b -> (a -> Maybe b) -> Propagator ConnectKey -- | Same as connect, but discards the returned ConnectKey. connect_ :: ConnectState -> CellKey a -> CellKey b -> (a -> Maybe b) -> Propagator () -- | 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 a -> CellKey a -> Propagator (ConnectKey, ConnectKey) -- | Same as sync, but discards the returned ConnectKeys. sync_ :: ConnectState -> CellKey a -> CellKey a -> Propagator () -- | 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 b) -> (b -> Maybe a) -> ConnectState -> CellKey a -> CellKey b -> Propagator (ConnectKey, ConnectKey) -- | Same as syncWith, but discards the returned ConnectKeys. syncWith_ :: (a -> Maybe b) -> (b -> Maybe a) -> ConnectState -> CellKey a -> CellKey b -> Propagator () -- | 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 a -> CellKey b -> CellKey c -> (a -> b -> Maybe c) -> Propagator ConnectKey -- | Same as combine, but discards the returned ConnectKey. combine_ :: ConnectState -> CellKey a -> CellKey b -> CellKey c -> (a -> b -> Maybe c) -> Propagator () -- | 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 -> CellKeys ts -> CellKey a -> (CellValues ts -> Maybe a) -> Propagator ConnectKey -- | Same as combineMany, but discards the returned -- ConnectKey. combineMany_ :: ConnectState -> CellKeys ts -> CellKey a -> (CellValues ts -> Maybe a) -> Propagator () -- | 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 a -> [CellKey b] -> (a -> Maybe b) -> Propagator ConnectKey -- | Same as distribute, but discards the returned -- ConnectKey. distribute_ :: ConnectState -> CellKey a -> [CellKey b] -> (a -> Maybe b) -> Propagator () -- | 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 -> CellKeys xs -> [CellKey a] -> (CellValues xs -> Maybe a) -> Propagator ConnectKey -- | Same as manyToMany, but discards the returned -- ConnectKey. manyToMany_ :: ConnectState -> CellKeys xs -> [CellKey a] -> (CellValues xs -> Maybe a) -> Propagator () -- | Removes a connection from the network. disconnect :: ConnectKey -> Propagator () -- | plus s a b c connects three cells using the following -- propagation schema: -- -- plus :: Num a => ConnectState -> CellKey a -> CellKey a -> CellKey a -> Propagator () -- | minus s a b c connects three cells using the following -- propagation schema: -- -- minus :: Num a => ConnectState -> CellKey a -> CellKey a -> CellKey a -> Propagator () -- | times s a b c connects three cells using the following -- propagation schema: -- -- times :: Num a => ConnectState -> CellKey a -> CellKey a -> CellKey a -> Propagator () -- | timesWith divOp s a b c connects three cells using the -- following propagation schema: -- -- timesWith :: Num a => (a -> a -> a) -> ConnectState -> CellKey a -> CellKey a -> CellKey a -> Propagator () -- | abs s a b connects two cells using the following propagation -- schema: -- -- abs :: Num a => ConnectState -> CellKey a -> CellKey a -> Propagator () -- | absWith inv s a b connects two cells using the following -- propagation schema: -- -- absWith :: Num a => (a -> a) -> ConnectState -> CellKey a -> CellKey a -> Propagator () -- | negate s a b connects two cells using the following -- propagation schema: -- -- negate :: Num a => ConnectState -> CellKey a -> CellKey a -> Propagator () -- | signum s a b connects two cells using the following -- propagation schema: -- -- signum :: Num a => ConnectState -> CellKey a -> CellKey a -> Propagator () -- | signumWith inv s a b connects two cells using the following -- propagation schema: -- -- signumWith :: Num a => (a -> a) -> ConnectState -> CellKey a -> CellKey a -> Propagator () instance GHC.Show.Show (Data.Propagator.Hetero.CellKey a) instance GHC.Classes.Ord (Data.Propagator.Hetero.CellKey a) instance GHC.Classes.Eq (Data.Propagator.Hetero.CellKey a) instance GHC.Show.Show Data.Propagator.Hetero.ConnectKey instance GHC.Classes.Ord Data.Propagator.Hetero.ConnectKey instance GHC.Classes.Eq Data.Propagator.Hetero.ConnectKey instance GHC.Show.Show Data.Propagator.Hetero.ConnectState instance GHC.Classes.Ord Data.Propagator.Hetero.ConnectState instance GHC.Classes.Eq Data.Propagator.Hetero.ConnectState instance GHC.Base.Functor Data.Propagator.Hetero.Propagator instance GHC.Base.Applicative Data.Propagator.Hetero.Propagator instance GHC.Base.Monad Data.Propagator.Hetero.Propagator -- | 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: -- -- 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: -- -- 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: -- -- 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: -- -- 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: -- -- abs :: Num a => Cell s a -> Cell s a -> ST s () -- | absWith inv a b connects two cells using the following -- propagation schema: -- -- absWith :: Num a => (a -> a) -> Cell s a -> Cell s a -> ST s () -- | negate a b connects two cells using the following propagation -- schema: -- -- negate :: Num a => Cell s a -> Cell s a -> ST s () -- | signum a b connects two cells using the following propagation -- schema: -- -- signum :: Num a => Cell s a -> Cell s a -> ST s () -- | signumWith inv a b connects two cells using the following -- propagation schema: -- -- signumWith :: Num a => (a -> a) -> Cell s a -> Cell s a -> ST s () instance GHC.Classes.Eq (Data.Propagator.ST.Cell s a)