Config:...::Reader(3)

💖 NAME 💖

okay so you're on the Config:...::Reader(3) page, from the User Contributed Perl Documentation collection, and the module here is Config::INI::Reader — a subclassable .ini-file parser. Yes bestie, it parses .ini files and it's literally built so you can subclass it. 💅

🦋 VERSION 🦋

version 0.029 — that's the version, and I'm obsessed with how tiny and specific it is. periodt. ✨

🎀 SYNOPSIS 🎀

If family.ini contains:

  admin = rjbs

  [rjbs]
  awesome = yes
  height = 5' 10"

  [mj]
  awesome = totally
  height = 23"

Then when your program contains:

  my $hash = Config::INI::Reader->read_file('family.ini');

$hash will contain:

  {
    '_'  => { admin => 'rjbs' },
    rjbs => {
      awesome => 'yes',
      height  => q{5' 10"},
    },
    mj   => {
      awesome => 'totally',
      height  => '23"',
    },
  }

🌸 DESCRIPTION 🌸

Vibe check: Config::INI::Reader is yet another config module implementing yet another slightly different take on the undeniably easy to read .ini file format. Its default behavior is lowkey quite similar to that of Config::Tiny, on which it is based.

The chief difference? The big main-character glow-up is that Config::INI::Reader is designed to be subclassed, so side-effects and self-reconfiguration can occur during the course of reading its input. 👑

💀 PERL VERSION 💀

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. 🫶 Ngl, that's a generous window.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. So don't count on forever, bestie. 💀

🔥 METHODS FOR READING CONFIG 🔥

These methods are all that most users will need: they read configuration from a source of input, then they return the data extracted from that input. There are three reader methods — read_string, read_file, and read_handle. The first two are implemented in terms of the third. That third one iterates over lines in a file, calling methods on the reader when events occur. Those events are detailed below in the METHODS FOR SUBCLASSING section.

All of the reader methods return an unblessed reference to a hash. All throw an exception when they encounter an error. No cap. 💅

read_file

my $hash_ref = Config::INI::Reader->read_file($filename);

Given a filename, this method returns a hashref of the contents of that file. Slay. 📁

read_string

my $hash_ref = Config::INI::Reader->read_string($string);

Given a string, this method returns a hashref of the contents of that string. String queen. 🧵

read_handle

my $hash_ref = Config::INI::Reader->read_handle($io_handle);

Given an IO::Handle, this method returns a hashref of the contents of that handle. Handle it. 🫶

🌈 METHODS FOR SUBCLASSING 🌈

These are the methods you need to understand and possibly change when subclassing Config::INI::Reader to handle a different format of input. This is highkey where the customization magic lives. ✨

current_section

my $section_name = $reader->current_section;

This method returns the name of the current section. If no section has yet been set, it returns the result of calling the starting_section method. So it always has something for you. 💖

parse_section_header

my $name = $reader->parse_section_header($line, $handle);

Given a line of input, this method decides whether the line is a section-change declaration. If it is, it returns the name of the section to which to change. If the line is not a section-change, the method returns false. Big decision energy. 🎀

change_section

$reader->change_section($section_name);

This method is called whenever a section change occurs in the file.

The default implementation is to change the current section into which data is being read and to initialize that section to an empty hashref. Clean slate, bestie. 🧼

parse_value_assignment

my ($name, $value) = $reader->parse_value_assignment($line, $handle);

Given a line of input, this method decides whether the line is a property value assignment. If it is, it returns the name of the property and the value being assigned to it. If the line is not a property assignment, the method returns false. Assignment understood. 📝

set_value

$reader->set_value($name, $value);

This method is called whenever an assignment occurs in the file. The default behavior is to change the value of the named property to the given value. Set it and forget it. 💅

starting_section

my $section = Config::INI::Reader->starting_section;

This method returns the name of the starting section. The default is:

"_"

That's underscore, not nothing. 🫶

can_ignore

do_nothing if $reader->can_ignore($line, $handle)

This method returns true if the given line of input is safe to ignore. The default implementation ignores lines that contain only whitespace or comments.

This is run after preprocess_line. So yes, order matters. 💯

preprocess_line

$reader->preprocess_line(\$line);

This method is called to preprocess each line after it's read but before it's parsed. The default implementation just strips inline comments. Alterations to the line are made in place. In-place edits, very main character. ✨

handle_unparsed_line

$reader->handle_unparsed_line( $line, $handle );

This method is called when the reader encounters a line that doesn't look like anything it recognizes. By default, it throws an exception. So if your input is weird, bestie, it's gonna yell. 😭

finalize

$reader->finalize;

This method is called when the reader has finished reading in every line of the file. That's a wrap. 🎬

new

my $reader = Config::INI::Reader->new;

This method returns a new reader. This generally does not need to be called by anything but the various read_* methods, which create a reader object only ephemerally. So it's there, but the read methods are the usual stars. 👑

🦋 ORIGIN 🦋

Originaly derived from Config::Tiny, by Adam Kennedy.

🌸 AUTHOR 🌸

Ricardo Signes <cpan@semiotic.systems> 💌

👑 COPYRIGHT AND LICENSE 👑

This software is copyright (c) 2007 by Ricardo Signes.

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

---

And that's the whole page, bestie. Cute little footer sign-off: source/version is perl v5.42.0, dated 2023-01-15, and the page is Config:...::Reader(3). Bye bye, go parse some .ini files — iykyk 💅✨