Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,9 +237,10 @@ The library provides a rich set of typed options out of the box. All option type

| Value Type | Option Class | Additional Settings | Description |
|------|-------|---------------------|-------------|
| String | `StringOption` | None | String values |
| String | `StringOption` | `requireNonEmpty` | Whether a non-empty string is required |
| Boolean | `FlagOption` | `negatable` | Whether the flag can be negated |
| Integer | `IntOption` | `min`<br>`max` | Minimum allowed value<br>Maximum allowed value |
| Double | `DoubleOption` | `min`<br>`max` | Minimum allowed value<br>Maximum allowed value |
| DateTime | `DateTimeOption` | `min`<br>`max` | Minimum allowed date/time<br>Maximum allowed date/time |
| Duration | `DurationOption` | `min`<br>`max` | Minimum allowed duration<br>Maximum allowed duration |
| Any Enum | `EnumOption<E>` | None | Typed enum values |
Expand Down
4 changes: 2 additions & 2 deletions packages/config/example/main.dart
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ import 'package:config/config.dart';
///
/// Command line usage:
/// ```sh
/// --until=<YYYY-MM-DDtHH:MM:SSz> The end timestamp of the series
/// (defaults to "2025-08-08 12:06:49.611906")
/// --until=<YYYY-MM-DDTHH:MM:SSZ> The end timestamp of the series
/// (defaults to "2025-08-08T12:06:49.611906")
/// -l, --length=<integer> The number of elements in the series
/// -i, --interval=<integer[us|ms|s|m|h|d]> The interval between the series elements
/// ```
Expand Down
2 changes: 1 addition & 1 deletion packages/config/lib/src/command/usage/options_usage.dart
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,7 @@ class OptionsUsageGenerator {
final format = option.multiParser.elementParser.format;
return def.any((final element) => format(element) == value);
}
return option.defaultValueString() == value;
return option.valueParser.format(def) == value;
}
}

