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.Option
s.
requiredPositionalArg : String -> Option String String BeginningOption
optionalKeywordArg : String -> Option (Maybe String) (Maybe String) BeginningOption
requiredKeywordArg : String -> Option String String BeginningOption
keywordArgList : String -> Option (List String) (List String) BeginningOption
flag : String -> Option Basics.Bool Basics.Bool BeginningOption
See note in Cli.OptionsParser
docs.
optionalPositionalArg : String -> Option (Maybe String) (Maybe String) OptionalPositionalArgOption
Note that this must be used with OptionsParser.withOptionalPositionalArg
.
restArgs : String -> Option (List String) (List String) RestArgsOption
Note that this must be used with OptionsParser.withRestArgs
.
oneOf : value -> List (MutuallyExclusiveValue value) -> Option from String builderState -> Option from value builderState
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 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"
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 (\a b -> ( a, b ))
|> 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.
validate : (to -> Cli.Validate.ValidationResult) -> Option from to builderState -> Option from to builderState
Run a validation. (See an example in the Validation section above, or
in the examples
folder).
validateIfPresent : (to -> Cli.Validate.ValidationResult) -> Option from (Maybe to) builderState -> Option from (Maybe to) builderState
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).
validateMap : (to -> Result String toMapped) -> Option from to builderState -> Option from toMapped builderState
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).
validateMapIfPresent : (to -> Result String toMapped) -> Option (Maybe from) (Maybe to) builderState -> Option (Maybe from) (Maybe toMapped) builderState
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).
map : (toRaw -> toMapped) -> Option from toRaw builderState -> Option from toMapped builderState
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
)
)
mapFlag : { present : union, absent : union } -> Option from Basics.Bool builderState -> Option from union builderState
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
}
)
)
withDefault : to -> Option from (Maybe to) builderState -> Option from to builderState
Provide a default value for the Option
.
BeginningOption
s can only be used with OptionsParser.with
.
OptionalPositionalArgOption
s can only be used with OptionsParser.withOptionalPositionalArg
.
BeginningOption
s can only be used with OptionsParser.with
.
OptionalPositionalArgOption
s can only be used with OptionsParser.withOptionalPositionalArg
.
RestArgsOption
s can only be used with OptionsParser.withRestArgs
.