-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A command-line interface for user input, written in Haskell. -- -- Haskeline provides a user interface for line input in command-line -- programs. This library is similar in purpose to readline, but since it -- is written in Haskell it is (hopefully) more easily used in other -- Haskell programs. -- -- Haskeline runs both on POSIX-compatible systems and on Windows. @package haskeline @version 0.8.0.1 module System.Console.Haskeline.Completion -- | Performs completions from the given line state. -- -- The first String argument is the contents of the line to the -- left of the cursor, reversed. The second String argument is the -- contents of the line to the right of the cursor. -- -- The output String is the unused portion of the left half of the -- line, reversed. type CompletionFunc m = (String, String) -> m (String, [Completion]) data Completion Completion :: String -> String -> Bool -> Completion -- | Text to insert in line. [replacement] :: Completion -> String -- | Text to display when listing alternatives. [display] :: Completion -> String -- | Whether this word should be followed by a space, end quote, etc. [isFinished] :: Completion -> Bool -- | Disable completion altogether. noCompletion :: Monad m => CompletionFunc m -- | Create a finished completion out of the given word. simpleCompletion :: String -> Completion -- | If the first completer produces no suggestions, fallback to the second -- completer's output. fallbackCompletion :: Monad m => CompletionFunc m -> CompletionFunc m -> CompletionFunc m -- | A custom CompletionFunc which completes the word immediately to -- the left of the cursor. -- -- A word begins either at the start of the line or after an unescaped -- whitespace character. completeWord :: Monad m => Maybe Char -> [Char] -> (String -> m [Completion]) -> CompletionFunc m -- | A custom CompletionFunc which completes the word immediately to -- the left of the cursor, and takes into account the line contents to -- the left of the word. -- -- A word begins either at the start of the line or after an unescaped -- whitespace character. completeWordWithPrev :: Monad m => Maybe Char -> [Char] -> (String -> String -> m [Completion]) -> CompletionFunc m completeQuotedWord :: Monad m => Maybe Char -> [Char] -> (String -> m [Completion]) -> CompletionFunc m -> CompletionFunc m completeFilename :: MonadIO m => CompletionFunc m -- | List all of the files or folders beginning with this path. listFiles :: MonadIO m => FilePath -> m [Completion] filenameWordBreakChars :: String instance GHC.Show.Show System.Console.Haskeline.Completion.Completion instance GHC.Classes.Ord System.Console.Haskeline.Completion.Completion instance GHC.Classes.Eq System.Console.Haskeline.Completion.Completion -- | This module provides a low-level API to the line history stored in the -- InputT monad transformer. -- -- For most application, it should suffice to instead use the following -- Settings flags: -- -- -- -- If you do want custom history behavior, you may need to disable the -- above default setting(s). module System.Console.Haskeline.History data History emptyHistory :: History addHistory :: String -> History -> History -- | Add a line to the history unless it matches the previously recorded -- line. addHistoryUnlessConsecutiveDupe :: String -> History -> History -- | Add a line to the history, and remove all previous entries which are -- the same as it. addHistoryRemovingAllDupes :: String -> History -> History -- | The input lines stored in the history (newest first) historyLines :: History -> [String] -- | Reads the line input history from the given file. Returns -- emptyHistory if the file does not exist or could not be read. readHistory :: FilePath -> IO History -- | Writes the line history to the given file. If there is an error when -- writing the file, it will be ignored. writeHistory :: FilePath -> History -> IO () -- | Limit the number of lines stored in the history. stifleHistory :: Maybe Int -> History -> History -- | The maximum number of lines stored in the history. If Nothing, -- the history storage is unlimited. stifleAmount :: History -> Maybe Int instance GHC.Show.Show System.Console.Haskeline.History.History -- | 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 https://github.com/judah/haskeline/wiki/UserPreferences 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
--
module System.Console.Haskeline -- | A monad transformer which carries all of the state and settings -- relevant to a line-reading application. data InputT m a -- | 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. runInputT :: (MonadIO m, MonadMask m) => Settings m -> InputT m a -> m a -- | Returns True if the current session uses terminal-style -- interaction. (See Behavior.) haveTerminalUI :: Monad m => InputT m Bool -- | Map a user interaction by modifying the base monad computation. mapInputT :: (forall b. m b -> m b) -> InputT m a -> InputT m a -- | Haskeline has two ways of interacting with the user: -- -- -- -- 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. data Behavior -- | 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. runInputTBehavior :: (MonadIO m, MonadMask m) => Behavior -> Settings m -> InputT m a -> m a -- | 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. defaultBehavior :: Behavior -- | Use file-style interaction, reading input from the given -- Handle. useFileHandle :: Handle -> Behavior -- | Use file-style interaction, reading input from the given file. useFile :: FilePath -> Behavior -- | 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. preferTerm :: Behavior -- | 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. getInputLine :: (MonadIO m, MonadMask m) => String -> InputT m (Maybe String) -- | Reads one line of input and fills the insertion space with initial -- text. When using terminal-style interaction, this function provides a -- rich line-editing user interface with the added ability to give the -- user default values. -- -- This function behaves in the exact same manner as getInputLine, -- except that it pre-populates the input area. The text that resides in -- the input area is given as a 2-tuple with two Strings. The -- string on the left of the tuple (obtained by calling fst) is -- what will appear to the left of the cursor and the string on the right -- (obtained by calling snd) is what will appear to the right of -- the cursor. -- -- Some examples of calling of this function are: -- -- 
--   getInputLineWithInitial "prompt> " ("left", "") -- The cursor starts at the end of the line.
--   getInputLineWithInitial "prompt> " ("left ", "right") -- The cursor starts before the second word.
--
getInputLineWithInitial :: (MonadIO m, MonadMask m) => String -> (String, String) -> InputT m (Maybe String) -- | 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. getInputChar :: (MonadIO m, MonadMask m) => String -> InputT m (Maybe Char) -- | 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. -- -- Note that if Haskeline is built against a version of the -- Win32 library earlier than 2.5, getPassword will -- incorrectly echo back input on MinTTY consoles (such as Cygwin or -- MSYS). getPassword :: (MonadIO m, MonadMask m) => Maybe Char -> String -> InputT m (Maybe String) -- | Waits for one key to be pressed, then returns. Ignores the value of -- the specific key. -- -- Returns True if it successfully accepted one key. Returns -- False if it encountered the end of input; i.e., an EOF -- in file-style interaction, or a Ctrl-D in terminal-style -- interaction. -- -- When using file-style interaction, consumes a single character from -- the input which may be non-printable. waitForAnyKey :: (MonadIO m, MonadMask m) => String -> InputT m Bool -- | Write a Unicode string to the user's standard output. outputStr :: MonadIO m => String -> InputT m () -- | Write a string to the user's standard output, followed by a newline. outputStrLn :: MonadIO m => String -> InputT m () -- | Return a printing function, which in terminal-style interactions is -- thread-safe and may be run concurrently with user input without -- affecting the prompt. getExternalPrint :: MonadIO m => InputT m (String -> IO ()) -- | Application-specific customizations to the user interface. data Settings m Settings :: CompletionFunc m -> Maybe FilePath -> Bool -> Settings m -- | Custom tab completion. [complete] :: Settings m -> CompletionFunc m -- | Where to read/write the history at the start and end of each line -- input session. [historyFile] :: Settings m -> Maybe FilePath -- | If True, each nonblank line returned by getInputLine -- will be automatically added to the history. [autoAddHistory] :: Settings m -> Bool -- | A useful default. In particular: -- -- 
--   defaultSettings = Settings {
--             complete = completeFilename,
--             historyFile = Nothing,
--             autoAddHistory = True
--             }
--
defaultSettings :: MonadIO 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. setComplete :: CompletionFunc m -> Settings m -> Settings m -- | 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
--
data Prefs -- | Read Prefs from a given file. If there is an error reading the -- file, the defaultPrefs will be returned. readPrefs :: FilePath -> IO Prefs -- | The default preferences which may be overwritten in the -- .haskeline file. defaultPrefs :: Prefs -- | Run a line-reading application. Uses defaultBehavior to -- determine the interaction behavior. runInputTWithPrefs :: (MonadIO m, MonadMask m) => Prefs -> Settings m -> InputT m a -> m a -- | Run a line-reading application. runInputTBehaviorWithPrefs :: (MonadIO m, MonadMask m) => Behavior -> Prefs -> Settings m -> InputT m a -> m a -- | Get the current line input history. getHistory :: MonadIO m => InputT m History -- | Set the line input history. putHistory :: MonadIO m => History -> InputT m () -- | Change the current line input history. modifyHistory :: MonadIO m => (History -> History) -> InputT m () -- | If Ctrl-C is pressed during the given action, throw an exception of -- type Interrupt. For example: -- -- 
--   tryAction :: InputT IO ()
--   tryAction = handle (\Interrupt -> outputStrLn "Cancelled.")
--                  $ withInterrupt $ someLongAction
--
-- -- The action can handle the interrupt itself; a new Interrupt -- exception will be thrown every time Ctrl-C is pressed. -- -- 
--   tryAction :: InputT IO ()
--   tryAction = withInterrupt loop
--       where loop = handle (\Interrupt -> outputStrLn "Cancelled; try again." >> loop)
--                      someLongAction
--
-- -- This behavior differs from GHC's built-in Ctrl-C handling, which may -- immediately terminate the program after the second time that the user -- presses Ctrl-C. withInterrupt :: (MonadIO m, MonadMask m) => InputT m a -> InputT m a data Interrupt Interrupt :: Interrupt -- | Catch and handle an exception of type Interrupt. -- -- 
--   handleInterrupt f = handle $ \Interrupt -> f
--
handleInterrupt :: MonadMask m => m a -> m a -> m a module System.Console.Haskeline.Internal -- | This function may be used to debug Haskeline's input. -- -- It loops indefinitely; every time a key is pressed, it will print that -- key as it was recognized by Haskeline. Pressing Ctrl-C will stop the -- loop. -- -- Haskeline's behavior may be modified by editing your -- ~/.haskeline file. For details, see: -- https://github.com/judah/haskeline/wiki/CustomKeyBindings debugTerminalKeys :: IO a -- | This module provides a stateful, IO-based interface to Haskeline, -- which may be easier to integrate into some existing programs or -- libraries. -- -- It is strongly recommended to use the safer, monadic API of -- System.Console.Haskeline, if possible, rather than the explicit -- state management functions of this module. -- -- The equivalent REPL example is: -- -- 
--   import System.Console.Haskeline
--   import System.Console.Haskeline.IO
--   import Control.Concurrent
--   
--   main = bracketOnError (initializeInput defaultSettings)
--               cancelInput -- This will only be called if an exception such
--                               -- as a SigINT is received.
--               (\hd -> loop hd >> closeInput hd)
--       where
--           loop :: InputState -> IO ()
--           loop hd = do
--               minput <- queryInput hd (getInputLine "% ")
--               case minput of
--                   Nothing -> return ()
--                   Just "quit" -> return ()
--                   Just input -> do queryInput hd $ outputStrLn
--                                       $ "Input was: " ++ input
--                                    loop hd
--
module System.Console.Haskeline.IO data InputState -- | Initialize a session of line-oriented user interaction. initializeInput :: Settings IO -> IO InputState -- | Finish and clean up the line-oriented user interaction session. Blocks -- on an existing call to queryInput. closeInput :: InputState -> IO () -- | Cancel and clean up the user interaction session. Does not block on an -- existing call to queryInput. cancelInput :: InputState -> IO () -- | Run one action (for example, getInputLine) as part of a session -- of user interaction. -- -- For example, multiple calls to queryInput using the same -- InputState will share the same input history. In constrast, -- multiple calls to runInputT will use distinct histories unless -- they share the same history file. -- -- This function should not be called on a closed or cancelled -- InputState. queryInput :: InputState -> InputT IO a -> IO a