data-aviary 0.2.3 → 0.4.0

raw patch · 6 files changed

+174/−241 lines, 6 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• data-aviary.cabal +38/−23
• src/Data/Aviary.hs +0/−193
• src/Data/Aviary/Birds.hs +13/−4
• src/Data/Aviary/BirdsInter.hs +9/−7
• src/Data/Aviary/BirdsVersion.hs +5/−3
• src/Data/Aviary/Functional.hs +109/−11

@@ -1,5 +1,5 @@ name:             data-aviary-version:          0.2.3+version:          0.4.0 license:          BSD3 license-file:     LICENSE copyright:        Stephen Tetley <stephen.tetley@gmail.com>@@ -8,33 +8,49 @@ category:         Combinators synopsis:         Combinator birds. description:+  .   A catalogue of the combinator birds (Data.Aviary.Birds etc.) - -  these modules are intended more for illustration than utility.+  these modules are intended for illustration and-or reference+  (i.e. looking up combinators by their type signature).   .-  Data.Aviary.Functional - operations from Applicative, Monad -  etc. with their types specialized to the function type. This -  might be usefulfor /bird-watching/ i.e. spotting instances -  where an Applicative, Monad or whatever operation corresponds -  to a combinator bird. Again this module is not intended for -  actual use.+  Using @Data.Aviary@ as a library (i.e. depending on it for +  other packages) is not recommended: combinator-mania leads to +  inscrutable code.+  .+  .+  Changelog+  .+  v0.4.0:+  .+  * Removed the \"useful\" combinators (to emphasize that +    Data.Aviary is not a utility library).    . -  Plus a smaller set (Data.Aviary) intended to be useful, -  collecting combinators that have already /escaped/ (published -  elsewhere) but aren\'t in Data.Function, along with some -  personal favourites.+  * Fixed typos in Haddock docs - thanks to Christopher Young for +    spotting them.   .-  Changelog:+  v0.3.0:   .-  0.2.3 added Data.Aviary.BirdsVersion - same as the original -        Birds module, but with type signatures following a -        revised naming scheme. +  * Added Monadic variations.   .-  0.2.2 added Data.Aviary.Functional - Applicative, Monad etc.-        signatures specialized to the function type. +  v0.2.3: +  . +  * Added Data.Aviary.BirdsVersion - same as the original Birds +    module, but with type signatures following a revised naming +    scheme.    .-  0.2.1 added @dup@ and the /combiner/ variants of cardinal-prime.+  v0.2.2: +  . +  * Added Data.Aviary.Functional - the Applicative, Monad etc. +    combinatorswith implementations and signatures specialized to +    the (simple) functional type cf. the Reader monad.    .-  0.2.0 added Haddock docs for @(\#\#)@.+  v0.2.1: +  .+  * Added @dup@ and the /combiner/ variants of cardinal-prime.+  .+  v0.2.0:+  . +  * Added Haddock docs for @(\#\#)@.    build-type:         Simple stability:          unstable@@ -44,15 +60,14 @@  library   hs-source-dirs:     src-  build-depends:      base<5+  build-depends:      base < 5       exposed-modules:-    Data.Aviary,     Data.Aviary.Birds,     Data.Aviary.BirdsInter,     Data.Aviary.BirdsVersion,-    Data.Aviary.Functional    +    Data.Aviary.Functional    other-modules:     

