Overview

GOptions : provides a unified framework to define, parse, validate, and persist configuration coming from YAML files and command-line arguments. It is designed to support:

small executables (a handful of options),
large frameworks/plugins (many modules contributing options),
reproducible batch workflows (automatic YAML snapshot of resolved configuration).

The subsystem is built around:

GSwitch : a presence-based boolean flag (e.g. -gui).
GOption : an option value container that can be scalar or structured.
GVariable : a schema entry used when defining scalar options or structured option keys.

Configuration sources are resolved in increasing precedence: schema defaults, YAML input, and finally command-line values. Dot-notation command-line updates replace one structured subkey without requiring the complete option value to be repeated.

Configuration source precedence and structured updates

Concepts

Switches

A GSwitch : is a lightweight boolean flag:

default is off,
specifying -<name> on the command line turns it on.

Example:

myprog -gui

Scalar options

A scalar GOption : stores exactly one value as a YAML scalar. Values can be supplied via:

YAML:
runno: 12
Command line:
myprog -runno=12

Structured options

A structured GOption : stores either:

a YAML map, or
a YAML sequence (commonly a sequence of maps).

A typical pattern is a sequence of maps where each entry represents one repeated item:

gparticle:
 - name: e-
   p: 1500
   theta: 23.0
   multiplicity: 4

Equivalent command-line option (quotes are usually required so your shell does not split the string):

myprog -gparticle="[{name: e-, p: 1500, theta: 23.0, multiplicity: 4}]"

Cumulative structured options and mandatory keys

Structured options can be declared cumulative when at least one schema key uses goptions::NODFLT : as its default value. That tells GOption : that:

the option expects a sequence of maps (multiple entries),
those keys are mandatory and must appear in every entry.

Missing non-mandatory keys are back-filled from schema defaults so every entry becomes complete.

Dot-notation updates for structured sub-options

Some structured options are updated using dot-notation:

myprog -verbosity.gemc=1

myprog -debug.gemc=true

This updates a single subkey within a structured option via set_sub_option_value() .

Verbosity and debug behavior

This module defines two conventional structured options commonly used across the project:

verbosity (integer levels)
debug (boolean or integer)

Typical semantics used by classes that consume these settings:

Level 0: minimal output ("shush") — only essential messages.
Level 1: detailed informational output — key configuration and progress.
Level 2: extra detailed output — expanded per-step or per-event diagnostics.
debug=true (or debug > 0): developer-focused diagnostics — internal state, parsing details, and other troubleshooting information beyond normal verbosity.

Examples

The following example program is provided with this module:

examples/define_options.cc : Defines switches and options (scalar + structured), constructs a parsing GOptions : instance, and reads back resolved values with typed getters.

Extensibility via merging option definitions

Frameworks or plugins can define their own options and switches, then merge them into the executable’s definition set using operator+=() (which internally calls addGOptions()).