Refactor the generation from a YAML configuration

main.dart

Index: main.dart
diff --git a/main.dart b/main.dart
index 5616c0e937faeac85f2c376d54432e0ca030135f..bf5e5e7fff3e59b332f11da31f763c654fb831ed 100644
--- a/main.dart
+++ b/main.dart
@@ -15,74 +15,88 @@ class Package {
   Package(this.name, this.apis, this.pubspec, this.readme, this.license);
 }
 
-String generateReadme(String readmeFile, List<DirectoryListItems> items) {
-  var sb = new StringBuffer();
-  if (readmeFile != null) {
-    sb.write(new File(readmeFile).readAsStringSync());
-  }
-  sb.writeln('''
-
-## Available Google APIs
-
-The following is a list of APIs that are currently available inside this
-package.
-''');
-  for (DirectoryListItems item in items) {
-    sb.write("#### ");
-    if (item.icons != null && item.icons.x16 != null) {
-      sb.write("![Logo](${item.icons.x16}) ");
-    }
-    sb..writeln('${item.title} - ${item.name} ${item.version}')
-        ..writeln()
-        ..writeln('${item.description}')
-        ..writeln();
-    if (item.documentationLink != null) {
-      sb.writeln(
-          'Official API documentation: ${item.documentationLink}');
-      sb.writeln();
-    }
-  }
-  return sb.toString();
-}
-
-main() {
-  listFromYaml(value) => value != null ? value : [];
-
-  // Set up paths to directories 'discovery' and 'generated'.
-  var discoveryDocsDir = Platform.script.resolve('discovery').path;
-  var generatedApisDir = Platform.script.resolve('generated').path;
-
-  // Read the configuration.
-  var configFile = Platform.script.resolve('config.yaml').path;
-  var config = loadYaml(new File(configFile).readAsStringSync());
-
-  listAllApis().then((List<DirectoryListItems> items) {
-    var pkgs = config['packages'];
-    var packages = {};
+/**
+ * Configuration of a set of pacakges generated from a set of APIs exposed by

[kustermann, 2014/08/25 09:47:29]

-> packages

[Søren Gjesse, 2014/08/26 13:44:12]

Done.

+ * A Discovery Service.

[kustermann, 2014/08/25 09:47:29]

A -> a 

[Søren Gjesse, 2014/08/26 13:44:13]

Done.

+ */
+class DiscoveryPackagesConfiguration {
+  final Map<String, Package> packages = {};
+  final List<String> skippedApis = [];
+  final _knownApis = new Set();
+
+  /// APIs which are returned by the
+  final excessApis = new Set();
+  final missingApis = new Set();

[kustermann, 2014/08/25 09:47:29]

Put generic types here and make the variables typed.

[Søren Gjesse, 2014/08/26 13:44:13]

Done.

+
+  /**
+   * Create a new discovery packages configuration.
+   *
+   * [config] is the path to the YAML configuration file.
+   *
+   * [allApis] is the list of all supported APIs returned by the Discovery
+   * Service.
+   *
+   * The format of a YAML document describing a number of packages looks
+   * like this:
+   *
+   *     packages:
+   *     - googleapis:
+   *         version: 0.1.0
+   *         author: Dart Team <misc@dartlang.org>
+   *         homepage: http://www.dartlang.org
+   *         readme: resources/README.md
+   *         license: resources/LICENSE
+   *         apis:
+   *         -  analytics:v3
+   *         -  bigquery:v2
+   *     - googleapis_beta:
+   *         version: 0.1.0
+   *         author: Dart Team <misc@dartlang.org>
+   *         homepage: http://www.dartlang.org
+   *         readme: resources/README.md
+   *         license: resources/LICENSE
+   *         apis:
+   *         -  datastore:v1beta2
+   *         -  dns:v1beta1
+   *     skipped_apis:
+   *     - adexchangebuyer:v1
+   *
+   * Each package to build is listed under the key `packages:`.
+   *
+   * The key `skipped_apis` is used to list APIs returned buy the Discovery
+   * Service but is not part of any generated packages.
+   *
+   * The file names for the content of readme and license files are resolved
+   * relative to the configuration file.
+   */
+  DiscoveryPackagesConfiguration(
+      String configFile, List<DirectoryListItems> allApis) {
+    var configYaml = new File(configFile).readAsStringSync();
+    var yaml = loadYaml(configYaml);
+    var configPackages = yaml['packages'];
     var supportedApis = [];
-    pkgs.forEach((package) {
+    configPackages.forEach((package) {
       package.forEach((name, values) {
-        var apis = listFromYaml(values['apis']);
+        var apis = _listFromYaml(values['apis']);
         var version =
             values['version'] != null ? values['version'] : '0.1.0-dev';
         var author = values['author'];
         var homepage = values['homepage'];
         var readmeFile;
         if (values['readme'] != null) {
-          readmeFile = Platform.script.resolve(values['readme']).path;
+          readmeFile = new Uri.file(configFile).resolve(values['readme']).path;
         }
         var licenseFile;
         if (values['license'] != null) {
-          licenseFile = Platform.script.resolve(values['license']).path;
+          licenseFile = new Uri.file(configFile).resolve(values['license']).path;

[kustermann, 2014/08/25 09:47:28]

long line :)

[Søren Gjesse, 2014/08/26 13:44:13]

Done.

         }
 
-
         // Generate package description.
         var apiDescriptions = [];
         var sb = new StringBuffer()
             ..write('"Auto-generated client libraries for accessing '
                     'the following APIs:\\n');
-        items.forEach((DirectoryListItems apiDescription) {
+        allApis.forEach((DirectoryListItems apiDescription) {
           if (apis.contains(apiDescription.id)) {
             sb..writeln('')
                 ..write('  ')
@@ -96,7 +110,7 @@ main() {
         sb.write('"');
 
         // Generate the README.md file content.
-        var readme = generateReadme(readmeFile, apiDescriptions);
+        var readme = _generateReadme(readmeFile, apiDescriptions);
 
         // Read the LICENSE
         var license = new File(licenseFile).readAsStringSync();
@@ -108,31 +122,31 @@ main() {
       });

[kustermann, 2014/08/25 09:47:28]

Maybe split this up into three private static functions?

static Map<String, Package> _packagesFromYaml(yaml['packages']);
static Package _packageFromYaml();
static List<String> _calculateMissingApis(Map<String,Package> packages,
allApis);
static List<String> _calculateExcessApis(Map<String,Package> packages, allApis);

[Søren Gjesse, 2014/08/26 13:44:13]

Done.

     });
 
+    // Read the skipped APIs.
+    skippedApis.addAll(_listFromYaml(yaml['skipped_apis']));
+
     // Check that all APIs are mentioned in the configuration.
-    var skippedApis = listFromYaml(config['skipped_apis']);
     packages.forEach((_, package) => supportedApis.addAll(package.apis));
-    var knownApis = new Set();
-    knownApis.addAll(supportedApis);
-    knownApis.addAll(skippedApis);
-    var excessApis = new Set.from(knownApis);
-
-    var missingApis = [];
-    items.forEach((item) {
-      if (!knownApis.contains(item.id)) missingApis.add(item.id);
+    _knownApis.addAll(supportedApis);
+    _knownApis.addAll(skippedApis);
+    excessApis.addAll(_knownApis);
+    allApis.forEach((item) {
+      if (!_knownApis.contains(item.id)) missingApis.add(item.id);
       excessApis.remove(item.id);
     });
+  }
 
-    if (missingApis.isNotEmpty) {
-      print('WARNING: No configuration for the following APIs:');
-      missingApis.forEach((id) => print('- $id'));
-    }
-
-    if (excessApis.isNotEmpty) {
-      print('WARNING: The following APIs does not exist:');
-      excessApis.forEach((id) => print('- $id'));
-    }
-
-    // Delete downloaded discovery documents.
+  /**
+   * Generate packages from the configuration.
+   *
+   * [discoveryDocsDir] is the directory where all the downloaded discovery
+   * documents are stored.
+   *
+   * [generatedApisDir] is the directory where the packages are generated.
+   * Each package is generated in a sub-directory.
+   */
+  Future generate(String discoveryDocsDir, String generatedApisDir) {
+    // Delete all downloaded discovery documents.
     var dir = new Directory(discoveryDocsDir);
     if (dir.existsSync()) dir.deleteSync(recursive: true);
 
@@ -143,9 +157,8 @@ main() {
                                              ids: package.apis));
     });
 
-    Future.wait(futures).then((_) {
+    return Future.wait(futures).then((_) {
       packages.forEach((name, package) {
-        print('Generating library $name');
         generateAllLibraries('$discoveryDocsDir/$name',
                              '$generatedApisDir/$name',
                              package.pubspec);
@@ -156,7 +169,61 @@ main() {
               .writeAsStringSync(package.license);
         }
       });
-      print('DONE');
     });
+  }
+
+  // Return empty list for YAML null value.
+  _listFromYaml(value) => value != null ? value : [];
+
+  String _generateReadme(String readmeFile, List<DirectoryListItems> items) {
+    var sb = new StringBuffer();
+    if (readmeFile != null) {
+      sb.write(new File(readmeFile).readAsStringSync());
+    }
+    sb.writeln('''
+
+## Available Google APIs
+
+The following is a list of APIs that are currently available inside this
+package.
+''');
+    for (DirectoryListItems item in items) {
+      sb.write("#### ");
+      if (item.icons != null && item.icons.x16 != null) {
+        sb.write("![Logo](${item.icons.x16}) ");
+      }
+      sb..writeln('${item.title} - ${item.name} ${item.version}')
+          ..writeln()
+          ..writeln('${item.description}')
+          ..writeln();
+      if (item.documentationLink != null) {
+        sb.writeln(
+            'Official API documentation: ${item.documentationLink}');
+        sb.writeln();
+      }
+    }
+    return sb.toString();
+  }
+}
+
+main() {
+  listAllApis().then((List<DirectoryListItems> items) {
+    var configuration = new DiscoveryPackagesConfiguration(
+        Platform.script.resolve('config.yaml').path, items);
+
+    // Print warnings for APIs not mentioned.
+    if (configuration.missingApis.isNotEmpty) {
+      print('WARNING: No configuration for the following APIs:');
+      configuration.missingApis.forEach((id) => print('- $id'));
+    }
+    if (configuration.excessApis.isNotEmpty) {
+      print('WARNING: The following APIs does not exist:');
+      configuration.excessApis.forEach((id) => print('- $id'));
+    }
+
+    // Generate the packages.
+    configuration.generate(Platform.script.resolve('discovery').path,
+                           Platform.script.resolve('generated').path)
+        .then((_) => print('Done!'));
   });
 }