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


-- | CLI
--   
--   please see README.md
@package cli
@version 0.2.0


-- | 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 -> ColorComponent -> String -> IO ()

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

-- | A progress bar widget created and used within the <a>progress</a>
--   function.
data ProgressBar

-- | Create a new progress bar context from a terminal display, a number of
--   items, and a progress update function.
--   
--   The progress bar update function should perform the desired actions on
--   each of the items, and call <a>progressTick</a> whenever an item is
--   fully processed.
--   
--   Each time the given update function calls progressTick the progress
--   bar fills by one item until the given number of items is matched. Once
--   the bar is filled it will not fill any further even if progressTick is
--   called again.
--   
--   The progress bar will disappear when the given update function
--   completes running, even if the progress bar is not yet entirely
--   filled.
--   
--   For example, the following function will create a progress bar of 100
--   items, and complete one of the items every tenth of a second. Once all
--   of the items are completed the progress bar is removed and a
--   completion String is returned.
--   
--   <pre>
--   runProgressBar :: IO String
--   runProgressBar = do
--       terminalDisplay &lt;- displayInit
--       progress terminalDisplay 100 (progressFunction 100)
--     where
--       progressFunction :: Int -&gt; ProgressBar -&gt; IO String
--       progressFunction 0 _   = return "Completed!"
--       progressFunction n bar = do
--         threadDelay 100000
--         progressTick bar
--         progressFunction (n - 1) bar
--   </pre>
progress :: TerminalDisplay -> Int -> (ProgressBar -> IO a) -> IO a

-- | Ticks an element on the given progress bar. Should be used within a
--   progress bar update function that is passed into <a>progress</a>.
--   
--   <pre>
--   progressFunction :: ProgressBar -&gt; IO String
--   progressFunction bar = do
--     threadDelay 100000
--     progressTick bar
--     threadDelay 200000
--     progressTick bar
--     return "Completed!"
--   </pre>
progressTick :: ProgressBar -> IO ()

-- | Summary
data Summary

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

-- | Set the summary
summarySet :: Summary -> [OutputElem] -> IO ()

-- | Simple color component on 8 color terminal (maximum compatibility)
type ColorComponent = Zn64 8

-- | Element to output text and attributes to the display
data OutputElem
Bg :: ColorComponent -> OutputElem
Fg :: ColorComponent -> OutputElem
T :: String -> OutputElem

-- | Left-aligned text
LeftT :: CountOf Char -> String -> OutputElem

-- | Right-aligned text
RightT :: CountOf Char -> String -> OutputElem

-- | Centered text
CenterT :: CountOf Char -> String -> OutputElem

-- | Justified text
JustifiedT :: CountOf Char -> String -> OutputElem
NA :: OutputElem
termText :: String -> String

-- | Boxes a string to a given size using the given justification.
--   
--   If the size of the given string is greater than or equal to the given
--   boxing size, then the original string is returned.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; justify JustifyRight 35 "Lorem ipsum dolor sit amet"
--   "Lorem ipsum dolor sit amet         "
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; justify JustifyLeft 35 "Lorem ipsum dolor sit amet"
--   "         Lorem ipsum dolor sit amet"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; justify JustifyCenter 35 "Lorem ipsum dolor sit amet"
--   "    Lorem ipsum dolor sit amet     "
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; justify JustifyJustified 35 "Lorem ipsum dolor sit amet"
--   "Lorem    ipsum   dolor   sit   amet"
--   </pre>
--   
--   Apply a justified justification to a one word string, resulting in a
--   string of the given length with the word at the left followed by the
--   remaining space.
--   
--   <pre>
--   &gt;&gt;&gt; justify JustifyJustified 10 "Hello."
--   "Hello.    "
--   </pre>
--   
--   Attempt to box a string that is larger than the given box, yielding
--   the original string.
--   
--   <pre>
--   &gt;&gt;&gt; justify JustifyRight 5 "Hello, World!"
--   "Hello, World!"
--   </pre>
justify :: Justify -> CountOf Char -> String -> String

-- | A justification of text.
data Justify

-- | Left align text
JustifyLeft :: Justify

-- | Right align text
JustifyRight :: Justify

-- | Center text
JustifyCenter :: Justify

-- | Text fills the whole line width
JustifyJustified :: Justify

-- | Table widget
data Table

-- | Column for a table
data Column

-- | Create a new column setting the right default parameters
columnNew :: CountOf Char -> 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
--   
--   default is the result of base's <a>getProgName</a>
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
--   <a>flagArg</a>
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 value. In case parsing failed Left should be returned.
type ValueParser a = String -> Either String a

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