Log::R...r::File(3pm)

💖 Log::R...r::File(3pm) 💖

okay bestie, this is a page from the User Contributed Perl Documentation of Perl 5, and it's lowkey one of the most useful little modules out here: Log::Report::Dispatcher::File. She's the dispatcher that takes your messages and yeets them into a file or a file-handle. Let's get into it ✨

---

🌸 NAME 🌸

Log::Report::Dispatcher::File — the way that this module literally sends messages to a file or a file-handle 💅

---

🦋 INHERITANCE 🦋

Log::Report::Dispatcher::File
  is a Log::Report::Dispatcher

So she's a subclass, she inherited the whole vibe from Log::Report::Dispatcher, and she built on top of it. No cap. 👑

---

✨ SYNOPSIS ✨

Here's the group chat, in code form 🫶:

dispatcher Log::Report::Dispatcher::File => 'stderr',
  to => \*STDERR, accept => 'NOTICE-';

# close a dispatcher
dispatcher close => 'stderr';

# let dispatcher open and close the file
dispatcher FILE => 'mylog', to => '/var/log/mylog', charset => 'utf-8';
...
dispatcher close => 'mylog';  # will close file

# open yourself, then also close yourself
open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog'
    or fault "...";
dispatcher FILE => 'mylog', to => \*OUT;
...
dispatcher close => 'mylog';
close OUT;

# dispatch into a scalar
my $output = '';
open $outfile, '>', \$output;
dispatcher FILE => 'into-scalar', to => \$outfile;
...
dispatcher close => 'into-scalar';
print $output;

Like, look at her. She can write to a file-handle, open a file herself and close it herself, or let you open and close it while she just borrows it, or even vibe into a scalar. Versatile. Slays. 💖

---

💜 DESCRIPTION 💜

This basic file logger accepts a file-handle or a filename as its destination. Simple, iconic, gets the job done.

[1.00] — writing to the file is protected by a lock, so multiple processes can write to the same file. Yes bestie, concurrency-safe. 🔥

Extends "DESCRIPTION" in Log::Report::Dispatcher.

---

🎀 METHODS 🎀

Extends "METHODS" in Log::Report::Dispatcher.

🌈 Constructors

Extends "Constructors" in Log::Report::Dispatcher.

$class->new($type, $name, %options)

Inherited, see "Constructors" in Log::Report::Dispatcher.

Here's the whole options table, no skipping, periodt:

 -Option       --Defined in             --Default
  accept         Log::Report::Dispatcher  depend on mode
  charset        Log::Report::Dispatcher  LC_CTYPE
  format                                  <adds timestamp>
  format_reason  Log::Report::Dispatcher  'LOWERCASE'
  locale         Log::Report::Dispatcher  <system locale>
  mode           Log::Report::Dispatcher  'NORMAL'
  replace                                 false
  to                                      <required>

• accept => $reasons|\@reasons
• charset => CHARSET
• format => CODE|'LONG' — [1.00] this processes each printed line. By default she adds a timestamp, but honestly you might want to add hostname, process number, or whatever else your heart desires:

format => sub { '['.localtime().'] '.$_[0] }
format => sub { shift }   # no timestamp
format => 'LONG'

The first parameter to format is the string to print; it's already translated and trailed by a newline. The second parameter is the text-domain (if it's known).

[1.10] As a third parameter, you get the message raw object as well (maybe you wanna use the message context?). 👀

[1.19] After those three positional parameters, there may be a list of pairs providing additional facts about the exception. It may contain "location" information.

The "LONG" format is equivalent to:

my $t = strftime "%FT%T", gmtime;
"[$t $$] $_[1] $_[0]"

And if you want to use context:

format => sub { my ($msgstr, $domain, $msg, %more) = @_;
   my $host = $msg->context->{host};
   "$host $msgstr";
}

• format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
• locale => LOCALE
• mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
• replace => BOOLEAN — only used in combination with a "to" filename: it throws away the old file if it exists. But bestie, you probably wanna append to your existing info instead. 🙈

