This is the type returned from using the commands function along with helpers like command and run to build up a nested structure of commands. We can manually traverse it by looking through the cmdChildren Map to acess nested commands, or inspecting the cmdHelp and cmdFunc properties of the current command. This makes it easy to do things like autocomplete commands, or print out help etc.

You probably won't ever need to interact with this type; it is just a State monad on our Command type in order that we can use monadic notation to build up our nested structure.

A collection of the errors that can be encountered upon trying to get and run a Command

Given a Commands type as its only argument, this resolves it to a Command object, ready to make use of. This is basically the entry point to defining our commands, inside which we can use the functions below to populate our structure.

Nest a command with some name inside the current command.

Attach help to the current command.

Attach a function which will be tried if the current command is matched. The parameters to the function must satisfy the IsParameter typeclasses, which will automatically make the function satisfy the ExtractParameters and InjectParameters typeclasses.

Attempt to run a function inside a Command object, using the first argument (a list of strings) to first navigate to the relevant subcommand and then have any remainder used as values to be passed to the command, and the second argument as a map of flags to be passed to the command.

Attempt to get hold of the nested Command at the path provided inside a provided Command object.

A tuple of typeclasses that must all be implemented for function parameter types in order that they can be used in the functions attached to commands. ToParam is the only mandatory requirement (ParamFlags and ParamHelp have default defitions), however it is recommended that you implement ParamHelp in all cases, and you must implement ParamFlags if you want your new type to match against provided flags. An example custom parameter implementation:

data Verbose = Verbose Bool

instance ParamFlags Verbose where
    paramFlags _ = Just ["v", "verbose"]
instance ParamHelp Verbose where
    paramHelp _ = "Make the command more verbose"
instance ToParam Verbose where
    toParam (Just _) = Right (Verbose True)
    toParam Nothing = Right (Verbose False)

Here, we define a Verbose type that will equal Verbose True if the "v" or "verbose" flag is used in the command, or Verbose False otherwise.

To extract the value, all we have to do is use (Verbose b) in our commands function now, where b will be either True or False.

See Params for the definitions of the provided Value and Flag parameter types.

Describe how to turn the String parameter given into our custom type. The input may be Nothing if the flag/value is not provided, else it will be Just str where str is the input string.

Should the parameter match against flags? If so, return Just [flags] from this. If the param should be a value instead, return Nothing.

Return a piece of help text describing what the parameter means.

Our existential Fn type is used for hiding away the details of some provided function. Any function that satisfies the IsParameter tuple of type classes can be wrapped in this.

given our Fn out type, containing some function that will return out on successful execution, attempt to run the function by injecting a list of values and a map of flags to it. This will either return a CommandError denoting what failed, or the output from running the function.

Run against our Fn out wrapped function, this will return a list of Parameter details for each parameter in the contained function.

A type containing information about a function parameter.