Documentation

CliParser state

A parser that interprets command line arguments and returns well-formed data.

weave : base -> CliBuilder base GetOptionsAction

Begin weaving together a CLI builder using the : <- builder notation.

Check the module-level documentation for general usage instructions.

expect
    { parser } =
        Cli.weave {
            verbosity: <- Opt.count { short: "v", long: "verbose" },
        }
        |> Cli.finish { name: "example" }
        |> Cli.assertValid

   parser ["example", "-vvv"]
   == SuccessfullyParsed { verbosity: 3 }

finish : CliBuilder state action, CliConfigParams -> Result (CliParser state) CliValidationErr

Bundle a CLI builder into a parser, ensuring that its configuration is valid.

Though the majority of the validation we'd need to do for type safety is rendered unnecessary by the design of this library, there are some things that the type system isn't able to prevent. Here are the checks we currently perform after building your CLI parser:

• All commands and subcommands must have kebab-case names.
• All options must have either:
  • A short flag which is a single character.
  • A long flag which is more than one character and kebab-case.
  • Both a short and a long flag with the above requirements.
• All parameters must be have kebab-case names.
• All custom option/parameter types are have kebab-case names.
• No options can overlap, even between different subcommands, so long as the options between the subcommands are ambiguous.
  • For example, a CLI with a -t option at the root level and also a -t option in the subcommand sub would fail validation since we wouldn't know who should get the -t option.
  • However, a CLI with two subcommands that each have a -t option would not fail validation since only one subcommand can be called at once.

If you would like to avoid these validations, you can use finishWithoutValidating instead, but you may receive some suprising results when parsing because our parsing logic assumes the above validations have been made.

expect
    Cli.weave {
        verbosity: <- Opt.count { short: "v", long: "verbose" },
    }
    |> Cli.finish { name: "example" }
    |> Result.isOk

expect
    Cli.weave {
        verbosity: <- Opt.count { short: "" },
    }
    |> Cli.finish { name: "example" }
    |> Result.isErr

finishWithoutValidating : CliBuilder state action, CliConfigParams -> CliParser state

Bundle a CLI builder into a parser without validating its configuration.

We recommend using the finish function to validate your parser as our library's logic assumes said validation has taken place. However, this method could be useful if you know better than our validations about the correctness of your CLI.

expect
    { parser } =
        Cli.weave {
            verbosity: <- Opt.count { short: "v", long: "verbose" },
        }
        |> Cli.finishWithoutValidating { name: "example" }

    parser ["example", "-v", "-v"]
    == SuccessfullyParsed { verbosity: 2 }

assertValid : Result (CliParser state) CliValidationErr -> CliParser state

Assert that a CLI is properly configured, crashing your program if not.

Given that there are some aspects of a CLI that we cannot ensure are correct at compile time, the easiest way to ensure that your CLI is properly configured is to validate it and crash immediately on failure, following the Fail Fast principle.

You can avoid making this assertion by handling the error yourself or by finish your CLI with the finishWithoutValidating function, but the validations we perform (detailed in finish's docs) are important for correct parsing.

Cli.weave {
    a: <- Opt.num { short: "a" }
}
|> Cli.finish { name: "example" }
|> Cli.assertValid

parseOrDisplayMessage : CliParser state, List Str -> Result state Str

Parse arguments using a CLI parser or show a useful message on failure.

We have the following priorities in returning messages to the user:

1. If the -h/--help flag is passed, the help page for the command/subcommand called will be displayed no matter if your arguments were correctly parsed.
2. If the -V/--version flag is passed, the version for the app will be displayed no matter if your arguments were correctly parsed.
3. If the provided arguments were parsed and neither of the above two built-in flags were passed, we return to you your data.
4. If the provided arguments were not correct, we return a short message with which argument was not provided correctly, followed by the usage section of the relevant command/subcommand's help text.

exampleCli =
    Cli.weave {
        verbosity: <- Opt.count { short: "v", help: "How verbose our logs should be." },
    }
    |> Cli.finish {
        name: "example",
        version: "v0.1.0",
        description: "An example CLI.",
    }
    |> Cli.assertValid

expect
    exampleCli
    |> Cli.parseOrDisplayMessage ["example", "-h"]
    == Err
        """
        example v0.1.0

        An example CLI.

        Usage:
          example [OPTIONS]

        Options:
          -v             How verbose our logs should be.
          -h, --help     Show this help page.
          -V, --version  Show the version.
        """

expect
    exampleCli
    |> Cli.parseOrDisplayMessage ["example", "-V"]
    == Err "v0.1.0"

expect
    exampleCli
    |> Cli.parseOrDisplayMessage ["example", "-v"]
    == Ok { verbosity: 1 }

expect
    exampleCli
    |> Cli.parseOrDisplayMessage ["example", "-x"]
    == Err
        """
        Error: The argument -x was not recognized.

        Usage:
          example [OPTIONS]
        """