-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Toolkit for quickly whipping up command-line interfaces.
--   
--   A simple toolkit for quickly whipping up REPLs, input validation and
--   sets of commands included.
@package repl-toolkit
@version 0.1.0.0


-- | Helper functions relating to State.
module System.REPL.State

-- | Extracts a result from the current state. Defined as <tt>get1 f =
--   liftM f get</tt>.
get1 :: Monad m => (s -> a) -> StateT s m a

-- | Extracts two results from the current state.
get2 :: Monad m => (s -> a) -> (s -> b) -> StateT s m (a, b)

-- | Extracts three results from the current state.
get3 :: Monad m => (s -> a) -> (s -> b) -> (s -> c) -> StateT s m (a, b, c)

-- | Extracts four results from the current state.
get4 :: Monad m => (s -> a) -> (s -> b) -> (s -> c) -> (s -> d) -> StateT s m (a, b, c, d)

-- | Extracts five results from the current state.
get5 :: Monad m => (s -> a) -> (s -> b) -> (s -> c) -> (s -> d) -> (s -> e) -> StateT s m (a, b, c, d, e)

-- | Extracts six results from the current state.
get6 :: Monad m => (s -> a) -> (s -> b) -> (s -> c) -> (s -> d) -> (s -> e) -> (s -> f) -> StateT s m (a, b, c, d, e, f)

-- | Extracts seven results from the current state.
get7 :: Monad m => (s -> a) -> (s -> b) -> (s -> c) -> (s -> d) -> (s -> e) -> (s -> f) -> (s -> g) -> StateT s m (a, b, c, d, e, f, g)

-- | Extracts eight results from the current state.
get8 :: Monad m => (s -> a) -> (s -> b) -> (s -> c) -> (s -> d) -> (s -> e) -> (s -> f) -> (s -> g) -> (s -> h) -> StateT s m (a, b, c, d, e, f, g, h)


-- | Functions to expedite the building of REPLs.
module System.REPL

-- | Prints a string to stderr.
putErr :: ListLikeIO full item => full -> IO ()

-- | Prints a string, followed by a newline character, to stderr.
putErrLn :: ListLikeIO full item => full -> IO ()

-- | The description of an 'ask for user input'-action. The type parameters
--   are the used monad (typically <tt>IO</tt>), the type of the read value
--   and the type of the error that is thrown in case of failures.
data Asker m a
Asker :: Text -> (Text -> Either Text a) -> (a -> m (Either Text Success)) -> Asker m a

-- | The prompt to be displayed to the user.
askerPrompt :: Asker m a -> Text

-- | The parser for the input value, which either delivers a value of type
--   <tt>a</tt> or an error message.
askerParser :: Asker m a -> Text -> Either Text a

-- | The predicate which the input, once read, must fulfill. It either
--   delivers <a>Success</a> or an error message.
askerPredicate :: Asker m a -> a -> m (Either Text Success)

-- | Singleton type representing success.
data Success
Success :: Success

-- | Represents a failure of an ask function. It can either be a type
--   failure (failure to interpret the user input as a value of the
--   required type) or a predicate failure (the user input could be
--   interpreter as a value of the required type, but it failed some
--   user-supplied test).
data AskFailure

-- | Indicates that the parsing as the required type failed.
TypeFailure :: Text -> AskFailure

-- | Indiciates that the parsed value failed a predicate.
PredicateFailure :: Text -> AskFailure

-- | Indicates that an incorrect number of parameters was passed.
ParamFailure :: Text -> AskFailure

-- | Indicates that no action was appropriate to the given input.
NothingFoundFailure :: AskFailure

-- | Creates a general <a>Asker</a> with <a>readMaybe</a> as its parser.
--   This suffices for most simple values. The main drawback of using
--   <a>readMaybe</a> is that the input <a>Text</a> is unpacked into a
--   String, which incurs a performance hit. For short (one-line) input.
--   this isn't important, but if large ones are expected, it's better to
--   pass a custom, <a>Text</a>-compatible parsing function, such as a
--   parsec-parser.
asker :: (Monad m, Functor m, Read a) => Text -> Text -> Text -> (a -> m Bool) -> Asker m a

