go-ruby-optparse

Ruby's OptionParser argv-parsing engine in pure Go — MRI-compatible, no cgo.

pure Go · zero cgo OptionParser core long · short · abbrev bundled flags --[no-]opt type coercion parse! · order! · permute! getopts full error taxonomy MRI byte-exact 100% coverage 6 arches
Documentation GitHub
Documentation (MkDocs Material + mike) License: BSD-3-Clause Go 1.26.4+ Coverage 100%

go-ruby-optparse is a pure-Go (no cgo) reimplementation of MRI's OptionParser argv-parsing engine — the interpreter-independent core that decides how an argument vector is matched against an option specification. It does the deterministic work: long, short, abbreviated and bundled options, the --[no-]opt negation form, type coercion, and the parse! / order! / permute! / getopts dispatch modes, with MRI's full error taxonomy (ambiguous, missing argument, invalid option, …). The per-option callbacks stay in the host, where the interpreter lives. It was extracted from rbgo's prelude/internals into a reusable standalone library: no dependency on the Ruby runtime, the dependency runs the other way. It is the OptionParser backend for go-embedded-ruby, bound by rbgo as a native module just like go-ruby-regexp and go-ruby-erb — differential-tested against MRI, 100% coverage, CI green across 6 arches and 3 OSes.

Option specification ready

The Spec model for an option: long and short names, whether it takes a required/optional argument, the --[no-] negation form, and the coercion type — built the way OptionParser#on describes one.

argv matching ready

Matching an argv against the spec: long --opt, short -o, unambiguous abbreviations, bundled short flags -abc, --opt=val and -oval argument attachment — exactly MRI’s rules.

Dispatch modes ready

parse! (permute, consume), order! (stop at the first non-option), permute! and the getopts convenience mode — each leaving the residual argv as MRI does.

Type coercion ready

Coercion of option arguments to Integer, Float, and the other built-in OptionParser accept-types, raising MRI’s InvalidArgument on a bad value.

Error taxonomy ready

MRI’s full OptionParser::ParseError family — AmbiguousOption, InvalidOption, MissingArgument, NeedlessArgument, InvalidArgument — surfaced as typed Go errors.

Differential oracle & coverage ready

A wide argv/spec corpus parsed both here and by the system ruby, compared against MRI’s residual argv and error classes; 100% coverage, gofmt + go vet clean, green across all six 64-bit Go arches and three OSes.

A faithful port of MRI's lib/optparse.rb matching engine in pure Go, cgo disabled, so it cross-compiles and embeds anywhere. It implements long / short / abbreviated / bundled options, the --[no-]opt form, type coercion, and the parse! / order! / permute! / getopts modes with the full error taxonomy. The per-option callbacks stay in the host. Validated differentially against the system ruby binary. It is a standalone, reusable module extracted from rbgo's internals, and the OptionParser backend for the sibling org github.com/go-embedded-ruby.