|
|
|
|
|
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 (REPL) 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 |
|
|
|
|
Interactive sessions
|
|
The InputT monad transformer
|
|
|
A monad transformer which carries all of the state and settings
relevant to a line-reading application.
| Instances | |
|
|
|
Run a line-reading application. This function should suffice for most applications.
This function is equivalent to runInputTBehavior defaultBehavior. It
uses terminal-style interaction if stdin is connected to a terminal and has
echoing enabled. Otherwise (e.g., if stdin is a pipe), it uses file-style interaction.
If it uses terminal-style interaction, Prefs will be read from the user's ~/.haskeline file
(if present).
If it uses file-style interaction, Prefs are not relevant and will not be read.
|
|
|
Returns True if the current session uses terminal-style interaction. (See Behavior.)
|
|
Behaviors
|
|
|
Haskeline has two ways of interacting with the user:
- "Terminal-style" interaction provides an rich user interface by connecting
to the user's terminal (which may be different than stdin or stdout).
- "File-style" interaction treats the input as a simple stream of characters, for example
when reading from a file or pipe. Input functions (e.g., getInputLine) print the prompt to stdout.
A Behavior is a method for deciding at run-time which type of interaction to use.
For most applications (e.g., a REPL), defaultBehavior should have the correct effect.
|
|
|
|
Run a line-reading application according to the given behavior.
If it uses terminal-style interaction, Prefs will be read from the
user's ~/.haskeline file (if present).
If it uses file-style interaction, Prefs are not relevant and will not be read.
|
|
|
Read input from stdin.
Use terminal-style interaction if stdin is connected to
a terminal and has echoing enabled. Otherwise (e.g., if stdin is a pipe), use
file-style interaction.
This behavior should suffice for most applications.
|
|
|
Use file-style interaction, reading input from the given Handle.
|
|
|
Use file-style interaction, reading input from the given file.
|
|
|
Use terminal-style interaction whenever possible, even if stdin and/or stdout are not
terminals.
If it cannot open the user's terminal, use file-style interaction, reading input from stdin.
|
|
User interaction functions
|
|
Reading user input
|
|
The following functions read one line or character of input from the user.
When using terminal-style interaction, these functions return Nothing if the user
pressed Ctrl-D when the input text was empty.
When using file-style interaction, these functions return Nothing if
an EOF was encountered before any characters were read.
|
|
|
:: MonadException m | | => String | The input prompt
| -> InputT m (Maybe String) | | Reads one line of input. The final newline (if any) is removed. When using terminal-style interaction, this function provides a rich line-editing user interface.
If autoAddHistory == True and the line input is nonblank (i.e., is not all
spaces), it will be automatically added to the history.
|
|
|
|
:: MonadException m | | => String | The input prompt
| -> InputT m (Maybe Char) | | Reads one character of input. Ignores non-printable characters.
When using terminal-style interaction, the character will be read without waiting
for a newline.
When using file-style interaction, a newline will be read if it is immediately
available after the input character.
|
|
|
|
:: MonadException m | | => Maybe Char | A masking character; e.g., Just '*'
| -> String | | -> InputT m (Maybe String) | | Reads one line of input, without displaying the input while it is being typed.
When using terminal-style interaction, the masking character (if given) will replace each typed character.
When using file-style interaction, this function turns off echoing while reading
the line of input.
|
|
|
Outputting text
|
|
The following functions enable cross-platform output of text that may contain
Unicode characters.
|
|
|
Write a Unicode string to the user's standard output.
|
|
|
Write a string to the user's standard output, followed by a newline.
|
|
Customization
|
|
Settings
|
|
|
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 | |
|
|
|
A useful default. In particular:
defaultSettings = Settings {
complete = completeFilename,
historyFile = Nothing,
autoAddHistory = True
}
|
|
|
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
|
|
|
Prefs allow the user to customize the terminal-style 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 | |
|
|
|
Read Prefs from a given file. If there is an error reading the file,
the defaultPrefs will be returned.
|
|
|
The default preferences which may be overwritten in the
.haskeline file.
|
|
|
Run a line-reading application. Uses defaultBehavior to determine the
interaction behavior.
|
|
|
Run a line-reading application.
|
|
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.
|
|
|
Constructors | | Instances | |
|
|
|
If Ctrl-C is pressed during the given computation, throw an exception of type
Interrupt.
|
|
|
:: 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.6.1 |