From 918afabce0133460d66d1baf79ed2b0079c033ce Mon Sep 17 00:00:00 2001 From: Dmitrii Kovanikov Date: Thu, 15 Nov 2018 11:35:06 +0800 Subject: [PATCH] [#13] Improve documentation and description (#72) --- .travis.yml | 18 +++--- co-log-core/CHANGELOG.md | 32 ++++++----- co-log-core/co-log-core.cabal | 28 ++++++--- co-log-core/src/Colog/Core/Action.hs | 61 ++++++++++++-------- co-log-core/src/Colog/Core/IO.hs | 85 +++++++++++++++++++--------- co-log-core/test/Doctests.hs | 1 + co-log/CHANGELOG.md | 23 +++++--- co-log/co-log.cabal | 19 +++++-- stack.yaml | 2 +- 9 files changed, 172 insertions(+), 97 deletions(-) diff --git a/.travis.yml b/.travis.yml index 66774fd..54080de 100644 --- a/.travis.yml +++ b/.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 diff --git a/co-log-core/CHANGELOG.md b/co-log-core/CHANGELOG.md index 44a800c..807bae3 100644 --- a/co-log-core/CHANGELOG.md +++ b/co-log-core/CHANGELOG.md @@ -1,25 +1,27 @@ -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`. @@ -27,8 +29,8 @@ The change log is available [on GitHub][2]. * [#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 diff --git a/co-log-core/co-log-core.cabal b/co-log-core/co-log-core.cabal index c3e680e..7ff6774 100644 --- a/co-log-core/co-log-core.cabal +++ b/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 diff --git a/co-log-core/src/Colog/Core/Action.hs b/co-log-core/src/Colog/Core/Action.hs index 401a279..c42b2b6 100644 --- a/co-log-core/src/Colog/Core/Action.hs +++ b/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 diff --git a/co-log-core/src/Colog/Core/IO.hs b/co-log-core/src/Colog/Core/IO.hs index e48d0de..b3b6b7d 100644 --- a/co-log-core/src/Colog/Core/IO.hs +++ b/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,6 +53,7 @@ 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 @@ -65,6 +61,43 @@ 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 diff --git a/co-log-core/test/Doctests.hs b/co-log-core/test/Doctests.hs index d842546..0b2a6ba 100644 --- a/co-log-core/test/Doctests.hs +++ b/co-log-core/test/Doctests.hs @@ -7,6 +7,7 @@ import Test.DocTest (doctest) main :: IO () main = doctest [ "-XInstanceSigs" + , "-XScopedTypeVariables" , "-XViewPatterns" , "src" ] diff --git a/co-log/CHANGELOG.md b/co-log/CHANGELOG.md index 1f887cf..5088bf0 100644 --- a/co-log/CHANGELOG.md +++ b/co-log/CHANGELOG.md @@ -1,28 +1,33 @@ -Change log -========== +# Change log -`co-log uses` [PVP Versioning][1]. +`co-log` uses [PVP Versioning][1]. The change log is available [on GitHub][2]. -0.2.0 -===== +## 0.2.0 — Nov 15, 2018 +* [#45](https://github.com/kowainik/co-log/issues/45): + Introduce approach for concurrent log writing. * [#46](https://github.com/kowainik/co-log/issues/46): Moves `logStringStdout`, `logStringStderr`, `logStringHandle`, `withLogStringFile` from `Colog.Actions` to `Colog.Core.IO` * [#77](https://github.com/kowainik/co-log/issues/77): Remove `relude` from dependencies. Add HLint check to Travis CI. +* [#64](https://github.com/kowainik/co-log/issues/64): + Introduce basic benchmarks. +* [#20](https://github.com/kowainik/co-log/issues/20): + Add experimental support for logger rotation (see `Colog.Rotation` module). +* [#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 * [#37](https://github.com/kowainik/co-log/issues/37): Add bounds to all dependencies. Move `Prelude` to the `other-modules` section. -0.0.0 -===== +## 0.0.0 + * Initially created. [1]: https://pvp.haskell.org diff --git a/co-log/co-log.cabal b/co-log/co-log.cabal index 5dbf007..ed201f0 100644 --- a/co-log/co-log.cabal +++ b/co-log/co-log.cabal @@ -1,21 +1,28 @@ cabal-version: 2.0 name: co-log version: 0.2.0 -description: Logging library -synopsis: Logging library +synopsis: Composable Contravariant Comonadic Logging Library +description: + The default implementation of logging based on + [co-log-core](http://hackage.haskell.org/package/co-log-core). + . + 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 license-file: LICENSE -author: Kowainik +author: Kowainik, Alexander Vershilov maintainer: xrom.xkov@gmail.com copyright: 2018 Kowainik category: Logging build-type: Simple extra-doc-files: CHANGELOG.md 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 @@ -57,7 +64,7 @@ library -fhide-source-paths -freverse-errors - default-language: Haskell2010 + default-language: Haskell2010 default-extensions: ConstraintKinds DeriveGeneric GeneralizedNewtypeDeriving diff --git a/stack.yaml b/stack.yaml index befa560..56bc538 100644 --- a/stack.yaml +++ b/stack.yaml @@ -1,4 +1,4 @@ -resolver: lts-12.9 +resolver: lts-12.18 packages: - co-log