System.Console.Haskeline

Contents

Description

A rich user interface for line input in command-line programs. Haskeline is Unicode-aware and runs both on POSIX-compatible systems and on Windows.

Users may customize the interface with a ~/.haskeline file; see http://trac.haskell.org/haskeline/wiki/UserPrefs for more information.

An example use of this library for a simple read-eval-print loop is the following:

 import System.Console.Haskeline
 
 main :: IO ()
 main = runInputT defaultSettings loop
    where 
        loop :: InputT IO ()
        loop = do
            minput <- getInputLine "% "
            case minput of
                Nothing -> return ()
                Just "quit" -> return ()
                Just input -> do outputStrLn $ "Input was: " ++ input
                                 loop

Synopsis

Main functions

The InputT monad transformer

data InputT m a Source

A monad transformer which carries all of the state and settings relevant to a line-reading application.

Instances

MonadTrans InputT
Monad m => MonadState History (InputT m)
Monad m => MonadState History (InputT m)
Monad m => MonadReader Prefs (InputT m)
Monad m => MonadReader RunTerm (InputT m)
Monad m => Monad (InputT m)
Monad m => Functor (InputT m)
Monad m => Applicative (InputT m)
MonadIO m => MonadIO (InputT m)
MonadException m => MonadException (InputT m)
Monad m => MonadReader (Settings m) (InputT m)

runInputT :: MonadException m => Settings m -> InputT m a -> m aSource

Run a line-reading application, reading user Prefs from ~/.haskeline

runInputTWithPrefs :: MonadException m => Prefs -> Settings m -> InputT m a -> m aSource

Reading user input

The following functions read one line or character of input from the user.

If stdin is connected to a terminal, then these functions perform all user interaction, including display of the prompt text, on the user's output terminal (which may differ from stdout). They return Nothing if the user pressed Ctrl-D when the input text was empty.

If stdin is not connected to a terminal or does not have echoing enabled, then these functions print the prompt to stdout, and they return Nothing if an EOF was encountered before any characters were read.

getInputLine Source

Arguments

:: forall m . MonadException m
=> String	The input prompt
-> InputT m (Maybe String)

Reads one line of input. The final newline (if any) is removed. Provides a rich line-editing user interface if stdin is a terminal.

If autoAddHistory == True and the line input is nonblank (i.e., is not all spaces), it will be automatically added to the history.

getInputChar Source

Arguments

:: MonadException m
=> String	The input prompt
-> InputT m (Maybe Char)

Reads one character of input. Ignores non-printable characters.

If stdin is a terminal, the character will be read without waiting for a newline.

If stdin is not a terminal, a newline will be read if it is immediately available after the input character.

Outputting text

The following functions allow cross-platform output of text that may contain Unicode characters.

outputStr :: MonadIO m => String -> InputT m ()Source

Write a string to the standard output.

outputStrLn :: MonadIO m => String -> InputT m ()Source

Write a string to the standard output, followed by a newline.

Settings

data Settings m Source

Application-specific customizations to the user interface.

Constructors

Settings
Fields complete :: CompletionFunc m Custom tab completion. historyFile :: Maybe FilePath Where to read/write the history at the start and end of each line input session. autoAddHistory :: Bool If `True`, each nonblank line returned by `getInputLine` will be automatically added to the history.

Instances

Monad m => MonadReader (Settings m) (InputT m)

defaultSettings :: MonadIO m => Settings mSource

A useful default. In particular:

 defaultSettings = Settings {
           complete = completeFilename,
           historyFile = Nothing,
           autoAddHistory = True
           }

setComplete :: CompletionFunc m -> Settings m -> Settings mSource

Because complete is the only field of Settings depending on m, the expression defaultSettings {completionFunc = f} leads to a type error from being too general. This function works around that issue, and may become unnecessary if another field depending on m is added.

User preferences

data Prefs Source

Prefs allow the user to customize the line-editing interface. They are read by default from ~/.haskeline; to override that behavior, use readPrefs and runInputTWithPrefs.

Each line of a .haskeline file defines one field of the Prefs datatype; field names are case-insensitive and unparseable lines are ignored. For example:

 editMode: Vi
 completionType: MenuCompletion
 maxhistorysize: Just 40

Instances

Show Prefs
Monad m => MonadReader Prefs (InputT m)

readPrefs :: FilePath -> IO Prefs Source

Read Prefs from a given file. If there is an error reading the file, the defaultPrefs will be returned.

defaultPrefs :: Prefs Source

The default preferences which may be overwritten in the .haskeline file.

Ctrl-C handling

The following functions provide portable handling of Ctrl-C events.

These functions are not necessary on GHC version 6.10 or later, which processes Ctrl-C events as exceptions by default.

data Interrupt Source

Constructors

Interrupt

Instances

Eq Interrupt
Show Interrupt
Typeable Interrupt
Exception Interrupt

withInterrupt :: MonadException m => InputT m a -> InputT m aSource

If Ctrl-C is pressed during the given computation, throw an exception of type Interrupt.

handleInterrupt Source

Arguments

:: MonadException m
=> m a	Handler to run if Ctrl-C is pressed
-> m a	Computation to run
-> m a

Catch and handle an exception of type Interrupt.

module System.Console.Haskeline.Completion

module System.Console.Haskeline.MonadException