-- | Creates an <a>Asker</a> which just cares about the type of the input.
typeAsker :: (Monad m, Functor m, Read a) => Text -> Text -> Asker m a

-- | Creates an <a>Asker</a> which takes its input verbatim as <a>Text</a>.
predAsker :: (Monad m, Functor m) => Text -> Text -> (Text -> m Bool) -> Asker m Verbatim

-- | An asker which asks for an optional value. If only whitespace is
--   entered (according to <a>isSpace</a>), it returns <a>Nothing</a>
--   without further parsing or checking; otherwise, it behaves identically
--   to <a>asker</a>.
maybeAsker :: (Monad m, Functor m, Read a) => Text -> Text -> Text -> (a -> m Bool) -> Asker m (Maybe a)

-- | Prints <tt>&gt; </tt> and asks the user to input a line.
prompt :: (MonadIO m, Functor m, ListLikeIO full item) => m full

-- | Prints its first argument and, in the same line, asks the user to
--   input a line.
prompt' :: (MonadIO m, Functor m, ListLikeIO full item, ListLikeIO full' item') => full -> m full'

-- | A verbatim Text whose Read instance simply returns the read string,
--   as-is. This is useful for askers which ask for strings without quotes.
newtype Verbatim
Verbatim :: Text -> Verbatim

-- | Extracts a <tt>Verbatim'</tt>s <a>Text</a>.
fromVerbatim :: Verbatim -> Text

-- | Executes an <a>Asker</a>. If the Text argument is Nothing, the user is
--   asked to enter a line on stdin. If it is <tt>Just x</tt>, <tt>x</tt>
--   is taken to be input. If the input is of the wrong type, an
--   error-message is printed and the user is asked again. In addition to
--   the condition that the input must be of the correct type, it must also
--   fulfill a predicate.
--   
--   Since the predicate is of monadic, arbitrarily complex tests can be
--   performed: checking whether an item is in a database, whether a date
--   was less than x years ago, etc.
ask :: (MonadIO m, MonadError SomeException m, Functor m, Read a) => Asker m a -> Maybe Text -> m a

-- | See <a>ask</a>. Always reads the input from stdin. <tt>ask' a = ask a
--   Nothing</tt>.
ask' :: (MonadIO m, MonadError SomeException m, Functor m, Read a) => Asker m a -> m a

-- | Repeatedly executes an ask action until the user enters a valid value.
--   Error messages are printed each time.
untilValid :: (MonadIO m, MonadError SomeException m, Functor m, Read a) => m a -> m a
instance Typeable AskFailure
instance Eq Success
instance Show Success
instance Read Success
instance Eq AskFailure
instance Read Verbatim
instance Show AskFailure
instance Exception AskFailure


-- | 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.
module System.REPL.Command

-- | A REPL command, possibly with parameters.
data Command m a
Command :: Text -> (Text -> Bool) -> Text -> Maybe Int -> (Text -> m a) -> Command m a

-- | The short name of the command. Purely informative.
commandName :: Command m a -> Text

-- | Returns whether a string matches a command name. The simplest form is
--   <tt>s==</tt> for some string s, but more liberal matchings are
--   possible.
commandTest :: Command m a -> Text -> Bool

-- | A description of the command.
commandDesc :: Command m a -> Text

-- | The number of parameters, if fixed.
numParameters :: Command m a -> Maybe Int

-- | Runs the command with the input text as parameter.
runCommand :: Command m a -> Text -> m a

-- | Prints information (the command name, description and, if given, the
--   number of parameters) about a command to the console.
commandInfo :: MonadIO m => Command m a -> m ()

