diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,17 @@ `co-log-polysemy` uses [PVP Versioning][1]. The changelog is available [on GitHub][2]. +## 0.0.1.0 — Jan 19, 2020 + +* [#121](https://github.com/kowainik/co-log/issues/121): + Add `LogAction` and interpreter that works directly with the `Sem` monad. + (by [@chshersh](https://github.com/chshersh)) +* [#148](https://github.com/kowainik/co-log/issues/148): + Support GHC-8.8.2. + (by [@chshersh](https://github.com/chshersh)) +* Bump up `polysemy` to the latest version. + (by [@Avi-D-coder](https://github.com/Avi-D-coder)) + ## 0.0.0.0 — May 5, 2019 * Initially created. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # co-log -[![MPL-2.0 license](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://github.com/kowainik/co-log/blob/master/LICENSE) [![Build status](https://img.shields.io/travis/kowainik/co-log.svg?logo=travis)](https://travis-ci.org/kowainik/co-log) +[![Windows build](https://ci.appveyor.com/api/projects/status/github/kowainik/co-log?branch=master&svg=true)](https://ci.appveyor.com/project/kowainik/co-log) +[![MPL-2.0 license](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://github.com/kowainik/co-log/blob/master/LICENSE) | | | | | | :------------ | :--------------------------------- | :---------------------------------------- | :---------------------------------------------------- | @@ -9,26 +10,48 @@ | `co-log` | [![Hackage][hk-img]][hk] | [![Stackage LTS][lts-img]][lts] | [![Stackage Nightly][nightly-img]][nightly] | | `co-log-polysemy` | [![Hackage][hk-img-ps]][hk-ps] | [![Stackage LTS][lts-img-ps]][lts-ps] | [![Stackage Nightly][nightly-img-ps]][nightly-ps] | -`co-log` is a composable and configurable logging framework. The idea of the approach is -described in the following blog post: +`co-log` is a composable and configurable logging framework. It +combines all the benefits of Haskell idioms to provide a reasonable +and convenient interface. Though it uses some advanced concepts in its +core, we are striving to provide beginner-friendly API. The library +also contains complete documentation with a lot of beginner-friendly +examples, explanations and tutorials to guide users. The combination +of pragmatic approach to logging and fundamental Haskell abstractions +allows us to create highly composable and configurable logging +framework. +If you're interested in how different Haskel typeclasses are used to +implement core functions of `co-log`, you can read the following blog +post which goes in detail about internal implementation specifics: + * [co-log: Composable Contravariant Combinatorial Comonadic Configurable Convenient Logging](https://kowainik.github.io/posts/2018-09-25-co-log) -The repository contains the following packages: +`co-log` is also modular on the level of packages. We care a lot about a +low dependency footprint so you can build your logging only on top of +the minimal required interface for your use-case. This repository contains +the following packages: * [`co-log-core`](co-log-core): lightweight package with basic data types and - general idea. + general idea which depends only on `base`. * [`co-log`](co-log): taggless final implementation of logging library based on `co-log-core`. * [`co-log-polysemy`](co-log-polysemy): implementation of logging library based on `co-log-core` and the [`polysemy`](http://hackage.haskell.org/package/polysemy) extensible effects library. * [`co-log-benchmark`](co-log-benchmark): Benchmarks of the `co-log` library. -See the following tutorial series about the library: +To provide more user-friendly introduction to the library, we've +created the tutorial series which introduces the main concepts behind `co-log` +smoothly: * [Intro: Using `LogAction`](https://github.com/kowainik/co-log/blob/master/co-log/tutorials/1-intro/Intro.md) * [Using custom monad that stores `LogAction` inside its environment](https://github.com/kowainik/co-log/blob/master/co-log/tutorials/2-custom/Custom.md) +`co-log` also cares about concurrent logging. For this purposes we have the `concurrent-playground` +executable where we experiment with different multithreading scenarios to test the library behavior. +You can find it here: + +* [tutorials/Concurrent.hs](co-log/tutorials/Concurrent.hs) + ## Benchmarks `co-log` is compared with basic functions like `putStrLn`. Since IO overhead is @@ -36,6 +59,12 @@ doesn't contain `Message` then this benchmark simply dumps string `"message"` to output, otherwise it works with `Message` data type from the `co-log` library. + +To run benchmarks, use the following command: + +``` +cabal v2-run co-log-bench +``` | Benchmarks | Time for 10K messages | | :------------------------------------------------------ | :-------------------- | diff --git a/co-log-polysemy.cabal b/co-log-polysemy.cabal --- a/co-log-polysemy.cabal +++ b/co-log-polysemy.cabal @@ -1,6 +1,6 @@ cabal-version: 2.4 name: co-log-polysemy -version: 0.0.0.0 +version: 0.0.1.0 synopsis: Composable Contravariant Comonadic Logging Library description: Implementation of the [co-log](http://hackage.haskell.org/package/co-log-core) @@ -21,22 +21,23 @@ license-file: LICENSE author: Dmitrii Kovanikov maintainer: Kowainik -copyright: 2019 Kowainik +copyright: 2019-2020 Kowainik category: Logging, Contravariant, Comonad, Effects build-type: Simple stability: provisional extra-doc-files: CHANGELOG.md - , README.md -tested-with: GHC == 8.6.5 + README.md +tested-with: GHC == 8.2.2 + GHC == 8.4.4 + GHC == 8.6.5 + GHC == 8.8.2 source-repository head type: git location: https://github.com/kowainik/co-log.git common common-options - if impl(ghc < 8.6) - buildable: False - build-depends: base >= 4.10.0.0 && < 4.13 + build-depends: base >= 4.10.1.0 && < 4.14 ghc-options: -Wall -Wincomplete-uni-patterns @@ -47,10 +48,18 @@ -fhide-source-paths -freverse-errors -Wpartial-fields - - -- special options to make @polysemy@ fast -O2 - -flate-specialise + if impl(ghc >= 8.8.1) + ghc-options: -Wmissing-deriving-strategies + -Werror=missing-deriving-strategies + + -- 8.2 lacks <> + if impl(ghc < 8.4) + buildable: False + + -- special options to make @polysemy@ fast + if impl(ghc >= 8.6) + ghc-options: -flate-specialise -fspecialise-aggressively default-language: Haskell2010 @@ -78,7 +87,7 @@ Colog.Polysemy.Effect build-depends: co-log-core ^>= 0.2.0.0 - , polysemy ^>= 0.1.2.0 + , polysemy ^>= 1.2.0.0 executable play-colog-poly import: common-options diff --git a/src/Colog/Polysemy.hs b/src/Colog/Polysemy.hs --- a/src/Colog/Polysemy.hs +++ b/src/Colog/Polysemy.hs @@ -1,6 +1,6 @@ {- | -Copyright: (c) 2019 Kowainik -License: MPL-2.0 +Copyright: (c) 2019-2020 Kowainik +SPDX-License-Identifier: MPL-2.0 Maintainer: Kowainik This package contains extensible effects implementation of composable, contravariant and diff --git a/src/Colog/Polysemy/Effect.hs b/src/Colog/Polysemy/Effect.hs --- a/src/Colog/Polysemy/Effect.hs +++ b/src/Colog/Polysemy/Effect.hs @@ -1,8 +1,8 @@ {-# LANGUAGE TemplateHaskell #-} {- | -Copyright: (c) 2019 Kowainik -License: MPL-2.0 +Copyright: (c) 2019-2020 Kowainik +SPDX-License-Identifier: MPL-2.0 Maintainer: Kowainik This module contains logging effect which can be interpreted in terms of @@ -16,6 +16,10 @@ -- * Actions , log + -- * Direct usages + , LogActionSem + , runLogActionSem + -- * Interpretations , runLogAction , runLogAsTrace @@ -24,16 +28,19 @@ -- * Interpretations for Other Effects , runTraceAsLog , runOutputAsLog + ) where import Prelude hiding (log) -import Colog.Core.Action (LogAction (..)) import Data.Kind (Type) -import Polysemy (Lift, Member, Sem, interpret, makeSem_, sendM) +import Polysemy (Embed, Member, Sem, embed, interpret, makeSem_) import Polysemy.Output (Output (..), output) import Polysemy.Trace (Trace (..), trace) +import Colog.Core.Action (LogAction (..)) + + {- | Effect responsible for logging messages of type @msg@. Has similar structure to 'LogAction'. @@ -63,6 +70,22 @@ => msg -- ^ Message to log -> Sem r () -- ^ Effectful computation with no result +{- | 'LogAction' that works directly with the 'Sem' monad. + +@since 0.0.1.0 +-} +type LogActionSem r msg = LogAction (Sem r) msg + +{- | Run 'Sem' action with the corresponding 'LogActionSem'. If you +have plain 'LogAction' that works with some monad @m@, use +'runLogAction' instead. + +@since 0.0.1.0 +-} +runLogActionSem :: forall msg r a . LogActionSem r msg -> Sem (Log msg ': r) a -> Sem r a +runLogActionSem (LogAction action) = interpret $ \case + Log msg -> action msg + {- | Run a 'Log' effect in terms of the given 'LogAction'. The idea behind this function is the following: if you have @'LogAction' m msg@ then you can use this action to tell how to io interpret effect 'Log'. However, this is only possible @@ -81,12 +104,12 @@ -} runLogAction :: forall m msg r a . - Member (Lift m) r + Member (Embed m) r => LogAction m msg -> Sem (Log msg ': r) a -> Sem r a runLogAction (LogAction action) = interpret $ \case - Log msg -> sendM $ action msg + Log msg -> embed $ action msg {-# INLINE runLogAction #-} {- | Run 'Log' as the 'Trace' effect. This function can be useful if you have an