butcher-1.2.1.0: Chops a command or program invocation into digestable pieces.

Description

Main module of the butcher interface. It reexports everything that is exposed in the submodules.

Synopsis

# Types

data Input Source #

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

Constructors

 InputString String InputArgs [String]

Instances

 Source # Methods(==) :: Input -> Input -> Bool #(/=) :: Input -> Input -> Bool # Source # MethodsshowsPrec :: Int -> Input -> ShowS #show :: Input -> String #showList :: [Input] -> ShowS #

type CmdParser f out = Free (CmdParserF f out) Source #

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.

Constructors

 ParsingError Fields_pe_messages :: [String] _pe_remaining :: Input

Instances

 Source # Methods Source # MethodsshowList :: [ParsingError] -> ShowS #

data CommandDesc out Source #

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.

Instances

 Source # Methodsfmap :: (a -> b) -> CommandDesc a -> CommandDesc b #(<\$) :: a -> CommandDesc b -> CommandDesc a # Show (CommandDesc out) Source # MethodsshowsPrec :: Int -> CommandDesc out -> ShowS #show :: CommandDesc out -> String #showList :: [CommandDesc out] -> ShowS #

cmd_out :: forall out. Lens' (CommandDesc out) (Maybe out) Source #

# Run or Check CmdParsers

runCmdParserSimple :: String -> CmdParser Identity out () -> Either String out Source #

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.

Arguments

 :: Maybe String program name to be used for the top-level CommandDesc -> Input input to be processed -> CmdParser Identity out () parser to use -> (CommandDesc (), Either ParsingError (CommandDesc 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).

Arguments

 :: Maybe String program name to be used for the top-level CommandDesc -> Input input to be processed -> CmdParser Identity out () parser to use -> (CommandDesc (), Input, 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.

Arguments

 :: Applicative f => Maybe String program name to be used for the top-level CommandDesc -> Input input to be processed -> CmdParser f out () parser to use -> f (CommandDesc (), Either ParsingError (CommandDesc out))

The Applicative-enabled version of runCmdParser.

Arguments

 :: Applicative f => Maybe String program name to be used for the top-level CommandDesc -> Input input to be processed -> CmdParser f out () parser to use -> f (CommandDesc (), Input, Either ParsingError (CommandDesc out))

The Applicative-enabled version of runCmdParserExt.

Arguments

 :: Maybe String program name to be used for the top-level CommandDesc -> Input input to be processed -> (CommandDesc () -> CmdParser Identity out ()) parser to use -> (CommandDesc (), 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.

Arguments

 :: Maybe String top-level command name -> CmdParser f out () parser to check -> Either String (CommandDesc ())

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.

# Builtin commands

addHelpCommand :: Applicative f => CommandDesc () -> CmdParser f (IO ()) () Source #

Adds a proper full help command. To obtain the CommandDesc value, see cmdRunParserWithHelpDesc or mainFromCmdParserWithHelpDesc.

addButcherDebugCommand :: Applicative f => CmdParser f (IO ()) () Source #

Prints the raw CommandDesc structure.

mapOut :: (outa -> outb) -> CmdParser f outa () -> CmdParser f outb () Source #

map over the out type argument