System.REPL.Command

Provides Commands for REPLs. Commands take care of input and parameter-handling, and allow parameters to be supplied in the same line as the command's name (e.g. ":cmd param1 param2" on stdin). Provided parameters can be parsed and checked (say, against databases) before they are passed to the actual command function. They are relatively large units of abstraction, but they allow the easy creation of relatively sophisticated command loops, and have the advantage that one doesn't need to fiddle around with input handling in the middle of the actual command code.

Command dispatch

Using the Command class is not necessary, but it makes dealing with user input considerably easier. When a command is run with a line of input, it automatically segments it by whitespace, tries to interpret each part as one of its arguments and passes them to the actual command function. If any arguments haven't been supplies, it asks for them on stdin. If too many arguments have been supplied, or if any argument' parsing returns an error, the command is aborted.

Example:

cd = makeCommand1 ...

>>> :cd ../
Directory changed!
>>> :cd
Enter new directory:
>>> ../
Directory changed!

data Command m a

A REPL command, possibly with parameters.

Constructors

Command

Fields

commandName :: Text

The short name of the command. Purely informative.

commandTest :: Text -> Bool

Returns whether a string matches a command name. The simplest form is s== for some string s, but more liberal matchings are possible.

commandDesc :: Text

A description of the command.

numParameters :: Maybe Int

The number of parameters, if fixed.

runCommand :: Text -> m a

Runs the command with the input text as parameter.

Instances

Functor m => Functor (Command m)

commandInfo :: MonadIO m => Command m a -> m ()

Prints information (the command name, description and, if given, the number of parameters) about a command to the console.

runOnce :: MonadIO m => Text -> Command m a -> m (Maybe a)

Takes a line of text and a command. If the text matches the given command's commandTest, the command is run with it. If not, Nothing is returned.

commandDispatch

Arguments

:: (MonadIO m, MonadCatch m, Functor m)

=> Text

The user's input.

-> [Command m z]

The command library.

-> m z

Takes an input and tries to run it against a list of commands, trying the out in sequence. The first command whose commandTest returns True is executed. If none of the commands match, NothingFoundFailure is thrown.

summarizeCommands :: MonadIO m => [Command m2 z] -> m ()

Prints out a list of command names, with their descriptions.

readArgs :: Text -> Either Text [Text]

Splits and trims the input of a command. Any non-whitespace sequence of characters is interpreted as one argument, unless double quotes (") are used, in which case they demarcate an argument. Each argument is parsed as a haskell string literal (quote-less arguments have quotes inserted around them). If the number of quotes in the input is not even, the operating will fail.

Arguments are parsed using parsec's stringLiteral (haskell-style), meaning that escape sequences and unicode characters are handled automatically.

quoteArg :: Text -> Text

Surrounds an argument in quote marks, if necessary. This is useful when arguments were extracted via readArgs, which deletes quote marks. Quotes are placed around the input iff it doesn't begin with a quote mark ("). readArgs and quoteArg are inverse up to suitable isomorphism, i.e. if 'readArgs orig = (Right res)', then it holds that readArgs orig = readArgs $ intercalate " " $ map quoteArg res

Making commands.

makeCommand

Arguments

:: (MonadIO m, MonadCatch m, Functor m)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description.

-> (Text -> m a)

The actual command.

-> Command m a

Creates a command without parameters.

makeCommand1

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> Asker m a

Asker for the first parameter.

-> (Text -> a -> m z)

-> Command m z

Creates a command with one parameter.

makeCommand2

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a, Read b)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> Asker m a

Asker for the first parameter.

-> Asker m b

Asker for the second perameter.

-> (Text -> a -> b -> m z)

-> Command m z

Creates a command with two parameters.

makeCommand3

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a, Read b, Read c)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> Asker m a

Asker for the first parameter.

-> Asker m b

Asker for the second perameter.

-> Asker m c

Asker for the third parameter.

-> (Text -> a -> b -> c -> m z)

-> Command m z

Creates a command with three parameters.

makeCommand4

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a, Read b, Read c, Read d)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> Asker m a

Asker for the first parameter.

-> Asker m b

Asker for the second perameter.

-> Asker m c

Asker for the third parameter.

-> Asker m d

Asker for the fourth parameter.

-> (Text -> a -> b -> c -> d -> m z)

-> Command m z

Creates a command with four parameters.

makeCommand5

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a, Read b, Read c, Read d, Read e)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> Asker m a

Asker for the first parameter.

-> Asker m b

Asker for the second perameter.

-> Asker m c

Asker for the third parameter.

-> Asker m d

Asker for the fourth parameter.

-> Asker m e

Asker for the fifth parameter.

-> (Text -> a -> b -> c -> d -> e -> m z)

-> Command m z

Creates a command with five parameters.

makeCommand6

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a, Read b, Read c, Read d, Read e, Read f)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> Asker m a

Asker for the first parameter.

-> Asker m b

Asker for the second perameter.

-> Asker m c

Asker for the third parameter.

-> Asker m d

Asker for the fourth parameter.

-> Asker m e

Asker for the fifth parameter.

-> Asker m f

Asker for the sixth parameter.

-> (Text -> a -> b -> c -> d -> e -> f -> m z)

-> Command m z

Creates a command with four parameters.

makeCommandN

Arguments

:: (MonadIO m, MonadCatch m, Functor m, Read a)

=> Text

Command name.

-> (Text -> Bool)

Command test.

-> Text

Command description

-> [Asker m a]

Askers for the necessary parameters.

-> [Asker m a]

Askers for the optional parameters.

-> (Text -> [a] -> m z)

-> Command m z

Creates a command with a list of parameters. The first list necc of Askers indicates the necessary parameters; the user must at least provide this many. The second list opt contains Askers for additional, optional parameters, and may be infinite. If the number of passed parameters exceeds length necc + length opt, or if any Asker fails, the command returns an AskFailure.