Use the locale setting by default, which is LC_CTYPE or LC_ALL or LANG (in that order). If these contain a character-set which Perl understands, then that's what she uses — otherwise it's silently ignored. 💀

• to => $file|$fh|OBJECT|CODE — you can either specify a $file by name, which is opened in append mode with autoflush on. Or you can pass any kind of file handle $fh, or some OBJECT which implements a print() method. You probably want autoflush enabled on your file-handles, ngl.

When cleaning-up the dispatcher, the file will only be closed in case of a named $file.

[1.10] When you pass a CODE, then for each log message the function is called with two arguments: this dispatcher object and the message object. In some way (maybe via the message context) you have to determine the log filename. This means that probably many log-files are open at the same time. 🫶

# configuration time
dispatcher FILE => 'logfile', to =>
   sub { my ($disp, $msg) = @_; $msg->context->{logfile} };

# whenever you want to change the logfile
textdomain->updateContext(logfile => '/var/log/app');
(textdomain 'mydomain')->setContext(logfile => '/var/log/app');

# or
error __x"help", _context => {logfile => '/dev/tty'};
error __x"help", _context => "logfile=/dev/tty";

🌟 Attributes

Extends "Attributes" in Log::Report::Dispatcher.

• $obj->filename() — returns the name of the opened file, or "undef" in case this dispatcher was started from a file-handle or file-object.
• $obj->format()
• $obj->isDisabled() — inherited, see "Attributes" in Log::Report::Dispatcher.
• $obj->mode() — inherited, see "Attributes" in Log::Report::Dispatcher.
• $obj->name() — inherited, see "Attributes" in Log::Report::Dispatcher.
• $obj->needs( [$reason] ) — inherited, see "Attributes" in Log::Report::Dispatcher.
• $obj->output($msg) — returns the file-handle to write the log lines to. [1.10] This may depend on the $msg (especially message context).
• $obj->type() — inherited, see "Attributes" in Log::Report::Dispatcher.

🧚 File maintenance

• $obj->rotate($filename|CODE) — [1.00] move the current file to $filename, and start a new file. Fresh file, same energy. ✨

🍓 Logging

Extends "Logging" in Log::Report::Dispatcher.

• $any->addSkipStack(@CODE) — inherited, see "Logging" in Log::Report::Dispatcher.
• $obj->close() — only when initiated with a FILENAME, the file will be closed. In any other case, nothing will be done. Improves base, see "Logging" in Log::Report::Dispatcher.
• $any->collectLocation() — inherited, see "Logging" in Log::Report::Dispatcher.
• $any->collectStack( [$maxdepth] ) — inherited, see "Logging" in Log::Report::Dispatcher.
• $obj->log(\%options, $reason, $message, $domain) — inherited, see "Logging" in Log::Report::Dispatcher.
• $obj->skipStack() — inherited, see "Logging" in Log::Report::Dispatcher.
• $any->stackTraceLine(%options) — inherited, see "Logging" in Log::Report::Dispatcher.
• $obj->translate(\%options, $reason, $message) — inherited, see "Logging" in Log::Report::Dispatcher.

---

🦄 DETAILS 🦄

Extends "DETAILS" in Log::Report::Dispatcher.

---

💅 DIAGNOSTICS 💅

These are the moments where she has to be dramatic 😭:

• Error: cannot rotate log file which was opened as file-handle
  • Cast by rotate()
• Fault: cannot write log into $file: $!
  • Cast by rotate()
• Error: dispatcher $name needs parameter 'to'
  • Cast by new()
• Fault: unable to rotate logfile $fn to $oldfn: $!
  • Cast by rotate()
• Error: unknown format parameter `$what'
  • Cast by new()

---

👑 SEE ALSO 👑

This module is part of Log-Report version 1.46, built on June 16, 2026. Website: http://perl.overmeer.net/CPAN/

---

🌸 LICENSE 🌸

For contributors see file ChangeLog.

This software is copyright (c) 2007-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie 🫶 this documentation shipped as perl v5.40.1, dated 2026-07-05, and it's giving "go write some logs" energy. slay, go forth, dispatcher icon 💖🌈✨