Cli.Extras

|

Documentation

type CliLog m = MonadLog Output m

type CliThrow e m = MonadError e m

newtype CliT e m a

Constructors

CliT

Fields

• unCliT :: ReaderT (CliConfig e) (DieT e m) a

Instances

MonadIO m => MonadError e (CliT e m)

Defined in Cli.Extras.Types

Methods

throwError :: e -> CliT e m a

catchError :: CliT e m a -> (e -> CliT e m a) -> CliT e m a

Monad m => MonadLog Output (CliT e m)

Defined in Cli.Extras.Types

Methods

logMessageFree :: (forall n. Monoid n => (Output -> n) -> n) -> CliT e m ()

Monad m => HasCliConfig e (CliT e m)

Defined in Cli.Extras.Types

Methods

getCliConfig :: CliT e m (CliConfig e)

MonadTrans (CliT e)

Defined in Cli.Extras.Types

Methods

lift :: Monad m => m a -> CliT e m a

Monad m => MonadReader (CliConfig e) (CliT e m)

Defined in Cli.Extras.Types

Methods

ask :: CliT e m (CliConfig e)

local :: (CliConfig e -> CliConfig e) -> CliT e m a -> CliT e m a

reader :: (CliConfig e -> a) -> CliT e m a

Monad m => Monad (CliT e m)

Defined in Cli.Extras.Types

Methods

(>>=) :: CliT e m a -> (a -> CliT e m b) -> CliT e m b

(>>) :: CliT e m a -> CliT e m b -> CliT e m b

return :: a -> CliT e m a

Functor m => Functor (CliT e m)

Defined in Cli.Extras.Types

Methods

fmap :: (a -> b) -> CliT e m a -> CliT e m b

(<$) :: a -> CliT e m b -> CliT e m a

MonadFail m => MonadFail (CliT e m)

Defined in Cli.Extras.Types

Methods

fail :: String -> CliT e m a

Applicative m => Applicative (CliT e m)

Defined in Cli.Extras.Types

Methods

pure :: a -> CliT e m a

(<*>) :: CliT e m (a -> b) -> CliT e m a -> CliT e m b

liftA2 :: (a -> b -> c) -> CliT e m a -> CliT e m b -> CliT e m c

(*>) :: CliT e m a -> CliT e m b -> CliT e m b

(<*) :: CliT e m a -> CliT e m b -> CliT e m a

MonadIO m => MonadIO (CliT e m)

Defined in Cli.Extras.Types

Methods

liftIO :: IO a -> CliT e m a

MonadThrow m => MonadThrow (CliT e m)

Defined in Cli.Extras.Types

Methods

throwM :: Exception e0 => e0 -> CliT e m a

MonadCatch m => MonadCatch (CliT e m)

Defined in Cli.Extras.Types

Methods

catch :: Exception e0 => CliT e m a -> (e0 -> CliT e m a) -> CliT e m a

MonadMask m => MonadMask (CliT e m)

Defined in Cli.Extras.Types

Methods

mask :: ((forall a. CliT e m a -> CliT e m a) -> CliT e m b) -> CliT e m b

uninterruptibleMask :: ((forall a. CliT e m a -> CliT e m a) -> CliT e m b) -> CliT e m b

generalBracket :: CliT e m a -> (a -> ExitCase b -> CliT e m c) -> (a -> CliT e m b) -> CliT e m (b, c)

runCli :: MonadIO m => CliConfig e -> CliT e m a -> m a

data CliConfig e

Instances

Monad m => MonadReader (CliConfig e) (CliT e m)

Defined in Cli.Extras.Types

Methods

ask :: CliT e m (CliConfig e)

local :: (CliConfig e -> CliConfig e) -> CliT e m a -> CliT e m a

reader :: (CliConfig e -> a) -> CliT e m a

class Monad m => HasCliConfig e m | m -> e

Minimal complete definition

getCliConfig

Instances

Monad m => HasCliConfig e (CliT e m)

Defined in Cli.Extras.Types

Methods

getCliConfig :: CliT e m (CliConfig e)

HasCliConfig e m => HasCliConfig e (ExceptT e m)

Defined in Cli.Extras.Types

Methods

getCliConfig :: ExceptT e m (CliConfig e)

HasCliConfig e m => HasCliConfig e (StateT s m)

Defined in Cli.Extras.Types

Methods

getCliConfig :: StateT s m (CliConfig e)

(Monoid w, HasCliConfig e m) => HasCliConfig e (WriterT w m)

Defined in Cli.Extras.Types

Methods

getCliConfig :: WriterT w m (CliConfig e)

HasCliConfig e m => HasCliConfig e (ReaderT r m)

Defined in Cli.Extras.Types

Methods

getCliConfig :: ReaderT r m (CliConfig e)

getCliConfig :: HasCliConfig e m => m (CliConfig e)

data Output

Instances

Eq Output

