-- 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: -- -- 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 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)