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


-- | Chops a command or program invocation into digestable pieces.
--   
--   See the <a>README</a> (it is properly formatted on github).
@package butcher
@version 1.3.3.2


-- | Flags are arguments to your current command that are prefixed with "-"
--   or "--", for example "-v" or "--verbose". These flags can have zero or
--   one argument. (Butcher internally has more general concept of
--   <a>CmdPart</a> that could handle any number of arguments, so take this
--   as what this module aims to provide, not what you could theoretically
--   implement on top of butcher).
module UI.Butcher.Monadic.Flag

-- | flag-description monoid. You probably won't need to use the
--   constructor; mzero or any (&lt;&gt;) of flag(Help|Default) works well.
data Flag p
Flag :: Maybe Doc -> Maybe p -> Visibility -> Flag p
[_flag_help] :: Flag p -> Maybe Doc
[_flag_default] :: Flag p -> Maybe p
[_flag_visibility] :: Flag p -> Visibility

-- | Create a <a>Flag</a> with just a help text.
flagHelp :: Doc -> Flag p

-- | Create a <a>Flag</a> with just a help text.
flagHelpStr :: String -> Flag p

-- | Create a <a>Flag</a> with just a default value.
flagDefault :: p -> Flag p

-- | Create a <a>Flag</a> marked as hidden. Similar to hidden commands,
--   hidden flags will not included in pretty-printing (help, usage etc.)
--   
--   This feature is not well tested yet.
flagHidden :: Flag p

-- | A no-parameter flag where non-occurence means False, occurence means
--   True.
addSimpleBoolFlag :: Applicative f => String -> [String] -> Flag Void -> CmdParser f out Bool

-- | A no-parameter flag that can occur multiple times. Returns the number
--   of occurences (0 or more).
addSimpleCountFlag :: Applicative f => String -> [String] -> Flag Void -> CmdParser f out Int

-- | Applicative-enabled version of <tt>addSimpleFlag</tt>
addSimpleFlagA :: String -> [String] -> Flag Void -> f () -> CmdParser f out ()

-- | One-argument flag, where the argument is parsed via its Read instance.
addFlagReadParam :: forall f p out. (Applicative f, Typeable p, Read p, Show p) => String -> [String] -> String -> Flag p -> CmdParser f out p

-- | One-argument flag, where the argument is parsed via its Read instance.
--   This version can accumulate multiple values by using the same flag
--   with different arguments multiple times.
--   
--   E.g. "--foo 3 --foo 5" yields [3,5].
addFlagReadParams :: forall f p out. (Applicative f, Typeable p, Read p, Show p) => String -> [String] -> String -> Flag p -> CmdParser f out [p]

-- | One-argument flag where the argument can be an arbitrary string.
addFlagStringParam :: forall f out. Applicative f => String -> [String] -> String -> Flag String -> CmdParser f out String

-- | One-argument flag where the argument can be an arbitrary string. This
--   version can accumulate multiple values by using the same flag with
--   different arguments multiple times.
--   
--   E.g. "--foo abc --foo def" yields ["abc", "def"].
addFlagStringParams :: forall f out. Applicative f => String -> [String] -> String -> Flag Void -> CmdParser f out [String]
instance GHC.Base.MonadPlus UI.Butcher.Monadic.Flag.InpParseString
instance GHC.Base.Alternative UI.Butcher.Monadic.Flag.InpParseString
instance Control.Monad.State.Class.MonadState GHC.Base.String UI.Butcher.Monadic.Flag.InpParseString
instance GHC.Base.Monad UI.Butcher.Monadic.Flag.InpParseString
instance GHC.Base.Applicative UI.Butcher.Monadic.Flag.InpParseString
instance GHC.Base.Functor UI.Butcher.Monadic.Flag.InpParseString
instance GHC.Base.Semigroup (UI.Butcher.Monadic.Flag.Flag p)
instance GHC.Base.Monoid (UI.Butcher.Monadic.Flag.Flag p)


-- | Parameters are arguments of your current command that are not prefixed
--   by some flag. Typical commandline interface is something like "PROGRAM
--   [FLAGS] INPUT". Here, FLAGS are Flags in butcher, and INPUT is a
--   Param, in this case a String representing a path, for example.
module UI.Butcher.Monadic.Param

-- | param-description monoid. You probably won't need to use the
--   constructor; mzero or any (&lt;&gt;) of param(Help|Default|Suggestion)
--   works well.
data Param p
Param :: Maybe p -> Maybe Doc -> Maybe [CompletionItem] -> Param p
[_param_default] :: Param p -> Maybe p
[_param_help] :: Param p -> Maybe Doc
[_param_suggestions] :: Param p -> Maybe [CompletionItem]

