Add WithWhiteSpaceParser() extension for custom whitespace handling

[Copilot]

• Explore repository structure and understand the codebase
• Build and test the project to verify current state
• Understand ParseContext and WhiteSpaceParser mechanism
• Create WithWhiteSpaceParser extension method
• Implement parser class that sets/resets WhiteSpaceParser
• Add comprehensive unit tests
• Build and verify all tests pass
• Run code review - No issues found
• Run security scan with CodeQL - No vulnerabilities found
• Manually verified the example from the issue works correctly
• Add documentation section in parsers.md

Implementation Summary

Added WithWhiteSpaceParser(Parser<TextSpan>) extension method that allows grammars to define custom whitespace parsers. The implementation:

1. WithWhiteSpaceParser class: Wraps a parser and temporarily sets a custom whitespace parser in the ParseContext
2. Extension method: Provides fluent API for using custom whitespace parsers
3. Proper cleanup: Uses try-finally to restore the previous whitespace parser after parsing
4. Compilation support: Implements ICompilable to support compiled parsers
5. ISeekable support: Propagates seekability information from the wrapped parser
6. Documentation: Added comprehensive documentation in parsers.md with usage examples

Testing

• Added 8 comprehensive unit tests covering:

  • Basic usage with custom whitespace
  • Regular whitespace should not be skipped with custom parser
  • Context restoration after parsing
  • Nested WithWhiteSpaceParser calls
  • Integration with ZeroOrMany combinator
  • Empty whitespace handling
  • Compilation support
  • Multi-character whitespace patterns

• All 649 tests pass on net9.0 and 621 tests pass on net8.0

• Manually verified the example from the issue works correctly

Security Summary

• No security vulnerabilities detected by CodeQL
• No code review issues found

Original prompt

---

This section details on the original issue you should resolve

<issue_title>New WithWhiteSpaceParser() parser extension</issue_title>
<issue_description>The WithWhiteSpaceParser(IParser<TextSpan>) extension will set the current parser context's WhiteSpaceParser property and reset it before existing.

This will allow grammars to define how to parse whitespace:

var hello = Terms.Text("hello");
var world = Terms.Text("world");
var parser = hello.And(world);
parser.WithWhiteSpace(Literals.Char('.'));

// Usage:

parser.Parse("..hello.world"); // Should succeed

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes New WithWhiteSpaceParser() parser extension #259

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[sebastienros]

@copilot add a section in parsers.md

[sebastienros]

/cc @lampersky

[Copilot]

@copilot add a section in parsers.md

Added documentation for WithWhiteSpaceParser in the Coordination parsers section of parsers.md. The section includes the method signature, usage examples showing both basic and nested usage, and a note about requiring TextSpan return type. (5eac370)