Prima::IniFile(3)

💖 NAME 💖

okay so bestie, this is Prima::IniFile — the manual page you're literally reading — and it's all about support of Windows-like initialization files. slay.

---

🌸 DESCRIPTION 🌸

The module gives you a mapping from a text initialization file to a two-level hash structure, and honestly it's giving organized queen energy. The first level is sections, which groups the second level hashes, items. Sections must have unique keys — no duplicates, periodt. The values of the item hashes are arrays of text strings. The methods that operate on these arrays are get_values, set_values, add_values, and replace_values — those four are the main characters here 💅.

---

✨ SYNOPSIS ✨

here's the whole vibe in code form, bestie — copy it exactly:

        use Prima::IniFile;

        my $ini = create Prima::IniFile;
        my $ini = create Prima::IniFile FILENAME;
        my $ini = create Prima::IniFile FILENAME,
                                        default => HASHREF_OR_ARRAYREF;
        my $ini = create Prima::IniFile file => FILENAME,
                                        default => HASHREF_OR_ARRAYREF;

        my @sections = $ini->sections;
        my @items = $ini->items(SECTION);
        my @items = $ini->items(SECTION, 1);
        my @items = $ini->items(SECTION, all => 1);

        my $value = $ini-> get_values(SECTION, ITEM);
        my @vals = $ini-> get_values(SECTION, ITEM);
        my $nvals = $ini-> nvalues(SECTION, ITEM);

        $ini-> set_values(SECTION, ITEM, LIST);
        $ini-> add_values(SECTION, ITEM, LIST);
        $ini-> replace_values(SECTION, ITEM, LIST);

        $ini-> write;
        $ini-> clean;
        $ini-> read( FILENAME);
        $ini-> read( FILENAME, default => HASHREF_OR_ARRAYREF);

        my $sec = $ini->section(SECTION);
        $sec->{ITEM} = VALUE;
        my $val = $sec->{ITEM};
        delete $sec->{ITEM};
        my %everything = %$sec;
        %$sec = ();
        for ( keys %$sec) { ... }
        while ( my ($k,$v) = each %$sec) { ... }

---

🦋 METHODS 🦋

add_values SECTION, ITEM, @LIST

Adds LIST of string values to ITEM in SECTION. lowkey just piles more values on, no cap.

clean

Cleans all internal data in the object — including the name of the file. it's giving fresh start, bestie 🧚.

create PROFILE

Creates an instance of the class. The PROFILE is treated partly as an array, and partly as a hash — yes, it's both, we contain multitudes 💜. If PROFILE consists of a single item, that item is treated as a filename. Otherwise, PROFILE is treated as a hash, where these keys are allowed:

• file FILENAME — selects the name of the file.
• default %VALUES — selects the initial values for the file, where VALUES is a two-level hash of sections and items. It gets passed to read, where it is merged with the file data.

get_values SECTION, ITEM

Returns an array of values for ITEM in SECTION. If you call it in scalar context and there is more than one value, you get the first value in the list — first one ate, no notes 🔥.

items SECTION [ HINTS ]

Returns items in SECTION. The HINTS parameters are used to tell if a multiple-valued item must be returned as several items of the same name. HINTS can be supplied in the following forms: items( $section, 1 ) or items( $section, all => 1); — both iconic, pick your fave.

new PROFILE

Same as create. literally the same thing, bestie.

nvalues SECTION, ITEM

Returns the number of values in ITEM in SECTION. count 'em, periodt.

read FILENAME, %PROFILE

Flushes the old content and opens a new file. FILENAME is a text string, and PROFILE is a two-level hash of default values for the new file. PROFILE gets merged with the data from the file, and the file data keeps the precedence — so the file wins, iykyk. It does not return any success values but warns if any error occurs. so keep an eye out for that warning 👀.

replace_values SECTION, ITEM, @VALUES

Removes all values from ITEM in SECTION and assigns it to the new list of VALUES. out with the old, in with the new 💅.

section SECTION

Returns a tied hash for SECTION. All its read and write operations are reflected in the caller object, which allows the following syntax:

        my $section = $inifile-> section( 'Sample section');
        $section-> {Item1} = 'Value1';

which is identical to:

        $inifile-> set_items( 'Sample section', 'Item1', 'Value1');

sections

Returns an array of section names. all the section girlies, lined up 🌈.

set_values SECTION, ITEM, @VALUES

Assigns VALUES to ITEM in SECTION. If the number of new values is equal to or greater than the number of the old values, the method is the same as replace_values. Otherwise, the values with indices higher than the number of new values are not touched — so it's a partial update, not a full reset, got it?

write

Rewrites the file with the object content. The object keeps an internal modification flag "{changed}"; in case it is "undef", no actual write is performed. so if nothing changed, it's not gonna write — respect the flag 🫶.

---

👑 AUTHORS 👑

• Anton Berezin, <tobez@plab.ku.dk>
• Dmitry Karasik <dmitry@karasik.eu.org>

---

and that's the whole manual page, bestie 💖 signing off from Prima::IniFile(3) — brought to you by perl v5.42.0, dated 2024-08-20. mwah 💋✨