-- | Create a <a>Param</a> with just a help text.
paramHelp :: Doc -> Param p

-- | Create a <a>Param</a> with just a help text.
paramHelpStr :: String -> Param p

-- | Create a <a>Param</a> with just a default value.
paramDefault :: p -> Param p

-- | Create a <a>Param</a> with just a list of suggestion values.
paramSuggestions :: [String] -> Param p

-- | Create a <a>Param</a> that is a file path.
paramFile :: Param p

-- | Create a <a>Param</a> that is a directory path.
paramDirectory :: Param p

-- | Add a parameter to the <a>CmdParser</a> by making use of a <a>Read</a>
--   instance. Take care not to use this to return Strings unless you
--   really want that, because it will require the quotation marks and
--   escaping as is normal for the Show/Read instances for String.
addParamRead :: forall f out a. (Applicative f, Typeable a, Show a, Read a) => String -> Param a -> CmdParser f out a

-- | Like addReadParam, but optional. I.e. if reading fails, returns
--   Nothing.
addParamReadOpt :: forall f out a. (Applicative f, Typeable a, Read a) => String -> Param a -> CmdParser f out (Maybe a)

-- | Add a parameter that matches any string of non-space characters if
--   input==String, or one full argument if input==[String]. See the
--   <a>Input</a> doc for this distinction.
addParamString :: forall f out. Applicative f => String -> Param String -> CmdParser f out String

-- | Like <a>addParamString</a>, but optional, I.e. succeeding with Nothing
--   if there is no remaining input.
addParamStringOpt :: forall f out. Applicative f => String -> Param Void -> CmdParser f out (Maybe String)

-- | Add a parameter that matches any string of non-space characters if
--   input==String, or one full argument if input==[String]. See the
--   <a>Input</a> doc for this distinction.
addParamStrings :: forall f out. Applicative f => String -> Param Void -> CmdParser f out [String]

-- | Like <a>addParamString</a> but does not match strings starting with a
--   dash. This prevents misinterpretation of flags as params.
addParamNoFlagString :: forall f out. Applicative f => String -> Param String -> CmdParser f out String

-- | Like <a>addParamStringOpt</a> but does not match strings starting with
--   a dash. This prevents misinterpretation of flags as params.
addParamNoFlagStringOpt :: forall f out. Applicative f => String -> Param Void -> CmdParser f out (Maybe String)

-- | Like <a>addParamStrings</a> but does not match strings starting with a
--   dash. This prevents misinterpretation of flags as params.
addParamNoFlagStrings :: forall f out. Applicative f => String -> Param Void -> CmdParser f out [String]

-- | Add a parameter that consumes _all_ remaining input. Typical usecase
--   is after a "--" as common in certain (unix?) commandline tools.
addParamRestOfInput :: forall f out. Applicative f => String -> Param Void -> CmdParser f out String

-- | Add a parameter that consumes _all_ remaining input, returning a raw
--   <a>Input</a> value.
addParamRestOfInputRaw :: forall f out. Applicative f => String -> Param Void -> CmdParser f out Input

-- | <i>Deprecated: use <a>addParamRead</a></i>
addReadParam :: forall f out a. (Applicative f, Typeable a, Show a, Read a) => String -> Param a -> CmdParser f out a

-- | <i>Deprecated: use <a>addParamReadOpt</a></i>
addReadParamOpt :: forall f out a. (Applicative f, Typeable a, Read a) => String -> Param a -> CmdParser f out (Maybe a)

-- | <i>Deprecated: use <a>addParamString</a></i>
addStringParam :: forall f out. Applicative f => String -> Param String -> CmdParser f out String

-- | <i>Deprecated: use <a>addParamStringOpt</a></i>
addStringParamOpt :: forall f out. Applicative f => String -> Param Void -> CmdParser f out (Maybe String)

-- | <i>Deprecated: use <a>addParamStrings</a></i>
addStringParams :: forall f out. Applicative f => String -> Param Void -> CmdParser f out [String]

-- | <i>Deprecated: use <a>addParamRestOfInput</a></i>
addRestOfInputStringParam :: forall f out. Applicative f => String -> Param Void -> CmdParser f out String
instance GHC.Base.Semigroup (UI.Butcher.Monadic.Param.Param p)
instance GHC.Base.Monoid (UI.Butcher.Monadic.Param.Param p)


