1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
# 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.
|
