CLI.Parser

A module for parsing arguments from the command line. With this you can turn the following

mycmd greet --overwrite file.txt

Into a data structure.

Application

type alias App result =
{ name : String
, version : String
, commands : GroupParser result
, intro : Document
, outro : Document
}

Defines a command line application.

  • name is the name of the application
  • version is the application version
  • commands is a group of commands that this application recognizes
  • intro and outro is used when the user calls the application without any arguments. They define what text comes before and after the list of supported commands.
run : Array String -> App result -> CommandParseResult result

Takes input from the user in the form of an Array of String, and parses it according to the given App definition.

Groups

type GroupParser result

A parser for a group, or collection, of commands.
type alias Command args flags result =
{ word : String
, arguments : ArgumentParser args
, flags : FlagParser flags
, commonDescription : Maybe String
, summary : String
, example : Document
, builder : args -> flags -> result
}

Definition of a command.
type CommandParseResult a
= UnknownCommand String
| BadFlags FlagParserError
| BadArguments ArgumentParserError
| HelpText Document
| Success a

The result of parsing user input.
defineGroup : GroupParser result

Defines an empty group of commands. To add commands to this group, you'll need to use withCommand and withPrefix.
withCommand :
Command args flags result
-> GroupParser result
-> GroupParser result

Returns a new group that contains the given command. If there are multiple commands in the group with the same word, then the last registered command wins.
withPrefix :
String
-> GroupParser result
-> GroupParser result
-> GroupParser result

Embeds a group of commands into an existing group, accessible by the given prefix.

Arguments

type alias ValueParser val =
{ singular : String
, plural : String
, fn : String -> Maybe val
, examples : Array String
}

Defines an argument value. The fn property is the function that parses the String representation of an argument into its final form.
type ArgumentParser val

Arguments are values that a Command requires to function. An ArgumentParser is a way of converting an arbitrary number of String inputs into Gren values.
type ArgumentParserError
= ArgumentParserWrongArity ({ expected : Int, actual : Int })
| ArgumentParserInvalidArgument ({ argument : String, title : String, examples : Array String })

There are mainly two things that can go wrong when parsing arguments. You can either get an unexpected number of arguments or one or more of those arguments may fail to parse.
argumentErrorPrettified : ArgumentParserError -> Document

Turns an ArgumentParserError into a prettified String.
noArgs : ArgumentParser {}

Some Commands doesn't require arguments. This parser checks that exactly 0 arguments were provided.
oneArg : ValueParser val -> ArgumentParser val

Parses exactly one argument.
twoArgs :
(a -> b -> c)
-> ValueParser a
-> ValueParser b
-> ArgumentParser c

Parses exactly two arguments.
threeArgs :
(a -> b -> c -> d)
-> ValueParser a
-> ValueParser b
-> ValueParser c
-> ArgumentParser d

Parses exactly three arguments.
zeroOrMoreArgs : ValueParser val -> ArgumentParser (Array val)

Parses zero or more arguments of a single type.
mapArgs : (a -> b) -> ArgumentParser a -> ArgumentParser b

Maps a successfully parsed set of arguments into something else.
oneOfArgs : Array (ArgumentParser val) -> ArgumentParser val

A list of parsers that will be tried one after another until one succeeds.

Flags

type FlagParser val

Flags are prefixed with -- and are meant to customize a command.
type FlagParserError
= FlagParserFoundValueOnToggle KnownFlags String
| FlagParserMissingValue KnownFlags String
| FlagParserInvalidValue KnownFlags String
| FlagParserUnknownFlag KnownFlags String

There are several things that can go wrong when parsing flags:

  • The parser can find an associated value for a flag that requires none.
  • The parser might not find an associated value for a flag that does require one.
  • The associated value might fail to parse.
  • The flag might be unknown.
flagErrorPrettified : FlagParserError -> Document

Returns a prettified error message for the given FlagParserError.
noFlags : FlagParser {}

A parser that verifies that no flags have been provided.
initFlags : a -> FlagParser a

Defines an empty group of flags. You'll need to register flags using the toggle and flag functions.
toggle : String -> String -> FlagParser (Bool -> b) -> FlagParser b

Defines a flag that doesn't require an associated value. We're simply checking if the flag is present or not.
flag :
String
-> ValueParser a
-> String
-> FlagParser (Maybe a -> b)
-> FlagParser b

Defines a flag that requires an associated value.

Common parsers

pathParser : ValueParser Path

Parses a String into a FileSystem.Path.
grenFileParser : ValueParser Path

Like pathParser, but verifies that the file extension is .gren.