-- | Building-blocks of a CmdParser.
--   
--   The simplest sensible CmdParser is just
--   
--   <pre>
--   addCmdImpl $ putStrLn "hello, world!"
--   </pre>
--   
--   (assuming out is IO ()).
--   
--   The empty CmdParser is also valid:
--   
--   <pre>
--   return ()
--   </pre>
--   
--   But not very interesting - you won't get an <tt>out</tt> value from
--   this (e.g. an IO-action to execute) when this matches (on the empty
--   input).
--   
--   <pre>
--   do
--     addCmd "sub" $ do
--       addCmdImpl $ putStrLn "sub successful"
--   </pre>
--   
--   Here, note that there is no implementation at the top-level. This
--   means that on the empty input the resulting CommandDesc has no
--   out-value, but on "sub" it has. Executed as a program, the user would
--   be shown the usage on empty input, and the putStrLn would happen on
--   "sub".
--   
--   More than one subcommand? easy:
--   
--   <pre>
--   do
--     addCmd "foo" $ do {..}
--     addCmd "bar" $ do {..}
--   </pre>
--   
--   Basic flag usage:
--   
--   <pre>
--   do
--     shouldVerbose &lt;- addSimpleBoolFlag "v" ["verbose"] mzero
--     addCmdImpl $ if shouldVerbose
--       then putStrLn "Hello, World!!!!!"
--       else putStrLn "hi."
--   </pre>
--   
--   Basic param usage:
--   
--   <pre>
--   addCmd "echo" $ do
--     addCmdHelpStr "print its parameter to output"
--     str &lt;- addRestOfInputStringParam "STRING" (paramHelpStr "the string to print")
--     addCmdImpl $ putStrLn str
--   addCmd "echoInt" $ do
--     i &lt;- addReadParam "INT" mempty
--     addCmdImpl $ print (i::Int) -- need to disambiguate via typesig.
--   </pre>
--   
--   There are some other flag/param methods in the respective modules.
--   Also note the example at <a>reorderStart</a>.
module UI.Butcher.Monadic.Command

-- | Add a new child command in the current context.
addCmd :: Applicative f => String -> CmdParser f out () -> CmdParser f out ()

-- | Add a new child command in the current context, but make it hidden. It
--   will not appear in docs/help generated by e.g. the functions in the
--   <tt>Pretty</tt> module.
--   
--   This feature is not well tested yet.
addCmdHidden :: Applicative f => String -> CmdParser f out () -> CmdParser f out ()

-- | Add a new nameless child command in the current context. Nameless
--   means that this command matches the empty input, i.e. will always
--   apply. This feature is experimental and CommandDesc pretty-printing
--   might not correctly in presense of nullCmds.
addNullCmd :: Applicative f => CmdParser f out () -> CmdParser f out ()

-- | Add an implementation to the current command.
addCmdImpl :: out -> CmdParser f out ()

-- | Add a synopsis to the command currently in scope; at top level this
--   will be the implicit top-level command.
--   
--   Adding a second synopsis will overwrite a previous synopsis;
--   <a>checkCmdParser</a> will check that you don't (accidentally) do this
--   however.
addCmdSynopsis :: String -> CmdParser f out ()

-- | Add a help document to the command currently in scope; at top level
--   this will be the implicit top-level command.
--   
--   Adding a second document will overwrite a previous document;
--   <a>checkCmdParser</a> will check that you don't (accidentally) do this
--   however.
addCmdHelp :: Doc -> CmdParser f out ()

-- | Like <tt><a>addCmdHelp</a> . PP.text</tt>
addCmdHelpStr :: String -> CmdParser f out ()

-- | Best explained via example:
--   
--   <pre>
--   do
--     reorderStart
--     bright &lt;- addSimpleBoolFlag "" ["bright"] mempty
--     yellow &lt;- addSimpleBoolFlag "" ["yellow"] mempty
--     reorderStop
--     ..
--   </pre>
--   
--   will accept any inputs "" "--bright" "--yellow" "--bright --yellow"
--   "--yellow --bright".
--   
--   This works for any flags/params, but bear in mind that the results
--   might be unexpected because params may match on any input.
--   
--   Note that start/stop must occur in pairs, and it will be a runtime
--   error if you mess this up. Use <a>checkCmdParser</a> if you want to
--   check all parts of your <a>CmdParser</a> without providing inputs that
--   provide 100% coverage.
reorderStart :: CmdParser f out ()

-- | See <a>reorderStart</a>
reorderStop :: CmdParser f out ()

-- | Safe wrapper around <a>reorderStart</a>/<a>reorderStop</a> for cases
--   where reducing to a single binding is possible/preferable.
withReorder :: CmdParser f out a -> CmdParser f out a

