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


-- | Application library for building interactive console CLIs
--   
--   This module provides the tools to build a complete "structured" CLI
--   application, similar to those found in systems like Cisco IOS or
--   console configuration utilities etc. It aims to be easy for
--   implementors to use.
@package structured-cli
@version 2.4.0.0


-- | This module provides the tools to build a complete "structured" CLI
--   application, similar to those found in systems like Cisco IOS or
--   console configuration utilities etc. It aims to be easy for
--   implementors to use.
module System.Console.StructuredCLI

-- | An <a>Action</a> is returned as the result of a command handler
--   provided by the user and it instructs the CLI of any changes in the
--   CLI state
data Action

-- | The command executed is "entered" into, creating a new CLI level.
NewLevel :: Action

-- | Do not enter a new level.
NoAction :: Action

-- | Reset the CLI state up to a given number of levels.
LevelUp :: Int -> Action

-- | Go back up all the way to the top (root) of the CLI.
ToRoot :: Action
data CLIException
Exit :: CLIException
InternalError :: String -> CLIException
SyntaxError :: String -> String -> CLIException
UndecisiveInput :: String -> [String] -> CLIException
HelpRequested :: [(String, String)] -> CLIException
InvalidOperation :: String -> CLIException

-- | An alias type for the case where CommandsT wraps IO only (i.e. no
--   state, etc)
type Commands = CommandsT IO

-- | The <a>CommandsT</a> transformer monad is the key to building a CLI
--   tree. It is meant to be used as a transformer wrapping an application
--   specific "user" monad (for example, a <a>State</a> monad encapsulating
--   application state). This monad is executed _once_ upon calling
--   <a>runCLI</a> to build the command tree. Keep in mind however that any
--   parsers or actions used in any given command all run in the "user"
--   monad and unlike the process of building the command tree, they will
--   be called multiple times as the user navigates the CLI at runtime.
--   Each <a>CommandsT</a> monadic action corresponds to a single "node"
--   (a.k.a. command) in the CLI. Succesive actions simply add commands to
--   the current "level". It is possible to "nest" a new level to a command
--   by using the '(&gt;+)' operator. When properly indented (see example
--   code above) it provides a pretty self explanatory way to build the CLI
--   tree.
data CommandsT m a
type Handler m a = a -> m Action

-- | The <a>Node</a> type contains the internal representation of a
--   command. Normally there is no need to be concerned with it other than
--   perhaps passing it opaquely to any utility parsers (like
--   <a>labelParser</a> for example), when writing a custom parser
data Node m
type Parser m a = Node m -> String -> m (ParseResult a)

-- | There is no need to concern oneself with the <a>ParseResult</a> type
--   unless one is writing a custom parser, which should actually be rarer
--   than not.
data ParseResult a
Done :: a -> String -> String -> ParseResult a

-- | Output string to be fed to the command action handler
[getOutput] :: ParseResult a -> a

-- | Part of the string matched during parsing of a command
[getDoneMatched] :: ParseResult a -> String

-- | Remaining input data
[getDoneRemaining] :: ParseResult a -> String
Partial :: [(String, String)] -> String -> ParseResult a

-- | List of possible completions along with a corresponding help string
[getPartialHints] :: ParseResult a -> [(String, String)]

-- | Remaining input data
[getPartialRemaining] :: ParseResult a -> String
Fail :: String -> String -> ParseResult a

-- | A message string containing a possible hint for correct useage
[getFailMessage] :: ParseResult a -> String

-- | Remaining input data
[getFailRemaining] :: ParseResult a -> String

-- | Parsing provided input doesnt match this command. The difference
--   between <a>Fail</a> and <a>NoMatch</a> is a fine but important one.
--   Failure should be used for example when a command keyword is correct
--   but a required parameter is invalid or contains an error for example.
--   A <a>NoMatch</a> should be exclusively used when a command keyword
--   does not correspond to the given input
NoMatch :: ParseResult a
data Settings m

-- | CLI Settings provided upon launching the CLI. It is recommended to
--   modify the settings provided by the <a>Default</a> instance: i.e: <tt>
--   def { getBanner = "My CLI" } </tt> that way you can use for example
--   the default exception handler which should suit usual needs, etc.
Settings :: Maybe FilePath -> String -> m String -> Bool -> ExceptionHandler m -> Settings m

-- | An optional filename to activate and store the CLI command history
--   function
[getHistory] :: Settings m -> Maybe FilePath

-- | Text to display upon start of the CLI application
[getBanner] :: Settings m -> String

-- | Prompt characters to display to the right of the current command
--   "stack"
[getPrompt] :: Settings m -> m String

-- | Disable prompt for use with batch scripts
[isBatch] :: Settings m -> Bool

-- | Exception handler
[handleException] :: Settings m -> ExceptionHandler m