Expand Down
107 changes: 96 additions & 11 deletions packages/config/lib/src/config/arg_parser_bridge.dart
Original file line number Diff line number Diff line change
Expand Up @@ -86,16 +86,25 @@ class OldParsedArgs implements ParsedArgs {
String oldUsage(final Iterable<OptionDefinition> options) {
final parser = ArgParser();
final argOptions = options.where((final o) => o.option.argName != null);
addOptionsToParser(argOptions, parser, addGroupSeparators: true);
addOptionsToParser(
argOptions,
parser,
addGroupSeparators: true,
usageOnly: true,
);
return parser.usage;
}

void addOptionsToParser(
final Iterable<OptionDefinition> argNameOpts,
final ArgParser argParser, {
final bool addGroupSeparators = false,
final bool usageOnly = false,
}) {
final receiver = _ArgParserOptionCollection(argParser);
final receiver = _ArgParserOptionCollection(
argParser,
usageOnly: usageOnly,
);
addOptionsToReceiver(
argNameOpts,
receiver,
Expand All @@ -105,8 +114,12 @@ void addOptionsToParser(

class _ArgParserOptionCollection implements OptionReceiver {
final ArgParser argParser;
final bool usageOnly;

_ArgParserOptionCollection(this.argParser);
_ArgParserOptionCollection(
this.argParser, {
required this.usageOnly,
});

@override
void addSeparator(final String separator) {
Expand All @@ -115,11 +128,15 @@ class _ArgParserOptionCollection implements OptionReceiver {

@override
void addOption(final OptionDefinition option) {
_addToArgParser(option, argParser);
_addToArgParser(option, argParser, usageOnly: usageOnly);
}
}

void _addToArgParser(final OptionDefinition option, final ArgParser argParser) {
void _addToArgParser(
final OptionDefinition option,
final ArgParser argParser, {
required final bool usageOnly,
}) {
final opt = option.option;
final argName = opt.argName;
if (argName == null) {
Expand All @@ -131,8 +148,8 @@ void _addToArgParser(final OptionDefinition option, final ArgParser argParser) {
argParser.addFlag(
argName,
abbr: opt.argAbbrev,
help: opt.helpText,
defaultsTo: opt.defaultValue(),
help: _flagHelp(opt, usageOnly: usageOnly),
defaultsTo: _flagDefault(opt, usageOnly: usageOnly),
negatable: opt.negatable,
hideNegatedUsage: opt.hideNegatedUsage,
hide: opt.hide,
Expand All @@ -149,9 +166,7 @@ void _addToArgParser(final OptionDefinition option, final ArgParser argParser) {
opt.multiParser.elementParser.format,
),
allowedHelp: opt.allowedHelp,
defaultsTo: opt.defaultValue()?.map(
opt.multiParser.elementParser.format,
),
defaultsTo: _legacyMultiDefaults(opt, usageOnly: usageOnly),
hide: opt.hide,
splitCommas: opt.multiParser.separator == ',',
aliases: opt.argAliases ?? const [],
Expand All @@ -165,10 +180,80 @@ void _addToArgParser(final OptionDefinition option, final ArgParser argParser) {
valueHelp: opt.valueHelpString(),
allowed: opt.allowedValues?.map(opt.valueParser.format),
allowedHelp: opt.allowedHelp,
defaultsTo: opt.defaultValueString(),
defaultsTo: _legacyDefaultString(opt, usageOnly: usageOnly),
mandatory: opt.mandatory,
hide: opt.hide,
aliases: opt.argAliases ?? const [],
);
}
}

/// Help text for a flag on the legacy parser.
///
/// [package:args] prints `(defaults to on)` from the boolean default and has
/// no slot for custom default text. Usage-only parsers put
/// [FlagOption.defaultValueHelp] in the help and omit that boolean line.
/// Parsers used to parse arguments keep [FlagOption.helpText] unchanged.
String? _flagHelp(final FlagOption opt, {required final bool usageOnly}) {
final help = opt.helpText;
if (!usageOnly) return help;
final custom = opt.defaultValueHelp;
if (custom == null) return help;
final line = '(defaults to $custom)';
if (help == null || help.isEmpty) return line;
return '$help\n$line';
}

/// Boolean default stored on the legacy parser.
///
/// A usage-only parser passes null when custom default text is shown, so
/// [package:args] does not also print `(defaults to on)`. A parser that
/// reads arguments keeps the real boolean.
bool? _flagDefault(final FlagOption opt, {required final bool usageOnly}) {
if (usageOnly && opt.defaultValueHelp != null) return null;
return opt.defaultValue();
}

/// Default string stored on the legacy parser.
///
/// Allowed values are matched against the formatted default to mark it,
/// so a custom help string is used only when there is nothing to match.
/// That help string is usage text: parsers that read arguments store the
/// formatted value instead, so an omitted option does not come back as the
/// help text.
String? _legacyDefaultString(
final ConfigOptionBase opt, {
required final bool usageOnly,
}) {
if (opt.allowedValues != null || opt.allowedHelp != null) {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
final value = opt.defaultValue();
if (value == null) return null;
return opt.valueParser.format(value);
}
if (!usageOnly) {
final value = opt.defaultValue();
if (value == null) return null;
return opt.valueParser.format(value);
}
return opt.defaultValueString();
}

/// Default list stored on the legacy parser for a [MultiOption].
///
/// Same rule as [_legacyDefaultString]: custom help text is only stored on
/// a parser that exists to render usage.
Iterable<String>? _legacyMultiDefaults(
final MultiOption opt, {
required final bool usageOnly,
}) {
final marksAllowed =
opt.allowedElementValues != null || opt.allowedHelp != null;
final help = opt.defaultValueHelp;
if (usageOnly &&
!marksAllowed &&
help != null &&
opt.defaultValue() != null) {
return [help];
}
return opt.defaultValue()?.map(opt.multiParser.elementParser.format);
}
1 change: 1 addition & 0 deletions packages/config/lib/src/config/config.dart
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ export 'config_source_provider.dart';
export 'configuration.dart';
export 'configuration_broker.dart';
export 'configuration_parser.dart';
export 'date_time_options.dart';
export 'exceptions.dart';
export 'file_system_options.dart';
export 'multi_config_source.dart';
Expand Down
6 changes: 5 additions & 1 deletion packages/config/lib/src/config/configuration.dart
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,11 @@ class Configuration<O extends OptionDefinition> {

final error = option.option.validateOptionValue(value);
if (error != null) return resolution.copyWithError(error);
return resolution;
if (value == null) return resolution;

final stored = option.option.valueToStore(value);
if (stored == value) return resolution;
return resolution.copyWithValue(stored);
}

void _validateGroups(
Expand Down
Loading
Loading