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

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.

Information about an error that occured when trying to parse some Input using some CmdParser.

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.

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.

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

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.

The Applicative-enabled version of runCmdParser.

The Applicative-enabled version of runCmdParserExt.

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.

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.

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)

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)

Adds a proper full help command, using the specified function to turn the relevant subcommand's CommandDesc into a String.

Prints the raw CommandDesc structure.

Adds the "completion" command and several subcommands.

This command can be used in the following manner:

$ source <(foo completion bash-script foo)

Adds the "completion" command and several subcommands

This command can be used in the following manner:

$ source <(foo completion bash-script foo)

map over the out type argument

Empty CommandDesc value. Mostly for butcher-internal usage.