goptions

Table of Contents

• Overview
• Concepts
  • Switches
  • Scalar options
  • Structured options
  • Cumulative structured options and mandatory keys
  • Dot-notation updates for structured sub-options
• Verbosity and debug behavior
• Logging and GUI language
• Examples
• Extensibility via merging option definitions
• YAML parsing and validation
• Ownership and maintenance

Configuration definition, merge, and validation

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::REQUIRED : 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.

Logging and GUI language

Upcoming in the next release: the scalar language option defaults to auto, letting GLogger and the Qt GUI select the language without requiring a user option. An explicit -language=it or YAML language: it overrides GEMC_LANGUAGE and locale detection; -language=en forces English. Supported values are:

• auto: detect the user's language automatically (default).
• en: English, using the original English messages.
• it: italiano (Italian).
• ja: 日本語 (Japanese).
• fr: français (French).
• zh: 中文 (Chinese).

Automatic detection checks GEMC_LANGUAGE, LC_ALL, LC_MESSAGES, and LANG, then native settings or English. Regional tags such as it_IT.UTF-8 use the base language when a regional entry is missing. C and POSIX locales select English. Missing translations use the original English template, without changing numeric formatting. The startup/version banner shares these catalogs; paths, dates, citation, and author are parameters. -v -language=it honors overrides before or after the version flag. Version remains an early action without reading YAML; the normal startup banner uses the fully parsed command-line/YAML settings.

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()).

Example:

goptions += eventDispenser::defineOptions();
goptions += g4display::defineOptions();
goptions += g4system::defineOptions();

YAML parsing and validation

YAML parsing is implemented using the yaml-cpp library. When a YAML file fails to parse, the option manager exits with a dedicated exit code so batch workflows can detect the failure mode.

Ownership and maintenance

The goptions module is maintained as part of GEMC and is intended to be:

• stable at the API level for consumers of GOptions : ,
• strict and explicit about error reporting (exit codes) for batch reproducibility,
• documentation-first: headers contain authoritative API docs; implementation files avoid duplication.

Author

© Maurizio Ungaro
e-mail: ungar.nosp@m.o@jl.nosp@m.ab.or.nosp@m.g