#parse_args

A simple and lightweight command-line argument parser for MoonBit.

Parse boolean flags, string options, and repeated collections with support for aliases, negatable flags, and combined short flags. Unknown options are treated as positional arguments, not errors.

#Installation

moon add peter_jerry_ye/parse_args

#Basic Usage

///|
test {
  let result = parse(
    ["--verbose", "-o", "output.txt", "input.txt"],
    flags=["verbose"],
    options=["output", "o"],
  )

  // Access parsed arguments
  assert_true(result.flags.get("verbose") is Some(true))
  assert_true(result.options is { "o": "output.txt", .. })
  assert_true(result.positional is ["input.txt"])
}

#Example

///|
test {
  // Define aliases: short flags map to long names
  let aliases = { "v": "verbose", "o": "output", "I": "include", "q": "quiet" }

  // Parse a complex command line with multiple features:
  // - Combined short flags: -vq (verbose + quiet)
  // - Option with value: -o output.txt (using alias)
  // - Negatable flag: --no-color (explicitly set to false)
  // - Collections: --include multiple times
  // - Key-value syntax: --format=json
  // - Positional arguments: input.txt
  let result = parse(
    [
      "-vq", // Combined short flags
       "-o", "output.txt", // Option with alias
       "--no-color", // Negatable flag
       "--include", "src", // Collection (first)
       "-I", "lib", // Collection (second, using alias)
       "--format=json", // Key-value syntax
       "input.txt", // Positional argument
    ],
    flags=["verbose", "quiet", "color"], // Define boolean flags
    options=["output", "format"], // Define string options
    collections=["include"], // Define repeated options
    negatable=["color"], // Allow --no-color
    aliases~, // Use the aliases map
  )

  // Access boolean flags
  assert_true(
    result.flags is { "verbose": true, "quiet": true, "color": false, .. },
  )

  // Access string options
  assert_true(
    result.options is { "output": "output.txt", "format": "json", .. },
  )

  // Access collections (multiple values)
  debug_inspect(
    result.collections.get("include"),
    content="Some([\"src\", \"lib\"])",
  )

  // Access positional arguments
  debug_inspect(result.positional, content="[\"input.txt\"]")
}

///|
test {
  // Error handling: option requires a value
  let _ = parse(["--output"], options=["output"]) catch {
    ParseError(msg) => {
      debug_inspect(msg, content="\"Option --output requires a value\"")
      return
    }
  }
  fail("Should have raised an error")
}

#What It Does

Parse boolean flags (--verbose, -v, combined -vq)
Parse string options (--output file.txt, --output=file.txt)
Parse repeated options (collections: --include src --include lib)
Support aliases (-v → --verbose)
Negatable flags (--no-verbose)
Reject values for boolean flags (--verbose=true)
Reject conflicting or invalid argument declarations
Handle -- separator (everything after is positional)
Stop early for subcommand parsing (stop_early=true)
Treat unknown options as positional arguments

#What It Doesn't Do

No automatic help generation
No required argument checking
No type conversion (all values are strings)
No default values
No environment variable support

#
ParseError

source

pub suberror ParseError {
  ParseError(String)
}

#
Args

source

pub struct Args {
  positional : Array[String]
  flags : Map[String, Bool]
  options : Map[String, String]
  collections : Map[String, Array[String]]
}

Represents parsed command line arguments

#
parse

source

fn parse(args : ArrayView[String], flags? : ArrayView[String], options? : ArrayView[String], collections? : ArrayView[String], aliases? : Map[String, String], negatable? : ArrayView[String], double_dash? : Bool, stop_early? : Bool) -> Args raise ParseError