-- | A <a>Validator</a> is a function to which a parsed string is given in
--   order to perform any checks for validity that may be applicable, or
--   even transforming the argument if necessary. Note that the validator
--   runs in the "user" monad
type Validator m a = String -> m (Maybe a)

-- | the CommandsT "nest" operation. It adds a new deeper CLI level to the
--   command on the left side with the commands on the right side, for
--   example: <tt> activate &gt;+ do foo bar baz </tt> Would result in the
--   following CLI command structure:
--   
--   <pre>
--   &gt;&gt;&gt; &gt; activate
--   
--   &gt;&gt;&gt; activate &gt; ?
--   
--   &gt;&gt;&gt; - foo ..
--   
--   &gt;&gt;&gt; - bar ..
--   
--   &gt;&gt;&gt; - baz ..
--   </pre>
(>+) :: Monad m => CommandsT m () -> CommandsT m () -> CommandsT m ()

-- | Build a command node that is always active and takes no parameters
command :: Monad m => String -> String -> m Action -> CommandsT m ()

-- | A variation of <a>command</a> that allows for "disabling" the command
--   at runtime by running the given "enable" monadic action (as always in
--   the "user" monad) to check if the command should be displayed as an
--   option and/or accepted or not.
command' :: Monad m => String -> String -> m Bool -> m Action -> CommandsT m ()

-- | Create a command using a custom parser, providing thus complete
--   flexibility
custom :: Monad m => String -> String -> Parser m a -> m Bool -> Handler m a -> CommandsT m ()

-- | A utility action to "leave" the current CLI level. Equivalent to
--   <tt>return $ LevelUp 1</tt>
exit :: Monad m => m Action
isCompleted :: Monad m => SearchResult m -> Bool
isIncomplete :: Monad m => SearchResult m -> Bool
isNoResult :: Monad m => SearchResult m -> Bool
isFailed :: Monad m => SearchResult m -> Bool

-- | A utility parser that reads an input and parses a command label. It
--   can be used as part of custom parsers to first read the command
--   keyword before parsing any arguments etc.
labelParser :: Monad m => Node m -> String -> m (ParseResult String)

-- | A utility action to "nest" into a new CLI level. Equivalent to
--   <tt>return NewLevel</tt>
newLevel :: Monad m => m Action

-- | A utility action to leave the current CLI level untouched. Equivalent
--   to <tt>return NoAction</tt>
noAction :: Monad m => m Action

-- | Build a command node that takes one parameter (delimited by space).
--   The parsed parameter is fed to the validator monadic function (in the
--   "user" monad) and the resulting string if any is fed in turn as an
--   argument to the handler action (also in the "user" monad).
param :: Monad m => String -> String -> Validator m a -> Handler m a -> CommandsT m ()

-- | A variation of <a>param</a> that allows for "disabling" the command at
--   runtime by running the given "enable" monadic action (as always in the
--   "user" monad) to check if the command should be displayed as an option
--   and/or accepted or not.
param' :: Monad m => String -> String -> Validator m a -> m Bool -> Handler m a -> CommandsT m ()

-- | Launches the CLI application. It doesn't normally return unless an
--   exception is thrown or if it runs out of input in batch mode. Normal
--   return value is that returned by the CommandsT action that built the
--   tree. Remember that <a>Settings</a> is an instance of <a>Default</a>
runCLI :: MonadException m => String -> Settings m -> CommandsT m a -> m (Either CLIException a)

-- | A utility action to reset the CLI tree to the root node . Equivalent
--   to <tt>return ToRoot</tt>
top :: Monad m => m Action
instance GHC.Show.Show System.Console.StructuredCLI.CLIException
instance GHC.Show.Show a => GHC.Show.Show (System.Console.StructuredCLI.ParseResult a)
instance GHC.Show.Show System.Console.StructuredCLI.Action
instance GHC.Base.Functor f => GHC.Base.Functor (System.Console.StructuredCLI.CommandsT f)
instance GHC.Base.Applicative a => GHC.Base.Applicative (System.Console.StructuredCLI.CommandsT a)
instance GHC.Base.Monad m => GHC.Base.Monad (System.Console.StructuredCLI.CommandsT m)
instance Control.Monad.Trans.Class.MonadTrans System.Console.StructuredCLI.CommandsT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (System.Console.StructuredCLI.CommandsT m)
instance Control.Monad.IO.Class.MonadIO m => Data.Default.Class.Default (System.Console.StructuredCLI.Settings m)
instance GHC.Base.Monad m => Data.Default.Class.Default (System.Console.StructuredCLI.Parser m GHC.Base.String)
instance GHC.Base.Monad m => Data.Default.Class.Default (System.Console.StructuredCLI.Validator m GHC.Base.String)