co-log-core 0.3.0.0 → 0.3.1.0
raw patch · 8 files changed
+97/−99 lines, 8 filesdep ~basenew-uploaderPVP ok
version bump matches the API change (PVP)
Dependency ranges changed: base
API changes (from Hackage documentation)
+ Colog.Core.Severity: WithSeverity :: msg -> Severity -> WithSeverity msg
+ Colog.Core.Severity: [getMsg] :: WithSeverity msg -> msg
+ Colog.Core.Severity: [getSeverity] :: WithSeverity msg -> Severity
+ Colog.Core.Severity: data WithSeverity msg
+ Colog.Core.Severity: instance Data.Foldable.Foldable Colog.Core.Severity.WithSeverity
+ Colog.Core.Severity: instance Data.Traversable.Traversable Colog.Core.Severity.WithSeverity
+ Colog.Core.Severity: instance GHC.Base.Functor Colog.Core.Severity.WithSeverity
+ Colog.Core.Severity: instance GHC.Classes.Eq msg => GHC.Classes.Eq (Colog.Core.Severity.WithSeverity msg)
+ Colog.Core.Severity: instance GHC.Classes.Ord msg => GHC.Classes.Ord (Colog.Core.Severity.WithSeverity msg)
+ Colog.Core.Severity: instance GHC.Show.Show msg => GHC.Show.Show (Colog.Core.Severity.WithSeverity msg)
+ Colog.Core.Severity: mapSeverity :: (Severity -> Severity) -> WithSeverity msg -> WithSeverity msg
Files
- CHANGELOG.md +7/−0
- README.md +32/−90
- co-log-core.cabal +12/−4
- src/Colog/Core.hs +1/−1
- src/Colog/Core/Action.hs +1/−1
- src/Colog/Core/Class.hs +1/−1
- src/Colog/Core/IO.hs +1/−1
- src/Colog/Core/Severity.hs +42/−1
CHANGELOG.md view
@@ -3,6 +3,13 @@ `co-log-core` uses [PVP Versioning][1]. The change log is available [on GitHub][2]. +## 0.3.1.0 — Feb 15, 2022++* [#7](https://github.com/co-log/co-log-core/issues/7):+ Support GHC-9.2.+* [#13](https://github.com/co-log/co-log-core/issues/13):+ Add `WithSeverity` and `mapSeverity` to `Colog.Severity`.+ ## 🎃 0.3.0.0 — Oct 29, 2021 * [#223](https://github.com/co-log/co-log/pull/223):
README.md view
@@ -1,111 +1,53 @@-# co-log+# co-log-core  -[](https://github.com/kowainik/co-log/actions)-[](https://travis-ci.org/kowainik/co-log)-[](https://ci.appveyor.com/project/kowainik/co-log)+[](https://github.com/co-log/co-log-core/actions)+[![Hackage][hk-img-core]][hk-core]+[![Stackage LTS][lts-img-core]][lts-core] [](https://github.com/kowainik/co-log/blob/main/LICENSE) +`co-log-core` is a lightweight package that provides core types and functions to +work with the @LogAction@ data type which is both simple and powerful. -| | | | |-| :------------ | :--------------------------------- | :---------------------------------------- | :---------------------------------------------------- |-| `co-log-core` | [![Hackage][hk-img-core]][hk-core] | [![Stackage LTS][lts-img-core]][lts-core] | [![Stackage Nightly][nightly-img-core]][nightly-core] |-| `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] |+## How to use -`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 a pragmatic approach to logging and fundamental Haskell abstractions-allows us to create a highly composable and configurable logging-framework.+`co-log-core` is compatible with the following GHC+versions - [supported versions](https://matrix.hackage.haskell.org/#/package/co-log-core) -If you're interested in how different Haskell typeclasses are used to-implement core functions of `co-log`, you can read the following blog-post which goes into detail about internal implementation specifics:+In order to start using `co-log-core` in your project, you+will need to set it up with these steps: -* [co-log: Composable Contravariant Combinatorial Comonadic Configurable Convenient Logging](https://kowainik.github.io/posts/2018-09-25-co-log)+1. Add the dependency on `co-log-core` in your project's+ `.cabal` file. For this, you should modify the `build-depends`+ section according to the below section: -`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:+ ```haskell+ build-depends: base ^>= LATEST_SUPPORTED_BASE+ , co-log-core ^>= LATEST_VERSION+ ``` -* [`co-log-core`](co-log-core): lightweight package with basic data types and- 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.+2. To use this package, refer to the below example. -To provide a more user-friendly introduction to the library, we've-created the tutorial series which introduces the main concepts behind `co-log`-smoothly:+ ```haskell+ module Main (main) where -* [Intro: Using `LogAction`](https://github.com/kowainik/co-log/blob/main/co-log/tutorials/1-intro/Intro.md)-* [Using custom monad that stores `LogAction` inside its environment](https://github.com/kowainik/co-log/blob/main/co-log/tutorials/2-custom/Custom.md)+ import Prelude hiding (log) -`co-log` also cares about concurrent logging. For this purpose we have the `concurrent-playground`-executable where we experiment with different multithreading scenarios to test the library's behavior.-You can find it here:+ import Colog.Core (LogAction, logStringStdout, (<&)) -* [tutorials/Concurrent.hs](co-log/tutorials/Concurrent.hs) -## Benchmarks--`co-log` is compared with basic functions like `putStrLn`. Since IO overhead is-big enough, every benchmark dumps 10K messages to output. If a benchmark's name-doesn't contain `Message` then this benchmark simply dumps the string `"message"`-to output, otherwise it works with the `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 |-| :------------------------------------------------------ | :-------------------- |-| `Prelude.putStrLn` | ` 5.117ms` |-| `Text.putStrLn` | ` 9.220ms` |-| `ByteString.putStrLn` | ` 2.971ms` |-| `mempty` | ` 1.181ms` |-| `logStringStdout` | ` 5.107ms` |-| `logPrint` | ` 5.248ms` |-| `logTextStdout` | ` 5.351ms` |-| `logByteStringStdout` | ` 2.933ms` |-| `logByteStringStderr` | ` 17.482ms` |-| `ByteString > (stdout <> stderr)` | ` 17.715ms` |-| `Message > format > stdout` | ` 9.188ms` |-| `Message > format > ByteString > stdout` | ` 3.524ms` |-| `Message{callstack} > format > stdout` | ` 9.139ms` |-| `Message{callstack:5} > format > stdout` | ` 9.464ms` |-| `Message{callstack:50} > format > stdout` | ` 9.439ms` |-| `Message{Time,ThreadId} > format > stdout` | ` 54.160ms` |-| `Message{Time,ThreadId} > format > ByteString > stdout` | ` 54.137ms` |-+ app :: LogAction IO String -> IO ()+ app log = do+ log <& "Starting app..."+ log <& "Finishing app..." -[hk-img]: https://img.shields.io/hackage/v/co-log.svg?logo=haskell-[hk-img-ps]: https://img.shields.io/hackage/v/co-log-polysemy.svg?logo=haskell+ main :: IO ()+ main = app logStringStdout+ ```+ + [hk-img-core]: https://img.shields.io/hackage/v/co-log-core.svg?logo=haskell-[hk]: https://hackage.haskell.org/package/co-log-[hk-ps]: https://hackage.haskell.org/package/co-log-polysemy [hk-core]: https://hackage.haskell.org/package/co-log-core-[lts-img]: http://stackage.org/package/co-log/badge/lts-[lts-img-ps]: http://stackage.org/package/co-log-polysemy/badge/lts [lts-img-core]: http://stackage.org/package/co-log-core/badge/lts-[lts]: http://stackage.org/lts/package/co-log-[lts-ps]: http://stackage.org/lts/package/co-log-polysemy [lts-core]: http://stackage.org/lts/package/co-log-core-[nightly-img]: http://stackage.org/package/co-log/badge/nightly-[nightly-img-ps]: http://stackage.org/package/co-log-polysemy/badge/nightly-[nightly-img-core]: http://stackage.org/package/co-log-core/badge/nightly-[nightly]: http://stackage.org/nightly/package/co-log-[nightly-ps]: http://stackage.org/nightly/package/co-log-polysemy-[nightly-core]: http://stackage.org/nightly/package/co-log-core
co-log-core.cabal view
@@ -1,6 +1,6 @@ cabal-version: 2.4 name: co-log-core-version: 0.3.0.0+version: 0.3.1.0 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.@@ -27,7 +27,7 @@ license-file: LICENSE author: Dmitrii Kovanikov maintainer: Kowainik <xrom.xkov@gmail.com>-copyright: 2018-2020 Kowainik, 2021 Co-Log+copyright: 2018-2020 Kowainik, 2021-2022 Co-Log category: Logging, Contravariant, Comonad build-type: Simple stability: stable@@ -38,14 +38,15 @@ GHC == 8.6.5 GHC == 8.8.4 GHC == 8.10.7- GHC == 9.0.1+ GHC == 9.0.2+ GHC == 9.2.1 source-repository head type: git location: https://github.com/co-log/co-log-core.git common common-options- build-depends: base >= 4.10.1.0 && < 4.16+ build-depends: base >= 4.10.1.0 && < 4.17 ghc-options: -Wall -Wcompat@@ -62,9 +63,16 @@ ghc-options: -Wmissing-deriving-strategies if impl(ghc >= 8.10) ghc-options: -Wunused-packages+ if impl(ghc >= 9.0)+ ghc-options: -Winvalid-haddock+ if impl(ghc >= 9.2)+ ghc-options: -Wredundant-bang-patterns+ -Woperator-whitespace default-language: Haskell2010 default-extensions: ConstraintKinds+ DeriveFunctor+ DeriveTraversable DeriveGeneric DerivingStrategies GeneralizedNewtypeDeriving
src/Colog/Core.hs view
@@ -1,6 +1,6 @@ {- | Module : Colog.Core-Copyright : (c) 2018-2020 Kowainik, 2021 Co-Log+Copyright : (c) 2018-2020 Kowainik, 2021-2022 Co-Log SPDX-License-Identifier : MPL-2.0 Maintainer : Co-Log <xrom.xkov@gmail.com> Stability : Stable
src/Colog/Core/Action.hs view
@@ -7,7 +7,7 @@ {- | Module : Colog.Core.Action-Copyright : (c) 2018-2020 Kowainik, 2021 Co-Log+Copyright : (c) 2018-2020 Kowainik, 2021-2022 Co-Log SPDX-License-Identifier : MPL-2.0 Maintainer : Co-Log <xrom.xkov@gmail.com> Stability : Stable
src/Colog/Core/Class.hs view
@@ -4,7 +4,7 @@ {- | Module : Colog.Core.Class-Copyright : (c) 2018-2020 Kowainik, 2021 Co-Log+Copyright : (c) 2018-2020 Kowainik, 2021-2022 Co-Log SPDX-License-Identifier : MPL-2.0 Maintainer : Co-Log <xrom.xkov@gmail.com> Stability : Stable
src/Colog/Core/IO.hs view
@@ -2,7 +2,7 @@ {- | Module : Colog.Core.IO-Copyright : (c) 2018-2020 Kowainik+Copyright : (c) 2018-2020 Kowainik, 2021-2022 Co-Log SPDX-License-Identifier : MPL-2.0 Maintainer : Co-Log <xrom.xkov@gmail.com> Stability : Stable
src/Colog/Core/Severity.hs view
@@ -2,7 +2,7 @@ {- | Module : Colog.Core.Severity-Copyright : (c) 2018-2020 Kowainik, 2021 Co-Log+Copyright : (c) 2018-2020 Kowainik, 2021-2022 Co-Log SPDX-License-Identifier : MPL-2.0 Maintainer : Co-Log <xrom.xkov@gmail.com> Stability : Stable@@ -34,6 +34,8 @@ , pattern W , pattern E , filterBySeverity+ , WithSeverity (..)+ , mapSeverity ) where import Data.Ix (Ix)@@ -102,3 +104,42 @@ -> LogAction m a filterBySeverity s fs = cfilter (\a -> fs a >= s) {-# INLINE filterBySeverity #-}++-- Note: the order of the fields here is to allow the constructor to be used infix.+{-| A message tagged with a 'Severity'.+ +It is common to want to log various types of messages tagged with a severity. +'WithSeverity' provides a standard way to do so while allowing the messages to be processed independently of the severity.++It is easy to 'cmap' over a 'LogAction m (WithSeverity a)', or to filter based on the severity.++@+logSomething :: 'LogAction' m ('WithSeverity' 'String') -> m ()+logSomething logger = logger <& "hello" \`WithSeverity\` 'Info'++cmap' :: (b -> a) -> 'LogAction' m ('WithSeverity' a) -> 'LogAction' m ('WithSeverity' b)+cmap' f action = 'cmap' ('fmap' f) action++filterBySeverity' :: ('Applicative' m) => 'Severity' -> 'LogAction' m ('WithSeverity' a) -> 'LogAction' m ('WithSeverity' a)+filterBySeverity' threshold action = 'filterBySeverity' threshold 'getSeverity' action+@++@since 0.3.1.0+-}+data WithSeverity msg = WithSeverity { getMsg :: msg , getSeverity :: Severity }+ deriving stock (Show, Eq, Ord, Functor, Foldable, Traversable)++{- | Map the given function over the severity of a 'WithSeverity'.+ +This can be useful to operate generically over the severity, for example:++@+suppressErrors :: 'LogAction' m ('WithSeverity' msg) -> 'LogAction' m ('WithSeverity' msg)+suppressErrors = 'cmap' ('mapSeverity' (\s -> if s == 'Error' then 'Warning' else s))+@++@since 0.3.1.0+-}+mapSeverity :: (Severity -> Severity) -> WithSeverity msg -> WithSeverity msg+mapSeverity f (WithSeverity msg sev) = WithSeverity msg (f sev)+{-# INLINE mapSeverity #-}