/ 
Developer-Dashboard-4.45
/ Developer::Dashboard::FileSlurp

NAME

Developer::Dashboard::FileSlurp - shared whole-file-read helper

SYNOPSIS

use Developer::Dashboard::FileSlurp qw(slurp_file);
my $text = slurp_file($path);
my $raw  = slurp_file($path, raw => 1, on_missing => 'empty');

DESCRIPTION

Provides slurp_file, the single home for the open/read-whole-file idiom that used to be written out independently, and had already drifted, at three call sites across three modules.

PURPOSE

This module exists to give the codebase one place to read a whole file into a string, with explicit options for raw-vs-text mode and missing-file behavior, instead of three independent copies of the same open/read loop.

WHY IT EXISTS

Collector.pm, CollectorRunner.pm and CLI/Ask.pm each carried their own _slurp sub, and by the time anyone looked (DD-888) the three had already diverged: one opened :raw and returned '' on a missing file, one opened without :raw and died unconditionally, and one opened :raw, died with a custom message, and explicitly normalized an undef read to ''. Same class of duplication DD-762 fixed for directory listings with DirEntries.pm.

WHEN TO USE

Use slurp_file whenever code needs to read an entire file into memory as a string. Choose raw => 1 for byte-exact reads (binary data, attachments); leave it off for text files where Perl's default encoding translation is wanted. Choose on_missing => 'empty' when a missing file is an expected, non-fatal case; leave the default ('die') when a missing file is a real error the caller should not swallow.

HOW TO USE

my $text = slurp_file('/path/to/file.txt');
my $raw  = slurp_file('/path/to/file.bin', raw => 1);
my $safe = slurp_file('/maybe/missing', on_missing => 'empty');
my $msg  = slurp_file(
    '/maybe/missing',
    missing_message => 'Unable to read attachment %s: %s',
);

WHAT USES IT

Developer::Dashboard::Collector, Developer::Dashboard::CollectorRunner and Developer::Dashboard::CLI::Ask, each preserving its own pre-existing raw-mode and missing-file contract via explicit options.

EXAMPLES

use Developer::Dashboard::FileSlurp qw(slurp_file);

# Collector.pm-shaped call: raw, empty string on a missing file
my $body = slurp_file($state_file, raw => 1, on_missing => 'empty');

# CollectorRunner.pm-shaped call: text mode, dies with the default message
my $config = slurp_file($config_file);

# CLI/Ask.pm-shaped call: raw, a custom die message, undef normalized to ''
my $attachment = slurp_file(
    $attachment_path,
    raw             => 1,
    missing_message => 'Unable to read attachment %s: %s',
    normalize_undef => 1,
);