-- | Semi-hacky way of accessing the output CommandDesc from inside of a
--   <a>CmdParser</a>. This is not implemented via knot-tying, i.e. the
--   CommandDesc you get is _not_ equivalent to the CommandDesc returned by
--   <a>runCmdParser</a>. Also see <tt>runCmdParserWithHelpDesc</tt> which
--   does knot-tying.
--   
--   For best results, use this "below" any <a>addCmd</a> invocations in
--   the current context, e.g. directly before the <a>addCmdImpl</a>
--   invocation.
peekCmdDesc :: CmdParser f out (CommandDesc ())

-- | Semi-hacky way of accessing the current input that is not yet
--   processed. This must not be used to do any parsing. The purpose of
--   this function is to provide a String to be used for output to the
--   user, as feedback about what command was executed. For example we may
--   think of an interactive program reacting to commandline input such as
--   "run --delay 60 fire-rockets" which shows a 60 second delay on the
--   "fire-rockets" command. The latter string could have been obtained via
--   <a>peekInput</a> after having parsed "run --delay 60" already.
peekInput :: CmdParser f out String

-- | Add part that is expected to occur exactly once in the input. May
--   succeed on empty input (e.g. by having a default).
addCmdPart :: (Applicative f, Typeable p) => PartDesc -> (String -> Maybe (p, String)) -> CmdParser f out p

-- | Add part that is not required to occur, and can occur as often as
--   indicated by <a>ManyUpperBound</a>. Must not succeed on empty input.
addCmdPartMany :: (Applicative f, Typeable p) => ManyUpperBound -> PartDesc -> (String -> Maybe (p, String)) -> CmdParser f out [p]

-- | Add part that is expected to occur exactly once in the input. May
--   succeed on empty input (e.g. by having a default).
--   
--   Only difference to <a>addCmdPart</a> is that it accepts <a>Input</a>,
--   i.e. can behave differently for <tt>String</tt> and <tt>[String]</tt>
--   input.
addCmdPartInp :: (Applicative f, Typeable p) => PartDesc -> (Input -> Maybe (p, Input)) -> CmdParser f out p

-- | Add part that is not required to occur, and can occur as often as
--   indicated by <a>ManyUpperBound</a>. Must not succeed on empty input.
--   
--   Only difference to <a>addCmdPart</a> is that it accepts <a>Input</a>,
--   i.e. can behave differently for <tt>String</tt> and <tt>[String]</tt>
--   input.
addCmdPartManyInp :: (Applicative f, Typeable p) => ManyUpperBound -> PartDesc -> (Input -> Maybe (p, Input)) -> CmdParser f out [p]

-- | Add a list of sub-parsers one of which will be selected and used based
--   on the provided predicate function. The input elements consist of: a)
--   a name used for the command description of the output, b) a predicate
--   function; the first True predicate determines which element to apply
--   c) a CmdParser.
addAlternatives :: Typeable p => [(String, String -> Bool, CmdParser f out p)] -> CmdParser f out p

-- | Specifies whether we accept 0-1 or 0-n for <tt>CmdParserPart</tt>s.
data ManyUpperBound
ManyUpperBound1 :: ManyUpperBound
ManyUpperBoundN :: ManyUpperBound

-- | Create a simple PartDesc from a string.
varPartDesc :: String -> PartDesc


-- | Pretty-print of CommandDescs. To explain what the different functions
--   do, we will use an example CmdParser. The CommandDesc derived from
--   that CmdParser will serve as example input to the functions in this
--   module.
--   
--   <pre>
--   main = mainFromCmdParserWithHelpDesc $ \helpDesc -&gt; do
--   
--     addCmdSynopsis "a simple butcher example program"
--     addCmdHelpStr "a very long help document"
--   
--     addCmd "version" $ do
--       porcelain &lt;- addSimpleBoolFlag "" ["porcelain"]
--         (flagHelpStr "print nothing but the numeric version")
--       addCmdHelpStr "prints the version of this program"
--       addCmdImpl $ putStrLn $ if porcelain
--         then "0.0.0.999"
--         else "example, version 0.0.0.999"
--   
--     addCmd "help" $ addCmdImpl $ print $ ppHelpShallow helpDesc
--   
--     short &lt;- addSimpleBoolFlag "" ["short"] (flagHelpStr "make the greeting short")
--     name &lt;- addStringParam "NAME"
--       (paramHelpStr "your name, so you can be greeted properly")
--   
--     addCmdImpl $ do
--       if short
--         then putStrLn $ "hi, " ++ name ++ "!"
--         else putStrLn $ "hello, " ++ name ++ ", welcome from butcher!"
--   </pre>
module UI.Butcher.Monadic.Pretty

