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


-- | Command Line Interface
--   
--   All you need for interacting with users at the Console level
--   
--   <ul>
--   <li>Display routines, formatting, progress bars</li>
--   <li>Options parsing</li>
--   </ul>
@package cli
@version 0.1.2


-- | Displaying utilities
module Console.Display

-- | Terminal display state
data TerminalDisplay

-- | Create a new display
displayInit :: IO TerminalDisplay

-- | Display
display :: TerminalDisplay -> [OutputElem] -> IO ()

-- | A simple utility that display a <tt>msg</tt> in <tt>color</tt>
displayTextColor :: TerminalDisplay -> Color -> String -> IO ()

-- | A simple utility that display a <tt>msg</tt> in <tt>color</tt> and
--   newline at the end.
displayLn :: TerminalDisplay -> Color -> String -> IO ()

-- | Progress bar widget
data ProgressBar

-- | Create a new progress bar context
progress :: TerminalDisplay -> Int -> (ProgressBar -> IO a) -> IO a

-- | Tick an element on the progress bar
progressTick :: ProgressBar -> IO ()

-- | Summary
data Summary

-- | Create a summary
summary :: TerminalDisplay -> IO Summary

-- | Set the summary
summarySet :: Summary -> [OutputElem] -> IO ()
data Color :: *
Black :: Color
Red :: Color
Green :: Color
Yellow :: Color
Blue :: Color
Magenta :: Color
Cyan :: Color
White :: Color
ColorNumber :: Int -> Color

-- | Element to output text and attributes to the display
data OutputElem
Bg :: Color -> OutputElem
Fg :: Color -> OutputElem
T :: String -> OutputElem
LeftT :: Int -> String -> OutputElem
RightT :: Int -> String -> OutputElem
NA :: OutputElem
termText :: String -> TermOutput

-- | box a string to a specific size, choosing the justification
justify :: Justify -> Int -> String -> String

-- | Justify position
data Justify
JustifyLeft :: Justify
JustifyRight :: Justify

-- | Table widget
data Table

-- | Column for a table
data Column

-- | Create a new column setting the right default parameters
columnNew :: Int -> String -> Column

-- | Create a new table
tableCreate :: [Column] -> Table

-- | Show the table headers
tableHeaders :: TerminalDisplay -> Table -> IO ()

-- | Append a row to the table.
--   
--   if the number of elements is greater than the amount of column the
--   table has been configured with, the extra elements are dropped.
tableAppend :: TerminalDisplay -> Table -> [String] -> IO ()
instance GHC.Classes.Eq Console.Display.OutputElem
instance GHC.Show.Show Console.Display.OutputElem


-- | Options parsing using a simple DSL approach.
--   
--   Using this API, your program should have the following shape:
--   
--   <pre>
--   defaultMain $ do
--       f1 &lt;- flag ..
--       f2 &lt;- argument ..
--       action $ \toParam -&gt;
--           something (toParam f1) (toParam f2) ..
--   </pre>
--   
--   You can also define subcommand using:
--   
--   <pre>
--   defaultMain $ do
--       subcommand "foo" $ do
--          &lt;..flags &amp; parameters definitions...&gt;
--          action $ \toParam -&gt; &lt;..IO-action..&gt;
--       subcommand "bar" $ do
--          &lt;..flags &amp; parameters definitions...&gt;
--          action $ \toParam -&gt; &lt;..IO-action..&gt;
--   </pre>
--   
--   Example:
--   
--   <pre>
--   main = defaultMain $ do
--       programName "test-cli"
--       programDescription "test CLI program"
--       flagA    &lt;- flag $ FlagShort 'a' &lt;&gt; FlagLong "aaa"
--       allArgs  &lt;- remainingArguments "FILE"
--       action $ \toParam -&gt; do
--           putStrLn $ "using flag A : " ++ show (toParam flagA)
--           putStrLn $ "args: " ++ show (toParam allArgs)
--   </pre>
module Console.Options

