Option parser (std)

std/option_parser is written in Agentica: import OP from "std/option_parser" and import {Arg, Opt, Kind} from "std/option_parser". It has the shape of Python’s argparse and the names of Ruby’s OptionParser. It uses only structs, enums and Optional: no JSON.Value. You describe the program with Arg (a positional argument) and Opt (an option), parse checks the words, and typed getters read each value into your own struct.

OP.new(program: String, description: String = "", args: List[Arg] = [], opts: List[Opt] = [], rest: String = "") -> Parser
OP.parse(parser: Parser, args: List[String]) -> Result[Parsed]
OP.string(parsed: Parsed, name: String) -> String
OP.int(parsed: Parsed, name: String) -> Int
OP.float(parsed: Parsed, name: String) -> Float
OP.flag(parsed: Parsed, name: String) -> Bool
OP.optional_string(parsed: Parsed, name: String) -> Optional[String]
OP.optional_int(parsed: Parsed, name: String) -> Optional[Int]
OP.optional_float(parsed: Parsed, name: String) -> Optional[Float]
OP.rest(parsed: Parsed) -> List[String]
OP.after_dashes(parsed: Parsed) -> List[String]
OP.run!(result: Result[T]) -> T
OP.usage(parser: Parser) -> String
OP.help?(message: String) -> Bool
OP.message(error_text: String) -> String
import OP from "std/option_parser"
import {Arg, Opt, Kind as K} from "std/option_parser"

struct Options
  file: String
  port: Int
  verbose: Bool
  user: Optional[String]
end

def load() -> Result[Options]
  parser = OP.new(
    "tool",
    "Serves a file over HTTP",
    [Arg(name: "file", help: "file to serve")],
    [
      Opt(name: "port", short: "p", kind: K.Int, default: "8080", help: "port"),
      Opt(name: "verbose", short: "v", kind: K.Flag, help: "more output"),
      Opt(name: "user", kind: K.String, help: "user name"),
    ],
  )

  p = try OP.parse(parser, System.args())
  ok(
    Options(
      file: OP.string(p, "file"),
      port: OP.int(p, "port"),
      verbose: OP.flag(p, "verbose"),
      user: OP.optional_string(p, "user"),
    ),
  )
end

def main() -> Void
  options = OP.run!(load())
  puts("serving #{options.file} on :#{options.port}")
end

This is the whole program of a tool. parse is given System.args(), and OP.run! is where the program ends when the command line is wrong or asks for help.

Arg and Opt #

Both are structs with defaults, so a call names only the fields it needs. The two lists of new hold the arguments, in the order of the command line, and the options.

Arg(name: String, help: String = "", kind: Kind = Kind.String, choices: List[String] = [], metavar: String = "",
    min: Optional[Int] = none, max: Optional[Int] = none, min_float: Optional[Float] = none,
    max_float: Optional[Float] = none)
Opt(name: String, short: String = "", kind: Kind = Kind.String, default: String = "", choices: List[String] = [],
    help: String = "", metavar: String = "", min: Optional[Int] = none, max: Optional[Int] = none,
    min_float: Optional[Float] = none, max_float: Optional[Float] = none)

Kind is Int, Float, String or Flag. A Flag takes no value: it is false unless given, and it has no default or choices. An argument cannot be a Flag (an error of parse), and every argument is required. short is one character: not a digit, -, = or a space. A name has no space or control character, and program is not empty. default is a String that is converted by kind, as the command line is (default: "8080" for an Int); an empty default means the option has none. choices lists the allowed texts, compared as text before the conversion. metavar is the name of the value in the help (<file> for an argument); an option without one shows its choices as on|off, else its name in capitals (--user USER; set metavar: "DIR" for a path). min and max limit an Int option or argument (some(0), some(65535); none is no limit), and min_float and max_float a Float one (some(0.0), some(1.0)); they also apply to the default. A limit on another kind, a min above its max, or a Float limit that is not a finite number is an error of the specification.

The command line #

  • --port 3000, --port=3000, -p 3000, -p3000 and -p=3000 give a value to an option. As in argparse, the next word is taken as the value only if it does not look like an option: a word that does not start with -, a lone - and a negative number (-1, -2.5) are values. Any other word that starts with - is not, so --port --verbose is an error (option --port needs a value). --name=--x and -n--x give the literal --x.
  • A negative number is also an argument: tool -5 gives the argument -5. Any other word that starts with - is an option (use -- before it).
  • -v and --verbose set a flag, and short flags may be joined: -vq. The last letter of a joined group may take a value (-vp3000).
  • -- ends the options: every later word is an argument, as is a lone -.
  • An option given twice keeps its last value.
  • --help and -h ask for the help; the names help and h are reserved.

Getters #

string, int, float and flag return the plain value of an argument, of a flag, and of an option that has a default. optional_string, optional_int and optional_float return an Optional: none when the option was not given and has no default.

import OP from "std/option_parser"
import {Arg, Opt, Kind as K} from "std/option_parser"

def main() -> Void
  parser = OP.new(
    "tool",
    "",
    [Arg(name: "file")],
    [
      Opt(name: "port", short: "p", kind: K.Int, default: "8080"),
      Opt(name: "ratio", kind: K.Float),
      Opt(name: "verbose", short: "v", kind: K.Flag),
    ],
  )

  p = OP.parse(parser, ["-v", "--port=3000", "--", "-notes.txt"]).unwrap!
  puts(OP.string(p, "file"))
  puts(OP.int(p, "port"))
  puts(OP.flag(p, "verbose"))
  puts(OP.optional_float(p, "ratio"))
  q = OP.parse(parser, ["a.txt"]).unwrap!
  puts(OP.int(q, "port"))
  puts(OP.flag(q, "verbose"))