-- | ppUsage exampleDesc yields:
--   
--   <pre>
--   example [--short] NAME [version | help]
--   </pre>
ppUsage :: CommandDesc a -> Doc

-- | ppUsageShortSub exampleDesc yields:
--   
--   <pre>
--   example [--short] NAME &lt;command&gt;
--   </pre>
--   
--   I.e. Subcommands are abbreviated using the <tt><a>command</a></tt>
--   label, instead of being listed.
ppUsageShortSub :: CommandDesc a -> Doc

-- | <pre>
--   ppUsageAt [] = ppUsage
--   </pre>
--   
--   fromJust $ ppUsageAt ["version"] exampleDesc yields:
--   
--   <pre>
--   example version [--porcelain]
--   </pre>
ppUsageAt :: [String] -> CommandDesc a -> Maybe Doc

-- | ppHelpShallow exampleDesc yields:
--   
--   <pre>
--   NAME
--   
--     example - a simple butcher example program
--   
--   USAGE
--   
--     example [--short] NAME [version | help]
--   
--   DESCRIPTION
--   
--     a very long help document
--   
--   ARGUMENTS
--   
--     --short             make the greeting short
--     NAME                your name, so you can be greeted properly
--   </pre>
ppHelpShallow :: CommandDesc a -> Doc

-- | ppHelpDepthOne exampleDesc yields:
--   
--   <pre>
--   NAME
--   
--     example - a simple butcher example program
--   
--   USAGE
--   
--     example [--short] NAME &lt;command&gt;
--   
--   DESCRIPTION
--   
--     a very long help document
--   
--   COMMANDS
--   
--     version
--     help
--   
--   ARGUMENTS
--   
--     --short             make the greeting short
--     NAME                your name, so you can be greeted properly
--   </pre>
ppHelpDepthOne :: CommandDesc a -> Doc

-- | ppUsageWithHelp exampleDesc yields:
--   
--   <pre>
--   example [--short] NAME
--           [version | help]: a simple butcher example program
--   </pre>
--   
--   And yes, the line break is not optimal in this instance with default
--   print.
ppUsageWithHelp :: CommandDesc a -> Doc

-- | Internal helper; users probably won't need this.
ppPartDescUsage :: PartDesc -> Maybe Doc

-- | Internal helper; users probably won't need this.
ppPartDescHeader :: PartDesc -> Doc

-- | Simple conversion from <a>ParsingError</a> to <a>String</a>.
parsingErrorString :: ParsingError -> String

-- | Access a child command's CommandDesc.
descendDescTo :: [String] -> CommandDesc a -> Maybe (CommandDesc a)


-- | Utilities when writing interactive programs that interpret commands,
--   e.g. a REPL.
module UI.Butcher.Monadic.Interactive

-- | Derives a potential completion from a given input string and a given
--   <a>CommandDesc</a>. Considers potential subcommands and where
--   available the completion info present in <a>PartDesc</a>s.
simpleCompletion :: String -> CommandDesc () -> String -> String

-- | Derives a list of completion items from a given input string and a
--   given <a>CommandDesc</a>. Considers potential subcommands and where
--   available the completion info present in <a>PartDesc</a>s.
--   
--   See <tt>addShellCompletion</tt> which uses this.
shellCompletionWords :: String -> CommandDesc () -> String -> [CompletionItem]

-- | Produces a <a>Doc</a> as a hint for the user during interactive
--   command input. Takes the current (incomplete) prompt line into
--   account. For example when you have commands (among others) 'config
--   set-email' and 'config get-email', then on empty prompt there will be
--   an item 'config'; on the partial prompt 'config ' the help doc will
--   contain the 'set-email' and 'get-email' items.
interactiveHelpDoc :: String -> CommandDesc () -> String -> Int -> Doc

-- | Obtains a list of "expected"/potential strings for a command part
--   described in the <a>PartDesc</a>. In constrast to the
--   <a>simpleCompletion</a> function this function does not take into
--   account any current input, and consequently the output elements can in
--   general not be appended to partial input to form valid input.
partDescStrings :: PartDesc -> [String]


-- | Turn your CmdParser into an IO () to be used as your program
--   <tt>main</tt>.
module UI.Butcher.Monadic.IO

-- | Utility method that allows using a <a>CmdParser</a> as your
--   <tt>main</tt> function:
--   
--   <pre>
--   main = mainFromCmdParser $ do
--     addCmdImpl $ putStrLn "This is a fairly boring program."
--   </pre>
--   
--   Uses <tt>System.Environment.getProgName</tt> as program name and
--   <tt>System.Environment.getArgs</tt> as the input to be parsed. Prints
--   some appropriate messages if parsing fails or if the command has no
--   implementation; if all is well executes the 'out' action (the IO ()).
mainFromCmdParser :: CmdParser Identity (IO ()) () -> IO ()

