Extra.CIO

CIO is a type class for the TIO monad, which tracks the cursor position of the console so that indentation and prefixes can be added to the output. TIO also has a style component which lets you control the output verbosity and the appearance of the prefix. There is an instance for the regular IO monad which doesn't use any of these features, to allow functions which do not use the TIO monad call functions in the Debian library.

The CIO class

class MonadIO m => CIO m where

Class representing ways of doing console (terminal?) output.

Methods

hPutStr :: Handle -> String -> m ()

Write output to a handle.

hBOL :: Handle -> m ()

If we are not already at the beginning of a line, move the cursor to the beginning of the next one.

ev :: Int -> m Int

Return the "effective verbosity" for a task. If the argument is 2 it means the caller is computing ev for a task that normally does output when the verbosity level is 2 or higher. If the verbosity of the current style is 1, then the ev or effective verbosity is 2-1 = -1, so the output should be quieter.

setStyle :: (TStyle -> TStyle) -> m a -> m a

Modify the current output style.

tryCIO :: m a -> m (Either Exception a)

Implementation of try for this monad

Instances

CIO IO

Use this module to call functions in the CIO module from the regular IO monad. This instance ignores all style and state information. The verbosity controlled output functions will ignore any calls when v is greater than zero. This allows you to call the functions in the haskell-debian package from the regular IO monad.

This is in a separate module from CIO so you don't accidentally do a liftIO of some other CIO operation and get this instance.

CIO TIO

The TIO instance of CIO adds some features to the normal console output. By tracking the cursor position it is able to insert a prefix to each line, and to implement a beginning of line (BOL) function which only adds a newline when the cursor is not already at BOL. It also allows verbosity controlled output, where a verbosity level is stored in the monad state and output requests are given a verbosity which must be greater or equal to the monad's verbosity level for the output to appear.

Style constructors and transformers

data TStyle

A record used to hold the output style information for a task. This The prefixes that will appear at the beginning of each line, and the desired verbosity level. Suggested verbosity level policy:

• -1: No output of any kind, as if you were directing all output to devnull
• 0: Error output only, suitable for a run whose log you might examine later
• 1: casual progress reporting - if you were running on a console but didn't expect anything to go wrong
• 2: detailed progress reporting - show more progress, particularly things that might fail during the normal operation of the autobuilder: patches that fail to apply, dpkg-buildpackage runs that return errors, etc.
• 3: Debugging output - use this level or higher if you suspect the autobuilder itself is failing, or you are doing development work on the autobuilder.

Constructors

TStyle

Fields

prefix :: String

Add this string at the beginning of each line

verbosity :: Int

Ignore v functions whose argument is more than this

hPrefix :: [(Handle, String)]

Per-handle prefix

Instances

Show TStyle

defStyle :: TStyle

withStyle :: CIO m => TStyle -> m a -> m a

Use a new style for the TIO action

setVerbosity :: Int -> TStyle -> TStyle

addVerbosity :: Int -> TStyle -> TStyle

setPrefix :: String -> TStyle -> TStyle

Set the output style for a handle to prefixed.

addPrefix :: String -> TStyle -> TStyle

Prepend some text to the prefix.

appPrefix :: String -> TStyle -> TStyle

Append some text to the prefix.

setPrefixes :: String -> String -> TStyle -> TStyle

Set the output style for the stdout and stderr handle to prefixed, using whatever prefixes were most recently set (default is [1] and [2].)

addPrefixes :: String -> String -> TStyle -> TStyle

Switch to prefixed mode and modify both the stdout and stderr prefixes.

appPrefixes :: String -> String -> TStyle -> TStyle

hGetPrefix :: Handle -> TStyle -> String

Get the current prefix for a particular handle

Output functions

putStr :: CIO m => String -> m ()

Write a string to stdout.

ePutStr :: CIO m => String -> m ()

Write a string to stderr.

vPutStr :: CIO m => Int -> String -> m ()

Write a string to stdout depending on the verbosity level.

vEPutStr :: CIO m => Int -> String -> m ()

Verbosity controlled version of ePutStr

hPutChar :: CIO m => Handle -> Char -> m ()

Write a character.

putChar :: CIO m => Char -> m ()

Write a character to stdout.

ePutChar :: CIO m => Char -> m ()

Write a character to stderr.

vHPutChar :: CIO m => Handle -> Int -> Char -> m ()

Verbosity controlled version of hPutChar.

vPutChar :: CIO m => Int -> Char -> m ()

Verbosity controlled version of putChar

vEPutChar :: CIO m => Int -> Char -> m ()

Verbosity controlled version of ePutChar

hPutStrBl :: CIO m => Handle -> String -> m ()

Move to beginning of next line (if necessary) and output a string.

putStrBl :: CIO m => String -> m ()

hPutStrBl to stdout.

ePutStrBl :: CIO m => String -> m ()

hPutStrBl to stderr.

vHPutStrBl :: CIO m => Handle -> Int -> String -> m ()

Verbosity controlled version of hPutStrBl

vPutStrBl :: CIO m => Int -> String -> m ()

Verbosity controlled version of putStrBl

vEPutStrBl :: CIO m => Int -> String -> m ()

Verbosity controlled version of ePutStrBl

hPutStrLn :: CIO m => Handle -> String -> m ()

Write a newline character and a string.

putStrLn :: CIO m => String -> m ()

hPutStrLn to stdout.

ePutStrLn :: CIO m => String -> m ()

hPutStrLn to stderr.

vHPutStrLn :: CIO m => Handle -> Int -> String -> m ()

Verbosity controlled version of hPutStrLn.

vPutStrLn :: CIO m => Int -> String -> m ()

Verbosity controlled version of putStrLn

vEPutStrLn :: CIO m => Int -> String -> m ()

Verbosity controlled version of ePutStrLn

bol :: CIO m => m ()

hBOL to stdout.

eBOL :: CIO m => m ()

hBOL to stderr.

vHBOL :: CIO m => Handle -> Int -> m ()

vBOL :: CIO m => Int -> m ()

Verbosity controlled version of BOL

vEBOL :: CIO m => Int -> m ()

Verbosity controlled version of eBOL