A positional argument that must be provided.

Example: src/Main.elm in elm make src/Main.elm Parses to: "src/Main.elm"

Option.requiredPositionalArg "input"

A keyword argument that may be omitted.

Example: --output main.js or --output=main.js Parses to: Just "main.js" (or Nothing if omitted)

Option.optionalKeywordArg "output"

A keyword argument that must be provided.

Example: --name my-app or --name=my-app Parses to: "my-app"

Option.requiredKeywordArg "name"

A keyword argument that can be provided multiple times.

Example: --header "Auth: token" --header "Accept: json" Parses to: ["Auth: token", "Accept: json"]

Option.keywordArgList "header"

A flag with no argument.

Example: --debug in elm make --debug Parses to: True (or False if omitted)

Option.flag "debug"

Note that this must be used with OptionsParser.withOptionalPositionalArg.

Note that this must be used with OptionsParser.withRestArgs.

Mutually exclusive option values.

type ReportFormat
    = Json
    | Junit
    | Console


type alias CliOptions =
    { reportFormat : ReportFormat
    , testFiles : List String
    }


program : Program.Config CliOptions
program =
    Program.config
        |> Program.add
            (OptionsParser.build CliOptions
                |> with
                    (Option.optionalKeywordArg "report"
                        |> Option.withDefault "console"
                        |> Option.oneOf
                            [ "json" => Json
                            , "junit" => Junit
                            , "console" => Console
                            ]
                    )
                |> OptionsParser.withRestArgs (Option.restArgs "TESTFILES")
            )

Now when you run it, you get the following in your help text:

$ ./elm-test --help
elm-test [--report <json|junit|console>] <TESTFILES>...

And if you run it with an unrecognized value, you get a validation error:

$ ./elm-test --report xml
Validation errors:

`report` failed a validation. Must be one of [json, junit, console]
Value was:
"xml"

Run a validation. (See an example in the Validation section above, or in the examples folder).

Run a validation if the value is Just someValue. Or do nothing if the value is Nothing. (See an example in the Validation section above, or in the examples folder).

Transform the value through a map function. If it returns Ok someValue then the Option will be transformed into someValue. If it returns Err someError then the User of the Command-Line Interface will see someError with details about the Option that had the validation error.

(See an example in the Validation section above, or in the examples folder).

Same as validateMap if the value is Just someValue. Does nothing if the value is Nothing.

(See an example in the Validation section above, or in the examples folder).

Transform an Option. For example, you may want to map an option from the raw String that comes from the command line into a Regex, as in this code snippet.

import Cli.Option as Option
import Cli.OptionsParser as OptionsParser
import Cli.Program as Program
import Regex exposing (Regex)


type alias CliOptions =
    { pattern : Regex }


programConfig : Program.Config CliOptions
programConfig =
    Program.config
        |> Program.add
            (OptionsParser.build buildCliOptions
                |> OptionsParser.with
                    (Option.requiredPositionalArg "pattern"
                        |> Option.map Regex.regex
                    )
            )

Useful for using a custom union type for a flag instead of a Bool.

import Cli.Option as Option
import Cli.OptionsParser as OptionsParser
import Cli.Program as Program


type Verbosity
    = Quiet
    | Verbose


type alias CliOptions =
    { verbosity : Verbosity
    }


programConfig : Program.Config CliOptions
programConfig =
    Program.config
        |> Program.add
            (OptionsParser.build CliOptions
                |> OptionsParser.with
                    (Option.flag "verbose"
                        |> Option.mapFlag
                            { present = Verbose
                            , absent = Quiet
                            }
                    )
            )

Provide a default value for the Option.

Add a description to an option. This will be shown in help text.

Option.requiredKeywordArg "name"
    |> Option.withDescription "Your name for the greeting"

Add a custom error message for when a required option is missing.

This only works on required options (requiredPositionalArg, requiredKeywordArg).

Option.requiredPositionalArg "repository"
    |> Option.withMissingMessage "You must specify a repository to clone."

The type returned by the builder functions below. Use with OptionsParser.with.

Phantom type marker for beginning options.

BeginningOptions can only be used with OptionsParser.with.

Phantom type marker for optional positional arg options.

OptionalPositionalArgOptions can only be used with OptionsParser.withOptionalPositionalArg.

Phantom type marker for rest args options.

RestArgsOptions can only be used with OptionsParser.withRestArgs.