-- | Same as mainFromCmdParser, but with one additional twist: You get
--   access to a knot-tied complete CommandDesc for this full command.
--   Useful in combination with <a>addHelpCommand</a>
mainFromCmdParserWithHelpDesc :: (CommandDesc () -> CmdParser Identity (IO ()) ()) -> IO ()


-- | Some CmdParser actions that add predefined commands.
module UI.Butcher.Monadic.BuiltinCommands

-- | Adds a proper full help command. To obtain the <a>CommandDesc</a>
--   value, see <a>cmdRunParserWithHelpDesc</a> or
--   <a>mainFromCmdParserWithHelpDesc</a>.
--   
--   <pre>
--   addHelpCommand = addHelpCommandWith
--     (pure . PP.renderStyle PP.style { PP.ribbonsPerLine = 1.0 } . ppHelpShallow)
--   </pre>
addHelpCommand :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()

-- | Adds a proper full help command. In contrast to <a>addHelpCommand</a>,
--   this version is a bit more verbose about available subcommands as it
--   includes their synopses.
--   
--   To obtain the <a>CommandDesc</a> value, see
--   <a>cmdRunParserWithHelpDesc</a> or
--   <a>mainFromCmdParserWithHelpDesc</a>.
--   
--   <pre>
--   addHelpCommand2 = addHelpCommandWith
--     (pure . PP.renderStyle PP.style { PP.ribbonsPerLine = 1.0 } . ppHelpDepthOne)
--   </pre>
addHelpCommand2 :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()

-- | Adds a proper full help command, using the specified function to turn
--   the relevant subcommand's <a>CommandDesc</a> into a String.
addHelpCommandWith :: Applicative f => (CommandDesc a -> IO String) -> CommandDesc a -> CmdParser f (IO ()) ()

-- | Adds a help command that prints help for the command currently in
--   context.
--   
--   This version does _not_ include further childcommands, i.e. "help foo"
--   will not print the help for subcommand "foo".
--   
--   This also yields slightly different output depending on if it is used
--   before or after adding other subcommands. In general
--   <a>addHelpCommand</a> should be preferred.
addHelpCommandShallow :: Applicative f => CmdParser f (IO ()) ()

-- | Prints the raw CommandDesc structure.
addButcherDebugCommand :: Applicative f => CmdParser f (IO ()) ()

-- | Adds the "completion" command and several subcommands.
--   
--   This command can be used in the following manner:
--   
--   <pre>
--   $ source &lt;(foo completion bash-script foo)
--   </pre>
addShellCompletionCommand :: CmdParser Identity (IO ()) () -> CmdParser Identity (IO ()) ()

-- | Adds the "completion" command and several subcommands
--   
--   This command can be used in the following manner:
--   
--   <pre>
--   $ source &lt;(foo completion bash-script foo)
--   </pre>
addShellCompletionCommand' :: (CommandDesc out -> CmdParser Identity (IO ()) ()) -> CmdParser Identity (IO ()) ()


-- | Types used in the butcher interface.
module UI.Butcher.Monadic.Types

-- | A representation/description of a command parser built via the
--   <a>CmdParser</a> monad. Can be transformed into a pretty Doc to
--   display as usage/help via <a>ppUsage</a> and related functions.
--   
--   Note that there is the <a>_cmd_out</a> accessor that contains
--   <tt>Maybe out</tt> which might be useful after successful parsing.
data CommandDesc out
CommandDesc :: Maybe (Maybe String, CommandDesc out) -> Maybe Doc -> Maybe Doc -> [PartDesc] -> Maybe out -> Deque (Maybe String, CommandDesc out) -> Visibility -> CommandDesc out
[_cmd_mParent] :: CommandDesc out -> Maybe (Maybe String, CommandDesc out)
[_cmd_synopsis] :: CommandDesc out -> Maybe Doc
[_cmd_help] :: CommandDesc out -> Maybe Doc
[_cmd_parts] :: CommandDesc out -> [PartDesc]
[_cmd_out] :: CommandDesc out -> Maybe out
[_cmd_children] :: CommandDesc out -> Deque (Maybe String, CommandDesc out)
[_cmd_visibility] :: CommandDesc out -> Visibility
cmd_out :: forall out_a9mr. Lens' (CommandDesc out_a9mr) (Maybe out_a9mr)

