Add listExamples gradle task. (#453)

* Add listExamples gradle task.

* Reworked task action to accomodate migration examples.

* Add search option.

* Fixed call from non-base directory

* Fix package name printout in traverseDirectory. Add comments explaining searchTerm argument.

* Minor groovy cleanup.

Author: AndrewMBurke

buildSrc/src/main/groovy/com.google.api-ads.java-conventions.gradle

@@ -16,6 +16,11 @@
  * These are shared settings common to all Google Ads Java library subprojects.
  */
 
+import org.gradle.api.DefaultTask
+import groovy.io.FileType
+import groovy.io.FileVisitResult
+import java.util.regex.Matcher
+
 plugins {
   id 'java-library'
   id 'maven-publish'
@@ -58,67 +63,212 @@ dependencies {
   testImplementation 'junit:junit:4.13.1'
 }
 
-public class ExampleRunnerTask extends JavaExec {
+class ExampleRunnerTask extends JavaExec {
 
-  @Input
-  public String basePackage = 'com.google.ads.googleads.examples.'
+  // The base package for all examples.
+  private String basePackage = 'com.google.ads.googleads.examples.'
 
+  // Hints for failed executions.
+  private final String exampleInvocation = 'For example, ' +
+    '\033[0;35m--example="basicoperations.GetCampaigns"\033[0m.\n' +
+    'Run \033[0;35m./gradlew -q listExamples\033[0m to list all examples, or ' +
+    '\033[0;35m./gradlew -q listExamples --subdirectory="basicoperations"\033[0m ' +
+    'to list examples in a specific subdirectory.\n\n'
+
+  // The package.ClassName and any arguments required to launch an example,
+  // for example "basicoperations.GetCampaigns --customerId 1234567890".
   @Optional
   @Input
   private String exampleArguments
 
-  public ExampleRunnerTask() {
+  ExampleRunnerTask() {
     group = 'Execution'
     description = 'Run a Google Ads API example.'
     errorOutput = System.err
   }
 
+  String getBasePackage() {
+    return this.basePackage
+  }
+
+  void setBasePackage(String basePackage) {
+    this.basePackage = basePackage
+  }
+
+  String getExampleArguments() {
+    return this.exampleArguments
+  }
+
   @Option(option = 'example', description = 'Sets the example to launch and' +
-      ' any arguments. Required for execution. E.g. ' +
-      '"basicoperations.GetCampaigns --customerId 1234567890"')
-  public void setExampleArguments(String exampleArguments) {
+    ' any arguments. Required for execution. For example, ' +
+    '"basicoperations.GetCampaigns --customerId 1234567890"')
+  void setExampleArguments(String exampleArguments) {
     this.exampleArguments = exampleArguments.trim()
     int firstSpaceIndex = this.exampleArguments.indexOf(' ')
 
     // No additional arguments were passed, just the example name.
     if (firstSpaceIndex == -1) {
-      main = basePackage + this.exampleArguments
+      main = this.basePackage + this.exampleArguments
     }
     // Otherwise, separate the input and set the arguments to pass to the
     // main class.
     else {
-      main = basePackage + this.exampleArguments[0..firstSpaceIndex - 1]
+      main = this.basePackage + this.exampleArguments[0..firstSpaceIndex - 1]
       argsString(exampleArguments[(firstSpaceIndex + 1)..-1])
     }
   }
 
   @TaskAction
   @Override
-  public void exec() {
+  void exec() {
     if (!(exampleArguments?.trim())) {
       throw new GradleException('\033[0;31mMissing example!\033[0m ' +
-          'Please rerun with one provided, e.g. ' +
-          '\033[0;35m--example="basicoperations.GetCampaigns"\033[0m')
+        'Please rerun with one provided. ' + exampleInvocation)
     }
     logQuietMessage('Running example: ' + main + ', args: ' +
-        args.toString())
+      args.toString())
     try {
       super.exec()
     }
     catch (Exception e) {
       logQuietMessage('\n\033[0;31mrunExample exception!\033[0m Did ' +
-          'you provide a valid example identifier? E.g. ' +
-          '\033[0;35m--example="basicoperations.GetCampaigns"\033[0m\n\n' +
-          e.message)
+        'you provide a valid example identifier? ' + exampleInvocation +
+        e.message)
     }
   }
 
-  public String getExampleArguments() {
-    return exampleArguments
-  }
-
+  // Prints a message to the console, even in quiet mode.
   private void logQuietMessage(String message) {
     logger.quiet(message)
   }
+}
+
+class ListExamplesTask extends DefaultTask {
+
+  // Regex for extracting descriptions. Isolates the Javadoc comment immediately
+  // preceeding the class definition.
+  private static final String COMMENT_REGEX =
+    '(?s)(/\\*\\*(?:(?!/\\*\\*).)*?\\*/)(?:(?:(?!\\*/).)*?)(?=public class )'
+
+  // Regex for comment markers.
+  private static final String COMMENT_MARKERS = '(/\\*\\*\\s+|\\*\\s|\\*/)'
+
+  // The base directory containing all examples.
+  private static final String MAIN_EXAMPLES_BASE_DIRECTORY =
+    'src/main/java/com/google/ads/googleads/examples/'
+
+  // The base directory containing all examples.
+  private static final String MIGRATION_EXAMPLES_BASE_DIRECTORY =
+    '../google-ads-migration-examples/src/main/java/com/google/ads/googleads/migration/'
+
+  // The name of the package with the migration examples (currently only one
+  // such package exists).
+  private static final String MIGRATION_PACKAGE_NAME = 'campaignmanagement'
+
+  // A list of subdirectories to exclude from the printout.
+  @Input
+  List<String> directoriesToExclude = ['utils']
+
+  // An optional subdirectory; if non-null, only examples in the specified
+  // subdirectory will be printed.
+  @Optional
+  @Input
+  private String subdirectory = null
+
+  // An optional case-sensitive search string; if non-null, only examples whose
+  // name or description contains the specified term will be printed.
+  @Optional
+  @Input
+  private String searchTerm = null
+
+  ListExamplesTask() {
+    description = 'List all available code examples with package name ' +
+      'and description.'
+  }
+
+  String getSubdirectory() {
+    return this.subdirectory
+  }
+
+  List<String> getDirectoriesToExclude() {
+    return this.directoriesToExclude
+  }
+
+  String getSearchTerm() {
+    return this.searchTerm
+  }
+
+  @Option(option = 'subdirectory', description = 'Sets a subdirectory of ' +
+    'google-ads-examples, for example "basicoperations". Only examples in this ' +
+    'subdirectory will be printed. If not specified, all the examples ' +
+    'will be printed.')
+  void setSubdirectory(String subdirectory) {
+    this.subdirectory = subdirectory.trim()
+  }
+
+  @Option(option = 'searchTerm', description = 'Sets a case-sensitive search term, ' +
+    'for example "conversion". If set, only examples whose name or description ' +
+    'contains the specified term will be printed.')
+  void setSearchTerm(String searchTerm) {
+    this.searchTerm = searchTerm.trim()
+  }
+
+  // Traverse a given directory, printing the information for each example.
+  int traverseDirectory(String dir, int offset) {
+    int count = 0
+
+    // Determine the number of leading characters in the directory path. This
+    // value is different depending on which subproject we are traversing.
+    int baseLength = (subdirectory ?
+      project.file(dir).absolutePath.lastIndexOf('/') :
+      project.file(dir).absolutePath.length()) + 1
+
+    project.file(dir).traverse(
+        type                : FileType.FILES,
+        preDir              : { if (it.name in directoriesToExclude)
+                                return FileVisitResult.SKIP_SUBTREE },
+        excludeNameFilter   : { it in directoriesToExclude },
+        nameFilter          : { it.endsWith('.java') },
+        sort                : { a, b -> a.name <=> b.name }
+    ) {
+        // Strip out the base directory, truncate the .java file extension,
+        // and replace the / with . to indicate package name.
+        String className = it.path.substring(baseLength,
+          it.path.length()-5).replaceAll('/','.')
+
+        // Fetch the example description.
+        Matcher matcher = it.text =~ COMMENT_REGEX
+        String description =
+          matcher ? matcher[0][0] : "*description missing*"
+
+        if (!searchTerm || className.contains(searchTerm) ||
+          description.contains(searchTerm)) {
+          // Print the count, package.class name, and description (without
+          // comment markers and trailing newlines).
+          println '' + (++count + offset) + ': ' + className + ' - ' +
+            description.replaceAll(COMMENT_MARKERS,'').strip()
+        }
+    }
+
+    return count
+  }
 
+  @TaskAction
+  void exec() {
+    String mainExamplesDirectory = subdirectory ?
+      MAIN_EXAMPLES_BASE_DIRECTORY + subdirectory + '/' : MAIN_EXAMPLES_BASE_DIRECTORY
+    String migrationExamplesDirectory = subdirectory ?
+      MIGRATION_EXAMPLES_BASE_DIRECTORY + subdirectory + '/' : MIGRATION_EXAMPLES_BASE_DIRECTORY
+    int count = 0
+
+    count += traverseDirectory(mainExamplesDirectory, count)
+
+    // Only print the migration examples if printing all examples or examples
+    // with the campaignmanagement package name.
+    if (!subdirectory || subdirectory == MIGRATION_PACKAGE_NAME) {
+      count += traverseDirectory(migrationExamplesDirectory, count)
+    }
+
+    println "\nTotal examples: $count"
+  }
 }

google-ads-examples/build.gradle

@@ -16,32 +16,43 @@
  * This is the build file for the google-ads-examples subproject. It depends on
  * the google-ads subproject.
  *
- * This project contains examples for using the Google Ads API. You can launch
- * examples by navigating to the google-ads-examples folder and running the
- * provided runExample gradle task. Note that we recommend running with the
- * quiet flag (-q) to reduce screen clutter:
- *     -- Mac/Linux --
- *     ./gradlew -q runExample --example='basicoperations.GetCampaigns --customerId 1234567890'
+ * This project contains examples for using the Google Ads API. You can interact
+ * with the examples by running the provided listExamples and runExample gradle
+ * tasks. Note that we recommend running with the quiet flag (-q) to reduce
+ * screen clutter:
+ *   -- Mac/Linux --
+ *   ./gradlew -q runExample --example='basicoperations.GetCampaigns --customerId 1234567890'
+ *   ./gradlew -q listExamples
+ *   ./gradlew -q listExamples --subdirectory="basicoperations"
  *
- *     -- Windows --
- *     gradlew -q runExample --example='basicoperations.GetCampaigns --customerId 1234567890'
+ *   -- Windows --
+ *   gradlew -q runExample --example='basicoperations.GetCampaigns --customerId 1234567890'
+ *   gradlew -q listExamples
+ *   gradlew -q listExamples --subdirectory="basicoperations"
+ *
+ * The listExamples task can also search for a specific term in example names
+ * and descriptions using the --search argument. Note that these search terms
+ * are case-sensitive:
+ *  ./gradlew -q listExamples --subdirectory="basicoperations" --searchTerm="REMOVE"
  */
 
 plugins {
-    id 'com.google.api-ads.java-conventions'
+  id 'com.google.api-ads.java-conventions'
 }
 
 dependencies {
-    implementation project(':google-ads')
-    implementation 'org.apache.commons:commons-lang3:3.11'
-    implementation 'com.beust:jcommander:1.72'
-    implementation 'joda-time:joda-time:2.8.2'
-    runtimeOnly 'org.apache.logging.log4j:log4j-slf4j-impl:2.11.1'
-    testImplementation 'org.mockito:mockito-core:2.27.0'
+  implementation project(':google-ads')
+  implementation 'org.apache.commons:commons-lang3:3.11'
+  implementation 'com.beust:jcommander:1.72'
+  implementation 'joda-time:joda-time:2.8.2'
+  runtimeOnly 'org.apache.logging.log4j:log4j-slf4j-impl:2.11.1'
+  testImplementation 'org.mockito:mockito-core:2.27.0'
 }
 
 description = 'Google Ads API client library for Java examples'
 
 task runExample(type: ExampleRunnerTask) {
-    classpath = sourceSets.main.runtimeClasspath
+  classpath = sourceSets.main.runtimeClasspath
 }
+
+task listExamples(type: ListExamplesTask)