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

-- | Chops a command or program invocation into digestable pieces.
--   
--   See the README (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
--   CmdPart 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 (<>) 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 Flag with just a help text.
flagHelp :: Doc -> Flag p

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

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

-- | Create a Flag 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 addSimpleFlag
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 (<>) 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 Param with just a help text.
paramHelp :: Doc -> Param p

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

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

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

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

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

-- | Add a parameter to the CmdParser by making use of a Read
--   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
--   Input doc for this distinction.
addParamString :: forall f out. Applicative f => String -> Param String -> CmdParser f out String

-- | Like addParamString, 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
--   Input doc for this distinction.
addParamStrings :: forall f out. Applicative f => String -> Param Void -> CmdParser f out [String]

-- | Like addParamString 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 addParamStringOpt 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 addParamStrings 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
--   Input value.
addParamRestOfInputRaw :: forall f out. Applicative f => String -> Param Void -> CmdParser f out Input

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

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

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

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

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

-- | Deprecated: use addParamRestOfInput
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
--   
--   
--   addCmdImpl $ putStrLn "hello, world!"
--   
--   
--   (assuming out is IO ()).
--   
--   The empty CmdParser is also valid:
--   
--   
--   return ()
--   
--   
--   But not very interesting - you won't get an out value from
--   this (e.g. an IO-action to execute) when this matches (on the empty
--   input).
--   
--   
--   do
--     addCmd "sub" $ do
--       addCmdImpl $ putStrLn "sub successful"
--   
--   
--   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:
--   
--   
--   do
--     addCmd "foo" $ do {..}
--     addCmd "bar" $ do {..}
--   
--   
--   Basic flag usage:
--   
--   
--   do
--     shouldVerbose <- addSimpleBoolFlag "v" ["verbose"] mzero
--     addCmdImpl $ if shouldVerbose
--       then putStrLn "Hello, World!!!!!"
--       else putStrLn "hi."
--   
--   
--   Basic param usage:
--   
--   
--   addCmd "echo" $ do
--     addCmdHelpStr "print its parameter to output"
--     str <- addRestOfInputStringParam "STRING" (paramHelpStr "the string to print")
--     addCmdImpl $ putStrLn str
--   addCmd "echoInt" $ do
--     i <- addReadParam "INT" mempty
--     addCmdImpl $ print (i::Int) -- need to disambiguate via typesig.
--   
--   
--   There are some other flag/param methods in the respective modules.
--   Also note the example at reorderStart.
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
--   Pretty 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;
--   checkCmdParser 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;
--   checkCmdParser will check that you don't (accidentally) do this
--   however.
addCmdHelp :: Doc -> CmdParser f out ()

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

-- | Best explained via example:
--   
--   
--   do
--     reorderStart
--     bright <- addSimpleBoolFlag "" ["bright"] mempty
--     yellow <- addSimpleBoolFlag "" ["yellow"] mempty
--     reorderStop
--     ..
--   
--   
--   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 checkCmdParser if you want to
--   check all parts of your CmdParser without providing inputs that
--   provide 100% coverage.
reorderStart :: CmdParser f out ()

-- | See reorderStart
reorderStop :: CmdParser f out ()

-- | Safe wrapper around reorderStart/reorderStop 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
--   CmdParser. This is not implemented via knot-tying, i.e. the
--   CommandDesc you get is _not_ equivalent to the CommandDesc returned by
--   runCmdParser. Also see runCmdParserWithHelpDesc which
--   does knot-tying.
--   
--   For best results, use this "below" any addCmd invocations in
--   the current context, e.g. directly before the addCmdImpl
--   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
--   peekInput 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 ManyUpperBound. 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 addCmdPart is that it accepts Input,
--   i.e. can behave differently for String and [String]
--   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 ManyUpperBound. Must not succeed on empty input.
--   
--   Only difference to addCmdPart is that it accepts Input,
--   i.e. can behave differently for String and [String]
--   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 CmdParserParts.
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.
--   
--   
--   main = mainFromCmdParserWithHelpDesc $ \helpDesc -> do
--   
--     addCmdSynopsis "a simple butcher example program"
--     addCmdHelpStr "a very long help document"
--   
--     addCmd "version" $ do
--       porcelain <- 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 <- addSimpleBoolFlag "" ["short"] (flagHelpStr "make the greeting short")
--     name <- 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!"
--   
module UI.Butcher.Monadic.Pretty

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

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

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

-- | ppHelpShallow exampleDesc yields:
--   
--   
--   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
--   
ppHelpShallow :: CommandDesc a -> Doc

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

-- | ppUsageWithHelp exampleDesc yields:
--   
--   
--   example [--short] NAME
--           [version | help]: a simple butcher example program
--   
--   
--   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 ParsingError to String.
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
--   CommandDesc. Considers potential subcommands and where
--   available the completion info present in PartDescs.
simpleCompletion :: String -> CommandDesc () -> String -> String

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

-- | Produces a Doc 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 PartDesc. In constrast to the
--   simpleCompletion 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
--   main.
module UI.Butcher.Monadic.IO

-- | Utility method that allows using a CmdParser as your
--   main function:
--   
--   
--   main = mainFromCmdParser $ do
--     addCmdImpl $ putStrLn "This is a fairly boring program."
--   
--   
--   Uses System.Environment.getProgName as program name and
--   System.Environment.getArgs 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 addHelpCommand
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 CommandDesc
--   value, see cmdRunParserWithHelpDesc or
--   mainFromCmdParserWithHelpDesc.
--   
--   
--   addHelpCommand = addHelpCommandWith
--     (pure . PP.renderStyle PP.style { PP.ribbonsPerLine = 1.0 } . ppHelpShallow)
--   
addHelpCommand :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()

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

-- | Adds a proper full help command, using the specified function to turn
--   the relevant subcommand's CommandDesc 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
--   addHelpCommand 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:
--   
--   
--   $ source <(foo completion bash-script foo)
--   
addShellCompletionCommand :: CmdParser Identity (IO ()) () -> CmdParser Identity (IO ()) ()

-- | Adds the "completion" command and several subcommands
--   
--   This command can be used in the following manner:
--   
--   
--   $ source <(foo completion bash-script foo)
--   
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
--   CmdParser monad. Can be transformed into a pretty Doc to
--   display as usage/help via ppUsage and related functions.
--   
--   Note that there is the _cmd_out accessor that contains
--   Maybe out 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_adjB. Lens' (CommandDesc out_adjB) (Maybe out_adjB)

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

-- | Butcher supports two input modi: String and
--   [String]. 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 String
--   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
--   Input using some CmdParser.
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 CommandDesc 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 CommandDesc 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: String and
--   [String]. 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 String
--   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 CmdParser is
--   a Monad.
type CmdParser f out = Free (CmdParserF f out)

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

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

-- | Wrapper around runCmdParser for very simple usage: Accept a
--   String 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 CmdParser on the given input, returning:
--   
--   a) A CommandDesc () that accurately represents the subcommand
--   that was reached, even if parsing failed. Because this is returned
--   always, the argument is () 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 runCmdParser, 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 runCmdParser.
runCmdParserA :: forall f out. Applicative f => Maybe String -> Input -> CmdParser f out () -> f (CommandDesc (), Either ParsingError (CommandDesc out))

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

-- | Like runCmdParser, but with one additional twist: You get
--   access to a knot-tied complete CommandDesc for this full command.
--   Useful in combination with addHelpCommand.
--   
--   Note that the CommandDesc () 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
--   CmdParser thereby ensuring that the CmdParser has a
--   valid structure.
--   
--   This method also yields a _complete_ CommandDesc output,
--   where the other runCmdParser* functions all traverse only a shallow
--   structure around the parts of the CmdParser 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 CommandDesc
--   value, see cmdRunParserWithHelpDesc or
--   mainFromCmdParserWithHelpDesc.
--   
--   
--   addHelpCommand = addHelpCommandWith
--     (pure . PP.renderStyle PP.style { PP.ribbonsPerLine = 1.0 } . ppHelpShallow)
--   
addHelpCommand :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()

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

-- | Adds a proper full help command, using the specified function to turn
--   the relevant subcommand's CommandDesc 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:
--   
--   
--   $ source <(foo completion bash-script foo)
--   
addShellCompletionCommand :: CmdParser Identity (IO ()) () -> CmdParser Identity (IO ()) ()

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

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

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