RIO

Abstract RIO to an arbitrary MonadReader instance, which can handle IO.

Using the environment run in IO the action that requires that environment.

The Reader+IO monad. This is different from a ReaderT because:

• It's not a transformer, it hardcodes IO for simpler usage and error messages.

• Instances of typeclasses like MonadLogger are implemented using classes defined on the environment, instead of using an underlying monad.

Same as askUnliftIO, but returns a monomorphic function instead of a polymorphic newtype wrapper. If you only need to apply the transformation on one concrete type, this function can be more convenient.

Capture the current monadic context, providing the ability to run monadic actions in IO.

See UnliftIO for an explanation of why we need a helper datatype here.

Prior to version 0.2.0.0 of this library, this was a method in the MonadUnliftIO type class. It was moved out due to https://github.com/fpco/unliftio/issues/55.

A helper function for lifting IO a -> IO b functions into any MonadUnliftIO.

Example

liftedTry :: (Exception e, MonadUnliftIO m) => m a -> m (Either e a)
liftedTry m = liftIOOp Control.Exception.try m

Convert an action in m to an action in IO.

Convenience function for capturing the monadic context and running an IO action. The UnliftIO newtype wrapper is rarely needed, so prefer withRunInIO to this function.

A helper function for implementing MonadUnliftIO instances. Useful for the common case where you want to simply delegate to the underlying transformer.

Note: You can derive MonadUnliftIO for newtypes without this helper function in unliftio-core 0.2.0.0 and later.

Example

newtype AppT m a = AppT { unAppT :: ReaderT Int (ResourceT m) a }
  deriving (Functor, Applicative, Monad, MonadIO)

-- Same as `deriving newtype (MonadUnliftIO)`
instance MonadUnliftIO m => MonadUnliftIO (AppT m) where
  withRunInIO = wrappedWithRunInIO AppT unAppT

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Monads which allow their actions to be run in IO.

While MonadIO allows an IO action to be lifted into another monad, this class captures the opposite concept: allowing you to capture the monadic context. Note that, in order to meet the laws given below, the intuition is that a monad must have no monadic state, but may have monadic context. This essentially limits MonadUnliftIO to ReaderT and IdentityT transformers on top of IO.

Laws. For any function run provided by withRunInIO, it must meet the monad transformer laws as reformulated for MonadUnliftIO:

• run . return = return

• run (m >>= f) = run m >>= run . f

Instances of MonadUnliftIO must also satisfy the following laws:

Identity law

withRunInIO (\run -> run m) = m

Inverse law

withRunInIO (\_ -> m) = liftIO m

As an example of an invalid instance, a naive implementation of MonadUnliftIO (StateT s m) might be

withRunInIO inner =
  StateT $ \s ->
    withRunInIO $ \run ->
      inner (run . flip evalStateT s)

This breaks the identity law because the inner run m would throw away any state changes in m.

The ability to run any monadic action m a as IO a.

This is more precisely a natural transformation. We need to new datatype (instead of simply using a forall) due to lack of support in GHC for impredicative types.

A contramap. Use this to wrap sub-loggers via mapRIO.

If you are on base > 4.12.0, you can just use contramap.

A vesion of contramapMaybeGLogFunc which supports filering.

Convert a CallStack value into a Utf8Builder indicating the first source location.

TODO Consider showing the entire call stack instead.

Make a GLogFunc via classic LogFunc. Use this if you'd like to log your generic data type via the classic RIO terminal logger.

Log a value generically.

Log a debug level message with no source.

Log a debug level message with the given source.

Log an error level message with no source.

Log an error level message with the given source.

What accent colors, indexed by Int, is the log func configured to use?

Intended for use by code which wants to optionally add additional color to its log messages.

What color is the log func configured to use for each LogLevel?

Intended for use by code which wants to optionally add additional color to its log messages.

What color is the log func configured to use for secondary content?

Intended for use by code which wants to optionally add additional color to its log messages.

Is the log func configured to use color output?

Intended for use by code which wants to optionally add additional color to its log messages.

Generic, basic function for creating other logging functions.

Log an info level message with no source.

Log an info level message with the given source.

Create a LogOptions value from the given Handle and whether to perform verbose logging or not. Individiual settings can be overridden using appropriate set functions. Logging output is guaranteed to be non-interleaved only for a UTF-8 Handle in a multi-thread environment. If the handle is not writable, an exception is thrown immediately.

