feat: Add ability to exclude parts of an example with ignore-extract and end-ignore

Author: TimothyJones

README.md

@@ -51,6 +51,8 @@ function sumArray(arr: number[]): number {
 ```
 ````
 
+By using `example-extractor`, you can easily maintain and manage code examples for documentation purposes, ensuring that your examples are always up-to-date with your source code.
+
 ### Example Usage in Source Files
 
 You can have multiple examples in your source files. Each example should have a unique name:
@@ -69,7 +71,39 @@ function maxArray(arr: number[]): number {
 // end-example
 ```
 
-By using `example-extractor`, you can easily maintain and manage code examples for documentation purposes, ensuring that your examples are always up-to-date with your source code.
+### Ignoring lines
+
+Sometimes you want to exclude some code that needs to be there for your example to compile.
+If you'd like to exclude some lines in your examples, you can turn off extraction during an example with `ignore-extract` and `end-ignore`:
+
+```typescript
+// example-extract general
+function reduceNumbers(arr: number[]): number {
+  return arr.reduce(
+    /* your function goes here */
+    // ignore-example
+    (sum, current) => {
+      return sum + current;
+    },
+    // end-ignore
+    0,
+  );
+}
+// end-example
+```
+
+This would result in the following extraction:
+
+````markdown
+```ts
+function reduceNumbers(arr: number[]): number {
+  return arr.reduce(
+    /* your function goes here */
+    0,
+  );
+}
+```
+````
 
 ### Clearing the examples directory
 

src/domain/exampleExtractor.ts

@@ -3,11 +3,17 @@ import { Example, ExampleLocation } from './types.js';
 
 const START_REGEX = /^\s*(\/\/|\/\*|\*|\*\/)\s*example-extract\s*(\w+.\w+)?/;
 const END_REGEX = /^\s*(\/\/|\/\*|\*|\*\/)\s*end-example/;
+const START_IGNORE_REGEX = /^\s*(\/\/|\/\*|\*|\*\/)\s*ignore-extract/;
+const END_IGNORE_REGEX = /^\s*(\/\/|\/\*|\*|\*\/)\s*end-ignore/;
 
 // example-extract partial-example
 interface PartialExample {
+  // The name of this example
   name: string;
+  // The lines of this example
   lines: string[];
+  // Whether we're currently ignoring lines
+  ignoring: boolean;
 }
 // end-example
 
@@ -34,6 +40,7 @@ export const extractExampleSections = (
       partialExample = {
         name: startMatch[2] || `${context.basename}-${count}`,
         lines: [],
+        ignoring: false,
       };
       count += 1;
     } else if (partialExample !== undefined) {
@@ -44,6 +51,14 @@ export const extractExampleSections = (
           context,
         });
         partialExample = undefined;
+        return;
+      }
+      if (partialExample.ignoring) {
+        if (END_IGNORE_REGEX.exec(line)) {
+          partialExample.ignoring = false;
+        }
+      } else if (START_IGNORE_REGEX.exec(line)) {
+        partialExample.ignoring = true;
       } else {
         partialExample.lines.push(line);
       }