Config::IniHash(3pm)

💖 Config::IniHash 💖

okay bestie, welcome to the Config::IniHash page — it's the Perl manual for a module that reads and writes INI files, and honestly? it's giving quiet overachiever. this is the 3pm page, so it's the module docs, and we're gonna go through literally everything. no skimming, no skipping, we eat the whole plate. 🍓

---

✨ VERSION ✨

Version 3.00.05 — that's the one we're talking about, periodt.

---

🌈 SYNOPSIS 🌈

look at this, it's so short and cute:

  use Config::IniHash;
  $Config = ReadINI 'c:\some\file.ini';

that's it. that's the whole vibe. one use, one call, you have config. 💅

---

👑 DESCRIPTION 👑

This module reads and writes INI files. that's the whole main character arc, bestie.

🎀 Functions 🎀

💜 ReadINI

        $hashreference = ReadINI ($filename, %options)
        $hashreference = ReadINI (\$data, %options)
        $hashreference = ReadINI (\@data, %options)
        $hashreference = ReadINI ($filehandle, %options)

so you can hand it a filename, a scalar ref holding the data, an array ref holding the data, or a filehandle. four whole ways to feed it, we love options (literally, there are options, see below).

The returned hash contains a reference to a hash for each section of the INI. so like:

        [section]
        name=value
  leads to
        $hash->{section}->{name}  = value;

yes bestie, section becomes a key, name becomes a key inside it, value is the value. the structure is structurally structuring. 💖

The available options are:

• heredoc — controls whether the module supports the heredoc syntax, which looks like this:

        name=<<END
        the
        many lines
        long value
        END
        othername=value

the possible values, and what you get:

• 0 : heredocs are ignored, and $data->{section}{name} will be '<<END'
• 1 : heredocs are supported, and $data->{section}{name} will be "the\nmany lines\nlong value"

⚠️ heads up — the Perl-lie extensions of name=<<"END" and <<'END' are not supported here!

• 'Perl' : heredocs are supported, $data->{section}{name} will be "the\nmany lines\nlong value", and the Perl-lie extensions of name=<<"END" and <<'END' are supported.

🫶 careful with this one: the <<'END' never interpolates %variables%, the "END" always interpolates variables, and — unlike in other values — the %variables% that are not defined do not stay in the string! 😭

Default: 0 = OFF

• systemvars — controls whether the (system) variables enclosed in %% are interpolated, and optionally contains the values in a hash ref. like:

        name=%USERNAME%
  leads to
        $data->{section}->{name} = "Jenda"

the values you can set:

• systemvars = 1 — yes, take values from %ENV
• systemvars = \%hash — yes, take values from %hash
• systemvars = 0 — no

• case — controls whether the created hash is case insensitive. the possible values are:
  • sensitive — the hash will be case sensitive
  • tolower — the hash will be case sensitive, all keys are made lowercase
  • toupper — the hash will be case sensitive, all keys are made uppercase
  • preserve — the hash will be case insensitive, the case is preserved (tied)
  • lower — the hash will be case insensitive, all keys are made lowercase (tied)
  • upper — the hash will be case insensitive, all keys are made uppercase (tied)
• withdefaults — controls whether the created section hashes support defaults. See Hash::WithDefaults. 🦋
• class — allows you to specify the class into which to tie the created hashes. 🚨 this option overwrites the "case" and "withdefaults" options! like, gone, replaced, no cap.

You may for example use

      class => 'Tie::IxHash',

to store the sections in hashes that remember the insertion order. iconic behaviour honestly.

• sectionorder — if set to a true value then the created hash will contain

        $config->{'__SECTIONS__'} = [ 'the', 'names', 'of', 'the', 'sections', 'in', 'the',
                'order', 'they', 'were', 'specified', 'in', 'the', 'INI file'];

and if set to an array ref, then the list will be stored in that array, and no $config->{'__SECTIONS__'} is created. The case of the section names stored in this array is controled by the "case" option even in case you specify the "class". 👑

• allowmultiple — if set to a true scalar value then multiple items with the same names in a section do not overwrite each other, but result in an array of the values. no more getting erased, we persist now.

if set to a hash of hashes (or hash of arrays or hash of comma separated item names) it specifies what items in what sections will end up as hashes containing the list of values. All the specified items will be arrays, even if there is just a single value. To affect the items in all sections use section name '*'.

By default false.

• forValue — allows you to install a callback that will be called for each value as soon as it is read but before it is stored in the hash. The function is called like this:

      $value = $forValue->($name, $value, $sectionname, $INIhashref);

If the callback returns an undef, the value will not be stored. 💀 (that's your delete button, bestie.)

• comment — regular expression used to identify comments or a string containing the list of characters starting a comment. Each line is tested against the regexp is ignored if matches. If you specify a string a regexp like this will be created:

        qr/^\s*[the_list]/

The default is

        qr/^\s*[#;]/

• layer — the IO layer(s) to use when opening the file. See perldoc "perlopen".

🌸 If the file is in UTF8 and starts with a BOM it will be automatically opened in UTF8 mode and the BOM will be stripped. If it doesn't start with the BOM you have to specify the utf8 layer!

You may also set the defaults for the options by modifying the $Config::IniHash::optionname variables. These default settings will be used if you do not specify the option in the ReadINI() or ReadSection() call.

🌟 AddDefaults

  AddDefaults( $config, 'normal section name', 'default section name');
  AddDefaults( $config, 'normal section name', \%defaults);

This subroutine adds a some default values into a section. The values are NOT copied into the section, but rather the section knows to look up the missing options in the default section or hash. it's not a copy, it's a reference, a little "go ask them" energy. 🫶

Eg.

  if (exists $config->{':default'}) {
        foreach my $section (keys %$config) {
          next if $section =~ /^:/;
          AddDefaults( $config, $section, ':default');
        }
  }

🌈 ReadSection

  $hashreference = ReadSection ($string)

This function parses a string as if it was a section of an INI file and creates a hash with the values. It accepts the same options as ReadINI. so yes, all of the above applies, every single one. 💅

🎀 WriteINI

  WriteINI ($filename, $hashreference)

Writes the hash of hashes to a file. short, sweet, slays.

⭐ PrintINI

The same as WriteINI().

---

💜 AUTHOR 💜

Jan Krynicky <Jenda@Krynicky.cz> http://Jenda.Krynicky.cz — the icon who wrote this. bow down. 👑

---

🦋 COPYRIGHT 🦋

Copyright (c) 2002-2005 Jan Krynicky <Jenda@Krynicky.cz>. All rights reserved.

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

---

okay so that's the whole entire page, bestie, nothing skipped, every flag accounted for 💖✨ and before you go — the footer says this was generated by perl v5.36.0 on 2022-11-19, so that's the version and date right there, tucked into the sign-off like a little bow 🎀 mwah, go read your INI files, you've got this 💅🌸