# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Data::Random is a CPAN Perl module for generating random data (words, characters, dates, times, images, etc.), primarily useful for test programs. Maintained by Buddy Burden (barefoot@cpan.org). Repository: https://github.com/barefootcoder/Data-Random

## Build & Test Commands

This project uses **Dist::Zilla** as its build/release system.

```bash
# Build the distribution
dzil build

# Run all tests
dzil test

# Run a single test file
prove -l t/rand_chars.t

# Run all tests directly (without dzil)
prove -l t/

# Release to CPAN (builds, tests, commits, tags, pushes, uploads)
dzil release
```

Note: `Makefile.PL` is auto-generated by Dist::Zilla and not in source control.

## Architecture

The module is intentionally simple — two Perl modules and a bundled wordlist:

- **`lib/Data/Random.pm`** — Main module. Exports 8 functions: `rand_words`, `rand_chars`, `rand_set`, `rand_enum`, `rand_date`, `rand_time`, `rand_datetime`, `rand_image`. Uses traditional Exporter pattern (all functions in `:all` tag, none exported by default). Errors are non-fatal (uses `Carp::cluck` + returns undef).
- **`lib/Data/Random/WordList.pm`** — OO helper that reads from the wordlist file efficiently (doesn't load entire file into memory). Methods: `new()`, `get_words()`, `close()`.
- **`lib/Data/Random/dict`** — Bundled wordlist (~45K words, derived from minix.dict). Installed via File::ShareDir.

## Code Style

This is a traditional-style Perl module (pre-Moose, pre-signatures):
- `use strict; use warnings;` but targets `use 5.005_62`
- Old-style OO (`@ISA`, `use vars`, `bless`)
- Options parsed as `my %options = @_`
- Context-sensitive returns (`wantarray`)
- K&R bracing style (opening brace on same line)

## Testing Notes

- Tests use `Test::More` with `done_testing` (no predeclared test count)
- `rand_image.t` skips if `GD` module is not installed
- `rand_time.t` uses `Test::MockTime` to avoid midnight-boundary failures
- POD tests (`z0_pod.t`, `z1_pod-coverage.t`) require `Test::Pod`
- Many tests run 1000 iterations to validate random distributions

## Key Dependencies

- **Runtime**: `Time::Piece` >= 1.16 (core since Perl 5.10)
- **Optional**: `GD` (only for `rand_image`)
- **Test**: `Test::More` >= 0.88, `Test::MockTime`, `File::Temp`

## Release Process

1. **Add changelog entries** under the `{{$NEXT}}` placeholder in `Changes` (the `[NextRelease]` plugin replaces this with the version and timestamp at release time).
2. **Run `dzil release`**, which:
   - Builds the distribution and runs tests
   - Rewrites `{{$NEXT}}` in Changes with version + timestamp
   - Commits with message `"packaging for CPAN: <version>"`
   - Creates a git tag
   - Pushes to GitHub
   - Uploads to CPAN
3. **After release**, `[BumpVersionAfterRelease]` increments `$VERSION` in the source files, which needs to be committed separately (e.g., `increment $VERSION after X.XX release`).

The version in `$VERSION` in `lib/Data/Random.pm` is the source of truth. `[RewriteVersion]` reads it at build time.
