1 files changed, 64 insertions, 0 deletions

diff --git a/FunctorToMaybe.hs b/FunctorToMaybe.hs
new file mode 100644
index 0000000..0fd6b7f
--- /dev/null
+++ b/FunctorToMaybe.hs
@@ -0,0 +1,64 @@
+---------------------------------------------------------------------------
+-- |
+-- Module      :  FunctorToMaybe
+--
+-- Maintainer  :  joe@jerkface.net
+-- Stability   :  experimental
+--
+-- Motivation: When parsing a stream of events, it is often desirable to
+-- let certain control events pass-through to the output stream without
+-- interrupting the parse.  For example, the conduit package uses 
+-- <http://hackage.haskell.org/package/conduit-1.0.13.1/docs/Data-Conduit.html#t:Flush Flush>
+-- which adds a special command to a stream and the blaze-builder-conduit 
+-- package has <http://hackage.haskell.org/package/blaze-builder-conduit-1.0.0/docs/Data-Conduit-Blaze.html#g:2 conduits> that treat the nullary constructor with special significance.
+--
+-- But for other intermediary conduits, the nullary @Flush@ constructor may 
+-- be noise that they should politely preserve in case it is meaningul downstream.
+-- If <http://hackage.haskell.org/package/conduit-1.0.13.1/docs/Data-Conduit.html#t:Flush Flush>
+-- implemented the 'FunctorToMaybe' type class, then 'functorToEither' could be used to
+-- seperate the noise from the work-product.
+--
+module FunctorToMaybe where
+
+
+-- | The 'FunctorToMaybe' class genaralizes 'Maybe' in that the
+-- there may be multiple null elements. 
+--
+-- Instances of 'FunctorToMaybe' should satisfy the following laws:
+--
+-- > functorToMaybe (fmap f g) == fmap f (functorToMaybe g)
+--
+class Functor g => FunctorToMaybe g where
+    functorToMaybe :: g a -> Maybe a
+
+
+instance FunctorToMaybe Maybe where
+    functorToMaybe = id
+instance FunctorToMaybe (Either a) where
+    functorToMaybe (Right x) = Just x
+    functorToMaybe _         = Nothing
+
+
+-- | 'functorToEither' is a null-preserving cast.
+--
+-- If @functorToMaybe g == Nothing@, then a casted value is returned with Left.
+-- If @functorToMaybe g == Just a@, then @Right a@ is returned.
+--
+-- Returning to our <http://hackage.haskell.org/package/conduit-1.0.13.1/docs/Data-Conduit.html#t:Flush Flush>
+-- example, if we define
+--
+-- > instance Flush where 
+-- >   functorToMaybe Flush     = Nothing
+-- >   functorToMaybe (Chunk a) = Just a
+--
+-- Now stream processors can use 'functorToEither' to transform any nullary constructors while
+-- while doing its work to transform the data before forwarding it into 
+-- <http://hackage.haskell.org/package/blaze-builder-conduit-1.0.0/docs/Data-Conduit-Blaze.html#v:builderToByteStringFlush builderToByteStringFlush>.
+--
+functorToEither :: FunctorToMaybe f => f a -> Either (f b) a
+functorToEither ga =
+    maybe (Left $ uncast ga)
+          Right
+          (functorToMaybe ga)
+ where
+    uncast = fmap (error "bad FunctorToMaybe instance")