dillonkearns / elm-cli-options-parser / Cli.Option

Here is the terminology used for building up Command-Line parsers with this library.

Terminology Legend

See the README and the examples folder for more in-depth examples of building and using Cli.Options.

Positional Arguments

requiredPositionalArg : String -> Option String String BeginningOption

Keyword Arguments

optionalKeywordArg : String -> Option (Maybe String) (Maybe String) BeginningOption

requiredKeywordArg : String -> Option String String BeginningOption

keywordArgList : String -> Option (List String) (List String) BeginningOption

Flags

flag : String -> Option Basics.Bool Basics.Bool BeginningOption

Ending Options

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.

Transformations

Mutually Exclusive Values

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"

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 (\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).

Mapping/Defaults

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.

Types


type Option from to middleOrEnding
    = Option (InnerOption from to)


type BeginningOption

BeginningOptions can only be used with OptionsParser.with.

OptionalPositionalArgOptions can only be used with OptionsParser.withOptionalPositionalArg.


type OptionalPositionalArgOption

BeginningOptions can only be used with OptionsParser.with.

OptionalPositionalArgOptions can only be used with OptionsParser.withOptionalPositionalArg.


type RestArgsOption

RestArgsOptions can only be used with OptionsParser.withRestArgs.