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

Safe Haskell | None
Language | Haskell2010

UI.Butcher.Monadic

Contents

- Types
- Run or Check CmdParsers
- Building CmdParsers
- PrettyPrinting CommandDescs (usage/help)
- Wrapper around System.Environment.getArgs
- Utilities for interactive feedback of commandlines (completions etc.)
- Builtin commands
- Advanced usage

Description

Reexports of everything that is exposed in the submodules.

Synopsis

- data Input
  - = InputString String
  - | InputArgs [String]
- type CmdParser f out = Free (CmdParserF f out)
- data ParsingError = ParsingError {
  - _pe_messages :: [String]
  - _pe_remaining :: Input
  }
- data CommandDesc out
- cmd_out :: forall out. Lens' (CommandDesc out) (Maybe out)
- runCmdParserSimple :: String -> CmdParser Identity out () -> Either String out
- runCmdParser :: Maybe String -> Input -> CmdParser Identity out () -> (CommandDesc (), Either ParsingError (CommandDesc out))
- runCmdParserExt :: Maybe String -> Input -> CmdParser Identity out () -> (CommandDesc (), Input, Either ParsingError (CommandDesc out))
- runCmdParserA :: forall f out. Applicative f => Maybe String -> Input -> CmdParser f out () -> f (CommandDesc (), Either ParsingError (CommandDesc out))
- runCmdParserAExt :: forall f out. Applicative f => Maybe String -> Input -> CmdParser f out () -> f (CommandDesc (), Input, Either ParsingError (CommandDesc out))
- runCmdParserWithHelpDesc :: Maybe String -> Input -> (CommandDesc () -> CmdParser Identity out ()) -> (CommandDesc (), Either ParsingError (CommandDesc out))
- checkCmdParser :: forall f out. Maybe String -> CmdParser f out () -> Either String (CommandDesc ())
- module UI.Butcher.Monadic.Command
- module UI.Butcher.Monadic.Pretty
- module UI.Butcher.Monadic.IO
- module UI.Butcher.Monadic.Interactive
- addHelpCommand :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()
- addHelpCommand2 :: Applicative f => CommandDesc a -> CmdParser f (IO ()) ()
- addHelpCommandWith :: Applicative f => (CommandDesc a -> IO String) -> CommandDesc a -> CmdParser f (IO ()) ()
- addButcherDebugCommand :: Applicative f => CmdParser f (IO ()) ()
- addShellCompletionCommand :: CmdParser Identity (IO ()) () -> CmdParser Identity (IO ()) ()
- addShellCompletionCommand' :: (CommandDesc out -> CmdParser Identity (IO ()) ()) -> CmdParser Identity (IO ()) ()
- mapOut :: (outa -> outb) -> CmdParser f outa a -> CmdParser f outb a
- emptyCommandDesc :: CommandDesc out
- data Visibility
  - = Visible
  - | Hidden

# 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

Instances details

Eq Input Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods (==) :: Input -> Input -> Bool (/=) :: Input -> Input -> Bool
Show Input Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods showsPrec :: 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`.

data ParsingError Source #

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

Instances details

Eq ParsingError Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods (==) :: ParsingError -> ParsingError -> Bool (/=) :: ParsingError -> ParsingError -> Bool
Show ParsingError Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods showsPrec :: Int -> ParsingError -> ShowS show :: ParsingError -> String showList :: [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

Instances details

Functor CommandDesc Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods fmap :: (a -> b) -> CommandDesc a -> CommandDesc b (<$) :: a -> CommandDesc b -> CommandDesc a
Show (CommandDesc out) Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods showsPrec :: 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.

runCmdParser Source #

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

runCmdParserExt Source #

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.

runCmdParserA Source #

Arguments

:: forall f out. 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`.

runCmdParserAExt Source #

Arguments

:: forall f out. 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`.

runCmdParserWithHelpDesc Source #

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.

checkCmdParser Source #

Arguments

:: forall f out. 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.

# Building CmdParsers

module UI.Butcher.Monadic.Command

# PrettyPrinting CommandDescs (usage/help)

module UI.Butcher.Monadic.Pretty

# Wrapper around System.Environment.getArgs

module UI.Butcher.Monadic.IO

# Utilities for interactive feedback of commandlines (completions etc.)

module UI.Butcher.Monadic.Interactive

# Builtin commands

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

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)

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

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)

addHelpCommandWith :: Applicative f => (CommandDesc a -> IO String) -> CommandDesc a -> CmdParser f (IO ()) () Source #

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

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

Prints the raw CommandDesc structure.

addShellCompletionCommand :: CmdParser Identity (IO ()) () -> CmdParser Identity (IO ()) () Source #

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 ()) () Source #

Adds the "completion" command and several subcommands

This command can be used in the following manner:

    $ source <(foo completion bash-script foo)

# Advanced usage

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

map over the `out` type argument

emptyCommandDesc :: CommandDesc out Source #

Empty `CommandDesc` value. Mostly for butcher-internal usage.

data Visibility Source #

Constructors

Visible |
Hidden |

#### Instances

Instances details

Eq Visibility Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods (==) :: Visibility -> Visibility -> Bool (/=) :: Visibility -> Visibility -> Bool
Show Visibility Source # |
Instance details Defined in UI.Butcher.Monadic.Internal.Types Methods showsPrec :: Int -> Visibility -> ShowS show :: Visibility -> String showList :: [Visibility] -> ShowS