examples/catalog/bin/sample_page.dart

// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// This application generates markdown pages and screenshots for each
// sample app. For more information see ../README.md.

import 'dart:io';

import 'package:path/path.dart';

class SampleError extends Error {
  SampleError(this.message);
  final String message;
  @override
  String toString() => 'SampleError($message)';
}

// Sample apps are .dart files in the lib directory which contain a block
// comment that begins with a '/* Sample Catalog' line, and ends with a line
// that just  contains '*/'. The following keywords may appear at the
// beginning of lines within the comment. A keyword's value is all of
// the following text up to the next keyword or the end of the comment,
// sans leading and trailing whitespace.
const String sampleCatalogKeywords = r'^Title:|^Summary:|^Description:|^Classes:|^Sample:|^See also:';

Directory outputDirectory;
Directory sampleDirectory;
Directory testDirectory;
Directory driverDirectory;
String sampleTemplate;
String screenshotTemplate;
String screenshotDriverTemplate;

void logMessage(String s) { print(s); }
void logError(String s) { print(s); }

File inputFile(String dir, String name) {
  return new File(dir + Platform.pathSeparator + name);
}

File outputFile(String name, [Directory directory]) {
  return new File((directory ?? outputDirectory).path + Platform.pathSeparator + name);
}

void initialize() {
  final File sampleTemplateFile = inputFile('bin', 'sample_page.md.template');
  final File screenshotTemplateFile = inputFile('bin', 'screenshot.dart.template');
  final File screenshotDriverTemplateFile = inputFile('bin', 'screenshot_test.dart.template');

  outputDirectory = new Directory('.generated');
  sampleDirectory = new Directory('lib');
  testDirectory = new Directory('test');
  driverDirectory = new Directory('test_driver');
  outputDirectory.createSync();
  sampleTemplate = sampleTemplateFile.readAsStringSync();
  screenshotTemplate = screenshotTemplateFile.readAsStringSync();
  screenshotDriverTemplate = screenshotDriverTemplateFile.readAsStringSync();
}

// Return a copy of template with each occurrence of @(foo) replaced
// by values[foo].
String expandTemplate(String template, Map<String, String> values) {
  // Matches @(foo), match[1] == 'foo'
  final RegExp tokenRE = new RegExp(r'@\(([\w ]+)\)', multiLine: true);
  return template.replaceAllMapped(tokenRE, (Match match) {
    if (match.groupCount != 1)
      throw new SampleError('bad template keyword $match[0]');
    final String keyword = match[1];
    return (values[keyword] ?? "");
  });
}

void writeExpandedTemplate(File output, String template, Map<String, String> values) {
  output.writeAsStringSync(expandTemplate(template, values));
  logMessage('wrote $output');
}

class SampleGenerator {
  SampleGenerator(this.sourceFile);

  final File sourceFile;
  String sourceCode;
  Map<String, String> commentValues;

  // If sourceFile is lib/foo.dart then sourceName is foo. The sourceName
  // is used to create derived filenames like foo.md or foo.png.
  String get sourceName => basenameWithoutExtension(sourceFile.path);

  // The name of the widget class that defines this sample app, like 'FooSample'.
  String get sampleClass => commentValues["sample"];

  // The relative import path for this sample, like '../lib/foo.dart'.
  String get importPath => '..' + Platform.pathSeparator + sourceFile.path;

  // Return true if we're able to find the "Sample Catalog" comment in the
  // sourceFile, and we're able to load its keyword/value pairs into
  // the commentValues Map. The rest of the file's contents are saved
  // in sourceCode.
  bool initialize() {
    final String contents = sourceFile.readAsStringSync();

    final RegExp startRE = new RegExp(r'^/\*\s+^Sample\s+Catalog', multiLine: true);
    final RegExp endRE = new RegExp(r'^\*/', multiLine: true);
    final Match startMatch = startRE.firstMatch(contents);
    if (startMatch == null)
      return false;

    final int startIndex = startMatch.end;
    final Match endMatch = endRE.firstMatch(contents.substring(startIndex));
    if (endMatch == null)
      return false;

    final String comment = contents.substring(startIndex, startIndex + endMatch.start);
    sourceCode = contents.substring(0, startMatch.start) + contents.substring(startIndex + endMatch.end);
    if (sourceCode.trim().isEmpty)
      throw new SampleError('did not find any source code in $sourceFile');

    final RegExp keywordsRE = new RegExp(sampleCatalogKeywords, multiLine: true);
    final List<Match> keywordMatches = keywordsRE.allMatches(comment).toList();
    if (keywordMatches.isEmpty)
      throw new SampleError('did not find any keywords in the Sample Catalog comment in $sourceFile');

    commentValues = <String, String>{};
    for (int i = 0; i < keywordMatches.length; i += 1) {
      final String keyword = comment.substring(keywordMatches[i].start, keywordMatches[i].end - 1);
      final String value = comment.substring(
        keywordMatches[i].end,
        i == keywordMatches.length - 1 ? null : keywordMatches[i + 1].start,
      );
      commentValues[keyword.toLowerCase()] = value.trim();
    }
    commentValues['name'] = sourceName;
    commentValues['path'] = 'examples/catalog/${sourceFile.path}';
    commentValues['source'] = sourceCode.trim();

    return true;
  }
}

void generate() {
  initialize();

  final List<SampleGenerator> samples = <SampleGenerator>[];
  sampleDirectory.listSync().forEach((FileSystemEntity entity) {
    if (entity is File && entity.path.endsWith('.dart')) {
      final SampleGenerator sample = new SampleGenerator(entity);
      if (sample.initialize()) { // skip files that lack the Sample Catalog comment
        writeExpandedTemplate(
          outputFile(sample.sourceName + '.md'),
          sampleTemplate,
          sample.commentValues,
        );
        samples.add(sample);
      }
    }
  });

  // Causes the generated imports to appear in alphabetical order.
  // Avoid complaints from flutter lint.
  samples.sort((SampleGenerator a, SampleGenerator b) {
    return a.sourceName.compareTo(b.sourceName);
  });

  writeExpandedTemplate(
    outputFile('screenshot.dart', driverDirectory),
    screenshotTemplate,
    <String, String>{
      'imports': samples.map((SampleGenerator page) {
        return "import '${page.importPath}' show ${page.sampleClass};\n";
      }).toList().join(),
      'widgets': samples.map((SampleGenerator sample) {
        return 'new ${sample.sampleClass}(),\n';
      }).toList().join(),
    },
  );

  writeExpandedTemplate(
    outputFile('screenshot_test.dart', driverDirectory),
    screenshotDriverTemplate,
    <String, String>{
      'paths': samples.map((SampleGenerator sample) {
        return "'${outputFile(sample.sourceName + '.png').path}'";
      }).toList().join(',\n'),
    },
  );

  // To generate the screenshots: flutter drive test_driver/screenshot.dart
}

void main(List<String> args) {
  try {
    generate();
  } catch (error) {
    logError(
      'Error: sample_page.dart failed: $error\n'
      'This sample_page.dart app expects to be run from the examples/catalog directory. '
      'More information can be found in examples/catalog/README.md.'
    );
    exit(255);
  }

  exit(0);
}