@@ -1,193 +0,0 @@-{-# OPTIONS -Wall #-}---------------------------------------------------------------------------------- |--- Module      :  Data.Aviary--- Copyright   :  (c) Stephen Peter Tetley 2009--- License     :  BSD3------ Maintainer  :  stephen.tetley@gmail.com--- Stability   :  experimental--- Portability :  to be determined------ Plainly named combinators------ Sometimes permuted to be generally useful...------ Note the fixity of @(\#)@ and @(\#\#)@ is not yet /fixed/.--- Some experience needs to be gathered as to whether the--- precendence levels are appropriate.-----------------------------------------------------------------------------------module Data.Aviary-  ( --  -- * The real stuff--    ( # )-  , ( ## )-  , subst-  , bigphi-  , appro-  , dup--  -- * Specs-  , oo-  , ooo-  , oooo--  -- * Combiners-  , combfi-  , combfii-  , combfiii--  ) where-------------------------------------------------------------------------------------- Combinators----infixl 7 #---- | T combinator - thrush------ Reverse application - the T combinator.--- Found in Peter Thiemann's WASH and the paper 'Client-Side Web --- Scripting in Haskell' - Erik Meijer, Daan Leijen & James Hook.----( # ) :: a -> (a -> b) -> b -x # f = f x---infixl 8 ##---- | Q Combinator - the queer bitd.--- --- Reverse composition - found in Peter Thiemann's WASH.--- You might perfer to use (<<<) from Control.Categoty.----( ## ) :: (a -> b) -> (b -> c) -> a -> c-f ## g = \x -> g (f x)- ---- | S combinator - subst.--- Familiar as Applicative\'s ('<*>') operator, which itself is --- fmap:------ f (b -> c) -> f b -> f c where f = ((->) a)-subst :: (a -> b -> c) -> (a -> b) -> a -> c-subst f g x = f x (g x) ---- | The big Phi, or Turner's @S'@ combinator.--- Known to Haskell programmers as liftA2 and liftM2 for the --- Applicative and Monad instances of (->).------ > (a1 -> a2 -> r) -> m a1 -> m a2 -> m r where m = ((->) a)--- --- Taste suggests you may prefer liftA2 especially as @bigphi@ is--- not a great name (calling it s\' would take a very useful --- variable name).----bigphi :: (b -> c -> d) -> (a -> b) -> (a -> c) -> a -> d-bigphi f g h x = f (g x) (h x)---- | A variant of the @D2@ or dovekie combinator - the argument--- order has been changed to be more satisfying for Haskellers:------ > (appro comb f g) x y------ > (f x) `comb` (g y)--- --- @on@ from Data.Function is similar but less general, where --- the two intermediate results are formed by applying the same --- function to the supplied arguments:------ > on = (appro comb f f)----appro :: (c -> d -> e) -> (a -> c) -> (b -> d) -> a -> b -> e-appro comb f g x y = comb (f x) (g y) ----- | dup - duplicator aka the W combinator aka Warbler. --- --- > dup f x = f x x----dup :: (a -> a -> b) -> a -> b-dup f x = f x x----------------------------------------------------------------------------------------- Specs - blackbird, bunting, ...---- Alleviate your composing-sectioning mania with specs!------ E.g.:--- (abs .) . (*) ==> abs `oo` (*)------ The family name /specs/ (glasses, specs, lunettes) is a --- visual pun when infix directives @`oo`@ are included. The --- @o@\'s of individual combinators are a fraternal nod to --- Clean and ML who use @o@ as function composition. Naturally--- we don\'t defined @o@ here and waste a good variable on a --- redundant combinator.---- | Compose an arity 1 function with an arity 2 function.--- B1 - blackbird-oo :: (c -> d) -> (a -> b -> c) -> a -> b -> d-oo f g = (f .) . g---- | Compose an arity 1 function with an arity 3 function.--- B2 - bunting-ooo :: (d -> e) -> (a -> b -> c -> d) -> a -> b -> c -> e-ooo f g = ((f .) .) . g---- | Compose an arity 1 function with an arity 4 function.-oooo :: (e -> f) -> (a -> b -> c -> d -> e) -> a -> b -> c -> d -> f-oooo f g = (((f .) .) .) . g  ------------------------------------------------------------------------------------- Combiners----- | Combiners - similar to the cardinal\' combinator. ------ Mnemonically - @comb@(ine) after applying @f@ to @x@ and a --- single identity: @y@. ------ > combfi comb f x y = comb (f x) y------ Equivalently:------ > combfi comb f = appro comb f id--- --- But combfi is a useful introduction to the (somewhat manic, --- but sometimes useful) higher arity versions.--- -combfi :: (c -> b -> d) -> (a -> c) -> a -> b -> d-combfi comb f x y = comb (f x) y - --- | Extrapolation of 'combfi' with another identity.------ Mnemonically - comb(ine) after applying @f@ to @x@ and two --- identities: @y@ and @z@.------ > combfii comb f x y z = comb (f x) y z----combfii :: (d -> b -> c -> e) -> (a -> d) -> a -> b -> c -> e-combfii comb f x y z = comb (f x) y z  ---- | Extrapolation of 'combfii' with a further identity.------ Mnemonically - comb(ine) after applying @f@ to @s@ and three--- identities: @t@ and @u@ and @v@.------ > combfii comb f s t u v = comb (f s) t u v----combfiii :: (e -> b -> c -> d -> f) -> (a -> e) -> a -> b -> c -> d -> f-combfiii comb f s t u v = comb (f s) t u v  

@@ -107,6 +107,8 @@ cardinal = flip  -- | A combinator - apply / applicator - Haskell ('$').+--+-- This is also called @i-star@. applicator :: (a -> b) -> a -> b applicator = ($) @@ -193,7 +195,7 @@ finchstar :: (c -> b -> a -> d) -> a -> b -> c -> d finchstar f x y z = f z y x --- | F** combinator - finch once removed.+-- | F** combinator - finch twice removed. finchstarstar :: (a -> d -> c -> b -> e) -> a -> b -> c -> d -> e finchstarstar f s t u v = f s v u t @@ -248,6 +250,9 @@   -- | (Big) Phi combinator - phoenix - Haskell 'liftM2'.+--+-- This is the same function as 'Data.Aviary.Birds.starling''. +--  phoenix :: (b -> c -> d) -> (a -> b) -> (a -> c) -> a -> d phoenix f g h x = f (g x) (h x) @@ -285,7 +290,7 @@ robinstar :: (b -> c -> a -> d) -> a -> b -> c -> d robinstar f x y z = f y z x --- | R* combinator - robin twice removed.+-- | R** combinator - robin twice removed. robinstarstar :: (a -> c -> d -> b -> e) -> a -> b -> c -> d -> e robinstarstar f s t u v = f s u v t @@ -299,7 +304,11 @@   -- | S' combinator - starling prime - Turner\'s big phi. --- Haskell: Applicative\'s liftA2 on functions.+-- Haskell: Applicative\'s 'liftA2' on functions (and similarly +-- Monad\'s 'liftM2').+--+-- This is the same function as 'Data.Aviary.Birds.phoenix'. +--  starling' :: (b -> c -> d) -> (a -> b) -> (a -> c) -> a -> d starling' f g h x = f (g x) (h x) @@ -309,7 +318,7 @@ thrush :: a -> (a -> b) -> b thrush x f = f x --- | V combinator - vireo.+-- | V combinator - vireo (pairing). vireo :: a -> b -> (a -> b -> c) -> c vireo x y f = f x y 

@@ -12,8 +12,7 @@ -- -- Bird monickered combinators interdefined. -- --- This module is intended for illustration (the type signatures!) --- rather than utility.+-- This module is intended for illustration rather than utility. --  -- The \'long reach\' Turner set { S, K, I, B, C, S\', B\', C\' } --@@ -110,11 +109,14 @@  -- | A combinator - apply / applicator - Haskell ('$'). ----- Note: the definition here is @- C (B B I) I -@ and not the --- familiar @- S (S K) -@ which as far as Haskell is concerned--- has a different type. +-- This is also called @i-star@.+--+-- Note: the (inter-) definition here is @- C (B B I) I -@ and +-- not the familiar @- S (S K) -@ which as far as Haskell is +-- concerned has a different type: -- --- @ (S(SK)) :: ((a -> b) -> a) -> (a -> b) -> a @+-- > (S(SK)) :: ((a -> b) -> a) -> (a -> b) -> a +-- applicator :: (a -> b) -> a -> b applicator = cardinal (bluebird bluebird idiot) idiot @@ -207,7 +209,7 @@ finchstar :: (c -> b -> a -> d) -> a -> b -> c -> d finchstar = bluebird cardinalstar robinstar  --- | F** combinator - finch once removed.+-- | F** combinator - finch twice removed. finchstarstar :: (a -> d -> c -> b -> e) -> a -> b -> c -> d -> e finchstarstar = bluebird finchstar 

@@ -107,7 +107,9 @@ cardinal :: (r2 -> r1 -> ans) -> r1 -> r2 -> ans cardinal = flip --- | A combinator - apply / applicator - Haskell ('$').+-- | A combinator - apply / applicator - Haskell ('$')+-- +-- This is also called @i-star@. applicator :: (r1 -> ans) -> r1 -> ans applicator = ($) @@ -194,7 +196,7 @@ finchstar :: (r3 -> r2 -> r1 -> ans) -> r1 -> r2 -> r3 -> ans finchstar f x y z = f z y x --- | F** combinator - finch once removed.+-- | F** combinator - finch twice removed. finchstarstar :: (r1 -> r4 -> r3 -> r2 -> ans) -> r1 -> r2 -> r3 -> r4 -> ans finchstarstar f x y z1 z2 = f x z2 z1 y @@ -286,7 +288,7 @@ robinstar :: (r2 -> r3 -> r1 -> ans) -> r1 -> r2 -> r3 -> ans robinstar f x y z = f y z x --- | R* combinator - robin twice removed.+-- | R** combinator - robin twice removed. robinstarstar :: (r1 -> r3 -> r4 -> r2 -> ans) -> r1 -> r2 -> r3 -> r4 -> ans robinstarstar f x y z1 z2 = f x z1 z2 y  

@@ -13,7 +13,7 @@ -- Functor, Applicative, Monad operations /specialized/ to  -- the functional type. ----- This is for reference (obviously) and is not intended for use.+-- This catalogue is for reference and is not intended for use. -- ----------------------------------------------------------------------------- @@ -92,7 +92,7 @@    ) where -import qualified Control.Applicative    as Ap+import qualified Control.Applicative    as App import qualified Control.Arrow          as Arr import qualified Control.Category       as Cat import qualified Control.Monad          as Mon@@ -105,6 +105,10 @@  -- ((->) r) replaces the type variable f ++-- | 'fmap' for the function instance of Functor is /compose/ +-- ('.') which in turn is 'Data.Aviary.Birds.bluebird'.+--  fmap        :: (a -> b) -> (r -> a) -> (r -> b) fmap        = Mon.fmap @@ -114,41 +118,65 @@  -- ((->) r) replaces the type variable f +-- | The Applicative combinator ('<$>') is a synonym for 'fmap', +-- so for the function instance of of Applicative it is +-- /compose/ ('.') which is 'Data.Aviary.Birds.bluebird'.+--  (<$>)       :: (a -> b) -> (r -> a) -> (r -> b) (<$>)       = Mon.fmap +-- | Applicative ('<$').+-- (<$)        :: a -> (r -> b) -> (r -> a)-(<$)        = (Ap.<$)+(<$)        = (App.<$)  -- Applicative class ++-- | The function instance of Applicative 'pure' is +-- 'const' which is 'Data.Aviary.Birds.kestrel'.+-- pure        :: a -> (r -> a)-pure        = Ap.pure+pure        = App.pure ++-- | The combinator ('<*>') for the function instance of +-- Applicative is the S combinator aka +-- 'Data.Aviary.Birds.starling'.+-- (<*>)       :: (r -> a -> b) -> (r -> a) -> (r -> b)-(<*>)       = (Ap.<*>)+(<*>)       = (App.<*>)  (*>)        :: (r -> a) -> (r -> b) -> (r -> b)-(*>)        = (Ap.*>)+(*>)        = (App.*>)  (<*)        :: (r -> a) -> (r -> b) -> (r -> a)-(<*)        = (Ap.<*)+(<*)        = (App.<*)  -- No function instance of Alternative.    (<**>)      :: (r -> a) -> (r -> a -> b) -> (r -> b)-(<**>)      = (Ap.<**>)+(<**>)      = (App.<**>) +-- | The Applicative function 'liftA' is a synonym for 'fmap', +-- so for the function instance of of Applicative it is +-- /compose/ ('.') which is 'Data.Aviary.Birds.bluebird'.+--  liftA       :: (a -> b) -> (r -> a) -> (r -> b)-liftA       = Ap.liftA+liftA       = App.liftA ++-- | 'liftA2' for the function instance of Applicative is the +-- 'Data.Aviary.Birds.phoenix' combinator, also called big Phi +-- and /starling-prime/.+-- liftA2      :: (a -> b -> c) -> (r -> a) -> (r -> b) -> (r -> c)-liftA2      = Ap.liftA2+liftA2      = App.liftA2  liftA3      :: (a -> b -> c -> d) -> (r -> a) -> (r -> b) -> (r -> c) -> (r -> d)-liftA3      = Ap.liftA3+liftA3      = App.liftA3  -- No optional (due to no Alternative instance) @@ -159,15 +187,30 @@  -- (->) replaces the type variable cat ++-- | For the function instance of Category @id@ is just the +-- identity function (Haskell\'s 'id').+-- id          :: a -> a id          = Cat.id +-- | For the function instance of Category composition is just +-- regular function composition aka 'Data.Aviary.Birds.bluebird'.+-- (.)         ::  (b -> c) -> (a -> b) -> (a -> c) (.)         = (Cat..) +-- | For the function instance of Category right-to-left +-- composition is just regular function composition aka+-- 'Data.Aviary.Birds.bluebird'.+-- (<<<)       :: (b -> c) -> (a -> b) -> (a -> c) (<<<)       = (Cat.<<<) ++-- | For the function instance of Category left-to-right +-- composition is the 'Data.Aviary.Birds.queer' bird.+-- (>>>)       :: (a -> b) -> (b -> c) -> (a -> c) (>>>)       = (Cat.>>>) @@ -183,6 +226,10 @@ (>>)        :: (r -> a) -> (r -> b) -> (r -> b) (>>)        = (Mon.>>) ++-- | The function instance of Monadic 'return' is equal to the+-- constant function ('const') aka 'Data.Aviary.Birds.kestrel'.+-- return      :: a -> (r -> a) return      = Mon.return @@ -260,9 +307,19 @@ unless      :: Bool -> (r -> ()) -> r -> () unless      = Mon.unless +-- | The Monadic function 'liftM' would ideally be a synonym for +-- 'fmap', so for the function instance of of Monad it corresponds +-- to composition - Haskell\'s ('.') and the +-- 'Data.Aviary.Birds.bluebird' combinator.+--  liftM       :: (a -> b) -> (r -> a) -> r -> b liftM       = Mon.liftM ++-- | 'liftM2' for the function instance of Monad is the +-- 'Data.Aviary.Birds.phoenix' combinator, also called big Phi +-- and /starling-prime/.+-- liftM2      :: (a -> b -> c) -> (r -> a) -> (r -> b) -> r -> c liftM2      = Mon.liftM2 @@ -277,6 +334,10 @@             -> (r -> a) -> (r -> b) -> (r -> c) -> (r -> d) -> (r -> e) -> r -> f liftM5      = Mon.liftM5 +-- | 'ap' is the Monadic equivalent of the Applicative operator +-- ('<*>'). So for the function instance of Monad it corresponds +-- to the S combinator aka 'Data.Aviary.Birds.starling'.+-- ap          :: (r -> a -> b) -> (r -> a) -> r -> b ap          = Mon.ap @@ -287,6 +348,13 @@ -- (->) replaces the type variable a  +-- | The Arrow operation 'arr' corresponds to function +-- application for the function instance of Arrow - i.e. +-- Haskell\'s ('$') operator.+-- +-- This is the 'Data.Aviary.Birds.applicator' combinator in +-- Data.Aviary.+-- arr         :: (b -> c) -> b -> c arr         = Arr.arr @@ -302,18 +370,48 @@ (&&&)       :: (b -> c) -> (b -> c') -> b -> (c, c') (&&&)       = (Arr.&&&) ++-- | For the function instance of Arrow, 'returnA' is the +-- identity function aka 'Data.Aviary.Birds.idiot'.+-- returnA     :: (b -> b) returnA     = Arr.returnA +-- | The Arrow operation /precomposition with a pure function/ +-- (left-to-right) is equal to the left-to-right composition +-- operator ('>>>') for function Arrows.+-- +-- This corresponds to 'Data.Aviary.Birds.queer'.+--  (^>>)       :: (b -> c) -> (c -> d) -> (b -> d) (^>>)       = (Arr.^>>) +-- | The Arrow operation /postcomposition with a pure function/+-- (left-to-right) is equal to the left-to-right composition +-- operator ('>>>') for function Arrows.+-- +-- This corresponds to 'Data.Aviary.Birds.queer'.+--  (>>^)       :: (b -> c) -> (c -> d) -> (b -> d) (>>^)       = (Arr.>>^) +-- | The Arrow operation /precomposition with a pure function/+-- (right-to-left) is equal to the right-to-left composition +-- operator ('<<<') for function Arrows, which in turn is equal to+-- regular function composition.+-- +-- This corresponds to 'Data.Aviary.Birds.bluebird'.+--  (<<^)       :: (c -> d) -> (b -> c) -> (b -> d) (<<^)       = (Arr.<<^) +-- | The Arrow operation /postcomposition with a pure function/+-- (right-to-left) is equal to the right-to-left composition +-- operator ('<<<') for function Arrows, which in turn is equal to+-- regular function composition.+-- +-- This corresponds to 'Data.Aviary.Birds.bluebird'.+--  (^<<)       :: (c -> d) -> (b -> c) -> (b -> d) (^<<)       = (Arr.^<<)