When Verbose Flag is True, the following happens:

• setLogVerboseFormat is called with True

• setLogUseColor is called with True (except on Windows)

• setLogUseLoc is called with True

• setLogUseTime is called with True

• setLogMinLevel is called with Debug log level

Create a LogOptions value which will store its data in memory. This is primarily intended for testing purposes. This will return both a LogOptions value and an IORef containing the resulting Builder value.

This will default to non-verbose settings and assume there is a terminal attached. These assumptions can be overridden using the appropriate set functions.

Log a message with the specified textual level and no source.

Log a message with the specified textual level and the given source.

Write a "sticky" line to the terminal. Any subsequent lines will overwrite this one, and that same line will be repeated below again. In other words, the line sticks at the bottom of the output forever. Running this function again will replace the sticky line with a new sticky line. When you want to get rid of the sticky line, run logStickyDone.

Note that not all LogFunc implementations will support sticky messages as described. However, the withLogFunc implementation provided by this module does.

This will print out the given message with a newline and disable any further stickiness of the line until a new call to logSticky happens.

Log a warn level message with no source.

Log a warn level message with the given source.

Make a custom generic logger. With this you could, for example, write to a database or a log digestion service. For example:

mkGLogFunc (\stack msg -> send (Data.Aeson.encode (JsonLog stack msg)))

Create a LogFunc from the given function.

Given a LogOptions value, returns both a new LogFunc and a sub-routine that disposes it.

Intended for use if you want to deal with the teardown of LogFunc yourself, otherwise prefer the withLogFunc function instead.

Disable logging capabilities in a given sub-routine

Intended to skip logging in general purpose implementations, where secrets might be logged accidently.

ANSI color codes for accents in the log output. Accent colors are indexed by Int.

Default: const "\ESC[92m" -- Bright green, for all indicies

Set format method for messages

Default: id

ANSI color codes for LogLevel in the log output.

Default: LevelDebug = "\ESC[32m" -- Green LevelInfo = "\ESC[34m" -- Blue LevelWarn = "\ESC[33m" -- Yellow LevelError = "\ESC[31m" -- Red LevelOther _ = "\ESC[35m" -- Magenta

Set the minimum log level. Messages below this level will not be printed.

Default: in verbose mode, LevelDebug. Otherwise, LevelInfo.

Refer to setLogMinLevel. This modifier allows to alter the verbose format value dynamically at runtime.

Default: in verbose mode, LevelDebug. Otherwise, LevelInfo.

ANSI color codes for secondary content in the log output.

Default: "\ESC[90m" -- Bright black (gray)

Do we treat output as a terminal. If True, we will enable sticky logging functionality.

Default: checks if the Handle provided to logOptionsHandle is a terminal with hIsTerminalDevice.

Use ANSI color codes in the log output.

Default: True if in verbose mode and the Handle is a terminal device.

Use code location in the log output.

Default: True if in verbose mode, False otherwise.

Include the time when printing log messages.

Default: True in debug mode, False otherwise.

Use the verbose format for printing log messages.

Default: follows the value of the verbose flag.

Refer to setLogVerboseFormat. This modifier allows to alter the verbose format value dynamically at runtime.

Default: follows the value of the verbose flag.

Given a LogOptions value, run the given function with the specified LogFunc. A common way to use this function is:

let isVerbose = False -- get from the command line instead
logOptions' <- logOptionsHandle stderr isVerbose
let logOptions = setLogUseTime True logOptions'
withLogFunc logOptions $ \lf -> do
  let app = App -- application specific environment
        { appLogFunc = lf
        , appOtherStuff = ...
        }
  runRIO app $ do
    logInfo "Starting app"
    myApp

CallStacks are a lightweight method of obtaining a partial call-stack at any point in the program.

A function can request its call-site with the HasCallStack constraint. For example, we can define

putStrLnWithCallStack :: HasCallStack => String -> IO ()

as a variant of putStrLn that will get its call-site and print it, along with the string given as argument. We can access the call-stack inside putStrLnWithCallStack with callStack.

>>> :{putStrLnWithCallStack :: HasCallStack => String -> IO ()putStrLnWithCallStack msg = do  putStrLn msg  putStrLn (prettyCallStack callStack):}

