Merge pull request #92 from dart-lang/cleanup
Clean up documentation and outdated names
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8771808..7cc69c0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,13 @@
+## 1.4.0
+
+* Deprecated `OptionType.FLAG`, `OptionType.SINGLE`, and `OptionType.MULTIPLE`
+ in favor of `OptionType.flag`, `OptionType.single`, and `OptionType.multiple`
+ which follow the style guide.
+
+* Deprecated `Option.abbreviation` and `Option.defaultValue` in favor of
+ `Option.abbr` and `Option.defaultsTo`. This makes all of `Option`'s fields
+ match the corresponding parameters to `ArgParser.addOption()`.
+
## 1.3.0
* Type `Command.run()`'s return value as `FutureOr<T>`.
diff --git a/lib/src/arg_parser.dart b/lib/src/arg_parser.dart
index 98312ec..c115197 100644
--- a/lib/src/arg_parser.dart
+++ b/lib/src/arg_parser.dart
@@ -77,7 +77,31 @@
return parser;
}
- /// Defines a flag. Throws an [ArgumentError] if:
+ /// Defines a boolean flag.
+ ///
+ /// This adds an [Option] with the given properties to [options].
+ ///
+ /// The [abbr] argument is a single-character string that can be used as a
+ /// shorthand for this flag. For example, `abbr: "a"` will allow the user to
+ /// pass `-a` to enable the flag.
+ ///
+ /// The [help] argument is used by [usage] to describe this flag.
+ ///
+ /// The [defaultsTo] argument indicates the value this flag will have if the
+ /// user doesn't explicitly pass it in.
+ ///
+ /// The [negatable] argument indicates whether this flag's value can be set to
+ /// `false`. For example, if [name] is `flag`, the user can pass `--no-flag`
+ /// to set its value to `false`.
+ ///
+ /// The [callback] argument is invoked with the flag's value when the flag
+ /// is parsed. Note that this makes argument parsing order-dependent in ways
+ /// that are often surprising, and its use is discouraged in favor of reading
+ /// values from the [ArgResult].
+ ///
+ /// If [hide] is `true`, this option won't be included in [usage].
+ ///
+ /// Throws an [ArgumentError] if:
///
/// * There is already an option named [name].
/// * There is already an option using abbreviation [abbr].
@@ -97,12 +121,53 @@
null,
defaultsTo,
callback == null ? null : (value) => callback(value as bool),
- OptionType.FLAG,
+ OptionType.flag,
negatable: negatable,
hide: hide);
}
- /// Defines a value-taking option. Throws an [ArgumentError] if:
+ /// Defines an option that takes a value.
+ ///
+ /// This adds an [Option] with the given properties to [options].
+ ///
+ /// The [abbr] argument is a single-character string that can be used as a
+ /// shorthand for this option. For example, `abbr: "a"` will allow the user to
+ /// pass `-a value` or `-avalue`.
+ ///
+ /// The [help] argument is used by [usage] to describe this option.
+ ///
+ /// The [valueHelp] argument is used by [usage] as a name for the value this
+ /// option takes. For example, `valueHelp: "FOO"` will include
+ /// `--option=<FOO>` rather than just `--option` in the usage string.
+ ///
+ /// The [allowed] argument is a list of valid values for this option. If
+ /// it's non-`null` and the user passes a value that's not included in the
+ /// list, [parse] will throw a [FormatException]. The allowed values will also
+ /// be included in [usage].
+ ///
+ /// The [allowedHelp] argument is a map from values in [allowed] to
+ /// documentation for those values that will be included in [usage].
+ ///
+ /// The [defaultsTo] argument indicates the value this option will have if the
+ /// user doesn't explicitly pass it in (or `null` by default).
+ ///
+ /// The [callback] argument is invoked with the option's value when the option
+ /// is parsed. Note that this makes argument parsing order-dependent in ways
+ /// that are often surprising, and its use is discouraged in favor of reading
+ /// values from the [ArgResult].
+ ///
+ /// If [allowMultiple] is `true`, the user may pass this option multiple times
+ /// and its value will be a `List<String>` rather than a `String`. The default
+ /// value will be `[]` rather than `null`, or `[defaultsTo]` if [defaultsTo]
+ /// is passed.
+ ///
+ /// If [splitCommas] is `true`, multiple values may be passed by writing
+ /// `--option a,b` in addition to `--option a --option b`. It defaults to
+ /// `true` if [allowMultiple] is `true` and `false` otherwise.
+ ///
+ /// If [hide] is `true`, this option won't be included in [usage].
+ ///
+ /// Throws an [ArgumentError] if:
///
/// * There is already an option with name [name].
/// * There is already an option using abbreviation [abbr].
@@ -124,7 +189,7 @@
}
_addOption(name, abbr, help, valueHelp, allowed, allowedHelp, defaultsTo,
- callback, allowMultiple ? OptionType.MULTIPLE : OptionType.SINGLE,
+ callback, allowMultiple ? OptionType.multiple : OptionType.single,
splitCommas: splitCommas, hide: hide);
}
@@ -192,13 +257,13 @@
if (!options.containsKey(option)) {
throw new ArgumentError('No option named $option');
}
- return options[option].defaultValue;
+ return options[option].defaultsTo;
}
/// Finds the option whose abbreviation is [abbr], or `null` if no option has
/// that abbreviation.
Option findByAbbreviation(String abbr) {
- return options.values.firstWhere((option) => option.abbreviation == abbr,
- orElse: () => null);
+ return options.values
+ .firstWhere((option) => option.abbr == abbr, orElse: () => null);
}
}
diff --git a/lib/src/arg_results.dart b/lib/src/arg_results.dart
index 744686d..78dacea 100644
--- a/lib/src/arg_results.dart
+++ b/lib/src/arg_results.dart
@@ -76,7 +76,7 @@
// Include the options that have defaults.
_parser.options.forEach((name, option) {
- if (option.defaultValue != null) result.add(name);
+ if (option.defaultsTo != null) result.add(name);
});
return result;
diff --git a/lib/src/option.dart b/lib/src/option.dart
index 55cc566..0902fe3 100644
--- a/lib/src/option.dart
+++ b/lib/src/option.dart
@@ -8,54 +8,94 @@
/// get to it. This function isn't exported to the public API of the package.
Option newOption(
String name,
- String abbreviation,
+ String abbr,
String help,
String valueHelp,
Iterable<String> allowed,
Map<String, String> allowedHelp,
- defaultValue,
+ defaultsTo,
Function callback,
OptionType type,
{bool negatable,
bool splitCommas,
bool hide: false}) {
- return new Option._(name, abbreviation, help, valueHelp, allowed, allowedHelp,
- defaultValue, callback, type,
+ return new Option._(name, abbr, help, valueHelp, allowed, allowedHelp,
+ defaultsTo, callback, type,
negatable: negatable, splitCommas: splitCommas, hide: hide);
}
-/// A command-line option. Includes both flags and options which take a value.
+/// A command-line option.
+///
+/// This represents both boolean flags and options which take a value.
class Option {
+ /// The name of the option that the user passes as an argument.
final String name;
- final String abbreviation;
- final List<String> allowed;
- final defaultValue;
- final Function callback;
+
+ /// A single-character string that can be used as a shorthand for this option.
+ ///
+ /// For example, `abbr: "a"` will allow the user to pass `-a value` or
+ /// `-avalue`.
+ final String abbr;
+
+ @Deprecated("Use abbr instead.")
+ String get abbreviation => abbr;
+
+ /// A description of this option.
final String help;
+
+ /// A name for the value this option takes.
final String valueHelp;
+
+ /// A list of valid values for this option.
+ final List<String> allowed;
+
+ /// A map from values in [allowed] to documentation for those values.
final Map<String, String> allowedHelp;
- final OptionType type;
+
+ /// The value this option will have if the user doesn't explicitly pass it in
+ final defaultsTo;
+
+ @Deprecated("Use defaultsTo instead.")
+ get defaultValue => defaultsTo;
+
+ /// Whether this flag's value can be set to `false`.
+ ///
+ /// For example, if [name] is `flag`, the user can pass `--no-flag` to set its
+ /// value to `false`.
+ ///
+ /// This is `null` unless [type] is [OptionType.flag].
final bool negatable;
+
+ /// The callback to invoke with the option's value when the option is parsed.
+ final Function callback;
+
+ /// Whether this is a flag, a single value option, or a multi-value option.
+ final OptionType type;
+
+ /// Whether multiple values may be passed by writing `--option a,b` in
+ /// addition to `--option a --option b`.
final bool splitCommas;
+
+ /// Whether this option should be hidden from usage documentation.
final bool hide;
/// Whether the option is boolean-valued flag.
- bool get isFlag => type == OptionType.FLAG;
+ bool get isFlag => type == OptionType.flag;
/// Whether the option takes a single value.
- bool get isSingle => type == OptionType.SINGLE;
+ bool get isSingle => type == OptionType.single;
/// Whether the option allows multiple values.
- bool get isMultiple => type == OptionType.MULTIPLE;
+ bool get isMultiple => type == OptionType.multiple;
Option._(
this.name,
- this.abbreviation,
+ this.abbr,
this.help,
this.valueHelp,
Iterable<String> allowed,
Map<String, String> allowedHelp,
- this.defaultValue,
+ this.defaultsTo,
this.callback,
OptionType type,
{this.negatable,
@@ -68,7 +108,7 @@
// If the user doesn't specify [splitCommas], it defaults to true for
// multiple options.
this.splitCommas =
- splitCommas == null ? type == OptionType.MULTIPLE : splitCommas {
+ splitCommas == null ? type == OptionType.multiple : splitCommas {
if (name.isEmpty) {
throw new ArgumentError('Name cannot be empty.');
} else if (name.startsWith('-')) {
@@ -80,14 +120,14 @@
throw new ArgumentError('Name "$name" contains invalid characters.');
}
- if (abbreviation != null) {
- if (abbreviation.length != 1) {
+ if (abbr != null) {
+ if (abbr.length != 1) {
throw new ArgumentError('Abbreviation must be null or have length 1.');
- } else if (abbreviation == '-') {
+ } else if (abbr == '-') {
throw new ArgumentError('Abbreviation cannot be "-".');
}
- if (_invalidChars.hasMatch(abbreviation)) {
+ if (_invalidChars.hasMatch(abbr)) {
throw new ArgumentError('Abbreviation is an invalid character.');
}
}
@@ -96,14 +136,14 @@
/// Returns [value] if non-`null`, otherwise returns the default value for
/// this option.
///
- /// For single-valued options, it will be [defaultValue] if set or `null`
+ /// For single-valued options, it will be [defaultsTo] if set or `null`
/// otherwise. For multiple-valued options, it will be an empty list or a
- /// list containing [defaultValue] if set.
+ /// list containing [defaultsTo] if set.
dynamic getOrDefault(value) {
if (value != null) return value;
- if (!isMultiple) return defaultValue;
- if (defaultValue != null) return [defaultValue];
+ if (!isMultiple) return defaultsTo;
+ if (defaultsTo != null) return [defaultsTo];
return [];
}
@@ -115,7 +155,10 @@
/// An option that can only be `true` or `false`.
///
/// The presence of the option name itself in the argument list means `true`.
- static const FLAG = const OptionType._("OptionType.FLAG");
+ static const flag = const OptionType._("OptionType.flag");
+
+ @Deprecated("Use OptionType.flag instead.")
+ static const FLAG = flag;
/// An option that takes a single value.
///
@@ -126,7 +169,10 @@
/// --mode=debug
///
/// If the option is passed more than once, the last one wins.
- static const SINGLE = const OptionType._("OptionType.SINGLE");
+ static const single = const OptionType._("OptionType.single");
+
+ @Deprecated("Use OptionType.single instead.")
+ static const SINGLE = single;
/// An option that allows multiple values.
///
@@ -136,7 +182,10 @@
///
/// In the parsed `ArgResults`, a multiple-valued option will always return
/// a list, even if one or no values were passed.
- static const MULTIPLE = const OptionType._("OptionType.MULTIPLE");
+ static const multiple = const OptionType._("OptionType.multiple");
+
+ @Deprecated("Use OptionType.multiple instead.")
+ static const MULTIPLE = multiple;
final String name;
diff --git a/lib/src/usage.dart b/lib/src/usage.dart
index 2b40332..85edcac 100644
--- a/lib/src/usage.dart
+++ b/lib/src/usage.dart
@@ -88,11 +88,11 @@
newline();
} else if (option.allowed != null) {
write(2, buildAllowedList(option));
- } else if (option.defaultValue != null) {
- if (option.isFlag && option.defaultValue == true) {
+ } else if (option.defaultsTo != null) {
+ if (option.isFlag && option.defaultsTo == true) {
write(2, '(defaults to on)');
} else if (!option.isFlag) {
- write(2, '(defaults to "${option.defaultValue}")');
+ write(2, '(defaults to "${option.defaultsTo}")');
}
}
@@ -106,13 +106,8 @@
return buffer.toString();
}
- String getAbbreviation(Option option) {
- if (option.abbreviation != null) {
- return '-${option.abbreviation}, ';
- } else {
- return '';
- }
- }
+ String getAbbreviation(Option option) =>
+ option.abbr == null ? '' : '-${option.abbr}, ';
String getLongOption(Option option) {
var result;
@@ -228,7 +223,7 @@
for (var allowed in option.allowed) {
if (!first) allowedBuffer.write(', ');
allowedBuffer.write(allowed);
- if (allowed == option.defaultValue) {
+ if (allowed == option.defaultsTo) {
allowedBuffer.write(' (default)');
}
first = false;
diff --git a/pubspec.yaml b/pubspec.yaml
index 2c5fa59..4985ea2 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: args
-version: 1.3.0
+version: 1.4.0-dev
author: "Dart Team <misc@dartlang.org>"
homepage: https://github.com/dart-lang/args
description: >
