[Feature] Enhanced Line Selection Syntax

[spenpal]

I propose an enhancement to adopt a Python-like slicing syntax for line selection. This would bring more flexibility, clarity, and ease of maintenance for developers, alongside new options: the ability to exclude specific lines/ranges and negative indexing.

This feature would extend the current line selection system (start-end, line). The new syntax would offer a versatile way to define inclusion and exclusion rules for lines in a file, improving usability and maintaining alignment with the needs of developers working with Typedoc.

Proposed Syntax

1. Indexing

   • Inclusive start and end (start:end).
   • Open-ended ranges (start: or :end) for selecting all lines from a starting point or up to an ending point, respectively.
   • Negative indexing (e.g., -1 for the last line, -2 for the second-to-last line, etc.).
   • Comma-separated values to combine multiple ranges and/or individual lines (e.g., 2:5, 10).

2. Exclusions

   • Use ! to exclude specific lines or ranges (!start:end, !line).
   • Exclusions take precedence over inclusions.

Usage

/**
 * @includeExample path/to/example.ts             // All lines
 * @includeExample path/to/example.ts[:]          // All lines (with brackets)
 * @includeExample path/to/example.ts[10]         // Line 10
 * @includeExample path/to/example.ts[2:]         // Lines 2, 3, 4, ...
 * @includeExample path/to/example.ts[!1]         // Lines 2, 3, 4, ...
 * @includeExample path/to/example.ts[:5]         // From the start to line 5
 * @includeExample path/to/example.ts[1:5]        // From the start to line 5
 * @includeExample path/to/example.ts[2:5,10]     // Lines 2, 3, 4, 5, and line 10
 * @includeExample path/to/example.ts[1:10,!5:7]  // Lines 1–4, 7–10 (excludes lines 5–7)
 * @includeExample path/to/example.ts[:10,!3,!7]  // Lines 1–2, 4–6, 8–10
 * @includeExample path/to/example.ts[-5]         // Last fifth line
 * @includeExample path/to/example.ts[-5:]        // Last 5 lines
 * @includeExample path/to/example.ts[:-5]        // All lines except the last 5
 * @includeExample path/to/example.ts[-5:-2]      // Last fifth line to second-to-last line
 */

Advantages

1. Flexibility: The new syntax handles a broad set of use cases, including open-ended selections, exclusions, and negative indexing.
2. Maintainability: Open-ended ranges (e.g., 2:) simplify maintenance, as files can grow without requiring updates to the tag.
3. Exclusions: Excluding specific lines or ranges provides precise control over what is included in documentation.
4. Compactness: The syntax remains concise and easy to read, even for complex selections.
5. Expressiveness: The syntax is versatile and allows the same selection to be expressed in multiple ways.

   /**
   * @includeExample path/to/example.ts[2:]       // Lines 2 to the end of the file
   * @includeExample path/to/example.ts[!1]       // From line 2 to the end of the file (excludes line 1)
   */

Roadmap

1. Python-like syntax with brackets and commas ([2:3, 10])
2. Exclusion for single lines and ranges ([!3, !5:7])
3. Negative indexing ([-3:, -5:-2])

Feedback

I would love to hear your thoughts on this proposed feature. Is this approach something you see aligning with the goals of this plugin? Are there additional edge cases or scenarios you'd like addressed?

[ferdodo]

Absolutely, you can give it a try as long as there is no more dependencies added. You can update directly the current line parsing code.

As this is a breaking change, we need a new major version. Also, if the old fashion syntax is detected, building the documentation should fail with a migration note, indicating syntax evolved since x.x version.