Cli.Option
Here is the terminology used for building up Command-Line parsers with this library.
See the README and the examples folder for more in-depth examples of building
and using Cli.Options.
Positional Arguments
Keyword Arguments
Flags
Ending Options
See note in Cli.OptionsParser docs.
Note that this must be used with OptionsParser.withOptionalPositionalArg.
Note that this must be used with OptionsParser.withRestArgs.
Transformations
Mutually Exclusive Values
Mutually exclusive option values.
type ReportFormat
= Json
| Junit
| Console
type alias CliOptions =
{ reportFormat : ReportFormat
, testFiles : List String
}
program : Program.Config CliOptions
program =
Program.config { version = "1.2.3" }
|> Program.add
(OptionsParser.build CliOptions
|> with
(Option.optionalKeywordArg "report"
|> Option.withDefault "console"
|> Option.oneOf Console
[ "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"Validation
Validations allow you to guarantee that if you receive the data in Elm, it meets a set of preconditions. If it doesn't, the User will see an error message describing the validation error, which option it came from, and the value the option had.
Note that failing a validation will not cause the next OptionsParser in
your Cli.Program.Config to be run. Instead,
if the OptionsParser is a match except for validation errors, you will get an
error message regardless.
Example:
capitalizedNameRegex =
"[A-Z][A-Za-z]*"
validateParser =
OptionsParser.build (,)
|> with
(Option.requiredKeywordArg "name"
|> Option.validate (Cli.Validate.regex capitalizedNameRegex)
)
|> with
(Option.optionalKeywordArg "age"
|> Option.validateMapIfPresent String.toInt
)
{-
$ ./validation --name Mozart --age 262
Mozart is 262 years old
$ ./validation --name Mozart --age "Two-hundred and sixty-two"
Validation errors:
`age` failed a validation. could not convert string 'Two-hundred and sixty-two' to an Int
Value was:
Just "Two-hundred and sixty-two"
-}See Cli.Validate for some validation helpers that can be used in conjunction
with the following functions.
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).
Mapping/Defaults
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 { version = "1.2.3" }
|> 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 { version = "1.2.3" }
|> Program.add
(OptionsParser.build CliOptions
|> OptionsParser.with
(Option.flag "verbose"
|> Option.mapFlag
{ present = Verbose
, absent = Quiet
}
)
)Provide a default value for the Option.
Types
BeginningOptions can only be used with OptionsParser.with.
OptionalPositionalArgOptions can only be used with OptionsParser.withOptionalPositionalArg.
BeginningOptions can only be used with OptionsParser.with.
OptionalPositionalArgOptions can only be used with OptionsParser.withOptionalPositionalArg.
RestArgsOptions can only be used with OptionsParser.withRestArgs.