rio-0.1.17.0: A standard library for Haskell
Safe HaskellNone
LanguageHaskell2010

RIO

Synopsis

Custom Prelude

One of the core features of rio is that it can be used as a Prelude replacement. Therefore it is best to disable the default Prelude with: NoImplicitPrelude pragma:

{-# LANGUAGE NoImplicitPrelude #-}
import RIO

Some functions not exported here can be found in RIO.Partial: fromJust, read, toEnum, pred, succ.

The RIO Monad

newtype RIO env a Source #

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.

Constructors

RIO 

Fields

Instances

Instances details
HasStateRef s env => MonadState s (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

get :: RIO env s #

put :: s -> RIO env () #

state :: (s -> (a, s)) -> RIO env a #

MonadReader env (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

ask :: RIO env env #

local :: (env -> env) -> RIO env a -> RIO env a #

reader :: (env -> a) -> RIO env a

(Monoid w, HasWriteRef w env) => MonadWriter w (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

writer :: (a, w) -> RIO env a #

tell :: w -> RIO env () #

listen :: RIO env a -> RIO env (a, w) #

pass :: RIO env (a, w -> w) -> RIO env a #

Monad (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

(>>=) :: RIO env a -> (a -> RIO env b) -> RIO env b #

(>>) :: RIO env a -> RIO env b -> RIO env b #

return :: a -> RIO env a #

Functor (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

fmap :: (a -> b) -> RIO env a -> RIO env b #

(<$) :: a -> RIO env b -> RIO env a #

Applicative (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

pure :: a -> RIO env a #

(<*>) :: RIO env (a -> b) -> RIO env a -> RIO env b #

liftA2 :: (a -> b -> c) -> RIO env a -> RIO env b -> RIO env c #

(*>) :: RIO env a -> RIO env b -> RIO env b #

(<*) :: RIO env a -> RIO env b -> RIO env a #

MonadIO (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

liftIO :: IO a -> RIO env a

MonadUnliftIO (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

askUnliftIO :: RIO env (UnliftIO (RIO env))

withRunInIO :: ((forall a. RIO env a -> IO a) -> IO b) -> RIO env b

PrimMonad (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Associated Types

type PrimState (RIO env) #

Methods

primitive :: (State# (PrimState (RIO env)) -> (# State# (PrimState (RIO env)), a #)) -> RIO env a #

MonadThrow (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

throwM :: Exception e => e -> RIO env a #

Semigroup a => Semigroup (RIO env a) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

(<>) :: RIO env a -> RIO env a -> RIO env a #

sconcat :: NonEmpty (RIO env a) -> RIO env a

stimes :: Integral b => b -> RIO env a -> RIO env a

Monoid a => Monoid (RIO env a) Source # 
Instance details

Defined in RIO.Prelude.RIO

Methods

mempty :: RIO env a #

mappend :: RIO env a -> RIO env a -> RIO env a #

mconcat :: [RIO env a] -> RIO env a #

type PrimState (RIO env) Source # 
Instance details

Defined in RIO.Prelude.RIO

type PrimState (RIO env) = PrimState IO

runRIO :: MonadIO m => env -> RIO env a -> m a Source #

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

Since: 0.0.1.0

liftRIO :: (MonadIO m, MonadReader env m) => RIO env a -> m a Source #

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

Since: 0.0.1.0

SimpleApp

If all you need is just some default environment that does basic logging and allows spawning processes, then you can use SimpleApp:

{-# LANGUAGE OverloadedStrings #-}
module Main where

main :: IO ()
main =
  runSimpleApp $ do
    logInfo "Hello World!"

Note the OverloadedStrings extension, which is enabled to simplify logging.

MonadIO and MonadUnliftIO

Logger

The logging system in RIO is built upon "log functions", which are accessed in RIO's environment via a class like "has log function". There are two provided:

  • In the common case: for logging plain text (via Utf8Builder) efficiently, there is LogFunc, which can be created via withLogFunc, and is accessed via HasLogFunc. This provides all the classical logging facilities: timestamped text output with log levels and colors (if terminal-supported) to the terminal. We log output via logInfo, logDebug, etc.
  • In the advanced case: where logging takes on a more semantic meaning and the logs need to be digested, acted upon, translated or serialized upstream (to e.g. a JSON logging server), we have GLogFunc (as in "generic log function"), and is accessed via HasGLogFunc. In this case, we log output via glog. See the Type-generic logger section for more information.

Running with logging

withLogFunc :: MonadUnliftIO m => LogOptions -> (LogFunc -> m a) -> m a Source #

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

Since: 0.0.0.0

newLogFunc :: (MonadIO n, MonadIO m) => LogOptions -> n (LogFunc, m ()) Source #

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.

Since: 0.1.3.0

data LogFunc Source #

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.

Since: 0.0.0.0

Instances

Instances details
Semigroup LogFunc Source #

Perform both sets of actions per log entry.

Since: 0.0.0.0

Instance details

Defined in RIO.Prelude.Logger

Monoid LogFunc Source #

mempty peforms no logging.

Since: 0.0.0.0

Instance details

Defined in RIO.Prelude.Logger

HasLogFunc LogFunc Source # 
Instance details

Defined in RIO.Prelude.Logger

class HasLogFunc env where Source #

Environment values with a logging function.

Since: 0.0.0.0

Methods

logFuncL :: Lens' env LogFunc Source #

Instances

Instances details
HasLogFunc LogFunc Source # 
Instance details

Defined in RIO.Prelude.Logger

HasLogFunc LoggedProcessContext Source # 
Instance details

Defined in RIO.Process

HasLogFunc SimpleApp Source # 
Instance details

Defined in RIO.Prelude.Simple

logOptionsHandle Source #

Arguments

:: MonadIO m 
=> Handle 
-> Bool

Verbose Flag

-> m LogOptions 

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.

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

Since: 0.0.0.0

Log options

data LogOptions Source #

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

Since: 0.0.0.0

setLogMinLevel :: LogLevel -> LogOptions -> LogOptions Source #

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

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

Since: 0.0.0.0

setLogMinLevelIO :: IO LogLevel -> LogOptions -> LogOptions Source #

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

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

Since: 0.1.3.0

setLogVerboseFormat :: Bool -> LogOptions -> LogOptions Source #

Use the verbose format for printing log messages.

Default: follows the value of the verbose flag.

Since: 0.0.0.0

setLogVerboseFormatIO :: IO Bool -> LogOptions -> LogOptions Source #

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

Default: follows the value of the verbose flag.

Since: 0.1.3.0

setLogTerminal :: Bool -> LogOptions -> LogOptions Source #

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

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

Since: 0.0.0.0

setLogUseTime :: Bool -> LogOptions -> LogOptions Source #

Include the time when printing log messages.

Default: True in debug mode, False otherwise.

Since: 0.0.0.0

setLogUseColor :: Bool -> LogOptions -> LogOptions Source #

Use ANSI color codes in the log output.

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

Since: 0.0.0.0

setLogUseLoc :: Bool -> LogOptions -> LogOptions Source #

Use code location in the log output.

Default: True if in verbose mode, False otherwise.

Since: 0.1.2.0

setLogFormat :: (Utf8Builder -> Utf8Builder) -> LogOptions -> LogOptions Source #

Set format method for messages

Default: id

Since: 0.1.13.0

Standard logging functions

logDebug :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m () Source #

Log a debug level message with no source.

Since: 0.0.0.0

logInfo :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m () Source #

Log an info level message with no source.

Since: 0.0.0.0

logWarn :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m () Source #

Log a warn level message with no source.

Since: 0.0.0.0

logError :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => Utf8Builder -> m () Source #

Log an error level message with no source.

Since: 0.0.0.0

logOther Source #

Arguments

:: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) 
=> Text

level

-> Utf8Builder 
-> m () 

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

Since: 0.0.0.0

Advanced logging functions

Sticky logging

logSticky :: (MonadIO m, HasCallStack, MonadReader env m, HasLogFunc env) => Utf8Builder -> m () 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.

Since: 0.0.0.0

logStickyDone :: (MonadIO m, HasCallStack, MonadReader env m, HasLogFunc env) => Utf8Builder -> m () Source #

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.

Since: 0.0.0.0

With source

There is a set of logging functions that take an extra LogSource argument to provide context, typically detailing what part of an application the message comes from.

For example, in verbose mode, infoLogS "database" "connected" will result in

[info] (database) connected

logDebugS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m () Source #

Log a debug level message with the given source.

Since: 0.0.0.0

logInfoS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m () Source #

Log an info level message with the given source.

Since: 0.0.0.0

logWarnS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m () Source #

Log a warn level message with the given source.

Since: 0.0.0.0

logErrorS :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> Utf8Builder -> m () Source #

Log an error level message with the given source.

Since: 0.0.0.0

logOtherS Source #

Arguments

:: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) 
=> Text

level

-> LogSource 
-> Utf8Builder 
-> m () 

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

Since: 0.0.0.0

Generic log function

logGeneric :: (MonadIO m, MonadReader env m, HasLogFunc env, HasCallStack) => LogSource -> LogLevel -> Utf8Builder -> m () Source #

Generic, basic function for creating other logging functions.

Since: 0.0.0.0

Advanced running functions

mkLogFunc :: (CallStack -> LogSource -> LogLevel -> Utf8Builder -> IO ()) -> LogFunc Source #

Create a LogFunc from the given function.

Since: 0.0.0.0

logOptionsMemory :: MonadIO m => m (IORef Builder, LogOptions) Source #

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.

Since: 0.0.0.0

Data types

data LogLevel Source #

The log level of a message.

Since: 0.0.0.0

Instances

Instances details
Eq LogLevel Source # 
Instance details

Defined in RIO.Prelude.Logger

Ord LogLevel Source # 
Instance details

Defined in RIO.Prelude.Logger

Read LogLevel Source # 
Instance details

Defined in RIO.Prelude.Logger

Methods

readsPrec :: Int -> ReadS LogLevel

readList :: ReadS [LogLevel]

readPrec :: ReadPrec LogLevel

readListPrec :: ReadPrec [LogLevel]

Show LogLevel Source # 
Instance details

Defined in RIO.Prelude.Logger

Methods

showsPrec :: Int -> LogLevel -> ShowS

show :: LogLevel -> String #

showList :: [LogLevel] -> ShowS

type LogSource = Text Source #

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

Since: 0.0.0.0

data CallStack #

Instances

Instances details
IsList CallStack 
Instance details

Defined in GHC.Exts

Associated Types

type Item CallStack

Methods

fromList :: [Item CallStack] -> CallStack

fromListN :: Int -> [Item CallStack] -> CallStack

toList :: CallStack -> [Item CallStack]

Show CallStack 
Instance details

Defined in GHC.Show

Methods

showsPrec :: Int -> CallStack -> ShowS

show :: CallStack -> String #

showList :: [CallStack] -> ShowS

NFData CallStack 
Instance details

Defined in Control.DeepSeq

Methods

rnf :: CallStack -> () #

type Item CallStack 
Instance details

Defined in GHC.Exts

type Item CallStack = (String, SrcLoc)

Convenience functions

displayCallStack :: CallStack -> Utf8Builder Source #

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

TODO Consider showing the entire call stack instead.

Since: 0.0.0.0

noLogging :: (HasLogFunc env, MonadReader env m) => m a -> m a Source #

Disable logging capabilities in a given sub-routine

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

Since: 0.1.5.0

Accessors

logFuncUseColorL :: HasLogFunc env => SimpleGetter env Bool Source #

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.

Since: 0.1.0.0

Type-generic logger

When logging takes on a more semantic meaning and the logs need to be digested, acted upon, translated or serialized upstream (to e.g. a JSON logging server), we have GLogFunc (as in "generic log function"), and is accessed via HasGLogFunc.

There is only one function to log in this system: the glog function, which can log any message. You determine the log levels or severity of messages when needed.

Using mapRIO and contramapGLogFunc (or contramapMaybeGLogFunc), you can build hierarchies of loggers.

Example:

import RIO

data DatabaseMsg = Connected String | Query String | Disconnected deriving Show
data WebMsg = Request String | Error String | DatabaseMsg DatabaseMsg deriving Show
data AppMsg = InitMsg String | WebMsg WebMsg deriving Show

main :: IO ()
main =
  runRIO
    (mkGLogFunc (stack msg -> print msg))
    (do glog (InitMsg "Ready to go!")
        runWeb
          (do glog (Request "/foo")
              runDB (do glog (Connected "127.0.0.1")
                        glog (Query "SELECT 1"))
              glog (Error "Oh noes!")))

runDB :: RIO (GLogFunc DatabaseMsg) () -> RIO (GLogFunc WebMsg) ()
runDB = mapRIO (contramapGLogFunc DatabaseMsg)

runWeb :: RIO (GLogFunc WebMsg) () -> RIO (GLogFunc AppMsg) ()
runWeb = mapRIO (contramapGLogFunc WebMsg)

If we instead decided that we only wanted to log database queries, and not bother the upstream with connect/disconnect messages, we could simplify the constructor to DatabaseQuery String:

data WebMsg = Request String | Error String | DatabaseQuery String deriving Show

And then runDB could use contramapMaybeGLogFunc to parse only queries:

runDB =
  mapRIO
    (contramapMaybeGLogFunc
       (msg ->
          case msg of
            Query string -> pure (DatabaseQuery string)
            _ -> Nothing))

This way, upstream only has to care about queries and not connect/disconnect constructors.

glog :: (MonadIO m, HasCallStack, HasGLogFunc env, MonadReader env m) => GMsg env -> m () Source #

Log a value generically.

Since: 0.1.13.0

data GLogFunc msg Source #

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.

Since: 0.1.13.0

Instances

Instances details
Contravariant GLogFunc Source #

Use this instance to wrap sub-loggers via mapRIO.

The Contravariant class is available in base 4.12.0.

Since: 0.1.13.0

Instance details

Defined in RIO.Prelude.Logger

Methods

contramap :: (a -> b) -> GLogFunc b -> GLogFunc a

(>$) :: b -> GLogFunc b -> GLogFunc a

Semigroup (GLogFunc msg) Source #

Perform both sets of actions per log entry.

Since: 0.1.13.0

Instance details

Defined in RIO.Prelude.Logger

Methods

(<>) :: GLogFunc msg -> GLogFunc msg -> GLogFunc msg #

sconcat :: NonEmpty (GLogFunc msg) -> GLogFunc msg

stimes :: Integral b => b -> GLogFunc msg -> GLogFunc msg

Monoid (GLogFunc msg) Source #

mempty peforms no logging.

Since: 0.1.13.0

Instance details

Defined in RIO.Prelude.Logger

Methods

mempty :: GLogFunc msg #

mappend :: GLogFunc msg -> GLogFunc msg -> GLogFunc msg #

mconcat :: [GLogFunc msg] -> GLogFunc msg #

HasGLogFunc (GLogFunc msg) Source #

Quick way to run a RIO that only has a logger in its environment.

Since: 0.1.13.0

Instance details

Defined in RIO.Prelude.Logger

Associated Types

type GMsg (GLogFunc msg) Source #

Methods

gLogFuncL :: Lens' (GLogFunc msg) (GLogFunc (GMsg (GLogFunc msg))) Source #

type GMsg (GLogFunc msg) Source # 
Instance details

Defined in RIO.Prelude.Logger

type GMsg (GLogFunc msg) = msg

gLogFuncClassic :: (HasLogLevel msg, HasLogSource msg, Display msg) => LogFunc -> GLogFunc msg Source #

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

Since: 0.1.13.0

mkGLogFunc :: (CallStack -> msg -> IO ()) -> GLogFunc msg 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)))

Since: 0.1.13.0

contramapMaybeGLogFunc :: (a -> Maybe b) -> GLogFunc b -> GLogFunc a Source #

A vesion of contramapMaybeGLogFunc which supports filering.

Since: 0.1.13.0

contramapGLogFunc :: (a -> b) -> GLogFunc b -> GLogFunc a Source #

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

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

Since: 0.1.13.0

class HasGLogFunc env where Source #

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

Since: 0.1.13.0

Associated Types

type GMsg env Source #

Methods

gLogFuncL :: Lens' env (GLogFunc (GMsg env)) Source #

Instances

Instances details
HasGLogFunc (GLogFunc msg) Source #

Quick way to run a RIO that only has a logger in its environment.

Since: 0.1.13.0

Instance details

Defined in RIO.Prelude.Logger

Associated Types

type GMsg (GLogFunc msg) Source #

Methods

gLogFuncL :: Lens' (GLogFunc msg) (GLogFunc (GMsg (GLogFunc msg))) Source #

class HasLogLevel msg where Source #

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.

Since: 0.1.13.0

Methods

getLogLevel :: msg -> LogLevel Source #

class HasLogSource msg where Source #

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.

Since: 0.1.13.0

Methods

getLogSource :: msg -> LogSource Source #

Display

newtype Utf8Builder Source #

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

Since: 0.1.0.0

Constructors

Utf8Builder 

class Display a where Source #

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.

Since: 0.1.0.0

Minimal complete definition

display | textDisplay

Methods

display :: a -> Utf8Builder Source #

textDisplay :: a -> Text Source #

Display data as Text, which will also be used for display if it is not overriden.

Since: 0.1.7.0

Instances

Instances details
Display Char Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Double Source # 
Instance details

Defined in RIO.Prelude.Display

Display Float Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Int Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Int8 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Int16 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Int32 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Int64 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Integer Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Word Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Word8 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Word16 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Word32 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Word64 Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display SomeException Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Methods

display :: SomeException -> Utf8Builder Source #

textDisplay :: SomeException -> Text Source #

Display IOException Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Methods

display :: IOException -> Utf8Builder Source #

textDisplay :: IOException -> Text Source #

Display Text Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Text Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display Utf8Builder Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

Display (ProcessConfig a b c) Source #

Since: 0.1.0.0

Instance details

Defined in RIO.Prelude.Display

displayShow :: Show a => a -> Utf8Builder Source #

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

Since: 0.1.0.0

utf8BuilderToText :: Utf8Builder -> Text Source #

Convert a Utf8Builder value into a strict Text.

Since: 0.1.0.0

utf8BuilderToLazyText :: Utf8Builder -> Text Source #

Convert a Utf8Builder value into a lazy Text.

Since: 0.1.0.0

displayBytesUtf8 :: ByteString -> Utf8Builder Source #

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.

Since: 0.1.0.0

writeFileUtf8Builder :: MonadIO m => FilePath -> Utf8Builder -> m () Source #

Write the given Utf8Builder value to a file.

Since: 0.1.0.0

Optics

microlens-based Lenses, Traversals, etc.

view :: MonadReader s m => Getting a s a -> m a #

preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a) #

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

type ASetter' s a = ASetter s s a a #

type Getting r s a = (a -> Const r a) -> s -> Const r s #

type Lens s t a b = forall (f :: Type -> Type). Functor f => (a -> f b) -> s -> f t #

type Lens' s a = Lens s s a a #

type SimpleGetter s a = forall r. Getting r s a #

lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b #

over :: ASetter s t a b -> (a -> b) -> s -> t #

set :: ASetter s t a b -> b -> s -> t #

sets :: ((a -> b) -> s -> t) -> ASetter s t a b #

to :: (s -> a) -> SimpleGetter s a #

(^.) :: s -> Getting a s a -> a #

(^?) :: s -> Getting (First a) s a -> Maybe a #

(^..) :: s -> Getting (Endo [a]) s a -> [a] #

(%~) :: ASetter s t a b -> (a -> b) -> s -> t #

(.~) :: ASetter s t a b -> b -> s -> t #

Concurrency

data ThreadId #

Instances

Instances details
Eq ThreadId 
Instance details

Defined in GHC.Conc.Sync

Ord ThreadId 
Instance details

Defined in GHC.Conc.Sync

Show ThreadId 
Instance details

Defined in GHC.Conc.Sync

Methods

showsPrec :: Int -> ThreadId -> ShowS

show :: ThreadId -> String #

showList :: [ThreadId] -> ShowS

NFData ThreadId 
Instance details

Defined in Control.DeepSeq

Methods

rnf :: ThreadId -> () #

Hashable ThreadId 
Instance details

Defined in Data.Hashable.Class

myThreadId :: MonadIO m => m ThreadId #

isCurrentThreadBound :: MonadIO m => m Bool #

threadWaitRead :: MonadIO m => Fd -> m () #

threadWaitWrite :: MonadIO m => Fd -> m () #

threadDelay :: MonadIO m => Int -> m () #

yieldThread :: MonadIO m => m () Source #

Async

STM

Chan

Timeout

Exceptions

Re-exported from Control.Monad.Catch:

throwM :: (MonadThrow m, Exception e) => e -> m a #

Files and handles

withLazyFile :: MonadUnliftIO m => FilePath -> (ByteString -> m a) -> m a Source #

Lazily get the contents of a file. Unlike readFile, this ensures that if an exception is thrown, the file handle is closed immediately.

withLazyFileUtf8 :: MonadUnliftIO m => FilePath -> (Text -> m a) -> m a Source #

Lazily read a file in UTF8 encoding.

Since: 0.1.13

readFileBinary :: MonadIO m => FilePath -> m ByteString Source #

Same as readFile, but generalized to MonadIO

writeFileBinary :: MonadIO m => FilePath -> ByteString -> m () Source #

Same as writeFile, but generalized to MonadIO

readFileUtf8 :: MonadIO m => FilePath -> m Text Source #

Read a file in UTF8 encoding, throwing an exception on invalid character encoding.

This function will use OS-specific line ending handling.

writeFileUtf8 :: MonadIO m => FilePath -> Text -> m () Source #

Write a file in UTF8 encoding

This function will use OS-specific line ending handling.

hPutBuilder :: MonadIO m => Handle -> Builder -> m () Source #

Exit

exitFailure :: MonadIO m => m a Source #

Lifted version of "System.Exit.exitFailure".

@since 0.1.9.0.

exitSuccess :: MonadIO m => m a Source #

Lifted version of "System.Exit.exitSuccess".

@since 0.1.9.0.

exitWith :: MonadIO m => ExitCode -> m a Source #

Lifted version of "System.Exit.exitWith".

@since 0.1.9.0.

data ExitCode #

Constructors

ExitSuccess 
ExitFailure Int 

Instances

Instances details
Eq ExitCode 
Instance details

Defined in GHC.IO.Exception

Ord ExitCode 
Instance details

Defined in GHC.IO.Exception

Read ExitCode 
Instance details

Defined in GHC.IO.Exception

Methods

readsPrec :: Int -> ReadS ExitCode

readList :: ReadS [ExitCode]

readPrec :: ReadPrec ExitCode

readListPrec :: ReadPrec [ExitCode]

Show ExitCode 
Instance details

Defined in GHC.IO.Exception

Methods

showsPrec :: Int -> ExitCode -> ShowS

show :: ExitCode -> String #

showList :: [ExitCode] -> ShowS

Generic ExitCode 
Instance details

Defined in GHC.IO.Exception

Associated Types

type Rep ExitCode :: Type -> Type

Methods

from :: ExitCode -> Rep ExitCode x

to :: Rep ExitCode x -> ExitCode

NFData ExitCode 
Instance details

Defined in Control.DeepSeq

Methods

rnf :: ExitCode -> () #

Exception ExitCode 
Instance details

Defined in GHC.IO.Exception

Methods

toException :: ExitCode -> SomeException

fromException :: SomeException -> Maybe ExitCode

displayException :: ExitCode -> String

type Rep ExitCode 
Instance details

Defined in GHC.IO.Exception

type Rep ExitCode = D1 ('MetaData "ExitCode" "GHC.IO.Exception" "base" 'False) (C1 ('MetaCons "ExitSuccess" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ExitFailure" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)))

Mutable Variables

SomeRef

class HasWriteRef w env | env -> w where Source #

Environment values with writing capabilities to SomeRef

Since: 0.1.4.0

Methods

writeRefL :: Lens' env (SomeRef w) Source #

Instances

Instances details
HasWriteRef a (SomeRef a) Source #

Identity write reference where the SomeRef is the env

Since: 0.1.4.0

Instance details

Defined in RIO.Prelude.RIO

class HasStateRef s env | env -> s where Source #

Environment values with stateful capabilities to SomeRef

Since: 0.1.4.0

Methods

stateRefL :: Lens' env (SomeRef s) Source #

Instances

Instances details
HasStateRef a (SomeRef a) Source #

Identity state reference where the SomeRef is the env

Since: 0.1.4.0

Instance details

Defined in RIO.Prelude.RIO

data SomeRef a Source #

Abstraction over how to read from and write to a mutable reference

Since: 0.1.4.0

Instances

Instances details
HasWriteRef a (SomeRef a) Source #

Identity write reference where the SomeRef is the env

Since: 0.1.4.0

Instance details

Defined in RIO.Prelude.RIO

HasStateRef a (SomeRef a) Source #

Identity state reference where the SomeRef is the env

Since: 0.1.4.0

Instance details

Defined in RIO.Prelude.RIO

mapRIO :: (outer -> inner) -> RIO inner a -> RIO outer a Source #

Lift one RIO env to another.

Since: 0.1.13.0

readSomeRef :: MonadIO m => SomeRef a -> m a Source #

Read from a SomeRef

Since: 0.1.4.0

writeSomeRef :: MonadIO m => SomeRef a -> a -> m () Source #

Write to a SomeRef

Since: 0.1.4.0

modifySomeRef :: MonadIO m => SomeRef a -> (a -> a) -> m () Source #

Modify a SomeRef This function is subject to change due to the lack of atomic operations

Since: 0.1.4.0

newSomeRef :: MonadIO m => a -> m (SomeRef a) Source #

create a new boxed SomeRef

Since: 0.1.4.0

newUnboxedSomeRef :: (MonadIO m, Unbox a) => a -> m (SomeRef a) Source #

create a new unboxed SomeRef

Since: 0.1.4.0

URef

data URef s a Source #

An unboxed reference. This works like an IORef, but the data is stored in a bytearray instead of a heap object, avoiding significant allocation overhead in some cases. For a concrete example, see this Stack Overflow question: https://stackoverflow.com/questions/27261813/why-is-my-little-stref-int-require-allocating-gigabytes.

The first parameter is the state token type, the same as would be used for the ST monad. If you're using an IO-based monad, you can use the convenience IOURef type synonym instead.

Since: 0.0.2.0

type IOURef = URef (PrimState IO) Source #

Helpful type synonym for using a URef from an IO-based stack.

Since: 0.0.2.0

newURef :: (PrimMonad m, Unbox a) => a -> m (URef (PrimState m) a) Source #

Create a new URef

Since: 0.0.2.0

readURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> m a Source #

Read the value in a URef

Since: 0.0.2.0

writeURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> a -> m () Source #

Write a value into a URef. Note that this action is strict, and will force evalution of the value.

Since: 0.0.2.0

modifyURef :: (PrimMonad m, Unbox a) => URef (PrimState m) a -> (a -> a) -> m () Source #

Modify a value in a URef. Note that this action is strict, and will force evaluation of the result value.

Since: 0.0.2.0

IORef

MVar

Memoize

Deque

module RIO.Deque

Debugging

Trace

Text

trace :: Text -> a -> a Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceId :: Text -> Text Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceIO :: MonadIO m => Text -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceM :: Applicative f => Text -> f () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceEvent :: Text -> a -> a Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceEventIO :: MonadIO m => Text -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceMarker :: Text -> a -> a Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceMarkerIO :: MonadIO m => Text -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceStack :: Text -> a -> a Source #

Warning: Trace statement left in code

Since: 0.1.0.0

Show

traceShow :: Show a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowId :: Show a => a -> a Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowIO :: (Show a, MonadIO m) => a -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowM :: (Show a, Applicative f) => a -> f () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowEvent :: Show a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowEventIO :: (Show a, MonadIO m) => a -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowMarker :: Show a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowMarkerIO :: (Show a, MonadIO m) => a -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceShowStack :: Show a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

Display

traceDisplay :: Display a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayId :: Display a => a -> a Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayIO :: (Display a, MonadIO m) => a -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayM :: (Display a, Applicative f) => a -> f () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayEvent :: Display a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayEventIO :: (Display a, MonadIO m) => a -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayMarker :: Display a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayMarkerIO :: (Display a, MonadIO m) => a -> m () Source #

Warning: Trace statement left in code

Since: 0.1.0.0

traceDisplayStack :: Display a => a -> b -> b Source #

Warning: Trace statement left in code

Since: 0.1.0.0