| haskeline-0.6.1.5: A command-line interface for user input, written in Haskell. | Source code | Contents | Index

System.Console.Haskeline

Contents

Main functions
  The InputT monad transformer
  Reading user input
  Outputting text
Settings
User preferences
Ctrl-C handling

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

data InputT m a
runInputT :: MonadException m => Settings m -> InputT m a -> m a
runInputTWithPrefs :: MonadException m => Prefs -> Settings m -> InputT m a -> m a
getInputLine :: forall m. MonadException m => String -> InputT m (Maybe String)
getInputChar :: MonadException m => String -> InputT m (Maybe Char)
outputStr :: MonadIO m => String -> InputT m ()
outputStrLn :: MonadIO m => String -> InputT m ()

data Settings m = Settings {

complete :: CompletionFunc m
historyFile :: Maybe FilePath
autoAddHistory :: Bool

}

defaultSettings :: MonadIO m => Settings m
setComplete :: CompletionFunc m -> Settings m -> Settings m
data Prefs
readPrefs :: FilePath -> IO Prefs
defaultPrefs :: Prefs
data Interrupt = Interrupt
withInterrupt :: MonadException m => InputT m a -> InputT m a
handleInterrupt :: MonadException m => m a -> m a -> m a
module System.Console.Haskeline.Completion
module System.Console.Haskeline.MonadException

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

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

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

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

:: 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

:: 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 |

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

A useful default. In particular:

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

setComplete :: CompletionFunc m -> Settings m -> Settings m | Source

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

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

handleInterrupt | Source

:: 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
Produced by Haddock version 2.4.2