Log::R...on::POT(3pm)

📦

version 1.15 · 5 versions

1.15 · ubuntu resolute, ubuntu stonking (latest)
1.11 · ubuntu jammy
1.15 · fedora 44
1.11 · debian bookworm, ubuntu noble
1.12 · debian trixie, ubuntu questing

✨ NAME ✨

Log::R...on::POT(3pm) — this is the manual page for it, bestie 💖 — and what it does is manage PO files. That's the whole vibe.

🧬 INHERITANCE 🧬

Log::Report::Lexicon::POT
  is a Log::Report::Lexicon::Table

So like, it's a Table, but make it POT-flavoured 💅

🎀 SYNOPSIS 🎀

okay so heads up: this is usually not for end-users, see ::Extract::PerlPPI. Got it? Cool. Now watch:

# this is usually not for end-users, See ::Extract::PerlPPI
# using a PO table

my $pot = Log::Report::Lexicon::POT->read('po/nl.po', charset => 'utf-8')
   or die;

my $po = $pot->msgid('msgid');
my $po = $pot->msgid($msgid, $msgctxt);
print $pot->nrPlurals;
print $pot->msgstr('msgid', 3);
print $pot->msgstr($msgid, 3, $msgctxt);
$pot->write;  # update the file

# fill the table, by calling the next a lot
my $po  = Log::Report::Lexicon::PO->new(...);
$pot->add($po);

# creating a PO table
$pot->write('po/nl.po')
    or die;

that last one or die is doing the lord's work, protect it 🫶

🌸 DESCRIPTION 🌸

This module is out here reading, extending, and writing POT files. POT files store translations in a humanly readable format for basically every translation framework that exists — we're talking GNU gettext and Perl's Maketext. Iconic. 👑

ngl tho, if all you want to do is access the translation, you should use the much more efficient Log::Report::Lexicon::POTcompact instead. She's slimmer and faster, no shade to POT.

The code is loosely based on Locale::PO, by Alan Schwartz. The coding style is a bit off from the rest of "Log::Report", and there was a genuine need for sincere simplification. Every single PO record gets represented by a Log::Report::Lexicon::PO.

Extends "DESCRIPTION" in Log::Report::Lexicon::Table.

🛠️ METHODS 🛠️

Extends "METHODS" in Log::Report::Lexicon::Table.

🧚 Constructors 🧚

Extends "Constructors" in Log::Report::Lexicon::Table.

`$class->new(%options)`

Creates a brand new POT file, bestie. The initial header is generated for you (so generous of it), but you can change it later with the header() method.

Here's the default situation 🍓:

-Option      --Default
 charset       'UTF-8'
 date          now
 filename      undef
 index         {}
 nr_plurals    2
 plural_alg    n!=1
 plural_forms  <constructed from nr_plurals and plural_alg>
 textdomain    <required>
 version       undef

charset => STRING — the charset for the created file. It is unwise to use anything other than 'UTF-8', but you're allowed. Before [1.09] this option was required, so count your blessings ✨
date => STRING — overrule the date that gets baked into the generated header.
filename => STRING — specify an output filename. You can also just hand it over when write() is called, whatever's easier.
index => HASH — a whole set of translations (Log::Report::Lexicon::PO objects), keyed by msgid.
nr_plurals => INTEGER — how many translations each translation with a plural form needs to have.
plural_alg => EXPRESSION — the algorithm used to figure out which translated msgstr to use.
plural_forms => RULE — [0.992] when you use this option it overrules "nr_plurals" and "plural_alg". The RULE should be a full "Plural-Forms" field. She said "I'll take it from here" 💅
textdomain => STRING — the package name, used in the directory structure for storing the PO files.
version => STRING — yeah. just that. 🙂

`$class->read($filename, %options)`

Reads the POT info straight out of $filename.

-Option --Default
 charset  <required>

charset => STRING — the character-set used for the file. You must specify this explicitly, no defaults, no shortcuts, no vibes-based guessing 🙈

`$obj->write( [$filename|$fh], %options )`

When you pass an open $fh, you are the one responsible for making sure the correct character-encoding (binmode) is set. That's on you, bestie. But when the write follows a read() — or the filename was explicitly set with filename() — then you get to skip the first parameter entirely. So relaxed.

-Option     --Default
 only_active  false

only_active => BOOLEAN — [1.02] don't write records that do have a translation but whose msgid has disappeared from the sources. By default, those records get commented out (marked with '#~') but left in the file. She's not ghosting them, just putting them on ice 🧊

🔮 Attributes 🔮

Extends "Attributes" in Log::Report::Lexicon::Table.

