docs: getLines support named section markers, fix #1320 (#1555)

Fix #1320 suggested in
#1318 (review)

docs/docs/hydroflow/quickstart/example_1_simplest.mdx

@@ -52,15 +52,15 @@ And then run the program:
 ## Understanding the Code
 Although this is a trivial program, it's useful to go through it line by line.
 
-<CodeBlock language="rust">{getLines(exampleCode, 1)}</CodeBlock>
+<CodeBlock language="rust">{getLines(exampleCode, 'use')}</CodeBlock>
 
-This import gives you everything you need from Hydroflow to write code with Hydroflow's
+This import gives you the macro you need from Hydroflow to write code in Hydroflow's
 [_surface syntax_](../syntax).
 
 Next, inside the main method we specify a flow by calling the
 `hydroflow_syntax!` macro. We assign the resulting `Hydroflow` instance to
 a mutable variable `flow`––mutable because we will be changing its status when we run it.
-<CodeBlock language="rust">{getLines(exampleCode, 3, 6)}</CodeBlock>
+<CodeBlock language="rust">{getLines(exampleCode, 'macro_call')}</CodeBlock>
 
 Hydroflow surface syntax defines a "flow" consisting of *operators* connected via `->` arrows.
 This simplest example uses a simple two-step linear flow.
@@ -74,7 +74,7 @@ The Hydroflow surface syntax is merely a *specification*; it does not actually d
 until we run it.
 We can run this flow from within Rust via the [`run_available()` method](https://hydro-project.github.io/hydroflow/doc/hydroflow/scheduled/graph/struct.Hydroflow.html#method.run_available).
 
-<CodeBlock language="rust">{getLines(exampleCode, 8)}</CodeBlock>
+<CodeBlock language="rust">{getLines(exampleCode, 'run')}</CodeBlock>
 
 Note that `run_available()` runs the Hydroflow graph until no more work is immediately
 available. In this example flow, running the graph drains the iterator completely, so no

docs/src/util.ts

@@ -1,8 +1,41 @@
-/// Grabs the specified lines `[lineStart, lineEnd]` from the string.
+/// Grabs the specified lines from the string.
+///
+/// Can specify a line number range `lineStart, lineEnd`, a specific line number `lineNumber` (no
+/// second arg), or a section name.
 ///
 /// Lines are one-indexed (start with `1`). Both `lineStart` and `lineEnd` are inclusive.
-export function getLines(str: string, lineStart: number, lineEnd?: number): string {
-    let lines = str.split('\n').slice(lineStart - 1, lineEnd || lineStart);
+///
+/// Sections are marked in the code with a start tag `//[mysection]//` and and end tag
+/// `//[/mysection]//`. The rest of these tag lines must be whitespace, and these tag lines are not
+/// included in the output. However they are included for line number _counting_.
+export function getLines(str: string, sectionName: string): string;
+export function getLines(str: string, lineStart: number, lineEnd?: number): string;
+export function getLines(str: string, lineStartOrSectionName: number | string, lineEnd?: number): string {
+    // `//[section]//` or `//[/section]//` (rest of line must be whitespace).
+    const SECTION_REGEX = /^\s*\/\/\[(\/?)(\S+)\]\/\/\s*$/;
+    let lines;
+    if ('string' === typeof lineStartOrSectionName) {
+        let inSection = false;
+        lines = str
+            .split('\n')
+            .filter(line => {
+                const match = SECTION_REGEX.exec(line);
+                if (null == match) {
+                    return inSection;
+                }
+                const [_, end, name] = match;
+                if (name == lineStartOrSectionName) {
+                    inSection = 0 === end.length;
+                }
+                return false;
+            })
+    }
+    else {
+        lines = str
+            .split('\n')
+            .slice(lineStartOrSectionName - 1, lineEnd || lineStartOrSectionName) // Select lines before removing section lines.
+            .filter(line => !SECTION_REGEX.test(line));
+    }
     const leadingWhitespace = Math.min(...lines.filter(line => 0 !== line.length).map(line => line.search(/\S/)).map(Number));
     if (0 < leadingWhitespace) {
         lines = lines.map(line => line.slice(leadingWhitespace));
@@ -40,7 +73,7 @@ ${stdOut}`;
 /// Extract the mermaid graph logged to stdout from the snapshots created by `surface_examples.rs`.
 export function extractMermaid(output: string): string {
     const outputLines = output.split('\n');
-     // Delete the first four lines, which are the snapshot front matter.
+    // Delete the first four lines, which are the snapshot front matter.
     outputLines.splice(0, 4);
     // Mermaid graph starts with double-percent signs.
     if (!outputLines[0].startsWith('%%')) {

hydroflow/examples/example_1_simplest.rs

@@ -1,9 +1,15 @@
+//[use]//
 use hydroflow::hydroflow_syntax;
+//[/use]//
 
+//[macro_call]//
 pub fn main() {
     let mut flow = hydroflow_syntax! {
         source_iter(0..10) -> for_each(|n| println!("Hello {}", n));
     };
+    //[/macro_call]//
 
+    //[run]//
     flow.run_available();
+    //[/run]//
 }