diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,16 @@ `co-log` uses [PVP Versioning][1]. The changelog is available [on GitHub][2]. +## 0.6.1.0 - Mar 1, 2024 + +## What's Changed + +* GA(deps): Bump actions/cache from 3 to 4 by @dependabot in https://github.com/co-log/co-log/pull/273 +* docs: refine the loggert tutorials by @xieyuschen in https://github.com/co-log/co-log/pull/272 +* Support ghc-9.8. by @alaendle in https://github.com/co-log/co-log/pull/270 + +**Full Changelog**: https://github.com/co-log/co-log/compare/v0.6.0.2...v0.6.1.0 + ## 0.6.0.0 - Sep 18, 2023 ### What's Changed diff --git a/co-log.cabal b/co-log.cabal --- a/co-log.cabal +++ b/co-log.cabal @@ -1,6 +1,6 @@ cabal-version: 2.4 name: co-log -version: 0.6.0.2 +version: 0.6.1.0 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). @@ -15,7 +15,7 @@ license-file: LICENSE author: Dmitrii Kovanikov maintainer: Kowainik -copyright: 2018-2022 Kowainik, 2023 Co-Log +copyright: 2018-2022 Kowainik, 2023-2024 Co-Log category: Logging, Contravariant, Comonad build-type: Simple stability: provisional @@ -24,8 +24,9 @@ tested-with: GHC == 8.10.7 GHC == 9.0.2 GHC == 9.2.8 - GHC == 9.4.7 - GHC == 9.6.2 + GHC == 9.4.8 + GHC == 9.6.4 + GHC == 9.8.2 flag tutorial description: Controls if tutorials get build (mainly to avoid building them on hackage). @@ -36,7 +37,7 @@ location: https://github.com/co-log/co-log.git common common-options - build-depends: base >= 4.14 && < 4.19 + build-depends: base >= 4.14 && < 4.20 ghc-options: -Wall -Wcompat @@ -100,14 +101,14 @@ Colog.Pure Colog.Rotation - build-depends: ansi-terminal >= 1.0 && < 1.1 + build-depends: ansi-terminal >= 1.0 && < 1.2 , bytestring >= 0.10.8 && < 0.13 , co-log-core ^>= 0.3 - , containers >= 0.5.7 && < 0.7 + , containers >= 0.5.7 && < 0.8 , contravariant ^>= 1.5 , directory ^>= 1.3.0 , exceptions >= 0.8.3 && < 0.11 - , filepath ^>= 1.4.1 + , filepath >= 1.4.1 && < 1.6 , mtl >= 2.2.2 && < 2.4 , text >= 1.2.3 && < 2.2 , chronos ^>= 1.1 && < 1.2 diff --git a/src/Colog.hs b/src/Colog.hs --- a/src/Colog.hs +++ b/src/Colog.hs @@ -1,5 +1,5 @@ {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 This package contains @mtl@ implementation of composable, contravariant and diff --git a/src/Colog/Actions.hs b/src/Colog/Actions.hs --- a/src/Colog/Actions.hs +++ b/src/Colog/Actions.hs @@ -1,5 +1,5 @@ {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 Logging actions for various text types. diff --git a/src/Colog/Contra.hs b/src/Colog/Contra.hs --- a/src/Colog/Contra.hs +++ b/src/Colog/Contra.hs @@ -3,7 +3,7 @@ {-# LANGUAGE CPP #-} {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 This module contains 'LogAction' orphan instances of @contravariant@ classes. diff --git a/src/Colog/Message.hs b/src/Colog/Message.hs --- a/src/Colog/Message.hs +++ b/src/Colog/Message.hs @@ -8,7 +8,7 @@ {-# LANGUAGE TypeFamilies #-} {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 This module contains logging messages data types along with the formatting and diff --git a/src/Colog/Monad.hs b/src/Colog/Monad.hs --- a/src/Colog/Monad.hs +++ b/src/Colog/Monad.hs @@ -1,7 +1,7 @@ {-# LANGUAGE InstanceSigs #-} {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 Core of the @mtl@ implementation. diff --git a/src/Colog/Pure.hs b/src/Colog/Pure.hs --- a/src/Colog/Pure.hs +++ b/src/Colog/Pure.hs @@ -1,5 +1,5 @@ {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 Pure implementation of logging action. diff --git a/src/Colog/Rotation.hs b/src/Colog/Rotation.hs --- a/src/Colog/Rotation.hs +++ b/src/Colog/Rotation.hs @@ -1,5 +1,5 @@ {- | -Copyright: (c) 2018-2022 Kowainik, 2023 Co-Log +Copyright: (c) 2018-2022 Kowainik, 2023-2024 Co-Log SPDX-License-Identifier: MPL-2.0 Stability: experimental diff --git a/tutorials/1-intro/Intro.lhs b/tutorials/1-intro/Intro.lhs --- a/tutorials/1-intro/Intro.lhs +++ b/tutorials/1-intro/Intro.lhs @@ -6,7 +6,7 @@ You can run this tutorial by executing the following command: ```shell -cabal new-run tutorial-intro +cabal new-run tutorial-intro --flag=tutorial ``` ## Preamble: imports and language extensions diff --git a/tutorials/2-loggert/loggert.lhs b/tutorials/2-loggert/loggert.lhs --- a/tutorials/2-loggert/loggert.lhs +++ b/tutorials/2-loggert/loggert.lhs @@ -1,11 +1,11 @@ # Simple Message and LoggerT -This tutorial will show you how to use LoggerT and Simple message to log with more information in a more flexiable way. +This tutorial will show you how to use LoggerT and Simple message to log with more information in a more flexible way. You can run this tutorial by executing the following command: ```shell -cabal new-run tutorial-loggert-simple +cabal new-run tutorial-loggert-simple --flag=tutorial ``` ## Preamble: imports and language extensions @@ -24,38 +24,55 @@ module Main (main) where +import Control.Monad.Reader +import GHC.Stack import Prelude hiding (log) import Data.Text (Text,append) -import Colog ( LogAction, SimpleMsg , usingLoggerT, +import Colog ( LogAction, SimpleMsg(..), usingLoggerT, LoggerT, (<&), WithLog, cmap, logText,fmtSimpleMessage,formatWith, - logTextStderr,logTextStdout + logTextStderr,logTextStdout, getLogAction ) ``` ## LoggerT -The `LoggerT` monad transformer wraps a ReaderT that keeps `LogAction` in its context. It denotes a -computation of logging. So you define your monadic actions with the `WithLog` constraint that allows you to perform logging: -```haskell -example1 :: WithLog env SimpleMsg m => m () -example1 = do - logText "this is a demo log for simple message!" -example2 :: WithLog env SimpleMsg m => m () -example2 = do - logText "you see the demo log for simple message again!\n" -``` +The `LoggerT` monad transformer wraps a ReaderT that keeps `LogAction` in its context. It denotes a +computation of logging. The `WithLog` constraint has three type parameters: the application environment, the type of the message and the monad. The actions constraint by `WithLog` could be used as `LoggerT`. +In this example, we use a `LoggerT` monad transformer and a monadic action with `WithLog` constraint to perform log (the preferred way). +```haskell +-- logTextExample1 asks a logger from the LoggerT monad transformer, and then writes the text into the LogAction +-- it needs `HasCallStack` to print the stack information correctly +logTextExample1 :: (HasCallStack, Monad m) => LoggerT SimpleMsg m () +logTextExample1 = + asks getLogAction >>= \logger -> + logger <& SimpleMsg{ + simpleMsgStack = callStack + , simpleMsgText = "this is a demo log for simple message!" + } + +-- logTextExample2 logs the text down with the respective call stack information by the logger carried by env +-- logTextExample2 is an equivalent version of LoggerT as logTextExample1 with more features so we recommend you to use it +logTextExample2 :: WithLog env SimpleMsg m => m () +logTextExample2 = do + logText "you see the demo log for simple message again!" +``` + + ## Simple Message + The simple message is data type without `severity`. It contains a callstack information and a text message. + ```idris data SimpleMsg = SimpleMsg { simpleMsgStack :: !CallStack , simpleMsgText :: !Text } ``` + When logging, simple messages require a format for transforming from simple messages to text. We can either use `formatWith` or its alias `cmap` to combine it with the `LogAction`. @@ -66,7 +83,9 @@ logStdErrAction :: LogAction IO SimpleMsg logStdErrAction = formatWith fmtSimpleMessage logTextStderr ``` -What's more, it's available to define a own formatter. + +What's more, it's possible to define an own formatter. + ```haskell selfDefinedFmtSimpleMessage :: SimpleMsg -> Text selfDefinedFmtSimpleMessage = append "+ self defined behavior: " . fmtSimpleMessage @@ -78,18 +97,19 @@ ## Running example Now we are ready to execute those actions defined above. + ```haskell main :: IO () main = do - usingLoggerT logStdoutAction example1 - usingLoggerT logStdoutAction example2 - usingLoggerT logStdErrAction example1 - usingLoggerT logStdErrAction example2 - usingLoggerT logByOwnFormatterAction example1 - usingLoggerT logByOwnFormatterAction example2 + usingLoggerT logStdoutAction logTextExample1 + usingLoggerT logStdoutAction logTextExample2 + usingLoggerT logStdErrAction logTextExample1 + usingLoggerT logStdErrAction logTextExample2 + usingLoggerT logByOwnFormatterAction logTextExample1 + usingLoggerT logByOwnFormatterAction logTextExample2 ``` -Run command `cabal new-run tutorial-loggert-simple`. +Run command `cabal new-run tutorial-loggert-simple --flag=tutorial`. And the output will look like this: diff --git a/tutorials/3-loggert-with-message/loggert.lhs b/tutorials/3-loggert-with-message/loggert.lhs --- a/tutorials/3-loggert-with-message/loggert.lhs +++ b/tutorials/3-loggert-with-message/loggert.lhs @@ -112,6 +112,6 @@ usingLoggerT richMessageAction example2 ``` -Run command `cabal new-run tutorial-loggert`, and the output will look like this: +Run command `cabal new-run tutorial-loggert --flag=tutorial`, and the output will look like this: ![](../img/3-loggert-message.jpg)