Skip to content

CLAUDE.md

Latest commit

 

History

History
75 lines (52 loc) · 3.08 KB

CLAUDE.md

File metadata and controls

75 lines (52 loc) · 3.08 KB

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.

# 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.