System.Console.Repline

Repline exposes an additional monad transformer on top of Haskeline called HaskelineT. It simplifies several aspects of composing Haskeline with State and Exception monads in modern versions of mtl.

type Repl a = HaskelineT IO a

The evaluator evalRepl evaluates a HaskelineT monad transformer by constructing a shell with several custom functions and evaluating it inside of IO:

• Commands: Handled on ordinary input.
• Completions: Handled when tab key is pressed.
• Options: Handled when a command prefixed by a colon is entered.
• Banner: Text Displayed at initialization.
• Initializer: Run at initialization.

A simple evaluation function might simply echo the output back to the screen.

-- Evaluation : handle each line user inputs
cmd :: String -> Repl ()
cmd input = liftIO $ print input

Several tab completion options are available, the most common is the WordCompleter which completes on single words separated by spaces from a list of matches. The internal logic can be whatever is required and can also access a StateT instance to query application state.

-- Tab Completion: return a completion for partial words entered
completer :: Monad m => WordCompleter m
completer n = do
  let names = ["kirk", "spock", "mccoy"]
  return $ filter (isPrefixOf n) names

Input which is prefixed by a colon (commands like ":type" and ":help") queries an association list of functions which map to custom logic. The function takes a space-separated list of augments in it's first argument. If the entire line is desired then the unwords function can be used to concatenate.

-- Commands
help :: [String] -> Repl ()
help args = liftIO $ print $ "Help: " ++ show args

say :: [String] -> Repl ()
say args = do
  _ <- liftIO $ system $ "cowsay" ++ " " ++ (unwords args)
  return ()

Now we need only map these functions to their commands.

options :: [(String, [String] -> Repl ())]
options = [
    ("help", help)  -- :help
  , ("say", say)    -- :say
  ]

The banner function is simply an IO action that is called at the start of the shell.

ini :: Repl ()
ini = liftIO $ putStrLn "Welcome!"

Putting it all together we have a little shell.

main :: IO ()
main = evalRepl ">>> " cmd options (Word completer) ini

Putting this in a file we can test out our cow-trek shell.

$ runhaskell Main.hs
Welcome!
>>> <TAB>
kirk spock mccoy

>>> k<TAB>
kirk

>>> spam
"spam"

>>> :say Hello Haskell
 _______________
< Hello Haskell >
 ---------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

See https://github.com/sdiehl/repline for more examples.

Documentation

data HaskelineT m a

Instances

MonadTrans HaskelineT

Methods

lift :: Monad m => m a -> HaskelineT m a

MonadState s m => MonadState s (HaskelineT m)

Methods

get :: HaskelineT m s

put :: s -> HaskelineT m ()

state :: (s -> (a, s)) -> HaskelineT m a

Monad m => Monad (HaskelineT m)

Methods

(>>=) :: HaskelineT m a -> (a -> HaskelineT m b) -> HaskelineT m b

(>>) :: HaskelineT m a -> HaskelineT m b -> HaskelineT m b

return :: a -> HaskelineT m a

fail :: String -> HaskelineT m a

Functor m => Functor (HaskelineT m)

Methods

fmap :: (a -> b) -> HaskelineT m a -> HaskelineT m b

(<$) :: a -> HaskelineT m b -> HaskelineT m a

Applicative m => Applicative (HaskelineT m)

Methods

pure :: a -> HaskelineT m a

(<*>) :: HaskelineT m (a -> b) -> HaskelineT m a -> HaskelineT m b

(*>) :: HaskelineT m a -> HaskelineT m b -> HaskelineT m b

(<*) :: HaskelineT m a -> HaskelineT m b -> HaskelineT m a

MonadIO m => MonadIO (HaskelineT m)

Methods

liftIO :: IO a -> HaskelineT m a

MonadException m => MonadException (HaskelineT m)

Methods

controlIO :: (RunIO (HaskelineT m) -> IO (HaskelineT m a)) -> HaskelineT m a

runHaskelineT :: MonadException m => Settings m -> HaskelineT m a -> m a

type Cmd m = [String] -> m ()

type Options m = [(String, Cmd m)]

type WordCompleter m = String -> m [String]

type LineCompleter m = String -> String -> m [Completion]

data CompleterStyle m

Constructors

Word (WordCompleter m)

Completion function takes single word.

Word0 (WordCompleter m)

Completion function takes single word ( no space ).

Cursor (LineCompleter m)

Completion function takes tuple of full line.

File

Completion function completes files in CWD.

Prefix (CompletionFunc m) [(String, CompletionFunc m)]

Conditional tab completion based on prefix.

type Command m = String -> m ()

type CompletionFunc m = (String, String) -> m (String, [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.

wordCompleter :: Monad m => WordCompleter m -> CompletionFunc m

listCompleter :: Monad m => [String] -> CompletionFunc m

fileCompleter :: MonadIO m => CompletionFunc m

listWordCompleter :: Monad m => [String] -> WordCompleter m

runMatcher :: Monad m => [(String, CompletionFunc m)] -> CompletionFunc m -> CompletionFunc m

evalRepl

Arguments

:: MonadException m

=> String

Banner

-> Command (HaskelineT m)

Command function

-> Options (HaskelineT m)

Options list and commands

-> CompleterStyle m

Tab completion function

-> HaskelineT m a

Initializer

-> m ()

Evaluate the REPL logic into a MonadException context.

abort :: MonadIO m => HaskelineT m a

Abort the current REPL loop, and continue.

tryAction :: MonadException m => HaskelineT m a -> HaskelineT m a

Wrap a HasklineT action so that if an interrupt is thrown the shell continues as normal.

trimComplete :: String -> Completion -> Completion