-- | run parse options description on the action
--   
--   to be able to specify the arguments manually (e.g. pre-handling), you
--   can use <a>defaultMainWith</a>. &gt;defaultMain dsl = getArgs
--   &gt;&gt;= defaultMainWith dsl
defaultMain :: OptionDesc (IO ()) () -> IO ()

-- | same as <a>defaultMain</a>, but with the argument
defaultMainWith :: OptionDesc (IO ()) () -> [String] -> IO ()

-- | This is only useful when you want to handle all the description
--   parsing manually and need to not automatically execute any action or
--   help/error handling.
--   
--   Used for testing the parser.
parseOptions :: OptionDesc r () -> [String] -> (ProgramDesc r, OptionRes r)

-- | return value of the option parser. only needed when using
--   <a>parseOptions</a> directly
data OptionRes r
OptionSuccess :: Params -> (Action r) -> OptionRes r
OptionHelp :: OptionRes r
OptionError :: String -> OptionRes r
OptionInvalid :: String -> OptionRes r

-- | Option description Monad
data OptionDesc r a

-- | Set the program name
programName :: String -> OptionDesc r ()

-- | Set the program version
programVersion :: Version -> OptionDesc r ()

-- | Set the program description
programDescription :: String -> OptionDesc r ()

-- | Create a new sub command
command :: String -> OptionDesc r () -> OptionDesc r ()

-- | Fragment of flag definition.
--   
--   Use the monoid approach to concat flags together e.g. &gt; FlagShort
--   <tt>o</tt> &lt;&gt; FlagLong "option"
data FlagFrag

-- | short option e.g. '-a'
FlagShort :: Char -> FlagFrag

-- | long option e.g. "--aaaa"
FlagLong :: String -> FlagFrag

-- | description of this flag. | FlagDefault String
FlagDescription :: String -> FlagFrag

-- | Flag option either of the form -short or --long
--   
--   for flag that expect a value (optional or mandatory), uses
--   <tt>flagArg</tt>
flag :: FlagFrag -> OptionDesc r (Flag Bool)

-- | Flag option either of the form -short or --long
--   
--   for flag that doesn't have parameter, use <a>flag</a>
flagParam :: FlagFrag -> FlagParser a -> OptionDesc r (FlagParam a)

-- | Apply on a <a>flagParam</a> to turn into a flag that can be invoked
--   multiples, creating a list of values in the action.
flagMany :: OptionDesc r (FlagParam a) -> OptionDesc r (FlagMany a)

-- | An unnamed positional argument
--   
--   For now, argument in a point of tree that contains sub trees will be
--   ignored. TODO: record a warning or add a strict mode (for developping
--   the CLI) and error.
argument :: String -> ValueParser a -> OptionDesc r (Arg a)

-- | All the remaining position arguments
--   
--   This is useful for example for a program that takes an unbounded list
--   of files as parameters.
remainingArguments :: String -> OptionDesc r (ArgRemaining [String])

-- | Set the action to run in this command
action :: Action r -> OptionDesc r ()

-- | Set the description for a command
description :: String -> OptionDesc r ()

-- | Represent a program to run
type Action r = (forall a p. Param p => p a -> Ret p a) -> r

-- | A parser for a flag's value, either optional or required.
data FlagParser a

-- | flag value parser with a required parameter.
FlagRequired :: (ValueParser a) -> FlagParser a

-- | Optional flag value parser: Default value if not present to a
FlagOptional :: a -> (ValueParser a) -> FlagParser a

-- | Represent a boolean flag (present / not present)
data Flag a

-- | Represent a Flag that can be called multiples times and will increase
--   a counter.
data FlagLevel a

-- | Represent a Flag with an optional or required value associated
data FlagParam a

-- | Represent a Flag with optional or required value that can be added
--   multiple times
data FlagMany a

-- | A positional argument
data Arg a

-- | All the remaining positional arguments
data ArgRemaining a

-- | A dictionary of parsed flags and arguments
data Params

-- | return all the flags and their unique identifier. internal only
paramsFlags :: Params -> [(Nid, Maybe String)]

-- | get the value associated with a specific Param (either a Flag,
--   FlagParam, or an Arg)
getParams :: Param p => Params -> (forall a. p a -> Ret p a)