diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,6 @@ +## 0.2.1.1 +* Fix dead links in documentation. + ## 0.2.1.0 * Add `toCont` function diff --git a/control-dsl.cabal b/control-dsl.cabal --- a/control-dsl.cabal +++ b/control-dsl.cabal @@ -2,11 +2,11 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 17ddc07e76440e405a2ac39604537ed62560c5bb90aa95d930e09770037ad0ad +-- hash: 3d963a3b297adf76cb7ad8c4341ee909913452fb539ebff4848ba4a18260fbb8 name: control-dsl -version: 0.2.1.1 -synopsis: An alternative to monads +version: 0.2.1.2 +synopsis: An alternative to monads for control flow DSLs description: This \"control-dsl\" package is a toolkit to create extensible Domain Specific Languages in @do@-notation. . See "Control.Dsl" for more information. diff --git a/src/Control/Dsl.hs b/src/Control/Dsl.hs --- a/src/Control/Dsl.hs +++ b/src/Control/Dsl.hs @@ -72,7 +72,7 @@ The type @r@ varies from different 'Control.Dsl.PolyCont.PolyCont' instances. By defining 'Control.Dsl.PolyCont.PolyCont' instances for @PureInterpreter@, -you can make @r@ be a @PureInterpreter@: +you can make @r@ be a pure interpreter: >>> type PureInterpreter = Int -> [String] -> Cont [String] IOError @@ -156,6 +156,16 @@ instance PolyCont (Return IOError) (IO ()) Void where runPolyCont (Return e) _ = hPutStrLn stderr (show e) :} + +The above three 'Control.Dsl.PolyCont.PolyCont' instances are not directly +implemented for @EffectfulInterpreter@. +Instead, they are implemented for @IO ()@. +Then, instances for @EffectfulInterpreter@ can be automatically derived from +instances for @IO ()@. +There are two built-in 'Control.Dsl.PolyCont.PolyCont' derivation rules, +for 'Control.Dsl.Cont.Cont' and 'State', respectively. +What interesting is that 'State' is defined as plain function, +which exactly matches the type of @EffectfulInterpreter@. === Running the DSL effectfully diff --git a/src/Control/Dsl/Cont.hs b/src/Control/Dsl/Cont.hs --- a/src/Control/Dsl/Cont.hs +++ b/src/Control/Dsl/Cont.hs @@ -23,14 +23,30 @@ >>> import Control.Dsl >>> import Control.Dsl.Yield >>> import Control.Dsl.Empty +>>> import Control.Dsl.Monadic + >>> :{ f :: IO () !! [Integer] !! [String] !! [Double] f = do Yield "foo" Yield 0.5 + Yield "bar" Yield 42 - empty + Yield "baz" + return ([] :: [Double]) :} + +>>> :{ +f >>= (\d -> do { Monadic $ putStrLn $ "double list: " ++ show d + ; return ([] :: [String]) }) + >>= (\s -> do { Monadic $ putStrLn $ "string list: " ++ show s + ; return ([] :: [Integer]) }) + >>= (\i -> do { Monadic $ putStrLn $ "integer list: " ++ show i + ; return () }) +:} +double list: [0.5] +string list: ["foo","bar","baz"] +integer list: [42] -} type (!!) = Cont @@ -50,6 +66,11 @@ guard True = Cont ($ ()) guard False = Cont (const empty) +{- | The 'PolyCont' derivation rule for any keywords in a 'Cont' @do@ block. + +This derivated instance provide the ability similar +to @ContT@ monad transformers. +-} instance {-# OVERLAPS #-} PolyCont k r a => PolyCont k (Cont r a') a where runPolyCont k f = Cont $ \g -> runPolyCont k $ \a -> runCont (f a) g diff --git a/src/Control/Dsl/Dsl.hs b/src/Control/Dsl/Dsl.hs --- a/src/Control/Dsl/Dsl.hs +++ b/src/Control/Dsl/Dsl.hs @@ -31,8 +31,8 @@ +-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------+ | Interpreted by | 'Control.Dsl.PolyCont.PolyCont' | N/A | 'Control.Dsl.PolyCont.PolyCont' | +-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------+ -| Can be present at | not the last statement of a @do@ block | the last statement of a @do@ block | -+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| Can be present at | not the last statement in a @do@ block | any position in a @do@ block | the last statement in a @do@ block | ++-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------+ Don't create custom instances of 'Dsl' for statement. Instead, create 'PolyCont' instances for your custom GADT keywords. diff --git a/src/Control/Dsl/Empty.hs b/src/Control/Dsl/Empty.hs --- a/src/Control/Dsl/Empty.hs +++ b/src/Control/Dsl/Empty.hs @@ -16,7 +16,7 @@ instance {-# OVERLAPS #-} Control.Applicative.Alternative m => PolyCont Empty (m a) Void where runPolyCont Empty _ = Control.Applicative.empty -{- | Return an empty @a@, similar to 'Control.Alternative.empty'. +{- | Return an empty @a@, similar to 'Control.Applicative.empty'. This 'empty' function aims to be used as the last statement of a @do@ block. -} diff --git a/src/Control/Dsl/Return.hs b/src/Control/Dsl/Return.hs --- a/src/Control/Dsl/Return.hs +++ b/src/Control/Dsl/Return.hs @@ -25,7 +25,7 @@ When 'return' is present in a nested @do@ block for 'Control.Dsl.Cont.when' or 'Control.Dsl.Cont.unless', -if the @r@ is not @()@, +if the @r'@ is not @()@, it will create a 'Control.Dsl.Cont.Cont' that performs early return, skipping the rest statements of the outer @do@ notation. diff --git a/src/Control/Dsl/State.hs b/src/Control/Dsl/State.hs --- a/src/Control/Dsl/State.hs +++ b/src/Control/Dsl/State.hs @@ -6,7 +6,7 @@ {- | Description : Mutable variables -This module provides keywords to 'Put' and 'Get' the value of multiple mutable variables in a @do@ block. +This module provides keywords to 'Put' and 'Get' the value on multiple mutable variables in a @do@ block. -} module Control.Dsl.State ( module Control.Dsl.State.Put, diff --git a/src/Control/Dsl/State/State.hs b/src/Control/Dsl/State/State.hs --- a/src/Control/Dsl/State/State.hs +++ b/src/Control/Dsl/State/State.hs @@ -3,7 +3,6 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE RebindableSyntax #-} {-# LANGUAGE GADTs #-} -{-# LANGUAGE RankNTypes #-} module Control.Dsl.State.State where @@ -31,8 +30,8 @@ >>> import Data.Foldable The following @append@ function 'Control.Dsl.State.Get's a @Seq String@ state, -appends @s@ to the 'Data.Sequence.Seq', -and 'Control.Dsl.State.Put's the new 'Data.Sequence.Seq' as the updated state. +appends @s@ to the @Seq@, +and 'Control.Dsl.State.Put's the new @Seq@ as the updated state. >>> :{ append s = do @@ -72,14 +71,19 @@ -} type State = (->) +{- | The 'PolyCont' derivation rule for any keywords in a 'State' @do@ block. + +This derivated instance provide the ability similar +to @StateT@ or @ReaterT@ monad transformers. +-} instance {-# OVERLAPS #-} PolyCont k r a => PolyCont k (State s r) a where - runPolyCont k f s = runPolyCont k $ \a -> f a s + runPolyCont k f s = runPolyCont k (\a -> f a s) instance {-# OVERLAPS #-} PolyCont k r Void => PolyCont k (State s r) Void where runPolyCont k _ _ = runPolyCont k absurd instance {-# OVERLAPS #-} PolyCont Empty r Void => PolyCont Empty (State s r) Void where runPolyCont k _ _ = empty - + instance PolyCont (Return r) (State s r) Void where runPolyCont (Return r) _ _ = r