Regex Chess

Overview

This skill provides strategic guidance for implementing chess move generators using only regular expressions. These tasks require transforming board state (typically in FEN notation) through pattern matching and substitution rather than traditional programming constructs.

Core Approach

Phase 1: Understand the String Representation

Before writing any patterns, thoroughly understand the board representation:

Parse the FEN structure: FEN notation encodes rank 8 to rank 1 (top to bottom), with files a-h (left to right) within each rank
Map coordinates to string positions: Determine the exact character index for each square after expanding digit placeholders (e.g., "8" becomes "........")
Document the ordering: Create a clear mapping of how squares appear sequentially in the expanded string

Phase 2: Start Minimal - One Move Type First

Critical: Get a single move type working completely before adding complexity.

Recommended order:

Start with a single pawn push (e.g., e2-e4)
Verify the pattern matches correctly
Verify the replacement produces correct output
Only then add more pawn moves
Only after all pawn moves work, add knights (simplest piece with no sliding)
Add remaining pieces incrementally

Phase 3: Coordinate Labeling Strategy

To simplify pattern matching, consider adding coordinate labels to the expanded board:

Original: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR
Expanded with labels: R8:a8r.R8:b8n.R8:c8b...R1:h1R.

This makes patterns self-documenting and reduces coordinate confusion.

Phase 4: Pattern Structure

For each move pattern:

Capture groups for context: Use groups to preserve surrounding board state
Source square pattern: Match the piece at its origin
Destination square pattern: Match the target (empty or enemy piece)
Replacement string: Reconstruct with piece moved, preserving all other state

Verification Strategies

Test Each Transformation Step

Pattern matching verification: Confirm the pattern matches the expected input
Replacement output verification: Confirm the substitution produces correct output
Round-trip verification: Verify the output FEN is valid and represents the intended move

Incremental Testing Protocol

For each new move pattern:
1. Test on known position with expected outcome
2. Verify exactly ONE move is generated
3. Verify the move is the CORRECT move
4. Only then add to the full pattern set

Debug Output Format

When debugging, output intermediate states:

The expanded board string before matching
Which pattern matched
The captured groups and their values
The replacement string before compression
The final FEN output

Common Pitfalls

Coordinate Ordering Errors

Problem: Squares appear in a specific order in the FEN string (rank 8 first, then 7, etc.). When matching two squares, the "earlier" square in the string depends on their coordinates, not their role in the move.

Solution: When a pattern needs to match source and destination squares, determine which appears first in the string based on coordinates, not based on which is source vs. destination.

Group Numbering Confusion

Problem: Using \1, \2, etc. in replacements without tracking which group corresponds to which board region.

Solution: Comment each pattern with explicit group assignments:

# Group 1: everything before source square
# Group 2: source square piece
# Group 3: everything between source and dest
# Group 4: destination square
# Group 5: everything after destination

Premature Pattern Generation

Problem: Generating thousands of patterns before verifying the basic infrastructure works.

Solution: Generate patterns incrementally. Verify 1 pattern works, then 10, then 100, etc.

Abandoning Partial Solutions

Problem: When something partially works, starting over with a "better" approach that breaks everything.

Solution: When you have partial success (e.g., 3/3 moves correct for a test position), preserve that working code. Add to it rather than replacing it.

Format Issues vs. Logic Issues

Problem: Spending excessive time on output formatting (trailing spaces, move counters) before the core logic works.

Solution: Get the board transformation correct first. Format adjustments are a final step.

Testing Pattern Matching Without Replacement

Problem: Verifying that patterns "match" but not verifying the replacement output is correct.

Solution: Always check both: (1) does it match? (2) is the replacement correct?

Implementation Checklist

Before running full tests:

One simple move (e.g., e2-e4) works end-to-end
All pawn single pushes work
Pawn captures work
Knight moves work (no sliding complexity)
Bishop/Rook/Queen sliding moves work
King moves work
Edge cases: moves near board edges

Features often deferred (verify requirements):

Move legality (king not in check after move)
Castling with proper rights tracking
En passant
Pawn promotion
Double pawn push with en passant square update

Debugging Workflow

When a move is incorrect:

Isolate the failing case: Test with only that one pattern
Print the expanded board: Verify the input is as expected
Print captured groups: Verify each group contains what you expect
Print the raw replacement: Before any compression or formatting
Compare to expected: Character by character if needed

Avoid:

Running full test suite repeatedly without isolating the issue
Adding more patterns before fixing existing ones
Rewriting from scratch when debugging would suffice

regex-chess