view release on metacpan or  search on metacpan

CLAUDE.md  view on Meta::CPAN

```bash
cpanm --installdeps .          # Install dependencies from cpanfile
```

### Building
```bash
perl Build.PL                  # Generate Build script
./Build                        # Build the distribution
```

### Testing
```bash
prove -lvr t                   # Run all tests (same as CI)
./Build test                   # Alternative test runner
minil test                     # Run full test suite (mirrors CI)
```

### Running Locally
```bash
greple -Ilib -Mwordle         # Run the game using local code
greple -Ilib -Mwordle --series=0 --index=0  # Test with specific answer
```

### Release Process
```bash
minil test                     # Verify all tests pass
# Update $VERSION in lib/App/Greple/wordle.pm
# Update Changes file
minil release                  # Tag and release
```

## Architecture

### Module Structure

The codebase follows a clear separation of concerns:

- **lib/App/Greple/wordle.pm**: Main entry point and CLI orchestration
  - Handles option parsing via Getopt::EX::Hashed
  - Dynamically loads dataset modules based on --data option
  - Manages interactive game loop and user input
  - Integrates with greple's pattern matching system
  - Implements command parsing (hint, uniq, filtering)

- **lib/App/Greple/wordle/game.pm**: Game state and logic
  - Tracks attempts and answer
  - Generates regex patterns for hints
  - Produces colored output (keymap, hints, result squares)
  - Uses Mo for minimal object system

- **lib/App/Greple/wordle/util.pm**: Shared utilities
  - Currently contains `uniqword()` for filtering unique-character words

- **lib/App/Greple/wordle/ORIGINAL.pm**: Original Wordle dataset
  - Exports `@WORDS` (all valid words) and `@HIDDEN` (answer list)
  - Contains classic Wordle word list from original game
  - Uses Data::Section::Simple for data storage

- **lib/App/Greple/wordle/NYT.pm**: New York Times Wordle dataset
  - Exports `@WORDS` (all valid words) and `@HIDDEN` (answer list)
  - Contains NYT Wordle word list (updated through November 2025)
  - Uses Data::Section::Simple for data storage

- **lib/App/Greple/wordle/word_all.pm**: Legacy word dictionary (deprecated)
  - Kept for backward compatibility
  - Exports `@word_all` array and `%word_all` hash

- **lib/App/Greple/wordle/word_hidden.pm**: Legacy answer list (deprecated)
  - Kept for backward compatibility
  - Shuffled using series number as seed

### Integration with greple

The module leverages greple's pattern matching engine:
- Game colors (green/yellow/black) map to regex patterns passed to greple
- `--interactive` mode hooks into greple's processing pipeline via `--begin`, `--end`, `--epilogue`
- Uses greple's colormap system for terminal output
- Pattern generation in `patterns()` creates position-aware regex

### Option Handling

Uses Getopt::EX::Hashed for declarative option definitions:
- Options defined with `has` macro including specs, defaults, actions
- `--data` option selects dataset (default: ORIGINAL)
- Custom action for `--compat` that sets series to 0
- Supports environment variables (`WORDLE_ANSWER`, `WORDLE_INDEX`)
- Negative index values are relative to current day
- Dataset modules are dynamically loaded via `eval "use $pkg"`

### Color and Display

Three distinct color systems:
1. **Game colors**: Green (correct position), Yellow (wrong position), Black (not in word)
2. **Keymap display**: Shows tried letters with their status
3. **Result squares**: Unicode emoji squares for sharing results

## Key Technical Details

### Answer Selection
- Default index calculated from days since 2021-06-19
- Dataset selected via `--data` option (ORIGINAL or NYT)
- Series 0 matches original Wordle answers
- Non-zero series shuffles answers using seed for reproducibility
- Out-of-range index triggers random selection with warning
- Supports manual answer via `--answer` or `WORDLE_ANSWER` env var

### Command System
Commands can be chained with spaces:
- `hint` / `h`: Filter to possible words based on attempts
- `uniq` / `u`: Filter to words with unique characters
- `=chars`: Include only words containing all chars
- `!chars`: Exclude words containing any chars
- `!!`: Recall last command result
- Any regex: Custom filtering

### Hint Generation Algorithm (game.pm:_hint)
1. Tracks confirmed positions (green) and excluded chars per position
2. Builds lookahead assertions for required chars
3. Creates negative lookahead for excluded chars
4. Combines into single regex pattern for word filtering