-- | The CmdParser monad type. It is a free monad over some functor but
--   users of butcher don't need to know more than that <a>CmdParser</a> is
--   a <a>Monad</a>.
type CmdParser f out = Free (CmdParserF f out)

-- | Butcher supports two input modi: <tt>String</tt> and
--   <tt>[String]</tt>. Program arguments have the latter form, while
--   parsing interactive command input (e.g. when you implement a terminal
--   of sorts) is easier when you can process the full <tt>String</tt>
--   without having to wordify it first by some means (and List.words is
--   not the right approach in many situations.)
data Input
InputString :: String -> Input
InputArgs :: [String] -> Input

-- | Information about an error that occured when trying to parse some
--   <tt>Input</tt> using some <tt>CmdParser</tt>.
data ParsingError
ParsingError :: [String] -> Input -> ParsingError
[_pe_messages] :: ParsingError -> [String]
[_pe_remaining] :: ParsingError -> Input

-- | A representation/description of a command's parts, i.e. flags or
--   params. As a butcher user, the higher-level pretty-printing functions
--   for <a>CommandDesc</a> are probably sufficient.
data PartDesc
PartLiteral :: String -> PartDesc
PartVariable :: String -> PartDesc
PartOptional :: PartDesc -> PartDesc
PartAlts :: [PartDesc] -> PartDesc
PartSeq :: [PartDesc] -> PartDesc
PartDefault :: String -> PartDesc -> PartDesc
PartSuggestion :: [CompletionItem] -> PartDesc -> PartDesc
PartRedirect :: String -> PartDesc -> PartDesc
PartReorder :: [PartDesc] -> PartDesc
PartMany :: PartDesc -> PartDesc
PartWithHelp :: Doc -> PartDesc -> PartDesc
PartHidden :: PartDesc -> PartDesc

-- | Empty <a>CommandDesc</a> value. Mostly for butcher-internal usage.
emptyCommandDesc :: CommandDesc out
data Visibility
Visible :: Visibility
Hidden :: Visibility


-- | Reexports of everything that is exposed in the submodules.
module UI.Butcher.Monadic

-- | Butcher supports two input modi: <tt>String</tt> and
--   <tt>[String]</tt>. Program arguments have the latter form, while
--   parsing interactive command input (e.g. when you implement a terminal
--   of sorts) is easier when you can process the full <tt>String</tt>
--   without having to wordify it first by some means (and List.words is
--   not the right approach in many situations.)
data Input
InputString :: String -> Input
InputArgs :: [String] -> Input

-- | The CmdParser monad type. It is a free monad over some functor but
--   users of butcher don't need to know more than that <a>CmdParser</a> is
--   a <a>Monad</a>.
type CmdParser f out = Free (CmdParserF f out)

-- | Information about an error that occured when trying to parse some
--   <tt>Input</tt> using some <tt>CmdParser</tt>.
data ParsingError
ParsingError :: [String] -> Input -> ParsingError
[_pe_messages] :: ParsingError -> [String]
[_pe_remaining] :: ParsingError -> Input

-- | A representation/description of a command parser built via the
--   <a>CmdParser</a> monad. Can be transformed into a pretty Doc to
--   display as usage/help via <a>ppUsage</a> and related functions.
--   
--   Note that there is the <a>_cmd_out</a> accessor that contains
--   <tt>Maybe out</tt> which might be useful after successful parsing.
data CommandDesc out
cmd_out :: forall out_a9mr. Lens' (CommandDesc out_a9mr) (Maybe out_a9mr)

-- | Wrapper around <a>runCmdParser</a> for very simple usage: Accept a
--   <tt>String</tt> input and return only the output from the parser, or a
--   plain error string on failure.
runCmdParserSimple :: String -> CmdParser Identity out () -> Either String out

-- | Run a <tt>CmdParser</tt> on the given input, returning:
--   
--   a) A <tt>CommandDesc ()</tt> that accurately represents the subcommand
--   that was reached, even if parsing failed. Because this is returned
--   always, the argument is <tt>()</tt> because "out" requires a
--   successful parse.
--   
--   b) Either an error or the result of a successful parse, including a
--   proper "CommandDesc out" from which an "out" can be extracted
--   (presuming that the command has an implementation).
runCmdParser :: Maybe String -> Input -> CmdParser Identity out () -> (CommandDesc (), Either ParsingError (CommandDesc out))

-- | Like <a>runCmdParser</a>, but also returning all input after the last
--   successfully parsed subcommand. E.g. for some input "myprog foo bar -v
--   --wrong" where parsing fails at "--wrong", this will contain the full
--   "-v --wrong". Useful for interactive feedback stuff.
runCmdParserExt :: Maybe String -> Input -> CmdParser Identity out () -> (CommandDesc (), Input, Either ParsingError (CommandDesc out))