Thus, if we call putStrLnWithCallStack we will get a formatted call-stack alongside our string.

>>> putStrLnWithCallStack "hello"helloCallStack (from HasCallStack):  putStrLnWithCallStack, called at <interactive>:... in interactive:Ghci...

GHC solves HasCallStack constraints in three steps:

1. If there is a CallStack in scope -- i.e. the enclosing function has a HasCallStack constraint -- GHC will append the new call-site to the existing CallStack.

2. If there is no CallStack in scope -- e.g. in the GHCi session above -- and the enclosing definition does not have an explicit type signature, GHC will infer a HasCallStack constraint for the enclosing definition (subject to the monomorphism restriction).

3. If there is no CallStack in scope and the enclosing definition has an explicit type signature, GHC will solve the HasCallStack constraint for the singleton CallStack containing just the current call-site.

CallStacks do not interact with the RTS and do not require compilation with -prof. On the other hand, as they are built up explicitly via the HasCallStack constraints, they will generally not contain as much information as the simulated call-stacks maintained by the RTS.

A CallStack is a [(String, SrcLoc)]. The String is the name of function that was called, the SrcLoc is the call-site. The list is ordered with the most recently called function at the head.

NOTE: The intrepid user may notice that HasCallStack is just an alias for an implicit parameter ?callStack :: CallStack. This is an implementation detail and should not be considered part of the CallStack API, we may decide to change the implementation in the future.

A generic logger of some type msg.

Your GLocFunc can re-use the existing classical logging framework of RIO, and/or implement additional transforms, filters. Alternatively, you may log to a JSON source in a database, or anywhere else as needed. You can decide how to log levels or severities based on the constructors in your type. You will normally determine this in your main app entry point.

An app is capable of generic logging if it implements this.

Environment values with a logging function.

Level, if any, of your logs. If unknown, use LogOther. Use for your generic log data types that want to sit inside the classic log framework.

Source of a log. This can be whatever you want. Use for your generic log data types that want to sit inside the classic log framework.

A logging function, wrapped in a newtype for better error messages.

An implementation may choose any behavior of this value it wishes, including printing to standard output or no action at all.

The log level of a message.

Configuration for how to create a LogFunc. Intended to be used with the withLogFunc function.

Where in the application a log message came from. Used for display purposes only.

Convert a ByteString into a Utf8Builder.

NOTE This function performs no checks to ensure that the data is, in fact, UTF8 encoded. If you provide non-UTF8 data, later functions may fail.

Use the Show instance for a value to convert it to a Utf8Builder.

Convert a Utf8Builder value into a lazy Text.

Convert a Utf8Builder value into a strict Text.

Write the given Utf8Builder value to a file.

A typeclass for values which can be converted to a Utf8Builder. The intention of this typeclass is to provide a human-friendly display of the data.

A builder of binary data, with the invariant that the underlying data is supposed to be UTF-8 encoded.

(%~) applies a function to the target; an alternative explanation is that it is an inverse of sets, which turns a setter into an ordinary function. mapped %~ reverse is the same thing as fmap reverse.

See over if you want a non-operator synonym.

Negating the 1st element of a pair:

>>> (1,2) & _1 %~ negate(-1,2)

Turning all Lefts in a list to upper case:

