Introduce basic glob support to option handling (#2365)

* Combine isDir/isFile

* Add the glob directory munging support

* Rename to OptionKind

Author: jcollins-g

lib/src/dartdoc_options.dart

@@ -433,6 +433,17 @@ class _YamlFileData {
   _YamlFileData(this.data, this.canonicalDirectoryPath);
 }
 
+/// An enum to specify the multiple different kinds of data an option might
+/// represent.
+enum OptionKind {
+  other, // Make no assumptions about the option data; it may be of any type
+  // or semantic.
+  file, // Option data references a filename or filenames with strings.
+  dir, // Option data references a directory name or names with strings.
+  glob, // Option data references globs with strings that may cover many
+  // filenames and/or directories.
+}
+
 /// Some DartdocOption subclasses need to keep track of where they
 /// got the value from; this class contains those intermediate results
 /// so that error messages can be more useful.
@@ -503,10 +514,15 @@ abstract class DartdocOption<T> {
   final String name;
 
   /// Set to true if this option represents the name of a directory.
-  final bool isDir;
+  bool get isDir => optionIs == OptionKind.dir;
 
   /// Set to true if this option represents the name of a file.
-  final bool isFile;
+  bool get isFile => optionIs == OptionKind.file;
+
+  /// Set to true if this option represents a glob.
+  bool get isGlob => optionIs == OptionKind.glob;
+
+  final OptionKind optionIs;
 
   /// Set to true if DartdocOption subclasses should validate that the
   /// directory or file exists.  Does not imply validation of [defaultsTo],
@@ -515,11 +531,13 @@ abstract class DartdocOption<T> {
 
   final ResourceProvider resourceProvider;
 
-  DartdocOption(this.name, this.defaultsTo, this.help, this.isDir, this.isFile,
+  DartdocOption(this.name, this.defaultsTo, this.help, this.optionIs,
       this.mustExist, this._convertYamlToType, this.resourceProvider) {
-    assert(!(isDir && isFile));
-    if (isDir || isFile) assert(_isString || _isListString || _isMapString);
+    if (isDir || isFile || isGlob) {
+      assert(_isString || _isListString || _isMapString);
+    }
     if (mustExist) {
+      // Globs by definition don't have to exist.
       assert(isDir || isFile);
     }
   }
@@ -604,7 +622,7 @@ abstract class DartdocOption<T> {
   /// For a [List<String>] or [String] value, if [isDir] or [isFile] is set,
   /// resolve paths in value relative to canonicalPath.
   T _handlePathsInContext(_OptionValueWithContext<Object> valueWithContext) {
-    if (valueWithContext?.value == null || !(isDir || isFile)) {
+    if (valueWithContext?.value == null || !(isDir || isFile || isGlob)) {
       return valueWithContext?.value;
     }
     _validatePaths(valueWithContext);
@@ -715,11 +733,10 @@ class DartdocOptionFileSynth<T> extends DartdocOption<T>
       String name, this._compute, ResourceProvider resourceprovider,
       {bool mustExist = false,
       String help = '',
-      bool isDir = false,
-      bool isFile = false,
+      OptionKind optionIs = OptionKind.other,
       bool parentDirOverridesChild,
       ConvertYamlToType<T> convertYamlToType})
-      : super(name, null, help, isDir, isFile, mustExist, convertYamlToType,
+      : super(name, null, help, optionIs, mustExist, convertYamlToType,
             resourceprovider) {
     _parentDirOverridesChild = parentDirOverridesChild;
   }
@@ -765,12 +782,10 @@ class DartdocOptionArgSynth<T> extends DartdocOption<T>
       bool mustExist = false,
       String help = '',
       bool hide = false,
-      bool isDir = false,
-      bool isFile = false,
+      OptionKind optionIs = OptionKind.other,
       bool negatable = false,
       bool splitCommas})
-      : super(name, null, help, isDir, isFile, mustExist, null,
-            resourceProvider) {
+      : super(name, null, help, optionIs, mustExist, null, resourceProvider) {
     _hide = hide;
     _negatable = negatable;
     _splitCommas = splitCommas;
@@ -818,10 +833,8 @@ class DartdocOptionSyntheticOnly<T> extends DartdocOption<T>
       String name, this._compute, ResourceProvider resourceProvider,
       {bool mustExist = false,
       String help = '',
-      bool isDir = false,
-      bool isFile = false})
-      : super(
-            name, null, help, isDir, isFile, mustExist, null, resourceProvider);
+      OptionKind optionIs = OptionKind.other})
+      : super(name, null, help, optionIs, mustExist, null, resourceProvider);
 }
 
 abstract class DartdocSyntheticOption<T> implements DartdocOption<T> {
@@ -856,7 +869,8 @@ typedef OptionGenerator = Future<List<DartdocOption<Object>>> Function(
 /// option itself.
 class DartdocOptionSet extends DartdocOption<void> {
   DartdocOptionSet(String name, ResourceProvider resourceProvider)
-      : super(name, null, null, false, false, false, null, resourceProvider);
+      : super(
+            name, null, null, OptionKind.other, false, null, resourceProvider);
 
   /// Asynchronous factory that is the main entry point to initialize Dartdoc
   /// options for use.
@@ -908,11 +922,10 @@ class DartdocOptionArgOnly<T> extends DartdocOption<T>
       bool mustExist = false,
       String help = '',
       bool hide = false,
-      bool isDir = false,
-      bool isFile = false,
+      OptionKind optionIs = OptionKind.other,
       bool negatable = false,
       bool splitCommas})
-      : super(name, defaultsTo, help, isDir, isFile, mustExist, null,
+      : super(name, defaultsTo, help, optionIs, mustExist, null,
             resourceProvider) {
     _hide = hide;
     _negatable = negatable;
@@ -949,12 +962,11 @@ class DartdocOptionArgFile<T> extends DartdocOption<T>
       bool mustExist = false,
       String help = '',
       bool hide = false,
-      bool isDir = false,
-      bool isFile = false,
+      OptionKind optionIs = OptionKind.other,
       bool negatable = false,
       bool parentDirOverridesChild = false,
       bool splitCommas})
-      : super(name, defaultsTo, help, isDir, isFile, mustExist, null,
+      : super(name, defaultsTo, help, optionIs, mustExist, null,
             resourceProvider) {
     _abbr = abbr;
     _hide = hide;
@@ -1007,12 +1019,11 @@ class DartdocOptionFileOnly<T> extends DartdocOption<T>
       String name, T defaultsTo, ResourceProvider resourceProvider,
       {bool mustExist = false,
       String help = '',
-      bool isDir = false,
-      bool isFile = false,
+      OptionKind optionIs = OptionKind.other,
       bool parentDirOverridesChild = false,
       ConvertYamlToType<T> convertYamlToType})
-      : super(name, defaultsTo, help, isDir, isFile, mustExist,
-            convertYamlToType, resourceProvider) {
+      : super(name, defaultsTo, help, optionIs, mustExist, convertYamlToType,
+            resourceProvider) {
     _parentDirOverridesChild = parentDirOverridesChild;
   }
 
@@ -1260,8 +1271,10 @@ abstract class _DartdocArgOption<T> implements DartdocOption<T> {
 
     T retval;
     // Unlike in _DartdocFileOption, we throw here on inputs being invalid
-    // rather than silently proceeding.  TODO(jcollins-g): throw on input
-    // formatting for files too?
+    // rather than silently proceeding.  This is because the user presumably
+    // typed something wrong on the command line and can therefore fix it.
+    // dartdoc_option.yaml files from other packages may not be fully in the
+    // user's control.
     if (_isBool || _isListString || _isString) {
       retval = _argResults[argName];
     } else if (_isInt) {
@@ -1566,7 +1579,7 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
     }, resourceProvider,
         help: 'Remove text from libraries with the following names.'),
     DartdocOptionArgFile<String>('examplePathPrefix', null, resourceProvider,
-        isDir: true,
+        optionIs: OptionKind.dir,
         help: 'Prefix for @example paths.\n(defaults to the project root)',
         mustExist: true),
     DartdocOptionArgFile<List<String>>('exclude', [], resourceProvider,
@@ -1580,7 +1593,7 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
         (DartdocSyntheticOption<String> option, Folder dir) =>
             resolveTildePath(Platform.environment['FLUTTER_ROOT']),
         resourceProvider,
-        isDir: true,
+        optionIs: OptionKind.dir,
         help: 'Root of the Flutter SDK, specified from environment.',
         mustExist: true),
     DartdocOptionArgOnly<bool>('hideSdkText', false, resourceProvider,
@@ -1592,7 +1605,7 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
         help: 'Library names to generate docs for.', splitCommas: true),
     DartdocOptionArgFile<List<String>>(
         'includeExternal', null, resourceProvider,
-        isFile: true,
+        optionIs: OptionKind.file,
         help:
             'Additional (external) dart files to include; use "dir/fileName", '
             'as in lib/material.dart.',
@@ -1605,7 +1618,9 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
             'HTML into dartdoc output.'),
     DartdocOptionArgOnly<String>(
         'input', resourceProvider.pathContext.current, resourceProvider,
-        isDir: true, help: 'Path to source directory', mustExist: true),
+        optionIs: OptionKind.dir,
+        help: 'Path to source directory',
+        mustExist: true),
     DartdocOptionSyntheticOnly<String>('inputDir',
         (DartdocSyntheticOption<String> option, Folder dir) {
       if (option.parent['sdkDocs'].valueAt(dir)) {
@@ -1614,7 +1629,7 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
       return option.parent['input'].valueAt(dir);
     }, resourceProvider,
         help: 'Path to source directory (with override if --sdk-docs)',
-        isDir: true,
+        optionIs: OptionKind.dir,
         mustExist: true),
     DartdocOptionSet('linkTo', resourceProvider)
       ..addAll([
@@ -1656,7 +1671,7 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
       ]),
     DartdocOptionArgOnly<String>('output',
         resourceProvider.pathContext.join('doc', 'api'), resourceProvider,
-        isDir: true, help: 'Path to output directory.'),
+        optionIs: OptionKind.dir, help: 'Path to output directory.'),
     DartdocOptionSyntheticOnly<PackageMeta>(
       'packageMeta',
       (DartdocSyntheticOption<PackageMeta> option, Folder dir) {
@@ -1691,7 +1706,9 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
       }
       return packageMetaProvider.defaultSdkDir.path;
     }, packageMetaProvider.resourceProvider,
-        help: 'Path to the SDK directory.', isDir: true, mustExist: true),
+        help: 'Path to the SDK directory.',
+        optionIs: OptionKind.dir,
+        mustExist: true),
     DartdocOptionArgFile<bool>(
         'showUndocumentedCategories', false, resourceProvider,
         help: "Label categories that aren't documented", negatable: true),

lib/src/generator/generator.dart

@@ -55,7 +55,7 @@ Future<List<DartdocOption<Object>>> createGeneratorOptions(
   var resourceProvider = packageMetaProvider.resourceProvider;
   return [
     DartdocOptionArgFile<List<String>>('footer', [], resourceProvider,
-        isFile: true,
+        optionIs: OptionKind.file,
         help:
             'Paths to files with content to add to page footers, but possibly '
             'outside of dedicated footer elements for the generator (e.g. '
@@ -64,13 +64,13 @@ Future<List<DartdocOption<Object>>> createGeneratorOptions(
         mustExist: true,
         splitCommas: true),
     DartdocOptionArgFile<List<String>>('footerText', [], resourceProvider,
-        isFile: true,
+        optionIs: OptionKind.file,
         help: 'Paths to files with content to add to page footers (next to the '
             'package name and version).',
         mustExist: true,
         splitCommas: true),
     DartdocOptionArgFile<List<String>>('header', [], resourceProvider,
-        isFile: true,
+        optionIs: OptionKind.file,
         help: 'Paths to files with content to add to page headers.',
         splitCommas: true),
     DartdocOptionArgOnly<bool>('prettyIndexJson', false, resourceProvider,
@@ -79,7 +79,7 @@ Future<List<DartdocOption<Object>>> createGeneratorOptions(
             'larger, but it\'s also easier to diff.',
         negatable: false),
     DartdocOptionArgFile<String>('favicon', null, resourceProvider,
-        isFile: true,
+        optionIs: OptionKind.file,
         help: 'A path to a favicon for the generated docs.',
         mustExist: true),
     DartdocOptionArgOnly<String>('relCanonicalPrefix', null, resourceProvider,
@@ -88,7 +88,7 @@ Future<List<DartdocOption<Object>>> createGeneratorOptions(
             'Consider using if building many versions of the docs for public '
             'SEO; learn more at https://goo.gl/gktN6F.'),
     DartdocOptionArgOnly<String>('templatesDir', null, resourceProvider,
-        isDir: true,
+        optionIs: OptionKind.dir,
         mustExist: true,
         hide: true,
         help:

lib/src/source_linker.dart

@@ -36,14 +36,14 @@ Future<List<DartdocOption<Object>>> createSourceLinkerOptions(
     DartdocOptionSet('linkToSource', resourceProvider)
       ..addAll([
         DartdocOptionArgFile<List<String>>('excludes', [], resourceProvider,
-            isDir: true,
+            optionIs: OptionKind.dir,
             help:
                 'A list of directories to exclude from linking to a source code repository.'),
         // TODO(jcollins-g): Use [DartdocOptionArgSynth], possibly in combination with a repository type and the root directory, and get revision number automatically
         DartdocOptionArgOnly<String>('revision', null, resourceProvider,
             help: 'Revision number to insert into the URI.'),
         DartdocOptionArgFile<String>('root', null, resourceProvider,
-            isDir: true,
+            optionIs: OptionKind.dir,
             help:
                 'Path to a local directory that is the root of the repository we link to.  All source code files under this directory will be linked.'),
         DartdocOptionArgFile<String>('uriTemplate', null, resourceProvider,