-- | The Applicative-enabled version of <a>runCmdParser</a>.
runCmdParserA :: forall f out. Applicative f => Maybe String -> Input -> CmdParser f out () -> f (CommandDesc (), Either ParsingError (CommandDesc out))

-- | The Applicative-enabled version of <a>runCmdParserExt</a>.
runCmdParserAExt :: forall f out. Applicative f => Maybe String -> Input -> CmdParser f out () -> f (CommandDesc (), Input, Either ParsingError (CommandDesc out))

-- | Like <a>runCmdParser</a>, but with one additional twist: You get
--   access to a knot-tied complete CommandDesc for this full command.
--   Useful in combination with <a>addHelpCommand</a>.
--   
--   Note that the <tt>CommandDesc ()</tt> in the output is _not_ the same
--   value as the parameter passed to the parser function: The output value
--   contains a more "shallow" description. This is more efficient for
--   complex CmdParsers when used interactively, because non-relevant parts
--   of the CmdParser are not traversed unless the parser function argument
--   is forced.
runCmdParserWithHelpDesc :: Maybe String -> Input -> (CommandDesc () -> CmdParser Identity out ()) -> (CommandDesc (), Either ParsingError (CommandDesc out))

-- | Because butcher is evil (i.e. has constraints not encoded in the
--   types; see the README), this method can be used as a rough check that
--   you did not mess up. It traverses all possible parts of the
--   <a>CmdParser</a> thereby ensuring that the <a>CmdParser</a> has a
--   valid structure.
--   
--   This method also yields a _complete_ <tt>CommandDesc</tt> output,
--   where the other runCmdParser* functions all traverse only a shallow
--   structure around the parts of the <a>CmdParser</a> touched while
--   parsing the current input.
checkCmdParser :: forall f out. Maybe String -> CmdParser f out () -> Either String (CommandDesc ())

-- | Adds a proper full help command. To obtain the <a>CommandDesc</a>
--   value, see <a>cmdRunParserWithHelpDesc</a> or
--   <a>mainFromCmdParserWithHelpDesc</a>.
--   
--   <pre>
--   addHelpCommand = addHelpCommandWith
--     (pure . PP.renderStyle PP.style { PP.ribbonsPerLine = 1.0 } . ppHelpShallow)
--   </pre>
addHelpCommand :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()

-- | Adds a proper full help command. In contrast to <a>addHelpCommand</a>,
--   this version is a bit more verbose about available subcommands as it
--   includes their synopses.
--   
--   To obtain the <a>CommandDesc</a> value, see
--   <a>cmdRunParserWithHelpDesc</a> or
--   <a>mainFromCmdParserWithHelpDesc</a>.
--   
--   <pre>
--   addHelpCommand2 = addHelpCommandWith
--     (pure . PP.renderStyle PP.style { PP.ribbonsPerLine = 1.0 } . ppHelpDepthOne)
--   </pre>
addHelpCommand2 :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()

-- | Adds a proper full help command, using the specified function to turn
--   the relevant subcommand's <a>CommandDesc</a> into a String.
addHelpCommandWith :: Applicative f => (CommandDesc a -> IO String) -> CommandDesc a -> CmdParser f (IO ()) ()

-- | Prints the raw CommandDesc structure.
addButcherDebugCommand :: Applicative f => CmdParser f (IO ()) ()

-- | Adds the "completion" command and several subcommands.
--   
--   This command can be used in the following manner:
--   
--   <pre>
--   $ source &lt;(foo completion bash-script foo)
--   </pre>
addShellCompletionCommand :: CmdParser Identity (IO ()) () -> CmdParser Identity (IO ()) ()

-- | Adds the "completion" command and several subcommands
--   
--   This command can be used in the following manner:
--   
--   <pre>
--   $ source &lt;(foo completion bash-script foo)
--   </pre>
addShellCompletionCommand' :: (CommandDesc out -> CmdParser Identity (IO ()) ()) -> CmdParser Identity (IO ()) ()

-- | map over the <tt>out</tt> type argument
mapOut :: (outa -> outb) -> CmdParser f outa a -> CmdParser f outb a

-- | Empty <a>CommandDesc</a> value. Mostly for butcher-internal usage.
emptyCommandDesc :: CommandDesc out
data Visibility
Visible :: Visibility
Hidden :: Visibility
instance GHC.Show.Show UI.Butcher.Monadic.Sample
