System.Console.Haskeline

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

Main functions

The InputT monad transformer

data InputT m a

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 a

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

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

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

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

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 ()

Write a string to the standard output.

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

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

Settings

data Settings m

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 m

A useful default. In particular:

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

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

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

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

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

defaultPrefs :: Prefs

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

Constructors

Interrupt

Instances

Eq Interrupt

Show Interrupt

Typeable Interrupt

Exception Interrupt

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

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

handleInterrupt

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