Defined in Cli.Extras.Types

Methods

(==) :: Output -> Output -> Bool

(/=) :: Output -> Output -> Bool

Ord Output

Defined in Cli.Extras.Types

Methods

compare :: Output -> Output -> Ordering

(<) :: Output -> Output -> Bool

(<=) :: Output -> Output -> Bool

(>) :: Output -> Output -> Bool

(>=) :: Output -> Output -> Bool

max :: Output -> Output -> Output

min :: Output -> Output -> Output

Show Output

Defined in Cli.Extras.Types

Methods

showsPrec :: Int -> Output -> ShowS

show :: Output -> String

showList :: [Output] -> ShowS

Monad m => MonadLog Output (CliT e m)

Defined in Cli.Extras.Types

Methods

logMessageFree :: (forall n. Monoid n => (Output -> n) -> n) -> CliT e m ()

Monad m => MonadLog Output (DieT e m)

Defined in Cli.Extras.Types

Methods

logMessageFree :: (forall n. Monoid n => (Output -> n) -> n) -> DieT e m ()

withSpinner :: (MonadIO m, MonadMask m, CliLog m, HasCliConfig e m) => Text -> m a -> m a

Run an action with a CLI spinner.

withSpinnerNoTrail :: (MonadIO m, MonadMask m, CliLog m, HasCliConfig e m) => Text -> m a -> m a

A spinner that leaves no trail after a successful run.

Use if you wish the spinner to be ephemerally visible to the user.

The 'no trail' property automatically carries over to sub-spinners (in that they won't leave a trail either).

withSpinner'

Arguments

:: (MonadIO m, MonadMask m, CliLog m, HasCliConfig e m)

=> Text

-> Maybe (a -> Text)

Leave an optional trail with the given message creator

-> m a

-> m a

Advanced version that controls the display and content of the trail message.

class AsUnstructuredError e where

Indicates unstructured errors form one variant (or conceptual projection) of the error type.

Shouldn't really use this, but who has time to clean up that much!

Methods

asUnstructuredError :: Prism' e Text

Instances

AsUnstructuredError Text

Defined in Cli.Extras.Logging

Methods

asUnstructuredError :: Prism' Text Text

newCliConfig

Arguments

:: Severity

The initial log level. Messages below this severity will not be logged, unless the log level is subsequently altered using setLogLevel.

-> Bool

Should ANSI terminal formatting be disabled?

-> Bool

Should spinners be disabled?

-> (e -> (Text, ExitCode))

How to display errors, and compute the ExitCode corresponding to each error.

-> IO (CliConfig e)

Create a new CliConfig, initialized with the provided values.

getLogLevel :: (MonadIO m, HasCliConfig e m) => m Severity

putLog :: CliLog m => Severity -> Text -> m ()

Log a message to the console.

The message is guaranteed to be logged uninterrupted, even if there are ongoing spinners.

failWith :: (CliThrow e m, AsUnstructuredError e) => Text -> m a

Like `putLog Alert` but also abrupts the program.

errorToWarning :: (HasCliConfig e m, CliLog m) => e -> m ()

Log an error as though it were a warning, in a non-fatal way.

withExitFailMessage :: (CliLog m, MonadCatch m) => Text -> m a -> m a

Intercept ExitFailure exceptions and log the given alert before exiting.

This is useful when you want to provide contextual information to a deeper failure.

data Severity

Classes of severity for log messages. These have been chosen to match syslog severity levels

Constructors

Emergency

System is unusable. By syslog convention, this level should not be used by applications.

Alert

Should be corrected immediately.

Critical

Critical conditions.

Error

Error conditions.

Warning

May indicate that an error will occur if action is not taken.

Notice

Events that are unusual, but not error conditions.

Informational

Normal operational messages that require no action.

Debug

Information useful to developers for debugging the application.

Instances

Bounded Severity

Defined in Control.Monad.Log

Methods

minBound :: Severity

maxBound :: Severity

Enum Severity

Defined in Control.Monad.Log

Methods

succ :: Severity -> Severity

pred :: Severity -> Severity

toEnum :: Int -> Severity

fromEnum :: Severity -> Int

enumFrom :: Severity -> [Severity]

enumFromThen :: Severity -> Severity -> [Severity]

enumFromTo :: Severity -> Severity -> [Severity]

enumFromThenTo :: Severity -> Severity -> Severity -> [Severity]

Eq Severity

Defined in Control.Monad.Log

Methods

(==) :: Severity -> Severity -> Bool

(/=) :: Severity -> Severity -> Bool

Ord Severity

Defined in Control.Monad.Log

Methods

compare :: Severity -> Severity -> Ordering

(<) :: Severity -> Severity -> Bool

(<=) :: Severity -> Severity -> Bool

(>) :: Severity -> Severity -> Bool

(>=) :: Severity -> Severity -> Bool

max :: Severity -> Severity -> Severity

min :: Severity -> Severity -> Severity

Read Severity

Defined in Control.Monad.Log

Methods

readsPrec :: Int -> ReadS Severity

readList :: ReadS [Severity]

readPrec :: ReadPrec Severity

readListPrec :: ReadPrec [Severity]

Show Severity

Defined in Control.Monad.Log

Methods

showsPrec :: Int -> Severity -> ShowS

show :: Severity -> String

showList :: [Severity] -> ShowS

Pretty Severity

Defined in Control.Monad.Log

Methods

pretty :: Severity -> Doc ann

prettyList :: [Severity] -> Doc ann

class AsProcessFailure e where

Indicates arbitrary process failures form one variant (or conceptual projection) of the error type.

Methods

asProcessFailure :: Prism' e ProcessFailure

Instances

AsProcessFailure ProcessFailure

Defined in Cli.Extras.Process

Methods

asProcessFailure :: Prism' ProcessFailure ProcessFailure

data ProcessFailure

Constructors

ProcessFailure CmdSpec Int

Instances

Show ProcessFailure

Defined in Cli.Extras.Process

Methods

showsPrec :: Int -> ProcessFailure -> ShowS

show :: ProcessFailure -> String

showList :: [ProcessFailure] -> ShowS

AsProcessFailure ProcessFailure

Defined in Cli.Extras.Process

Methods

asProcessFailure :: Prism' ProcessFailure ProcessFailure

data ProcessSpec

Constructors

ProcessSpec

Fields

• _processSpec_createProcess :: !CreateProcess
• _processSpec_overrideEnv :: !(Maybe (Map String String -> Map String String))

callCommand :: (MonadIO m, CliLog m) => String -> m ()

Like callCommand, but logging (with Debug severity) the process which was started.

callProcess :: (MonadIO m, CliLog m) => String -> [String] -> m ()

Like callProcess, but logging (with Debug severity) the process which was started.

callProcessAndLogOutput

Arguments

:: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadMask m)

=> (Severity, Severity)

This tuple controls the severity of each output stream. Its fst is the severity of stdout; snd is the severity of stderr.

-> ProcessSpec

-> m ()

Like readProcess, but such that each of the child processes' standard output streams (stdout and stderr) is logged, with the corresponding severity.

Usually, this function is called as callProcessAndLogOutput (Debug, Error). If the child process is known to print diagnostic or informative messages to stderr, it is advisable to call callProcessAndLogOutput with a non-Error severity for stderr, for example callProcessAndLogOutput (Debug, Debug).

createProcess :: (MonadIO m, CliLog m) => ProcessSpec -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

Like createProcess, but logging (with Debug severity) the process which was started.

createProcess_ :: (MonadIO m, CliLog m) => String -> ProcessSpec -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)

Like createProcess_, but logging (with Debug severity) the process which was started.

throwExitCode :: (CliThrow e m, AsProcessFailure e) => ProcessSpec -> ExitCode -> m ()

Aborts the computation (using throwError) when given a non-ExitSuccess ExitCode.

overCreateProcess :: (CreateProcess -> CreateProcess) -> ProcessSpec -> ProcessSpec

proc :: FilePath -> [String] -> ProcessSpec

readCreateProcessWithExitCode :: (MonadIO m, CliLog m) => ProcessSpec -> m (ExitCode, String, String)

readProcessAndLogOutput

Arguments

:: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m)

=> (Severity, Severity)

This tuple controls the severity of each output stream. Its fst is the severity of stdout; snd is the severity of stderr.

-> ProcessSpec

-> m Text

Like readProcess, but such that each of the child processes' standard output streams (stdout and stderr) is logged, with the corresponding severity.

Usually, this function is called as readProcessAndLogOutput (Debug, Error). If the child process is known to print diagnostic or informative messages to stderr, it is advisable to call readProcessAndLogOutput with a non-Error severity for stderr, for example readProcessAndLogOutput (Debug, Debug).

readProcessAndLogStderr :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadMask m) => Severity -> ProcessSpec -> m Text

readProcessJSONAndLogStderr :: (FromJSON a, MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadMask m) => Severity -> ProcessSpec -> m a

reconstructCommand :: CmdSpec -> Text

Pretty print a CmdSpec

runProcess_ :: (MonadIO m, CliLog m, CliThrow e m, MonadMask m, AsProcessFailure e) => ProcessSpec -> m ()

Runs a process to completion, aborting the computation (using throwExitCode) in case of a non-ExitSuccess exit status.

setCwd :: Maybe FilePath -> ProcessSpec -> ProcessSpec

setDelegateCtlc :: Bool -> ProcessSpec -> ProcessSpec

setEnvOverride :: (Map String String -> Map String String) -> ProcessSpec -> ProcessSpec

shell :: String -> ProcessSpec

waitForProcess :: MonadIO m => ProcessHandle -> m ExitCode

Wrapper around waitForProcess