Function extractCodeSnippet

docs/src/preprocess/include_code.js:91–190

* Parse a code file, looking for identifiers of the form: * `docs:start:${identifier}` and `docs:end:{identifier}`. * Extract that section of code. * * It's complicated if code snippet identifiers overlap (i.e. the 'start' of one code snippet is in the * middle of another code snippet). The ext

(filePath, identifier)

 * @returns the code snippet, and start and end line numbers which can later be used for creating a link to github source code.
 */
function extractCodeSnippet(filePath, identifier) {
  let fileContent = fs.readFileSync(filePath, "utf-8");
  let linesToRemove = [];

  const startRegex = /(?:\/\/|#)\s+docs:start:([a-zA-Z0-9-._:]+)/g; // `g` will iterate through the regex.exec loop
  const endRegex = /(?:\/\/|#)\s+docs:end:([a-zA-Z0-9-._:]+)/g;

  /**
   * Search for one of the regex statements in the code file. If it's found, return the line as a string and the line number.
   */
  const lookForMatch = (regex) => {
    let match;
    let matchFound = false;
    let matchedLineNum = null;
    let actualMatch = null;
    let lines = fileContent.split("\n");
    while ((match = regex.exec(fileContent))) {
      if (match !== null) {
        const identifiers = match[1].split(":");
        let tempMatch = identifiers.includes(identifier) ? match : null;

        if (tempMatch === null) {
          // If it's not a match, we'll make a note that we should remove the matched text, because it's from some other identifier and should not appear in the snippet for this identifier.
          for (let i = 0; i < lines.length; i++) {
            let line = lines[i];
            if (line.trim() == match[0].trim()) {
              linesToRemove.push(i + 1); // lines are indexed from 1
            }
          }
        } else {
          if (matchFound === true) {
            throw new Error(
              `Duplicate for regex ${regex} and identifier ${identifier}`
            );
          }
          matchFound = true;
          matchedLineNum = getLineNumberFromIndex(fileContent, tempMatch.index);
          actualMatch = tempMatch;
        }
      }
    }

    return [actualMatch, matchedLineNum];
  };

  let [startMatch, startLineNum] = lookForMatch(startRegex);
  let [endMatch, endLineNum] = lookForMatch(endRegex);

  // Double-check that the extracted line actually contains the required start and end identifier.
  if (startMatch !== null) {
    const startIdentifiers = startMatch[1].split(":");
    startMatch = startIdentifiers.includes(identifier) ? startMatch : null;
  }
  if (endMatch !== null) {
    const endIdentifiers = endMatch[1].split(":");
    endMatch = endIdentifiers.includes(identifier) ? endMatch : null;
  }