From cd32085a752d6fcbfc9a0ddf8d01f78206940081 Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin <pete@bacondarwin.com>
Date: Sat, 29 Feb 2020 12:02:44 +0000
Subject: [PATCH] refactor(localize): allow hints from `canParse()` to
 `parse()` (#35793)

This enables complex work to be done in `TranslationParser.canParse()`
without duplicating the work in `TranslationParser.parse()`.

PR Close #35793
---
 .../translation_files/translation_loader.ts   |  2 +-
 .../translation_parsers/translation_parser.ts | 42 +++++++++++++++++--
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/packages/localize/src/tools/src/translate/translation_files/translation_loader.ts b/packages/localize/src/tools/src/translate/translation_files/translation_loader.ts
index 10cd4c112e..120f43f910 100644
--- a/packages/localize/src/tools/src/translate/translation_files/translation_loader.ts
+++ b/packages/localize/src/tools/src/translate/translation_files/translation_loader.ts
@@ -15,7 +15,7 @@ import {TranslationParser} from './translation_parsers/translation_parser';
  */
 export class TranslationLoader {
   constructor(
-      private translationParsers: TranslationParser[],
+      private translationParsers: TranslationParser<any>[],
       /** @deprecated */ private diagnostics?: Diagnostics) {}
 
   /**
diff --git a/packages/localize/src/tools/src/translate/translation_files/translation_parsers/translation_parser.ts b/packages/localize/src/tools/src/translate/translation_files/translation_parsers/translation_parser.ts
index 126e1c69d9..14b2ab71bc 100644
--- a/packages/localize/src/tools/src/translate/translation_files/translation_parsers/translation_parser.ts
+++ b/packages/localize/src/tools/src/translate/translation_files/translation_parsers/translation_parser.ts
@@ -19,21 +19,57 @@ export interface ParsedTranslationBundle {
 
 /**
  * Implement this interface to provide a class that can parse the contents of a translation file.
+ *
+ * The `canParse()` method can return a hint that can be used by the `parse()` method to speed up
+ * parsing. This allows the parser to do significant work to determine if the file can be parsed
+ * without duplicating the work when it comes to actually parsing the file.
+ *
+ * Example usage:
+ *
+ * ```
+ * const parser: TranslationParser = getParser();
+ * const result = parser.canParse(filePath, content);
+ * if (result) {
+ *   return parser.parse(filePath, content, result);
+ * }
+ * ```
  */
-export interface TranslationParser {
+export interface TranslationParser<Hint = true> {
   /**
-   * Returns true if this parser can parse the given file.
+   * Can this parser parse the given file?
    *
    * @param filePath The absolute path to the translation file.
    * @param contents The contents of the translation file.
+   * @returns A hint, which can be used in doing the actual parsing, if the file can be parsed by
+   * this parser; false otherwise.
    */
-  canParse(filePath: string, contents: string): boolean;
+  canParse(filePath: string, contents: string): Hint|false;
 
   /**
    * Parses the given file, extracting the target locale and translations.
    *
+   * Note that this method should not throw an error. Check the `bundle.diagnostics` property for
+   * potential parsing errors and warnings.
+   *
    * @param filePath The absolute path to the translation file.
    * @param contents The contents of the translation file.
+   * @param hint A value that can be used by the parser to speed up parsing of the file. This will
+   * have been provided as the return result from calling `canParse()`.
+   * @returns The translation bundle parsed from the file.
+   * @throws No errors. If there was a problem with parsing the bundle will contain errors
+   * in the `diagnostics` property.
+   */
+  parse(filePath: string, contents: string, hint: Hint): ParsedTranslationBundle;
+  /**
+   * Parses the given file, extracting the target locale and translations.
+   *
+   * @deprecated This overload is kept for backward compatibility. Going forward use the Hint
+   * returned from `canParse()` so that this method can avoid duplicating effort.
+   *
+   * @param filePath The absolute path to the translation file.
+   * @param contents The contents of the translation file.
+   * @returns The translation bundle parsed from the file.
+   * @throws An error if there was a problem parsing this file.
    */
   parse(filePath: string, contents: string): ParsedTranslationBundle;
 }