>>> (mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"][Left "FOO",Right "bar"]

(.~) assigns a value to the target. It's the same thing as using (%~) with const:

l .~ x = l %~ const x

See set if you want a non-operator synonym.

Here it is used to change 2 fields of a 3-tuple:

>>> (0,0,0) & _1 .~ 1 & _3 .~ 3(1,0,3)

(^.) applies a getter to a value; in other words, it gets a value out of a structure using a getter (which can be a lens, traversal, fold, etc.).

Getting 1st field of a tuple:

(^. _1) :: (a, b) -> a
(^. _1) = fst

When (^.) is used with a traversal, it combines all results using the Monoid instance for the resulting type. For instance, for lists it would be simple concatenation:

>>> ("str","ing") ^. each"string"

The reason for this is that traversals use Applicative, and the Applicative instance for Const uses monoid concatenation to combine “effects” of Const.

A non-operator version of (^.) is called view, and it's a bit more general than (^.) (it works in MonadReader). If you need the general version, you can get it from microlens-mtl; otherwise there's view available in Lens.Micro.Extras.

s ^.. t returns the list of all values that t gets from s.

A Maybe contains either 0 or 1 values:

>>> Just 3 ^.. _Just[3]

Gathering all values in a list of tuples:

>>> [(1,2),(3,4)] ^.. each.each[1,2,3,4]

s ^? t returns the 1st element t returns, or Nothing if t doesn't return anything. It's trivially implemented by passing the First monoid to the getter.

Safe head:

>>> [] ^? eachNothing

>>> [1..3] ^? eachJust 1

Converting Either to Maybe:

>>> Left 1 ^? _RightNothing

>>> Right 1 ^? _RightJust 1

A non-operator version of (^?) is called preview, and – like view – it's a bit more general than (^?) (it works in MonadReader). If you need the general version, you can get it from microlens-mtl; otherwise there's preview available in Lens.Micro.Extras.

lens creates a Lens from a getter and a setter. The resulting lens isn't the most effective one (because of having to traverse the structure twice when modifying), but it shouldn't matter much.

A (partial) lens for list indexing:

ix :: Int -> Lens' [a] a
ix i = lens (!! i)                                   -- getter
            (\s b -> take i s ++ b : drop (i+1) s)   -- setter

Usage:

>>> [1..9] ^. ix 3
4

>>> [1..9] & ix 3 %~ negate
[1,2,3,-4,5,6,7,8,9]

When getting, the setter is completely unused; when setting, the getter is unused. Both are used only when the value is being modified. For instance, here we define a lens for the 1st element of a list, but instead of a legitimate getter we use undefined. Then we use the resulting lens for setting and it works, which proves that the getter wasn't used:

>>> [1,2,3] & lens undefined (\s b -> b : tail s) .~ 10[10,2,3]

over is a synonym for (%~).

Getting fmap in a roundabout way:

over mapped :: Functor f => (a -> b) -> f a -> f b
over mapped = fmap

Applying a function to both components of a pair:

over both :: (a -> b) -> (a, a) -> (b, b)
over both = \f t -> (f (fst t), f (snd t))

Using over _2 as a replacement for second:

>>> over _2 show (10,20)(10,"20")

set is a synonym for (.~).

Setting the 1st component of a pair:

set _1 :: x -> (a, b) -> (x, b)
set _1 = \x t -> (x, snd t)

Using it to rewrite (Data.Functor.<$):

set mapped :: Functor f => a -> f b -> f a
set mapped = (Data.Functor.<$)

to creates a getter from any function:

a ^. to f = f a

It's most useful in chains, because it lets you mix lenses and ordinary functions. Suppose you have a record which comes from some third-party library and doesn't have any lens accessors. You want to do something like this:

value ^. _1 . field . at 2

However, field isn't a getter, and you have to do this instead:

field (value ^. _1) ^. at 2

but now value is in the middle and it's hard to read the resulting code. A variant with to is prettier and more readable:

value ^. _1 . to field . at 2

sets creates an ASetter from an ordinary function. (The only thing it does is wrapping and unwrapping Identity.)

preview is a synonym for (^?), generalised for MonadReader (just like view, which is a synonym for (^.)).

>>> preview each [1..5]Just 1

view is a synonym for (^.), generalised for MonadReader (we are able to use it instead of (^.) since functions are instances of the MonadReader class):

>>> view _1 (1, 2)1

When you're using Reader for config and your config type has lenses generated for it, most of the time you'll be using view instead of asks:

doSomething :: (MonadReader Config m) => m Int
doSomething = do
  thingy        <- view setting1  -- same as “asks (^. setting1)”
  anotherThingy <- view setting2
  ...

ASetter s t a b is something that turns a function modifying a value into a function modifying a structure. If you ignore Identity (as Identity a is the same thing as a), the type is:

type ASetter s t a b = (a -> b) -> s -> t

The reason Identity is used here is for ASetter to be composable with other types, such as Lens.

Technically, if you're writing a library, you shouldn't use this type for setters you are exporting from your library; the right type to use is Setter, but it is not provided by this package (because then it'd have to depend on distributive). It's completely alright, however, to export functions which take an ASetter as an argument.

This is a type alias for monomorphic setters which don't change the type of the container (or of the value inside). It's useful more often than the same type in lens, because we can't provide real setters and so it does the job of both ASetter' and Setter'.

Functions that operate on getters and folds – such as (^.), (^..), (^?) – use Getter r s a (with different values of r) to describe what kind of result they need. For instance, (^.) needs the getter to be able to return a single value, and so it accepts a getter of type Getting a s a. (^..) wants the getter to gather values together, so it uses Getting (Endo [a]) s a (it could've used Getting [a] s a instead, but it's faster with Endo). The choice of r depends on what you want to do with elements you're extracting from s.

Lens s t a b is the lowest common denominator of a setter and a getter, something that has the power of both; it has a Functor constraint, and since both Const and Identity are functors, it can be used whenever a getter or a setter is needed.

• a is the type of the value inside of structure

• b is the type of the replaced value

• s is the type of the whole structure

• t is the type of the structure after replacing a in it with b

This is a type alias for monomorphic lenses which don't change the type of the container (or of the value inside).

A SimpleGetter s a extracts a from s; so, it's the same thing as (s -> a), but you can use it in lens chains because its type looks like this:

type SimpleGetter s a =
  forall r. (a -> Const r a) -> s -> Const r s

Since Const r is a functor, SimpleGetter has the same shape as other lens types and can be composed with them. To get (s -> a) out of a SimpleGetter, choose r ~ a and feed Const :: a -> Const a a to the getter:

-- the actual signature is more permissive:
-- view :: Getting a s a -> s -> a
view :: SimpleGetter s a -> s -> a
view getter = getConst . getter Const

The actual Getter from lens is more general:

type Getter s a =
  forall f. (Contravariant f, Functor f) => (a -> f a) -> s -> f s

I'm not currently aware of any functions that take lens's Getter but won't accept SimpleGetter, but you should try to avoid exporting SimpleGetters anyway to minimise confusion. Alternatively, look at microlens-contra, which provides a fully lens-compatible Getter.

Lens users: you can convert a SimpleGetter to Getter by applying to . view to it.

A ThreadId is an abstract type representing a handle to a thread. ThreadId is an instance of Eq, Ord and Show, where the Ord instance implements an arbitrary total ordering over ThreadIds. The Show instance lets you convert an arbitrary-valued ThreadId to string form; showing a ThreadId value is occasionally useful when debugging or diagnosing the behaviour of a concurrent program.

Note: in GHC, if you have a ThreadId, you essentially have a pointer to the thread itself. This means the thread itself can't be garbage collected until you drop the ThreadId. This misfeature would be difficult to correct while continuing to support threadStatus.

Lifted version of myThreadId.

Lifted version of isCurrentThreadBound.

Lifted version of threadWaitRead.

Lifted version of threadWaitWrite.

Lifted version of threadDelay.

If the first argument evaluates to True, then the result is the second argument. Otherwise an AssertionFailed exception is raised, containing a String with the source file and line number of the call to assert.

Assertions can normally be turned on or off with a compiler flag (for GHC, assertions are normally on unless optimisation is turned on with -O or the -fignore-asserts option is given). When assertions are turned off, the first argument to assert is ignored, and the second argument is returned as the result.

Allocate and clean up a resource safely.

For more information on motivation and usage of this function, see base's bracket. This function has two differences from the one in base. The first, and more obvious, is that it works on any MonadUnliftIO instance, not just IO.

The more subtle difference is that this function will use uninterruptible masking for its cleanup handler. This is a subtle distinction, but at a high level, means that resource cleanup has more guarantees to complete. This comes at the cost that an incorrectly written cleanup function cannot be interrupted.

For more information, please see https://github.com/fpco/safe-exceptions/issues/3.

Same as bracket, but only perform the cleanup if an exception is thrown.

A variant of bracketOnError where the return value from the first computation is not required.

Same as bracket, but does not pass the acquired resource to cleanup and use functions.

For more information, see base's bracket_.

Catch a synchronous (but not asynchronous) exception and recover from it.

This is parameterized on the exception type. To catch all synchronous exceptions, use catchAny.

catch specialized to catch all synchronous exceptions.

catchDeep specialized to catch all synchronous exception.

Same as catch, but fully force evaluation of the result value to find all impure exceptions.