end
Output
-notes.txt
3000
true
none
8080
false

A getter called with a name that was not declared, with the getter of another kind, or on an option that may be absent (OP.string where optional_string is needed) is a bug of the program, not a mistake of its user. It halts with RUNTIME-UNWRAP-ERROR, whose message names the option and whose stack names the line of the call. It is not an Optional or a Result, so the getters stay plain.

The rest of the words #

Every argument is required, and a word past the last one is an error (unexpected argument 'g'), unless new gets a fifth argument, rest: the name of those words in the usage line ("FILE" shows [FILE...]; the rows of the help have none for it, and the name has no space or control character). parse then keeps them, and OP.rest(p) returns them in order, those after -- included, as Ruby’s OptionParser#parse returns the rest of ARGV. OP.after_dashes(p) returns the last words of rest that came after --, so a command such as check FILE... -- FLAGS splits them without looking at the words itself:

import OP from "std/option_parser"
import {Opt, Kind as K} from "std/option_parser"

def main() -> Void
  # The fifth argument, "FILE", names the rest in the usage line.
  parser = OP.new("check", "", [], [Opt(name: "verbose", short: "v", kind: K.Flag)], "FILE")
  p = OP.parse(parser, ["a.c", "-v", "b.c", "--", "-Iinclude", "-DX=1"]).unwrap!
  rest = OP.rest(p)
  flags = OP.after_dashes(p)
  puts(rest.take(rest.size - flags.size))
  puts(flags)
  puts(OP.usage(parser).split("\n")[0])
end
Output
["a.c", "b.c"]
["-Iinclude", "-DX=1"]
Usage: check [options] [FILE...]

Errors #

parse returns an error for a mistake of the command line. The text is tool: and a message that names the option or the argument, then a line Try 'tool --help' for more information. A program that prints the error itself prints OP.message(error_text): it is the text as it is, except for a request of help (below), where it leaves out a marker line that the raw text starts with. The messages are:

  • unknown option --bogus (or -x)
  • option --port needs a value
  • option --verbose does not take a value
  • invalid value for --port: 'abc' is not an Int (or a Float; '99999999999999999999' does not fit an Int for a number too big)
  • invalid value for --ratio: '1e400' does not fit a Float: a Float option or argument refuses a value that is not finite (+inf.0, -inf.0, +nan.0, or a number too big), with limits or without
  • invalid value for --user: 'cy' is not one of ana, bob
  • invalid value for --port: '70000' is above the maximum 65535 (or below the minimum; the maximum 1.0 for a Float)
  • missing argument <file>
  • unexpected argument 'g'

A mistake in the specification itself, such as a duplicate name, a short name that is not one character, or a default that does not convert, is an error of parse too (tool: invalid specification: invalid default for --port: 'x' is not an Int), without the hint.

import OP from "std/option_parser"
import {Opt, Kind as K} from "std/option_parser"

def main() -> Void
  parser = OP.new("tool", "", [], [Opt(name: "port", short: "p", kind: K.Int)])
  puts(OP.parse(parser, ["--port", "abc"]).message)
  puts(OP.parse(parser, ["--bogus"]).message)
end
Output
tool: invalid value for --port: 'abc' is not an Int
Try 'tool --help' for more information
tool: unknown option --bogus
Try 'tool --help' for more information

Help and run! #

--help or -h makes parse return an error for which OP.help?(message) is true and whose kind is option_parser.help; the text of the help is OP.usage(parser). A mistake in the words (an unknown option, a bad value) is an error of the kind option_parser.parse, and a bad specification one of the kind argument. It lists the usage line, the description, and one row for each argument and option, with its short and long names, the value name, the help, and notes in square brackets (so a help text may have its own parentheses): [default: X], [choices: a, b] when the value name does not already show them (an argument, or an option with a metavar), and [min: 0, max: 65535].

import OP from "std/option_parser"
import {Arg, Opt, Kind as K} from "std/option_parser"

def main() -> Void
  parser = OP.new(
    "tool",
    "Serves a file over HTTP",
    [Arg(name: "file", help: "file to serve")],
    [
      Opt(name: "port", short: "p", kind: K.Int, default: "8080", min: some(0), max: some(65535), help: "port"),
      Opt(name: "verbose", short: "v", kind: K.Flag, help: "more output"),
      Opt(name: "user", kind: K.String, choices: ["ana", "bob"], help: "user name"),
      Opt(name: "dir", metavar: "DIR", help: "model folder (a path)"),
    ],
  )

  result = OP.parse(parser, ["--help"])
  puts(OP.help?(result.message))
  puts(OP.usage(parser))
end
Output
true
Usage: tool [options] <file>

Serves a file over HTTP

Arguments:
  <file>              file to serve

Options:
  -p, --port PORT     port [default: 8080] [min: 0, max: 65535]
  -v, --verbose       more output
      --user ana|bob  user name
      --dir DIR       model folder (a path)
  -h, --help          show this help

On and off #

There is no Bool kind. A Flag takes no value, so a setting that is given as --stats on or --stats off is a String option with choices: ["on", "off"] (and usually a default). The help shows it as --stats on|off, any other word is refused, and the program reads it with OP.string(p, "stats") == "on". Use a Flag when giving the name alone is enough.

A program that handles the error itself tests OP.help?(message) first, or just prints OP.message(message), which gives the help text for a request of help and the message otherwise.

OP.run!(result) is the one function of the module that ends the program, and it is the usual last step. It returns the value of an ok. For the help it prints OP.usage to standard output and exits with 0; for any other error it prints the message to standard error and exits with 2. The name ends in ! as the halting functions do, because it does not return when the result is an error. A program that wants another behavior reads parse itself and calls System.exit.