$obj->charset() — the character-set used for reading and writing. You do not need to be aware of Perl's internal encoding for the characters. Phew.
$obj->filename() — returns the filename, derived from read() or specified during initiation with new(filename).
$obj->index() — returns a HASH of all defined PO objects, organized by msgid. But please, try to avoid using this? Use msgid() for lookup and add() for adding translations. This is the "don't touch the thing directly" situation 😭
$obj->language() — returns the language code, which is derived from the filename.

👑 Managing PO's 👑

Extends "Managing PO's" in Log::Report::Lexicon::Table.

$obj->keepReferencesTo($table) — removes every reference that isn't found as a key in the hash $table. Returns the number of references left.
$obj->removeReferencesTo($filename) — removes all the references to the indicated $filename from all defined translations. Returns the number of refs left.
$obj->stats() — returns a HASH with some statistics about this POT table. Numbers! 📊
$obj->updated( [$date] ) — replaces the "PO-Revision-Date" with the specified $date, or with the current moment if you don't bother.

🦋 Translation 🦋

Extends "Translation" in Log::Report::Lexicon::Table.

$obj->msgid( STRING, [$msgctxt] ) — looks up the Log::Report::Lexicon::PO matching the "STRING". Wanna add a new translation? Use add(). Returns "undef" when it's not defined. Improves base, see "Translation" in Log::Report::Lexicon::Table
$obj->msgstr( $msgid, [$count, [$msgctxt]] ) — returns the translated string for $msgid. When $count isn't specified or is "undef", you get the translation string related to "1". Improves base, see "Translation" in Log::Report::Lexicon::Table

💜 Administration 💜

Extends "Administration" in Log::Report::Lexicon::Table.

$obj->add($po) — adds the info from a $po into this POT. If the msgid of the $po is already known? That's an error, no cap. Improves base, see "Administration" in Log::Report::Lexicon::Table
$obj->header( [$field, [$content]] ) — the translation of a blank MSGID is used to store a MIME header, which holds some meta-data. When you only specify a $field, that content gets looked up (case-insensitive) and returned. When you specify a $content, the knowledge gets stored — and in that case the header structure may get created. Set the $content to "undef" and the field gets removed. Improves base, see "Administration" in Log::Report::Lexicon::Table
$obj->nrPlurals() — inherited, see "Administration" in Log::Report::Lexicon::Table
$obj->pluralIndex($count) — inherited, see "Administration" in Log::Report::Lexicon::Table
$obj->setupPluralAlgorithm() — inherited, see "Administration" in Log::Report::Lexicon::Table
$obj->translations( [$active] ) — returns a list with all defined Log::Report::Lexicon::PO objects. When the string $active is given as a parameter, only the objects that have references come back. Improves base, see "Administration" in Log::Report::Lexicon::Table

💀 DIAGNOSTICS 💀

the way this module is very honest about everything that can go wrong. we love a transparent king 🔥

Error: cannot detect charset in $fn — cast by read()
Fault: cannot read from file $fn (unknown charset): $! — cast by read()
Fault: cannot read in $cs from file $fn: $! — cast by read()
Fault: cannot write to file $fn with $layers: $! — cast by write()
Fault: failed reading from file $fn: $! — cast by read()
Error: invalid plural-form algorithm '$alg' — cast by setupPluralAlgorithm()
Error: no filename or file-handle specified for PO — when a PO file gets written, a filename or file-handle must be specified explicitly, or set beforehand using the filename() method, or known because the write follows a read() of the file. Cast by write()
Error: no filename or file-handle specified for PO — cast by write()
Error: no header defined in POT for file $fn — cast by header()
Error: textdomain parameter is required — cast by new()
Error: the only acceptable parameter is 'ACTIVE', not '$p' — cast by translations()
Error: there is no Plural-Forms field in the header, but needed — cast by pluralIndex()
Error: translation already exists for '$msgid' with '$ctxt — cast by add()
Error: unsupported charset $charset in $fn — cast by read()

yes, that "no filename or file-handle specified for PO" really is listed twice. we keep the facts exactly as they are, periodt 💅

🌈 SEE ALSO 🌈

This module is part of Log-Report-Lexicon version 1.15, built on November 06, 2025. Website: http://perl.overmeer.net/CPAN/

📜 LICENSE 📜

For contributors see file ChangeLog.

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 — perl v5.40.1, dated 2025-11-11, from the Log::R...on::POT(3pm) era 💖 go forth and manage those PO files, you absolute icon 🎀✨

📦 where this page comes from

ubuntu resolute: liblog-report-lexicon-perl 1.15-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: liblog-report-lexicon-perl 1.15-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms