Safe Haskell	None
Language	Haskell2010

Cli.Extras

Description

Package for writing great CLI apps.

See Demo.hs for an example

This package should eventually be made its own library.

Synopsis

type CliLog m = MonadLog Output m
type CliThrow e m = MonadError e m
newtype CliT e m a = CliT {
- unCliT :: ReaderT CliConfig (LoggingT Output (ExceptT e m)) a
}
runCli :: MonadIO m => CliConfig -> CliT e m a -> m (Either e a)
data CliConfig
class Monad m => HasCliConfig m
getCliConfig :: HasCliConfig m => m CliConfig
data Output
withSpinner :: (MonadIO m, MonadMask m, CliLog m, HasCliConfig m) => Text -> m a -> m a
withSpinnerNoTrail :: (MonadIO m, MonadMask m, CliLog m, HasCliConfig m) => Text -> m a -> m a
withSpinner' :: (MonadIO m, MonadMask m, CliLog m, HasCliConfig m) => Text -> Maybe (a -> Text) -> m a -> m a
class AsUnstructuredError e where
- asUnstructuredError :: Prism' e Text
newCliConfig :: Severity -> Bool -> Bool -> IO CliConfig
mkDefaultCliConfig :: [String] -> IO CliConfig
getLogLevel :: (MonadIO m, HasCliConfig m) => m Severity
putLog :: CliLog m => Severity -> Text -> m ()
failWith :: (CliThrow e m, AsUnstructuredError e) => Text -> m a
withExitFailMessage :: (CliLog m, MonadCatch m) => Text -> m a -> m a
data Severity
- = Emergency
- | Alert
- | Critical
- | Error
- | Warning
- | Notice
- | Informational
- | Debug
class AsProcessFailure e where
- asProcessFailure :: Prism' e ProcessFailure
data ProcessFailure = ProcessFailure CmdSpec Int
prettyProcessFailure :: ProcessFailure -> Text
data ProcessSpec = ProcessSpec {
- _processSpec_createProcess :: !CreateProcess
- _processSpec_overrideEnv :: !(Maybe (Map String String -> Map String String))
}
callCommand :: (MonadIO m, CliLog m) => String -> m ()
callProcess :: (MonadIO m, CliLog m) => String -> [String] -> m ()
callProcessAndLogOutput :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m) => (Severity, Severity) -> ProcessSpec -> m ()
createProcess_ :: (MonadIO m, CliLog m) => String -> ProcessSpec -> m (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
overCreateProcess :: (CreateProcess -> CreateProcess) -> ProcessSpec -> ProcessSpec
proc :: FilePath -> [String] -> ProcessSpec
readCreateProcessWithExitCode :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e) => ProcessSpec -> m (ExitCode, String, String)
readProcessAndLogOutput :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m) => (Severity, Severity) -> ProcessSpec -> m Text
readProcessAndLogStderr :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m) => Severity -> ProcessSpec -> m Text
readProcessJSONAndLogStderr :: (FromJSON a, MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m) => Severity -> ProcessSpec -> m a
reconstructCommand :: CmdSpec -> Text
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

Documentation

type CliLog m = MonadLog Output m Source #

type CliThrow e m = MonadError e m Source #

newtype CliT e m a Source #

Constructors

CliT
Fields unCliT :: ReaderT CliConfig (LoggingT Output (ExceptT e m)) a

Instances

Monad m => MonadError e (CliT e m) Source #
Instance details 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) Source #
Instance details Defined in Cli.Extras.Types Methods logMessageFree :: (forall n. Monoid n => (Output -> n) -> n) -> CliT e m () #
MonadTrans (CliT e) Source #
Instance details Defined in Cli.Extras.Types Methods lift :: Monad m => m a -> CliT e m a #
Monad m => Monad (CliT e m) Source #
Instance details 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 # fail :: String -> CliT e m a #
Functor m => Functor (CliT e m) Source #
Instance details 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) Source #
Instance details Defined in Cli.Extras.Types Methods fail :: String -> CliT e m a #
Monad m => Applicative (CliT e m) Source #
Instance details 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) Source #
Instance details Defined in Cli.Extras.Types Methods liftIO :: IO a -> CliT e m a #
MonadThrow m => MonadThrow (CliT e m) Source #
Instance details Defined in Cli.Extras.Types Methods throwM :: Exception e0 => e0 -> CliT e m a #
MonadCatch m => MonadCatch (CliT e m) Source #
Instance details 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) Source #
Instance details 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) #
Monad m => HasCliConfig (CliT e m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: CliT e m CliConfig Source #

runCli :: MonadIO m => CliConfig -> CliT e m a -> m (Either e a) Source #

data CliConfig Source #

class Monad m => HasCliConfig m Source #

Minimal complete definition

getCliConfig

Instances

HasCliConfig m => HasCliConfig (ExceptT e m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: ExceptT e m CliConfig Source #
(Monoid w, HasCliConfig m) => HasCliConfig (WriterT w m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: WriterT w m CliConfig Source #
HasCliConfig m => HasCliConfig (StateT s m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: StateT s m CliConfig Source #
HasCliConfig m => HasCliConfig (ReaderT r m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: ReaderT r m CliConfig Source #
Monad m => HasCliConfig (CliT e m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: CliT e m CliConfig Source #
HasCliConfig m => HasCliConfig (SubExceptT e eSub m) Source #
Instance details Defined in Cli.Extras.Types Methods getCliConfig :: SubExceptT e eSub m CliConfig Source #

getCliConfig :: HasCliConfig m => m CliConfig Source #

data Output Source #

Instances

Eq Output Source #
Instance details Defined in Cli.Extras.Types Methods (==) :: Output -> Output -> Bool # (/=) :: Output -> Output -> Bool #
Ord Output Source #
Instance details 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 Source #
Instance details Defined in Cli.Extras.Types Methods showsPrec :: Int -> Output -> ShowS # show :: Output -> String # showList :: [Output] -> ShowS #
Monad m => MonadLog Output (CliT e m) Source #
Instance details Defined in Cli.Extras.Types Methods logMessageFree :: (forall n. Monoid n => (Output -> n) -> n) -> CliT e m () #
MonadFail m => MonadFail (LoggingT Output m) Source #
Instance details Defined in Cli.Extras.Types Methods fail :: String -> LoggingT Output m a #

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

Run an action with a CLI spinner.

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

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' Source #

Arguments

:: (MonadIO m, MonadMask m, CliLog m, HasCliConfig 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 Source #

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 Source #

Instances

AsUnstructuredError Text Source #
Instance details Defined in Cli.Extras.Logging Methods asUnstructuredError :: Prism' Text Text Source #

newCliConfig :: Severity -> Bool -> Bool -> IO CliConfig Source #

mkDefaultCliConfig :: [String] -> IO CliConfig Source #

getLogLevel :: (MonadIO m, HasCliConfig m) => m Severity Source #

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

Log a message to the console.

Logs safely even if there are ongoing spinners.

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

Like `putLog Alert` but also abrupts the program.

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

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
Instance details Defined in Control.Monad.Log Methods minBound :: Severity # maxBound :: Severity #
Enum Severity
Instance details 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
Instance details Defined in Control.Monad.Log Methods (==) :: Severity -> Severity -> Bool # (/=) :: Severity -> Severity -> Bool #
Ord Severity
Instance details 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
Instance details Defined in Control.Monad.Log Methods readsPrec :: Int -> ReadS Severity # readList :: ReadS [Severity] # readPrec :: ReadPrec Severity # readListPrec :: ReadPrec [Severity] #
Show Severity
Instance details Defined in Control.Monad.Log Methods showsPrec :: Int -> Severity -> ShowS # show :: Severity -> String # showList :: [Severity] -> ShowS #
Pretty Severity
Instance details Defined in Control.Monad.Log Methods pretty :: Severity -> Doc ann # prettyList :: [Severity] -> Doc ann #

class AsProcessFailure e where Source #

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

Methods

asProcessFailure :: Prism' e ProcessFailure Source #

Instances

AsProcessFailure ProcessFailure Source #
Instance details Defined in Cli.Extras.Process Methods asProcessFailure :: Prism' ProcessFailure ProcessFailure Source #

data ProcessFailure Source #

Constructors

ProcessFailure CmdSpec Int

Instances

Show ProcessFailure Source #
Instance details Defined in Cli.Extras.Process Methods showsPrec :: Int -> ProcessFailure -> ShowS # show :: ProcessFailure -> String # showList :: [ProcessFailure] -> ShowS #
AsProcessFailure ProcessFailure Source #
Instance details Defined in Cli.Extras.Process Methods asProcessFailure :: Prism' ProcessFailure ProcessFailure Source #

prettyProcessFailure :: ProcessFailure -> Text Source #

data ProcessSpec Source #

Constructors

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

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

Like callCommand but also logs (debug) the command being run

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

Like callProcess but also logs (debug) the process being run

callProcessAndLogOutput :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m) => (Severity, Severity) -> ProcessSpec -> m () Source #

Like callProcess but logs the combined output (stdout and stderr) with the corresponding severity.

Usually this function is called as `callProcessAndLogOutput (Debug, Error)`. However some processes are known to spit out diagnostic or informative messages in stderr, in which case it is advisable to call it with a non-Error severity for stderr, like `callProcessAndLogOutput (Debug, Debug)`.

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

Like createProcess_ but also logs (debug) the process being run

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

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

readCreateProcessWithExitCode :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e) => ProcessSpec -> m (ExitCode, String, String) Source #

readProcessAndLogOutput :: (MonadIO m, CliLog m, CliThrow e m, AsProcessFailure e, MonadFail m) => (Severity, Severity) -> ProcessSpec -> m Text Source #

Like readProcess but logs the combined output (stdout and stderr) with the corresponding severity.

Usually this function is called as `callProcessAndLogOutput (Debug, Error)`. However some processes are known to spit out diagnostic or informative messages in stderr, in which case it is advisable to call it with a non-Error severity for stderr, like `callProcessAndLogOutput (Debug, Debug)`.

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

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

reconstructCommand :: CmdSpec -> Text Source #

Pretty print a CmdSpec

setCwd :: Maybe FilePath -> ProcessSpec -> ProcessSpec Source #

setDelegateCtlc :: Bool -> ProcessSpec -> ProcessSpec Source #

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

shell :: String -> ProcessSpec Source #

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

Wrapper around waitForProcess