-- | Takes a line of text and a command. If the text matches the given
--   command's <a>commandTest</a>, the command is run with it. If not,
--   <a>Nothing</a> is returned.
runOnce :: MonadIO m => Text -> Command m a -> m (Maybe a)

-- | Takes an input and tries to run it against a list of commands, trying
--   the out in sequence. The first command whose <a>commandTest</a>
--   returns True is executed. If none of the commands match,
--   <tt>NothingFoundFailure</tt> is thrown.
commandDispatch :: (MonadIO m, MonadError SomeException m, Functor m) => Text -> [Command m z] -> m z

-- | Prints out a list of command names, with their descriptions.
summarizeCommands :: MonadIO m => [Command m2 z] -> m ()

-- | 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 <tt>stringLiteral</tt>
--   (haskell-style), meaning that escape sequences and unicode characters
--   are handled automatically.
readArgs :: Text -> Either Text [Text]

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

-- | Creates a command without parameters.
makeCommand :: (MonadIO m, MonadError SomeException m, Functor m) => Text -> (Text -> Bool) -> Text -> (Text -> m a) -> Command m a

-- | Creates a command with one parameter.
makeCommand1 :: (MonadIO m, MonadError SomeException m, Functor m, Read a) => Text -> (Text -> Bool) -> Text -> Asker m a -> (Text -> a -> m z) -> Command m z

-- | Creates a command with two parameters.
makeCommand2 :: (MonadIO m, MonadError SomeException m, Functor m, Read a, Read b) => Text -> (Text -> Bool) -> Text -> Asker m a -> Asker m b -> (Text -> a -> b -> m z) -> Command m z

-- | Creates a command with three parameters.
makeCommand3 :: (MonadIO m, MonadError SomeException m, Functor m, Read a, Read b, Read c) => Text -> (Text -> Bool) -> Text -> Asker m a -> Asker m b -> Asker m c -> (Text -> a -> b -> c -> m z) -> Command m z

-- | Creates a command with four parameters.
makeCommand4 :: (MonadIO m, MonadError SomeException m, Functor m, Read a, Read b, Read c, Read d) => Text -> (Text -> Bool) -> Text -> Asker m a -> Asker m b -> Asker m c -> Asker m d -> (Text -> a -> b -> c -> d -> m z) -> Command m z

-- | Creates a command with five parameters.
makeCommand5 :: (MonadIO m, MonadError SomeException m, Functor m, Read a, Read b, Read c, Read d, Read e) => Text -> (Text -> Bool) -> Text -> Asker m a -> Asker m b -> Asker m c -> Asker m d -> Asker m e -> (Text -> a -> b -> c -> d -> e -> m z) -> Command m z

-- | Creates a command with four parameters.
makeCommand6 :: (MonadIO m, MonadError SomeException m, Functor m, Read a, Read b, Read c, Read d, Read e, Read f) => Text -> (Text -> Bool) -> Text -> Asker m a -> Asker m b -> Asker m c -> Asker m d -> Asker m e -> Asker m f -> (Text -> a -> b -> c -> d -> e -> f -> m z) -> Command m z

-- | Creates a command with a list of parameters. The first list
--   <tt>necc</tt> of <a>Asker</a>s indicates the necessary parameters; the
--   user must at least provide this many. The second list <tt>opt</tt>
--   contains <a>Asker</a>s for additional, optional parameters, and may be
--   infinite. If the number of passed parameters exceeds <tt>length necc +
--   length opt</tt>, or if any <a>Asker</a> fails, the command returns an
--   <a>AskFailure</a>.
makeCommandN :: (MonadIO m, MonadError SomeException m, Functor m, Read a) => Text -> (Text -> Bool) -> Text -> [Asker m a] -> [Asker m a] -> (Text -> [a] -> m z) -> Command m z
instance Typeable ParamNumError
instance Enum ParamNumError
instance Show ParamNumError
instance Eq ParamNumError
instance Read ParamNumError
instance Ord ParamNumError
instance Functor m => Functor (Command m)