[#13] Improve documentation and description (#72)

.travis.yml

@@ -25,30 +25,30 @@ matrix:
         - ghc-8.2.2
         - cabal-install-head
 
-  - ghc: 8.4.3
-    env: GHCVER='8.4.3' CABALVER='head'
+  - ghc: 8.4.4
+    env: GHCVER='8.4.4' CABALVER='head'
     os: linux
     addons:
       apt:
         sources:
         - hvr-ghc
         packages:
-        - ghc-8.4.3
+        - ghc-8.4.4
         - cabal-install-head
 
-  - ghc: 8.6.1
-    env: GHCVER='8.6.1' CABALVER='head'
+  - ghc: 8.6.2
+    env: GHCVER='8.6.2' CABALVER='head'
     os: linux
     addons:
       apt:
         sources:
         - hvr-ghc
         packages:
-        - ghc-8.6.1
+        - ghc-8.6.2
         - cabal-install-head
 
-  - ghc: 8.4.3
-    env: GHCVER='8.4.3' STACK_YAML="$TRAVIS_BUILD_DIR/stack.yaml"
+  - ghc: 8.4.4
+    env: GHCVER='8.4.4' STACK_YAML="$TRAVIS_BUILD_DIR/stack.yaml"
     os: linux
     addons:
       apt:
@@ -75,7 +75,7 @@ install:
 script:
   - |
     if [ -z "$STACK_YAML" ]; then
-       cabal new-test co-log-core
+       cabal new-test all
     else
       stack build co-log-core --test --bench --no-run-benchmarks --no-terminal
       stack build co-log      --test --bench --no-run-benchmarks --no-terminal

co-log-core/CHANGELOG.md

@@ -1,34 +1,36 @@
-Change log
-==========
+# Change log
 
 `co-log-core` uses [PVP Versioning][1].
 The change log is available [on GitHub][2].
 
-0.1.1
-=====
+## 0.1.1 — Nov 15, 2018
 
-* [#63](https://github.com/kowainik/co-log/issues/63)
-  Add `logPrint` and `logPrintStderr` to Colog.Core.IO
+* [#63](https://github.com/kowainik/co-log/issues/63):
+  Add `logPrint`, `logPrintStderr`, `logPrintHandle` and `withLogPrintFile` to `Colog.Core.IO`.
 * [#46](https://github.com/kowainik/co-log/issues/46):
   Moves `logStringStdout`, `logStringStderr`, `logStringHandle`,
-  `withLogStringFile` from `Colog.Actions` to `Colog.Core.IO`
-* [#48](https://github.com/kowainik/co-log/issues/48)
+  `withLogStringFile` from `Colog.Actions` to `Colog.Core.IO`.
+* [#48](https://github.com/kowainik/co-log/issues/48):
   Adds `liftLogIO` function.
-* [#49](https://github.com/kowainik/co-log/issues/49)
-  Adds `<&` and `&>`operators for `unLogAction`.
+* [#49](https://github.com/kowainik/co-log/issues/49):
+  Add `<&` and `&>`operators for `unLogAction`.
+* [#47](https://github.com/kowainik/co-log/issues/47):
+  Add `doctest` tests.
+* [#13](https://github.com/kowainik/co-log/issues/13):
+  Add `.cabal` file description and improve documentation.
+* [#39](https://github.com/kowainik/co-log/issues/39):
+  Support GHC-8.2.2 and GHC-8.6.2.
 
-
-0.1.0
-=====
+## 0.1.0
 
 * [#38](https://github.com/kowainik/co-log/issues/38):
   Rename `cbind` to `cmapM`.
 
 * [#37](https://github.com/kowainik/co-log/issues/37):
   Add `base` bounds.
 
-0.0.0
-=====
+## 0.0.0
+
 * Initially created.
 
 [1]: https://pvp.haskell.org

co-log-core/co-log-core.cabal

@@ -1,7 +1,20 @@
+cabal-version:       2.0
 name:                co-log-core
 version:             0.1.1
-description:         Logging library
-synopsis:            Logging library
+synopsis:            Composable Contravariant Comonadic Logging Library
+description:
+    This package provides core types and functions to work with the @LogAction@ data type which is both simple and powerful.
+    .
+    @
+    __newtype__ LogAction m msg = LogAction
+    \    { unLogAction :: msg -> m ()
+    \    }
+    @
+    .
+    The ideas behind this package are described in the following blog post:
+    .
+    * [co-log: Composable Contravariant Combinatorial Comonadic Configurable Convenient Logging](https://kowainik.github.io/posts/2018-09-25-co-log)
+
 homepage:            https://github.com/kowainik/co-log
 bug-reports:         https://github.com/kowainik/co-log/issues
 license:             MPL-2.0
@@ -12,10 +25,9 @@ copyright:           2018 Kowainik
 category:            Logging
 build-type:          Simple
 extra-doc-files:     CHANGELOG.md
-cabal-version:       2.0
 tested-with:         GHC == 8.2.2
-                   , GHC == 8.4.3
-                   , GHC == 8.6.1
+                   , GHC == 8.4.4
+                   , GHC == 8.6.2
 
 source-repository head
   type:                git
@@ -44,6 +56,7 @@ library
   default-extensions:  ConstraintKinds
                        DeriveGeneric
                        GeneralizedNewtypeDeriving
+                       InstanceSigs
                        LambdaCase
                        OverloadedStrings
                        RecordWildCards
@@ -54,8 +67,9 @@ library
                        ViewPatterns
 
 test-suite doctest
-  build-depends:        base, doctest ^>= 0.16.0
+  type:                 exitcode-stdio-1.0
+  build-depends:        base >= 4.10 && < 4.13
+                      , doctest ^>= 0.16.0
   default-language:     Haskell2010
   hs-source-dirs:       test
   main-is:              Doctests.hs
-  type:                 exitcode-stdio-1.0

co-log-core/src/Colog/Core/Action.hs

@@ -1,5 +1,4 @@
-{-# LANGUAGE CPP          #-}
-{-# LANGUAGE InstanceSigs #-}
+{-# LANGUAGE CPP #-}
 
 {- | Implements core data types and combinators for logging actions.
 -}
@@ -119,32 +118,53 @@ instance Applicative m => Monoid (LogAction m a) where
     mconcat = foldActions
     {-# INLINE mconcat #-}
 
+#if MIN_VERSION_base(4,12,0)
+instance Contravariant.Contravariant (LogAction m) where
+    contramap = cmap
+    {-# INLINE contramap #-}
 
-{- | Operator version of 'unLogAction'
+    (>$) = (Colog.Core.Action.>$)
+    {-# INLINE (>$) #-}
+#endif
+
+{- | Operator version of 'unLogAction'. Note that because of the types, something like:
+
+@
+action <& msg1 <& msg2
+@
 
-Note that because of the types, something like:
-> action <& msg1 <& msg2
 doesn't make sense. Instead you want:
-> action <& msg1 >> action <& msg2
-
-In addition, because '<&' has higher precedence
-than the other operators in this module,
-the following:
-> f >$< action <& msg
-should be replaced by
-> (f >$< action) <& msg
+
+@
+action <& msg1 >> action <& msg2
+@
+
+In addition, because '<&' has higher precedence than the other operators in this
+module, the following:
+
+@
+f >$< action <& msg
+@
+
+is equivalent to:
+
+@
+(f >$< action) <& msg
+@
 -}
 infix 5 <&
 (<&) :: LogAction m msg -> msg -> m ()
 (<&) = coerce
 {-# INLINE (<&) #-}
 
-{- | A flipped version of '<&'
+{- | A flipped version of '<&'.
 
-It shares the same precedence as '<&',
-so make sure to surround lower precedence
+It shares the same precedence as '<&', so make sure to surround lower precedence
 operators in parentheses:
-> msg &> (f >$< action)
+
+@
+msg &> (f >$< action)
+@
 -}
 infix 5 &>
 (&>) :: msg -> LogAction m msg -> m ()
@@ -411,10 +431,3 @@ infixr 1 <<=
 (<<=) :: Semigroup msg => (LogAction m msg -> m ()) -> LogAction m msg -> LogAction m msg
 (<<=) = extend
 {-# INLINE (<<=) #-}
-
-
-#if MIN_VERSION_base(4,12,0)
-instance Contravariant.Contravariant (LogAction m) where
-    contramap = cmap
-    (>$)      = (Colog.Core.Action.>$)
-#endif

co-log-core/src/Colog/Core/IO.hs

@@ -1,32 +1,27 @@
-module Colog.Core.IO 
-    ( logPrint
-    , logPrintStderr
-    , logStringStdout
-    , logStringStderr
-    , logStringHandle
-    , withLogStringFile
-    , liftLogIO
-    ) where
+module Colog.Core.IO
+       ( -- * 'String' actions
+         logStringStdout
+       , logStringStderr
+       , logStringHandle
+       , withLogStringFile
 
-import Control.Monad.IO.Class (MonadIO, liftIO)
-import System.IO (Handle, IOMode( AppendMode ), hPrint, hPutStrLn, stderr, withFile)
-import Colog.Core.Action (LogAction (..))
+         -- * 'Show' actions
+       , logPrint
+       , logPrintStderr
+       , logPrintHandle
+       , withLogPrintFile
 
-{- | Action that prints to stdout using 'Show'.
+         -- * Various combinators
+       , liftLogIO
+       ) where
 
->>> unLogAction logPrint 5
-5
--}
-logPrint :: (Show s, MonadIO m) => LogAction m s
-logPrint = LogAction (liftIO . print)
-
-{- | Action that prints to stderr using 'Show'.
+import Colog.Core.Action (LogAction (..))
+import Control.Monad.IO.Class (MonadIO, liftIO)
+import System.IO (Handle, IOMode (AppendMode), hPrint, hPutStrLn, stderr, withFile)
 
->>> unLogAction logPrintStderr 5
-5
--}
-logPrintStderr :: (Show s, MonadIO m) => LogAction m s
-logPrintStderr = LogAction (liftIO . hPrint stderr)
+----------------------------------------------------------------------------
+-- String
+----------------------------------------------------------------------------
 
 {- | Action that prints 'String' to stdout.
 
@@ -46,7 +41,7 @@ logStringStderr = logStringHandle stderr
 
 {- | Action that prints 'String' to 'Handle'.
 
->>> (unLogAction . logStringHandle) stderr "foo"
+>>> unLogAction (logStringHandle stderr) "foo"
 foo
 -}
 logStringHandle :: MonadIO m => Handle -> LogAction m String
@@ -58,13 +53,51 @@ file only once at the start of the application and write to 'Handle' instead of
 opening file each time we need to write to it.
 
 Opens file in 'AppendMode'.
+
 >>> logger action = unLogAction action "foo"
 >>> withLogStringFile "/dev/stdout" logger
 foo
 -}
 withLogStringFile :: MonadIO m => FilePath -> (LogAction m String -> IO r) -> IO r
 withLogStringFile path action = withFile path AppendMode $ action . logStringHandle
 
+----------------------------------------------------------------------------
+-- Show
+----------------------------------------------------------------------------
+
+{- | Action that prints to stdout using 'Show'.
+
+>>> unLogAction logPrint 5
+5
+-}
+logPrint :: forall a m . (Show a, MonadIO m) => LogAction m a
+logPrint = LogAction $ liftIO . print
+
+{- | Action that prints to stderr using 'Show'.
+
+>>> unLogAction logPrintStderr 5
+5
+-}
+logPrintStderr :: forall a m . (Show a, MonadIO m) => LogAction m a
+logPrintStderr = logPrintHandle stderr
+
+{- | Action that prints to a 'Handle' using 'Show'.
+
+>>> unLogAction (logPrintHandle stderr) 5
+5
+-}
+logPrintHandle :: forall a m . (Show a, MonadIO m) => Handle -> LogAction m a
+logPrintHandle handle = LogAction $ liftIO . hPrint handle
+
+{- | Action that prints to a file using 'Show'. See 'withLogStringFile' for details.
+-}
+withLogPrintFile :: forall a m r . (Show a, MonadIO m) => FilePath -> (LogAction m a -> IO r) -> IO r
+withLogPrintFile path action = withFile path AppendMode $ action . logPrintHandle
+
+----------------------------------------------------------------------------
+-- Misc
+----------------------------------------------------------------------------
+
 {- | Lifts a LogAction over IO into a more general Monad.
 
 >>> logToStdout = LogAction putStrLn

co-log-core/test/Doctests.hs

@@ -7,6 +7,7 @@ import Test.DocTest (doctest)
 main :: IO ()
 main = doctest
     [ "-XInstanceSigs"
+    , "-XScopedTypeVariables"
     , "-XViewPatterns"
     , "src"
     ]