addOptionsToReceiver function

void addOptionsToReceiver(
  1. Iterable<OptionDefinition> argNameOpts,
  2. OptionReceiver receiver, {
  3. bool addGroupSeparators = false,
})

Adds argNameOpts to argParser.

When addGroupSeparators is true,

  • options are grouped by OptionGroup and a
  • separator with the group name is inserted
  • before each group that has at least one visible option.
  • Note:
    • groupless options are added first in their original order
    • relative order of all options within a group is preserved
    • relative order of all groups is preserved

By default, addGroupSeparators is false to ensure backwards compatibility.

Implementation

void addOptionsToReceiver(
  final Iterable<OptionDefinition> argNameOpts,
  final OptionReceiver receiver, {
  final bool addGroupSeparators = false,
}) {
  // plain option-addition without any group separator logic
  if (!addGroupSeparators) {
    for (final o in argNameOpts) {
      receiver.addOption(o.option);
    }
    return;
  }

  // the following containers are ordered by default i.e.
  // preserves insertion-order:
  // - Map  : https://stackoverflow.com/q/79786585/10251345
  // - List : https://api.dart.dev/dart-core/List-class.html
  final optionGroups = <OptionGroup, List<OptionDefinition>>{};
  final grouplessOptions = <OptionDefinition>[];

  // gather all necessary option-group information
  for (final opt in argNameOpts) {
    final group = opt.option.group;
    if (group != null) {
      optionGroups.update(
        group,
        (final options) => options..add(opt),
        ifAbsent: () => [opt],
      );
    } else {
      grouplessOptions.add(opt);
    }
  }

  // add all groupless-options first (in order)
  for (final o in grouplessOptions) {
    receiver.addOption(o.option);
  }

  // add all explicit groups (in order)
  optionGroups.forEach((final group, final groupedOptions) {
    // add the group-name-separator only if it has at least one visible option
    if (groupedOptions.any((final o) => !o.option.hide)) {
      receiver.addSeparator(group.name);
    }
    // add all options within this group (in order)
    for (final o in groupedOptions) {
      receiver.addOption(o.option);
    }
  });
}