# LLM Prompt for Documentation ## Documentation ### Opt #### single **Type Annotation** ```roc DefaultableOptionConfigParams a -> CliBuilder a GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a custom type to your CLI builder. You need to provide a kebab-case type name for your help messages as well as a parser for said type. The parser needs to return an `Err (InvalidValue Str)` on failure, where the `Str` is the reason the parsing failed that will get displayed in the incorrect usage message. Parsing arguments will fail if the option is not given as an argument or a value is not provided to the option. ```roc expect Color : [Green, Red, Blue] parse_color : Arg -> Result Color [InvalidValue Str, InvalidUtf8] parse_color = \color -> when Arg.to_str color is Ok "green" -> Ok Green Ok "red" -> Ok Red Ok "blue" -> Ok Blue other -> Err (InvalidValue "'$(other)' is not a valid color, must be green, red, or blue") { parser } = Opt.single { short: "c", parser: parse_color, type: "color" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-c", "green"] == SuccessfullyParsed Green ``` #### maybe **Type Annotation** ```roc OptionConfigParams data -> CliBuilder (Result data [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a custom type to your CLI builder. You need to provide a kebab-case type name for your help messages as well as a parser for said type. The parser needs to return an `Err (InvalidValue Str)` on failure, where the `Str` is the reason the parsing failed that will get displayed in the incorrect usage message. Parsing arguments will fail if more than one instance of the argument is provided, there is no value given for the option call, or the value doesn't parse correctly. ```roc expect Color : [Green, Red, Blue] parse_color : Arg -> Result Color [InvalidValue Str, InvalidUtf8] parse_color = \color -> when Arg.to_str color is Ok "green" -> Ok Green Ok "red" -> Ok Red Ok "blue" -> Ok Blue other -> Err (InvalidValue "'$(other)' is not a valid color, must be green, red, or blue") { parser } = Opt.maybe { short: "c", type: "color", parser: parse_color }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### list **Type Annotation** ```roc OptionConfigParams data -> CliBuilder (List data) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a custom type and can be given multiple times to your CLI builder. You need to provide a kebab-case type name for your help messages as well as a parser for said type. The parser needs to return an `Err (InvalidValue Str)` on failure, where the `Str` is the reason the parsing failed that will get displayed in the incorrect usage message. Parsing arguments will fail if any calls of the option don't provide a value or any of the options don't parse correctly. ```roc expect Color : [Green, Red, Blue] parse_color : Arg -> Result Color [InvalidValue Str, InvalidUtf8] parse_color = \color -> when Arg.to_str color is Ok "green" -> Ok Green Ok "red" -> Ok Red Ok "blue" -> Ok Blue other -> Err (InvalidValue "'$(other)' is not a valid color, must be green, red, or blue") { parser } = Opt.list { short: "c", type: "color", parser: parse_color }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-c", "green", "--color=red"] == SuccessfullyParsed [Green, Red] ``` #### flag **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder Bool GetOptionsAction GetOptionsAction ``` **Description** Add an optional flag to your CLI builder. Parsing arguments will fail if the flag is given more than once or if a value is provided to it, e.g. `--flag=value`. ```roc expect { parser } = Opt.flag { short: "f", long: "force" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-f"] == SuccessfullyParsed Bool.true ``` #### count **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder U64 GetOptionsAction GetOptionsAction ``` **Description** Add a flag that can be given multiple times to your CLI builder. Parsing arguments will fail if this flag is ever given a value, e.g. `--flag=value`. ```roc expect { parser } = Opt.count { short: "f", long: "force" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-f", "--force", "-fff"] == SuccessfullyParsed 5 ``` #### arg **Type Annotation** ```roc DefaultableOptionConfigBaseParams Arg -> CliBuilder Arg GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes an [Arg] to your CLI builder. Parsing arguments will fail if the option is not given as an argument or a value is not provided to the option. ```roc expect { parser } = Opt.arg { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=abc"] == SuccessfullyParsed (Arg.from_str "abc") ``` #### maybe_arg **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result Arg [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes an [Arg] to your CLI builder. Parsing arguments will fail if more than one instance of the argument is provided or there is no value given for the option call. ```roc expect { parser } = Opt.maybe_arg { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### arg_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List Arg) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes an [Arg] and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value. ```roc expect { parser } = Opt.arg_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "abc", "--answer", "def", "--answer=ghi"] == SuccessfullyParsed (List.map ["abc", "def", "ghi"] Arg.from_str) ``` #### bytes **Type Annotation** ```roc DefaultableOptionConfigBaseParams (List U8) -> CliBuilder (List U8) GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a byte list to your CLI builder. Parsing arguments will fail if the option is not given as an argument or a value is not provided to the option. ```roc expect { parser } = Opt.bytes { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=abc"] == SuccessfullyParsed [97, 98, 99] ``` #### maybe_bytes **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result (List U8) [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a byte list to your CLI builder. Parsing arguments will fail if more than one instance of the argument is provided or there is no value given for the option call. ```roc expect { parser } = Opt.maybe_bytes { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### bytes_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List (List U8)) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a byte list and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value. ```roc expect { parser } = Opt.bytes_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "abc", "--answer", "def", "--answer=ghi"] == SuccessfullyParsed [[97, 98, 99], [100, 101, 102], [103, 104, 105]] ``` #### str **Type Annotation** ```roc DefaultableOptionConfigBaseParams Str -> CliBuilder Str GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a string to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not valid UTF-8. ```roc expect { parser } = Opt.str { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=abc"] == SuccessfullyParsed "abc" ``` #### maybe_str **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result Str [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a string to your CLI builder. Parsing arguments will fail if more than one instance of the argument is provided, there is no value given for the option call, or the value is not valid UTF-8. ```roc expect { parser } = Opt.maybe_str { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### str_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List Str) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a string and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value or any of the values are not valid UTF-8. ```roc expect { parser } = Opt.str_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "abc", "--answer", "def", "--answer=ghi"] == SuccessfullyParsed ["abc", "def", "ghi"] ``` #### dec **Type Annotation** ```roc DefaultableOptionConfigBaseParams Dec -> CliBuilder Dec GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `Dec` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.dec { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42.5"] == SuccessfullyParsed 42.5 ``` #### maybe_dec **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result Dec [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `Dec` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_dec { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### dec_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List Dec) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `Dec` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.dec_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "-3.0"] == SuccessfullyParsed [1.0, 2.0, -3.0] ``` #### f32 **Type Annotation** ```roc DefaultableOptionConfigBaseParams F32 -> CliBuilder F32 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `F32` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.f32 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42.5"] == SuccessfullyParsed 42.5 ``` #### maybe_f32 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result F32 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `F32` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_f32 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### f32_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List F32) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `F32` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.f32_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "-3.0"] == SuccessfullyParsed [1.0, 2.0, -3.0] ``` #### f64 **Type Annotation** ```roc DefaultableOptionConfigBaseParams F64 -> CliBuilder F64 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `F64` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.f64 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42.5"] == SuccessfullyParsed 42.5 ``` #### maybe_f64 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result F64 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `F64` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_f64 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### f64_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List F64) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `F64` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.f64_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "-3.0"] == SuccessfullyParsed [1.0, 2.0, -3.0] ``` #### u8 **Type Annotation** ```roc DefaultableOptionConfigBaseParams U8 -> CliBuilder U8 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `U8` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.u8 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_u8 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result U8 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `U8` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_u8 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u8_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List U8) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `U8` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.u8_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### u16 **Type Annotation** ```roc DefaultableOptionConfigBaseParams U16 -> CliBuilder U16 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `U16` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.u16 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_u16 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result U16 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `U16` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_u16 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u16_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List U16) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `U16` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.u16_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### u32 **Type Annotation** ```roc DefaultableOptionConfigBaseParams U32 -> CliBuilder U32 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `U32` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.u32 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_u32 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result U32 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `U32` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_u32 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u32_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List U32) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `U32` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.u32_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### u64 **Type Annotation** ```roc DefaultableOptionConfigBaseParams U64 -> CliBuilder U64 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `U64` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.u64 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_u64 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result U64 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `U64` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_u64 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u64_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List U64) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `U64` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.u64_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### u128 **Type Annotation** ```roc DefaultableOptionConfigBaseParams U128 -> CliBuilder U128 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes a `U128` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.u128 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_u128 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result U128 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes a `U128` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_u128 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u128_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List U128) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes a `U128` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.u128_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### i8 **Type Annotation** ```roc DefaultableOptionConfigBaseParams I8 -> CliBuilder I8 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes an `I8` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.i8 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_i8 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result I8 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes an `I8` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_i8 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i8_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List I8) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes an `I8` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.i8_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### i16 **Type Annotation** ```roc DefaultableOptionConfigBaseParams I16 -> CliBuilder I16 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes an `I16` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.i16 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_i16 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result I16 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes an `I16` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_i16 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i16_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List I16) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes an `I16` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.i16_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### i32 **Type Annotation** ```roc DefaultableOptionConfigBaseParams I32 -> CliBuilder I32 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes an `I32` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.i32 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_i32 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result I32 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes an `I32` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_i32 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i32_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List I32) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes an `I32` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.i32_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### i64 **Type Annotation** ```roc DefaultableOptionConfigBaseParams I64 -> CliBuilder I64 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes an `I64` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.i64 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_i64 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result I64 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes an `I64` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_i64 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i64_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List I64) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes an `I64` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.i64_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` #### i128 **Type Annotation** ```roc DefaultableOptionConfigBaseParams I128 -> CliBuilder I128 GetOptionsAction GetOptionsAction ``` **Description** Add a required option that takes an `I128` to your CLI builder. Parsing arguments will fail if the option is not given as an argument, a value is not provided to the option, or the value is not a number. ```roc expect { parser } = Opt.i128 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "--answer=42"] == SuccessfullyParsed 42 ``` #### maybe_i128 **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (Result I128 [NoValue]) GetOptionsAction GetOptionsAction ``` **Description** Add an optional option that takes an `I128` to your CLI builder. Parsing arguments will fail if a value is not provided to the option, the value is not a number, or there is more than one call to the option. ```roc expect { parser } = Opt.maybe_i128 { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i128_list **Type Annotation** ```roc OptionConfigBaseParams -> CliBuilder (List I128) GetOptionsAction GetOptionsAction ``` **Description** Add an option that takes an `I128` and can be given multiple times to your CLI builder. Parsing arguments will fail if any calls of the option don't provide a value, or the values are not all numbers. ```roc expect { parser } = Opt.i128_list { long: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-a", "1", "--answer=2", "--answer", "3"] == SuccessfullyParsed [1, 2, 3] ``` ### Base #### ArgParserResult **Type Annotation** **Description** The result of attempting to parse args into config data. #### ArgParserParams **Type Annotation** **Description** The parameters that an [ArgParser] takes to extract data from args. #### ArgParserState **Type Annotation** **Description** The intermediate state that an [ArgParser] passes between different parsing steps. #### ArgParser **Type Annotation** **Description** A function that takes command line arguments and a subcommand, and attempts to extract configuration data from said arguments. #### on_successful_arg_parse **Type Annotation** ```roc ArgParser a, (ArgParserState a -> ArgParserResult (ArgParserState b)) -> ArgParser b ``` **Description** A bind operation for [ArgParserState]. If an [ArgParser] successfully parses some data, then said data is provided to a callback and the resulting [ArgParserResult] is passed along in the newly bound [ArgParser]. #### map_successfully_parsed **Type Annotation** ```roc ArgParserResult a, (a -> b) -> ArgParserResult b ``` **Description** Maps successfully parsed data that was parsed by an [ArgParser] by a user-defined operation. #### ArgExtractErr **Type Annotation** **Description** Errors that can occur while extracting values from command line arguments. #### str_type_name **Type Annotation** #### num_type_name **Type Annotation** #### TextStyle **Type Annotation** ```roc [ Color, Plain ] ``` **Description** Whether help text should have fancy styling. #### ExpectedValue **Type Annotation** **Description** The type of value that an option expects to parse. #### Plurality **Type Annotation** ```roc [ Optional, One, Many ] ``` **Description** How many values an option/parameter can take. #### SpecialFlags **Type Annotation** **Description** The two built-in flags that we parse automatically. #### InvalidValue **Type Annotation** #### DefaultValue **Type Annotation** ```roc [ NoDefault, Value a, Generate ({} -> a) ] ``` #### ValueParser **Type Annotation** **Description** A parser that extracts an argument value from a string. #### OptionConfigBaseParams **Type Annotation** #### DefaultableOptionConfigBaseParams **Type Annotation** #### OptionConfigParams **Type Annotation** **Description** Default-value options for creating an option. #### DefaultableOptionConfigParams **Type Annotation** **Description** Default-value options for creating an option. #### OptionConfig **Type Annotation** **Description** Metadata for options in our CLI building system. #### help_option **Type Annotation** ```roc OptionConfig ``` **Description** Metadata for the `-h/--help` option that we parse automatically. #### version_option **Type Annotation** ```roc OptionConfig ``` **Description** Metadata for the `-V/--version` option that we parse automatically. #### ParameterConfigBaseParams **Type Annotation** #### DefaultableParameterConfigBaseParams **Type Annotation** #### ParameterConfigParams **Type Annotation** **Description** Default-value options for creating an parameter. #### DefaultableParameterConfigParams **Type Annotation** **Description** Default-value options for creating an parameter. #### ParameterConfig **Type Annotation** **Description** Metadata for parameters in our CLI building system. #### CliConfigParams **Type Annotation** **Description** Default-value options for bundling an CLI. #### CliConfig **Type Annotation** **Description** Metadata for a root-level CLI. #### SubcommandConfigParams **Type Annotation** **Description** Default-value options for bundling a subcommand. #### SubcommandsConfig **Type Annotation** **Description** Metadata for a set of subcommands under a parent command. Since subcommands can have their own sub-subcommands, this type alias needs to be an enum with an empty variant to avoid infinite recursion. #### SubcommandConfig **Type Annotation** **Description** Metadata for a subcommand. ### Cli #### CliParser **Type Annotation** **Description** A parser that interprets command line arguments and returns well-formed data. #### map **Type Annotation** ```roc CliBuilder a from_action to_action, (a -> b) -> CliBuilder b from_action to_action ``` **Description** Map over the parsed value of a Weaver field. Useful for naming bare fields, or handling default values. ```roc expect { parser } = { Cli.weave <- verbosity: Opt.count { short: "v", long: "verbose" } |> Cli.map Verbosity, file: Param.maybe_str { name: "file" } |> Cli.map \f -> Result.withDefault f "NO_FILE", } |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "-vvv"] == SuccessfullyParsed { verbosity: Verbosity 3, file: "NO_FILE" } ``` #### weave **Type Annotation** ```roc CliBuilder a action1 action2, CliBuilder b action2 action3, (a, b -> c) -> CliBuilder c action1 action3 ``` **Description** Begin weaving together a CLI builder using the `<-` builder notation. Check the module-level documentation for general usage instructions. ```roc expect { parser } = { Cli.weave <- verbosity: Opt.count { short: "v", long: "verbose" }, file: Param.str { name: "file" }, } |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "file.txt", "-vvv"] == SuccessfullyParsed { verbosity: 3, file: "file.txt" } ``` #### finish **Type Annotation** ```roc CliBuilder data from_action to_action, CliConfigParams -> Result (CliParser data) CliValidationErr ``` **Description** 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 [finish_without_validating] instead, but you may receive some suprising results when parsing because our parsing logic assumes the above validations have been made. ```roc expect { Cli.weave <- verbosity: Opt.count { short: "v", long: "verbose" }, file: Param.str { name: "file" }, } |> Cli.finish { name: "example" } |> Result.isOk expect { Cli.weave <- verbosity: Opt.count { short: "" }, file: Param.str { name: "" }, } |> Cli.finish { name: "example" } |> Result.isErr ``` #### finish_without_validating **Type Annotation** ```roc CliBuilder data from_action to_action, CliConfigParams -> CliParser data ``` **Description** 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. ```roc expect { parser } = { Cli.weave <- verbosity: Opt.count { short: "v", long: "verbose" }, file: Param.maybe_str { name: "file" }, } |> Cli.finish_without_validating { name: "example" } parser ["example", "-v", "-v"] == SuccessfullyParsed { verbosity: 2, file: Err NoValue } ``` #### assert_valid **Type Annotation** ```roc Result (CliParser data) CliValidationErr -> CliParser data ``` **Description** 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 [finish_without_validating] function, but the validations we perform (detailed in [finish]'s docs) are important for correct parsing. ```roc Opt.num { short: "a" } |> Cli.finish { name: "example" } |> Cli.assert_valid ``` #### parse_or_display_message **Type Annotation** ```roc CliParser data, List arg, (arg -> [ Unix (List U8), Windows (List U16) ]) -> Result data Str ``` **Description** 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. ```roc exampleCli = { Cli.weave <- verbosity: Opt.count { short: "v", long: "verbose" }, alpha: Opt.maybe_num { short: "a", long: "alpha" }, } |> Cli.finish { name: "example", version: "v0.1.0", description: "An example CLI.", } |> Cli.assert_valid expect exampleCli |> Cli.parse_or_display_message ["example", "-h"] Arg.to_os_raw == Err """ example v0.1.0 An example CLI. Usage: example [OPTIONS] Options: -v How verbose our logs should be. -a, --alpha Set the alpha level. -h, --help Show this help page. -V, --version Show the version. """ expect exampleCli |> Cli.parse_or_display_message ["example", "-V"] Arg.to_os_raw == Err "v0.1.0" expect exampleCli |> Cli.parse_or_display_message ["example", "-v"] Arg.to_os_raw == Ok { verbosity: 1 } expect exampleCli |> Cli.parse_or_display_message ["example", "-x"] Arg.to_os_raw == Err """ Error: The argument -x was not recognized. Usage: example [OPTIONS] """ ``` ### ErrorFormatter #### format_arg_extract_err **Type Annotation** ```roc ArgExtractErr -> Str ``` **Description** Render [ArgExtractErr] errors as readable messages. Used in [Cli.parse_or_display_message]. #### format_cli_validation_err **Type Annotation** ```roc CliValidationErr -> Str ``` **Description** Render [CliValidationErr] errors as readable messages. Displayed as the crash message when [Cli.assert_valid] fails. ### Help #### help_text **Type Annotation** ```roc CliConfig, List Str, TextStyle -> Str ``` **Description** Render the help text for a command at or under the root config. The second argument should be a list of subcommand names, e.g. `["example", "subcommand-1", "subcommand-2"]`. If the subcommand isn't found, the root command's help page is rendered by default. ```roc example_cli = Opt.count { short: "v", help: "How verbose our logs should be." } |> Cli.finish { name: "example", version: "v0.1.0", description: "An example CLI.", } |> Cli.assert_valid expect help_text example_cli.config ["example"] == """ example v0.1.0 An example CLI. Usage: example -v [OPTIONS] Options: -v How verbose our logs should be. -h, --help Show this help page. -V, --version Show the version. """ ``` #### usage_help **Type Annotation** ```roc CliConfig, List Str, TextStyle -> Str ``` **Description** Render just the usage text for a command at or under the root config. The second argument should be a list of subcommand names, e.g. `["example", "subcommand-1", "subcommand-2"]`. If the subcommand isn't found, the root command's usage text is rendered by default. ```roc example_cli = Opt.count { short: "v", help: "How verbose our logs should be." } |> Cli.finish { name: "example", version: "v0.1.0", description: "An example CLI.", } |> Cli.assert_valid expect help_text example_cli.config ["example"] == """ Usage: example -v [OPTIONS] """ ``` ### Param #### single **Type Annotation** ```roc DefaultableParameterConfigParams data -> CliBuilder data {}action GetParamsAction ``` **Description** Add a required parameter of a custom type to your CLI builder. You need to provide a kebab-case type name for your help messages as well as a parser for said type. The parser needs to return an `Err (InvalidValue Str)` on failure, where the `Str` is the reason the parsing failed that will get displayed in the incorrect usage message. Parsing arguments will fail if the parameter fails to parse or is not provided. Parameters must be provided last after any option or subcommand fields, as they are parsed last of the three extracted values, and parameter list fields cannot be followed by any other fields. This is enforced using the type state pattern, where we encode the state of the program into its types. If you're curious, check the internal `Builder` module to see how this works using the `action` type variable. ```roc expect Color : [Green, Red, Blue] parse_color : Arg -> Result Color [InvalidValue Str, InvalidUtf8] parse_color = \color -> when Arg.to_str color is Ok "green" -> Ok Green Ok "red" -> Ok Red Ok "blue" -> Ok Blue other -> Err (InvalidValue "'$(other)' is not a valid color, must be green, red, or blue") { parser } = Param.single { name: "answer", type: "color", parser: parse_color }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "blue"] == SuccessfullyParsed Blue ``` #### maybe **Type Annotation** ```roc ParameterConfigParams data -> CliBuilder (Result data [NoValue]) {}action GetParamsAction ``` **Description** Add an optional parameter of a custom type to your CLI builder. You need to provide a kebab-case type name for your help messages as well as a parser for said type. The parser needs to return an `Err (InvalidValue Str)` on failure, where the `Str` is the reason the parsing failed that will get displayed in the incorrect usage message. Parsing arguments will fail if the parameter fails to parse. Parameters must be provided last after any option or subcommand fields, as they are parsed last of the three extracted values, and parameter list fields cannot be followed by any other fields. This is enforced using the type state pattern, where we encode the state of the program into its types. If you're curious, check the internal `Builder` module to see how this works using the `action` type variable. ```roc expect Color : [Green, Red, Blue] parse_color : Arg -> Result Color [InvalidValue Str, InvalidUtf8] parse_color = \color -> when Arg.to_str color is Ok "green" -> Ok Green Ok "red" -> Ok Red Ok "blue" -> Ok Blue other -> Err (InvalidValue "'$(other)' is not a valid color, must be green, red, or blue") { parser } = Param.maybe { name: "answer", type: "color", parser: parse_color }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### list **Type Annotation** ```roc ParameterConfigParams data -> CliBuilder (List data) {}action StopCollectingAction ``` **Description** Add a parameter of a custom type that can be provided multiple times to your CLI builder. You need to provide a kebab-case type name for your help messages as well as a parser for said type. The parser needs to return an `Err (InvalidValue Str)` on failure, where the `Str` is the reason the parsing failed that will get displayed in the incorrect usage message. Parsing arguments will fail if any of the values fail to parse. Parameters must be provided last after any option or subcommand fields, as they are parsed last of the three extracted values, and parameter list fields cannot be followed by any other fields. This is enforced using the type state pattern, where we encode the state of the program into its types. If you're curious, check the internal `Builder` module to see how this works using the `action` type variable. ```roc expect Color : [Green, Red, Blue] parse_color : Arg -> Result Color [InvalidValue Str, InvalidUtf8] parse_color = \color -> when Arg.to_str color is Ok "green" -> Ok Green Ok "red" -> Ok Red Ok "blue" -> Ok Blue other -> Err (InvalidValue "'$(other)' is not a valid color, must be green, red, or blue") { parser } = Param.list { name: "answer", type: "color", parser: parse_color }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "blue", "red", "green"] == SuccessfullyParsed [Blue, Red, Green] ``` #### arg **Type Annotation** ```roc DefaultableParameterConfigBaseParams Arg -> CliBuilder Arg {}action GetParamsAction ``` **Description** Add a required [Arg] parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided. ```roc expect { parser } = Param.arg { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "abc"] == SuccessfullyParsed (Arg.from_str "abc") ``` #### maybe_arg **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder ArgValue {}action GetParamsAction ``` **Description** Add an optional [Arg] parameter to your CLI builder. Parsing arguments cannot fail because of this parameter. ```roc expect { parser } = Param.maybe_arg { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### arg_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List Arg) {}action StopCollectingAction ``` **Description** Add an [Arg] parameter that can be provided multiple times to your CLI builder. Parsing arguments cannot fail because of this parameter. ```roc expect { parser } = Param.arg_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "abc", "def", "ghi"] == SuccessfullyParsed (List.map ["abc", "def", "ghi"] Arg.from_str) ``` #### bytes **Type Annotation** ```roc DefaultableParameterConfigBaseParams (List U8) -> CliBuilder (List U8) {}action GetParamsAction ``` **Description** Add a required byte list parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided. ```roc expect { parser } = Param.arg { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "abc"] == SuccessfullyParsed [97, 98, 99] ``` #### maybe_bytes **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result (List U8) [NoValue]) {}action GetParamsAction ``` **Description** Add an optional byte list parameter to your CLI builder. Parsing arguments cannot fail because of this parameter. ```roc expect { parser } = Param.maybe_bytes { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### bytes_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List (List U8)) {}action StopCollectingAction ``` **Description** Add a byte list parameter that can be provided multiple times to your CLI builder. Parsing arguments cannot fail because of this parameter. ```roc expect { parser } = Param.bytes_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "abc", "def", "ghi"] == SuccessfullyParsed [[97, 98, 99], [100, 101, 102], [103, 104, 105]] ``` #### str **Type Annotation** ```roc DefaultableParameterConfigBaseParams Str -> CliBuilder Str {}action GetParamsAction ``` **Description** Add a required string parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or if it is not valid UTF-8. ```roc expect { parser } = Param.str { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "abc"] == SuccessfullyParsed "abc" ``` #### maybe_str **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result Str [NoValue]) {}action GetParamsAction ``` **Description** Add an optional string parameter to your CLI builder. Parsing arguments will fail if the parameter is not valid UTF-8. ```roc expect { parser } = Param.maybe_str { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### str_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List Str) {}action StopCollectingAction ``` **Description** Add a string parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the arguments are not valid UTF-8. ```roc expect { parser } = Param.str_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "abc", "def", "ghi"] == SuccessfullyParsed ["abc", "def", "ghi"] ``` #### dec **Type Annotation** ```roc DefaultableParameterConfigBaseParams Dec -> CliBuilder Dec {}action GetParamsAction ``` **Description** Add a required `Dec` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.dec { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42.5"] == SuccessfullyParsed 42.5 ``` #### maybe_dec **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result Dec [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `Dec` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_dec { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### dec_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List Dec) {}action StopCollectingAction ``` **Description** Add a `Dec` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.dec_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56.0"] == SuccessfullyParsed [12.0, 34.0, -56.0] ``` #### f32 **Type Annotation** ```roc DefaultableParameterConfigBaseParams F32 -> CliBuilder F32 {}action GetParamsAction ``` **Description** Add a required `F32` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.f32 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42.5"] == SuccessfullyParsed 42.5 ``` #### maybe_f32 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result F32 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `F32` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_f32 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### f32_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List F32) {}action StopCollectingAction ``` **Description** Add a `F32` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.f32_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56.0"] == SuccessfullyParsed [12.0, 34.0, -56.0] ``` #### f64 **Type Annotation** ```roc DefaultableParameterConfigBaseParams F64 -> CliBuilder F64 {}action GetParamsAction ``` **Description** Add a required `F64` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.f64 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42.5"] == SuccessfullyParsed 42.5 ``` #### maybe_f64 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result F64 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `F64` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_f64 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### f64_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List F64) {}action StopCollectingAction ``` **Description** Add a `F64` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.f64_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56.0"] == SuccessfullyParsed [12, 34, -56.0] ``` #### u8 **Type Annotation** ```roc DefaultableParameterConfigBaseParams U8 -> CliBuilder U8 {}action GetParamsAction ``` **Description** Add a required `U8` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.u8 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_u8 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result U8 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `U8` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_u8 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u8_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List U8) {}action StopCollectingAction ``` **Description** Add a `U8` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.u8_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "56"] == SuccessfullyParsed [12, 34, 56] ``` #### u16 **Type Annotation** ```roc DefaultableParameterConfigBaseParams U16 -> CliBuilder U16 {}action GetParamsAction ``` **Description** Add a required `U16` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.u16 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_u16 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result U16 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `U16` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_u16 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u16_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List U16) {}action StopCollectingAction ``` **Description** Add a `U16` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.u16_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "56"] == SuccessfullyParsed [12, 34, 56] ``` #### u32 **Type Annotation** ```roc DefaultableParameterConfigBaseParams U32 -> CliBuilder U32 {}action GetParamsAction ``` **Description** Add a required `U32` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.u32 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_u32 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result U32 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `U32` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_u32 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u32_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List U32) {}action StopCollectingAction ``` **Description** Add a `U32` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.u32_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "56"] == SuccessfullyParsed [12, 34, 56] ``` #### u64 **Type Annotation** ```roc DefaultableParameterConfigBaseParams U64 -> CliBuilder U64 {}action GetParamsAction ``` **Description** Add a required `U64` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.u64 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_u64 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result U64 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `U64` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_u64 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u64_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List U64) {}action StopCollectingAction ``` **Description** Add a `U64` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.u64_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "56"] == SuccessfullyParsed [12, 34, 56] ``` #### u128 **Type Annotation** ```roc DefaultableParameterConfigBaseParams U128 -> CliBuilder U128 {}action GetParamsAction ``` **Description** Add a required `U128` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.u128 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_u128 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result U128 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `U128` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_u128 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### u128_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List U128) {}action StopCollectingAction ``` **Description** Add a `U128` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.u128_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "56"] == SuccessfullyParsed [12, 34, 56] ``` #### i8 **Type Annotation** ```roc DefaultableParameterConfigBaseParams I8 -> CliBuilder I8 {}action GetParamsAction ``` **Description** Add a required `I8` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.i8 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_i8 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result I8 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `I8` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_i8 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i8_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List I8) {}action StopCollectingAction ``` **Description** Add an `I8` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.i8_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56"] == SuccessfullyParsed [12, 34, -56] ``` #### i16 **Type Annotation** ```roc DefaultableParameterConfigBaseParams I16 -> CliBuilder I16 {}action GetParamsAction ``` **Description** Add a required `I16` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.i16 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_i16 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result I16 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `I16` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_i16 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i16_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List I16) {}action StopCollectingAction ``` **Description** Add an `I16` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.i16_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56"] == SuccessfullyParsed [12, 34, -56] ``` #### i32 **Type Annotation** ```roc DefaultableParameterConfigBaseParams I32 -> CliBuilder I32 {}action GetParamsAction ``` **Description** Add a required `I32` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.i32 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_i32 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result I32 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `I32` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_i32 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i32_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List I32) {}action StopCollectingAction ``` **Description** Add an `I32` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.i32_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56"] == SuccessfullyParsed [12, 34, -56] ``` #### i64 **Type Annotation** ```roc DefaultableParameterConfigBaseParams I64 -> CliBuilder I64 {}action GetParamsAction ``` **Description** Add a required `I64` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.i64 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_i64 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result I64 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `I64` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_i64 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i64_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List I64) {}action StopCollectingAction ``` **Description** Add an `I64` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.i64_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56"] == SuccessfullyParsed [12, 34, -56] ``` #### i128 **Type Annotation** ```roc DefaultableParameterConfigBaseParams I128 -> CliBuilder I128 {}action GetParamsAction ``` **Description** Add a required `I128` parameter to your CLI builder. Parsing arguments will fail if the parameter is not provided or it is not a valid number. ```roc expect { parser } = Param.i128 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "42"] == SuccessfullyParsed 42 ``` #### maybe_i128 **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (Result I128 [NoValue]) {}action GetParamsAction ``` **Description** Add an optional `I128` parameter to your CLI builder. Parsing arguments will fail if the parameter is not a valid number. ```roc expect { parser } = Param.maybe_i128 { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example"] == SuccessfullyParsed (Err NoValue) ``` #### i128_list **Type Annotation** ```roc ParameterConfigBaseParams -> CliBuilder (List I128) {}action StopCollectingAction ``` **Description** Add an `I128` parameter that can be provided multiple times to your CLI builder. Parsing arguments will fail if any of the parameters are not valid numbers. ```roc expect { parser } = Param.i128_list { name: "answer" }, |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "12", "34", "--", "-56"] == SuccessfullyParsed [12, 34, -56] ``` ### SubCmd #### SubcommandParserConfig **Type Annotation** #### finish **Type Annotation** ```roc CliBuilder state fromAction toAction, { name : Str, description ? Str, mapper : state -> commonState } -> { name : Str, parser : ArgParser commonState, config : SubcommandConfig } ``` **Description** Bundle a CLI builder into a subcommand. Subcommands use the same CLI builder that top-level CLIs do, so they are composed using the same tools. The difference lies in how subcommands are prepared for usage by parents. In addition to providing a `name` and a `description`, you also provide a `mapper`, which is a function that converts the subcommand's data into a common type that all subcommands under a parent command need to share. This is required since the parent command will have a field (added with the [field] function) that must have a unified type. ```roc fooSubcommand = { Cli.weave <- foo: Opt.str { short: "f" }, bar: Opt.str { short: "b" }, } |> SubCmd.finish { name: "foobar", description: "Foo and bar subcommand", mapper: FooBar } ``` #### optional **Type Annotation** ```roc List (SubcommandParserConfig sub_state) -> CliBuilder (Result sub_state [NoSubcommand]) GetOptionsAction GetParamsAction ``` **Description** Use previously defined subcommands as data in a parent CLI builder. Once all options have been parsed, we then check the first parameter passed to see if it's one of the provided subcommands. If so, we parse the remaining arguments as that subcommand's data, and otherwise continue parsing the current command. The [optional] function can only be used after all `Opt` fields have been registered (if any) as we don't want to parse options for a subcommand instead of a parent, and cannot be used after any parameters have been registered. This is enforced using the type state pattern, where we encode the state of the program into its types. If you're curious, check the internal `Builder` module to see how this works using the `action` type variable. ```roc expect foo_subcommand = Opt.str { short: "f" } |> SubCmd.finish { name: "foo", description: "Foo subcommand", mapper: Foo } bar_subcommand = Opt.str { short: "b" } |> SubCmd.finish { name: "bar", description: "Bar subcommand", mapper: Bar } { parser } = SubCmd.optional [foo_subcommand, bar_subcommand], |> Cli.finish { name: "example" } |> Cli.assert_valid parser ["example", "bar", "-b", "abc"] == SuccessfullyParsed (Ok (Bar "abc")) ``` #### required **Type Annotation** ```roc List (SubcommandParserConfig sub_data) -> CliBuilder sub_data GetOptionsAction GetParamsAction ``` **Description** Use previously defined subcommands as data in a parent CLI builder. Once all options have been parsed, we then check the first parameter passed to see if it's one of the provided subcommands. If so, we parse the remaining arguments as that subcommand's data, and otherwise we fail parsing. The [required] function can only be used after all `Opt` fields have been registered (if any) as we don't want to parse options for a subcommand instead of a parent, and cannot be used after any parameters have been registered. This is enforced using the type state pattern, where we encode the state of the program into its types. If you're curious, check the internal `Builder` module to see how this works using the `action` type variable. ```roc expect foo_subcommand = Opt.str { short: "f" } |> SubCmd.finish { name: "foo", description: "Foo subcommand", mapper: Foo } bar_subcommand = Opt.str { short: "b" } |> SubCmd.finish { name: "bar", description: "Bar subcommand", mapper: Bar } { parser } = SubCmd.required [foo_subcommand, bar_subcommand], |> Cli.finish { name: "example" } |> Cli.assertValid parser ["example", "bar", "-b", "abc"] == SuccessfullyParsed (Bar "abc") ``` ### Validate #### CliValidationErr **Type Annotation** **Description** The types of errors that might be found in a misconfigured CLI. #### validate_cli **Type Annotation** ```roc CliConfig -> Result {} CliValidationErr ``` **Description** Ensure that a CLI's 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. - 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.