co-log 0.4.0.0 → 0.4.0.1
raw patch · 6 files changed
+102/−91 lines, 6 filesdep ~basedep ~textPVP ok
version bump matches the API change (PVP)
Dependency ranges changed: base, text
API changes (from Hackage documentation)
Files
- CHANGELOG.md +5/−0
- co-log.cabal +18/−14
- src/Colog/Message.hs +7/−7
- tutorials/1-intro/Intro.lhs +39/−39
- tutorials/2-custom/Custom.lhs +30/−30
- tutorials/Main.hs +3/−1
CHANGELOG.md view
@@ -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):
co-log.cabal view
@@ -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
src/Colog/Message.hs view
@@ -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] \<Text message\>@@ -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@
tutorials/1-intro/Intro.lhs view
@@ -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
tutorials/2-custom/Custom.lhs view
@@ -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 ()
tutorials/Main.hs view
@@ -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)