repline-0.2.1.0: Haskeline wrapper for GHCi-like REPL interfaces.

Safe Haskell | None
Language | Haskell2010

System.Console.Repline

Description

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 prefix character is entered.
- Command prefix character: Optional command prefix ( passing Nothing ignores the Options argument ).
- 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 (pure ">>> ") cmd options (Just ':') (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.

Synopsis

- data 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
  - = Word (WordCompleter m)
  - | Word0 (WordCompleter m)
  - | Cursor (LineCompleter m)
  - | File
  - | Prefix (CompletionFunc m) [(String, CompletionFunc m)]
- type Command m = String -> m ()
- type CompletionFunc (m :: Type -> Type) = (String, String) -> m (String, [Completion])
- 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 :: (Functor m, MonadException m) => HaskelineT m String -> Command (HaskelineT m) -> Options (HaskelineT m) -> Maybe Char -> CompleterStyle m -> HaskelineT m a -> m ()
- abort :: MonadIO m => HaskelineT m a
- tryAction :: MonadException m => HaskelineT m a -> HaskelineT m a
- dontCrash :: (MonadIO m, MonadException m) => m () -> m ()
- trimComplete :: String -> Completion -> Completion

# Documentation

data HaskelineT (m :: * -> *) a Source #

Instances

MonadTrans HaskelineT Source # |
Instance details Defined in System.Console.Repline Methods lift :: Monad m => m a -> HaskelineT m a Source #
MonadState s m => MonadState s (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods get :: HaskelineT m s Source # put :: s -> HaskelineT m () Source # state :: (s -> (a, s)) -> HaskelineT m a Source #
MonadReader r m => MonadReader r (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods ask :: HaskelineT m r Source # local :: (r -> r) -> HaskelineT m a -> HaskelineT m a Source # reader :: (r -> a) -> HaskelineT m a Source #
Monad m => Monad (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods (>>=) :: HaskelineT m a -> (a -> HaskelineT m b) -> HaskelineT m b Source # (>>) :: HaskelineT m a -> HaskelineT m b -> HaskelineT m b Source # return :: a -> HaskelineT m a Source # fail :: String -> HaskelineT m a Source #
Functor m => Functor (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods fmap :: (a -> b) -> HaskelineT m a -> HaskelineT m b Source # (<$) :: a -> HaskelineT m b -> HaskelineT m a Source #
MonadFail m => MonadFail (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods fail :: String -> HaskelineT m a Source #
Applicative m => Applicative (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods pure :: a -> HaskelineT m a Source # (<*>) :: HaskelineT m (a -> b) -> HaskelineT m a -> HaskelineT m b Source # liftA2 :: (a -> b -> c) -> HaskelineT m a -> HaskelineT m b -> HaskelineT m c Source # (*>) :: HaskelineT m a -> HaskelineT m b -> HaskelineT m b Source # (<*) :: HaskelineT m a -> HaskelineT m b -> HaskelineT m a Source #
MonadIO m => MonadIO (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods liftIO :: IO a -> HaskelineT m a Source #
MonadException m => MonadException (HaskelineT m) Source # |
Instance details Defined in System.Console.Repline Methods controlIO :: (RunIO (HaskelineT m) -> IO (HaskelineT m a)) -> HaskelineT m a Source #

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

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

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

type WordCompleter m = String -> m [String] Source #

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

data CompleterStyle m Source #

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

type CompletionFunc (m :: Type -> Type) = (String, String) -> m (String, [Completion]) Source #

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

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

fileCompleter :: MonadIO m => CompletionFunc m Source #

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

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

evalRepl Source #

Arguments

:: (Functor m, MonadException m) |
=> HaskelineT m String | Banner
-> Command (HaskelineT m) | Command function
-> Options (HaskelineT m) | Options list and commands
-> Maybe Char | Optional command prefix ( passing Nothing ignores the Options argument )
-> CompleterStyle m | Tab completion function
-> HaskelineT m a | Initializer
-> m () |

Evaluate the REPL logic into a MonadException context.

abort :: MonadIO m => HaskelineT m a Source #

Abort the current REPL loop, and continue.

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

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

dontCrash :: (MonadIO m, MonadException m) => m () -> m () Source #

Catch all toplevel failures.

trimComplete :: String -> Completion -> Completion Source #