diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,11 @@ `co-log` uses [PVP Versioning][1]. The changelog is available [on GitHub][2]. +## 0.4.0.1 — Apr 18, 2020 + +* [#186](https://github.com/kowainik/co-log/issues/186): + Support GHC-8.10.1. + ## 0.4.0.0 — Jan 19, 2020 * [#120](https://github.com/kowainik/co-log/issues/120): 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.4.0.0 +version: 0.4.0.1 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). @@ -24,27 +24,31 @@ tested-with: GHC == 8.2.2 GHC == 8.4.4 GHC == 8.6.5 - GHC == 8.8.1 + GHC == 8.8.3 + GHC == 8.10.1 source-repository head type: git location: https://github.com/kowainik/co-log.git common common-options - build-depends: base >= 4.10.1.0 && < 4.14 + build-depends: base >= 4.10.1.0 && < 4.15 ghc-options: -Wall - -Wincomplete-uni-patterns - -Wincomplete-record-updates -Wcompat -Widentities + -Wincomplete-uni-patterns + -Wincomplete-record-updates -Wredundant-constraints - -fhide-source-paths - -freverse-errors + if impl(ghc >= 8.2) + ghc-options: -fhide-source-paths + if impl(ghc >= 8.4) + ghc-options: -Wmissing-export-lists -Wpartial-fields - if impl(ghc >= 8.8.1) + if impl(ghc >= 8.8) ghc-options: -Wmissing-deriving-strategies - -Werror=missing-deriving-strategies + if impl(ghc >= 8.10) + ghc-options: -Wunused-packages default-language: Haskell2010 default-extensions: ConstraintKinds @@ -64,8 +68,7 @@ import: common-options if os(windows) buildable: False - build-depends: co-log - , co-log-core + build-depends: co-log-core build-tool-depends: markdown-unlit:markdown-unlit ghc-options: -pgmL markdown-unlit @@ -106,7 +109,6 @@ build-depends: co-log , mtl , typerep-map - , text ghc-options: -threaded -rtsopts @@ -125,7 +127,8 @@ executable readme import: tutorial-options main-is: README.lhs - build-depends: text + build-depends: co-log + , text executable tutorial-intro import: tutorial-options @@ -134,7 +137,8 @@ executable tutorial-custom import: tutorial-options main-is: tutorials/2-custom/Custom.lhs - build-depends: mtl + build-depends: co-log + , mtl test-suite test-co-log import: common-options diff --git a/src/Colog/Message.hs b/src/Colog/Message.hs --- a/src/Colog/Message.hs +++ b/src/Colog/Message.hs @@ -96,7 +96,7 @@ {- | General logging message data type. Contains the following fields: -1. Polymorhic severity. This can be anything you want if you need more +1. Polymorphic severity. This can be anything you want if you need more flexibility. 2. Function 'CallStack'. It provides useful information about source code locations where each particular function was called. @@ -148,7 +148,7 @@ logException :: forall e m env . (WithLog env Message m, Exception e) => e -> m () logException = withFrozenCallStack (logError . T.pack . displayException) -{- | Log 'SimpleMsg' without severity, only 'CallStack' and 'Text' +{- | Logs 'SimpleMsg' without severity, only 'CallStack' and 'Text' body message. @since 0.4.0.0 @@ -156,7 +156,7 @@ logText :: WithLog env SimpleMsg m => Text -> m () logText msgText = withFrozenCallStack (logMsg SimpleMsg{ simpleMsgStack = callStack, simpleMsgText = msgText }) -{- | Formats the 'Message' type in according to the following format: +{- | Formats the 'Message' type according to the following format: @ [Severity] [SourceLocation] \ @@ -169,7 +169,7 @@ [Debug] [Main.example#34] app: First message... @ -See 'fmtRichMessageDefault' for richer format. +See 'fmtRichMessageDefault' for a richer format. -} fmtMessage :: Message -> Text fmtMessage Msg{..} = @@ -234,7 +234,7 @@ square :: Text -> Text square t = "[" <> t <> "] " -{- | Show source code locations in the following format: +{- | Shows source code locations in the following format: @ [Main.example#35] @@ -361,7 +361,7 @@ [Info] [03 May 2019 05:23:19.059 +00:00] [Main.example#35] [ThreadId 11] app: Second message... @ -See 'fmtMessage' if you don't need both time and thread id. +See 'fmtMessage' if you don't need both time and thread ID. -} fmtRichMessageDefault :: MonadIO m => RichMessage m -> m Text fmtRichMessageDefault msg = fmtRichMessageCustomDefault msg formatRichMessage @@ -431,7 +431,7 @@ -- Chronos extra ---------------------------------------------------------------------------- -{- | Given a 'Datetime', construct a 'Text' 'TB.Builder' corresponding to a +{- | Given a 'Datetime', constructs a 'Text' 'TB.Builder' corresponding to a Day\/Month\/Year,Hour\/Minute\/Second\/Offset encoding of the given 'Datetime'. Example: @29 Dec 2019 22:00:00.000 +00:00@ 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 @@ -1,9 +1,9 @@ # Intro: Using `LogAction` This tutorial is an introduction to `co-log`. It contains basic examples of -using core data types and functions. +using `co-log`'s core data types and functions. -You can run this tutorial by calling the following command: +You can run this tutorial by executing the following command: ```shell cabal new-run tutorial-intro @@ -11,8 +11,8 @@ ## Preamble: imports and language extensions -Since this is a literate haskell file, we need to specify all our language -extensions and imports up front. +Since this is a literate Haskell file, we need to specify all our imports up +front: ```haskell import Colog.Core (LogAction (..), (<&), logStringStdout) @@ -28,10 +28,10 @@ } ``` -Logging action is a function from some message of user-defined type `msg` that -performs all logic inside some monad `m`. In the `co-log` library **logger** is represented as a -value. With such approach, you can modify the way you do logging by simply performing some -transformations with the value you have. +Logging action is a function from some message of a user-defined type `msg` that +performs all logic inside some monad `m`. In the `co-log` library, **logger** is +represented as a value. With this approach, you can modify the way you do +logging by simply performing some transformations with the value you have. Let's first look at a very basic example of simply using `putStrLn` for logging: @@ -43,22 +43,22 @@ ``` Using `putStrLn` for logging is a very simple and basic approach for logging. -When your application becomes bigger and more complex, you might want to bring -some logging library into it. For example, you might want to do something from -the following list: +When your application grows bigger and more complex, you might want to introduce +some logging library to it. For example, you might want to do something from the +following list: -1. Specify messages with the given `Severity` so you can control the verbosity - of the output. -2. Automatically print timestamps, thread ids, source code line of the logging - with each message. -3. You would like to submit some statistics to some web-server with each logging - message so later you can have analytics provided by external parties. +1. Specify messages with a given `Severity` so you can control the verbosity of +the output. +2. Automatically print timestamps, thread IDs, and source code lines next to the +log messages. +3. Submit some statistics to a web server along with each log message so later +you can have analytics provided by external parties. -Now let's look at how you can use `LogAction` instead of `putStrLn` to achieve the -same goal. With `co-log` you need to have a value of type `LogAction` that defines -how you are going to do logging. So you configure your logging settings separately and -then pass and use this `LogAction` value. See the following example for more -details: +Now, let's look at how you can use `LogAction` instead of `putStrLn` to achieve +the same goal. With `co-log`, you need to have a value of type `LogAction` that +defines how you are going to perform logging. So you configure your logging +settings separately and then pass and use this `LogAction` value. See the +following example for more details: ```haskell example1 :: LogAction IO String -> IO () @@ -67,18 +67,18 @@ unLogAction logger "Example 1: Second message" ``` -> **NOTE:** this function currently does exactly the same thing as in `example0`. However, -> given `LogAction` can do many different interesting things which you can -> configure later in one place and automatically get proper behavior for your -> whole application instead of changing the code of every function. +> **NOTE:** this function currently does exactly the same thing as `example0`. +> However, given `LogAction` can do many different interesting things which you +> can configure later in one place and automatically get the proper behavior for +> your whole application instead of changing the code of every function. -If you want to do logging with `co-log`, then one of the options (and the simplest one) -is to pass `LogAction` explicitly as an argument to your -function. In the example above, we are using `LogAction` that takes `String`s as messages -and performs logging inside `IO` monad. +If you want to do logging with `co-log`, then one of the options (and the simplest +one) is to pass `LogAction` explicitly as an argument to your function. In the +example above, we are using `LogAction` that takes `String`s as messages and +performs logging inside the `IO` monad. -For convenience, library defines useful operator `<&` that makes code more -concise and simpler: +For convenience, the library defines the useful operator `<&` that makes the +code more concise and simpler: ```haskell example2 :: LogAction IO String -> IO () @@ -87,19 +87,19 @@ logger <& "Example 2: Second message" ``` -In order to do some logging, we need to pass some `logger` to our functions. +In order to do some logging, we need to pass a `logger` to our functions. Here we are going to use the following `LogAction`: ```idris logStringStdout :: LogAction IO String ``` -This action uses `putStrLn` underhood and just prints given string to `stdout`. -In this particular case using `LogAction` from `co-log` might seem redundant, -however, now it's much easier to replace simple `putStrLn` with something more -complex and useful. +This action uses `putStrLn` under the hood and just writes a given string to +`stdout`. In this particular case, using `LogAction` from `co-log` might seem +redundant. However, now it's much easier to replace the simple `putStrLn` with +something more complex and useful. -Putting all together, we can now perform our +Putting it all together, we can now run our examples ```haskell main :: IO () @@ -110,7 +110,7 @@ example2 logger ``` -And the output is exactly what you expect: +And the output is exactly what you'd expect: ``` Example 0: First message diff --git a/tutorials/2-custom/Custom.lhs b/tutorials/2-custom/Custom.lhs --- a/tutorials/2-custom/Custom.lhs +++ b/tutorials/2-custom/Custom.lhs @@ -1,9 +1,9 @@ -# Using custom monad that stores `LogAction` inside its environment +# Using a custom monad that stores `LogAction` inside its environment -This tutorial covers more advanced topic of using `co-log` library with custom -application monad. +This tutorial covers the more advanced topic of using the `co-log` library with +a custom application monad. -You can run this tutorial by calling the following command: +You can run this tutorial by executing the following command: ```shell cabal new-run tutorial-custom @@ -11,7 +11,7 @@ ## Preamble: imports and language extensions -Since this is a literate haskell file, we need to specify all our language +Since this is a literate Haskell file, we need to specify all our language extensions and imports up front. ```haskell @@ -32,13 +32,13 @@ ## Application environment -If you have complex Haskell application, then most likely you also have +If you have a complex Haskell application, then you are likely to also have non-trivial settings that configure your application environment. The -environment may store various parameters important for the work of your application. -Interestingly, we can store `LogAction` inside the same environment to use it -automatically for our logging functions. +environment may store various parameters relevant to your application's +behavior. Interestingly, we can store a `LogAction` inside the same +environment to use it for our logging functions. -The environment for your application can look like this: +The environment for your application may look like this: ```haskell data Env m = Env @@ -49,15 +49,15 @@ Several notes about this data type: -1. It stores different parameters, like server port. -2. It stores `LogAction` that can log `Message` data type from `co-log` in the - `m` monad. -3. `Env` is parameterized by type variable `m` which is going to be application - monad. +1. It stores different parameters, like the server port. +2. It stores a `LogAction` that can log values of the `Message` type +from `co-log` in the `m` monad. +3. `Env` is parameterized by type variable `m` which is going to be the +application monad. -Next step is to define an instance of the `HasLog` typeclass for the `Env` data -type. This instance will tell how to get and update `LogAction` stored inside -the environment. +The next step is to define an instance of the `HasLog` typeclass for the `Env` +data type. This instance will specify how to get and update the `LogAction` +stored inside the environment. ```haskell instance HasLog (Env m) Message m where @@ -74,7 +74,7 @@ ## Application monad -Now let's define our application monad. +Now let's define our application monad: ```haskell newtype App a = App @@ -82,14 +82,14 @@ } deriving newtype (Functor, Applicative, Monad, MonadIO, MonadReader (Env App)) ``` -This monad stores `Env` parameterized by the monad itself in it's context. -Nothing special required here to tell the monad how to use logger. +This monad stores `Env` parameterized by the monad itself in its context. +Nothing special is required here to tell the monad how to use the logger. ## Example -`co-log` relies on tagless final technique for writing function. So you define -your monadic actions with the `WithLog` constraint that allows you to perform -logging: +`co-log` relies on the tagless final technique for writing functions. So you +define your monadic actions with the `WithLog` constraint that allows you to +perform logging: ```haskell example :: WithLog env Message m => m () @@ -98,15 +98,15 @@ log I "Second message..." ``` -Constraint `WithLog` has three type parameters: application environment, type of -the message and monad. Function `log` takes two parameters: logger severity and -message text. +The `WithLog` constraint has three type parameters: the application environment, +the type of the message and the monad. Function `log` takes two parameters: +the logger severity and the log message's text. ## Running example Now we are ready to execute this action. -First, let's create example environment: +First, let's create an example environment: ```haskell simpleEnv :: Env App @@ -123,8 +123,8 @@ runApp env app = runReaderT (unApp app) env ``` -Putting all together, we can specialize `WithLog` constraint to our `App` monad -and run our example. +Putting it all together, we can specialize the `WithLog` constraint to our +`App` monad and run our example. ```haskell main :: IO () diff --git a/tutorials/Main.hs b/tutorials/Main.hs --- a/tutorials/Main.hs +++ b/tutorials/Main.hs @@ -1,3 +1,5 @@ +{-# OPTIONS_GHC -Wno-unused-top-binds #-} + {-# LANGUAGE DataKinds #-} {-# LANGUAGE DeriveAnyClass #-} {-# LANGUAGE DerivingStrategies #-} @@ -11,7 +13,7 @@ {-# LANGUAGE TypeApplications #-} {-# LANGUAGE TypeSynonymInstances #-} -module Main where +module Main (main) where import Prelude hiding (log)