co-log · alaendle · Mar 1, 2024 · Jan 8, 2024 · Jan 28, 2024
@@ -6,7 +6,7 @@ using `co-log`'s core data types and functions.
 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

@@ -8,22 +8,30 @@
 
 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
               )
 
-
-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"
-
+-- 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!"
 
 logStdoutAction :: LogAction IO SimpleMsg
 logStdoutAction = cmap fmtSimpleMessage logTextStdout
@@ -39,9 +47,9 @@ logByOwnFormatterAction = formatWith selfDefinedFmtSimpleMessage logTextStderr
 
 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
@@ -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 @@ extensions and imports up front.
 
 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 @@ logStdoutAction = cmap fmtSimpleMessage logTextStdout
 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 @@ logByOwnFormatterAction = formatWith selfDefinedFmtSimpleMessage logTextStderr
 ## 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:
 

@@ -112,6 +112,6 @@ main = do
     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)