Config::INI::Reader(3) User Contributed Perl Documentation Config::INI::Reader(3)

# [SYNOPSIS](#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](#DESCRIPTION)

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 quite similar to that of Config::Tiny, on which it is based.

The chief difference is that Config::INI::Reader is designed to be subclassed to allow for side-effects and self-reconfiguration to occur during the course of reading its input.

# [METHODS FOR READING CONFIG](#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. It 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.

## [read\_file](#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.

## [read\_string](#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.

## [read\_handle](#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.

# [METHODS FOR SUBCLASSING](#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.

## [current\_section](#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.

## [parse\_section\_header](#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.

## [change\_section](#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.

## [parse\_value\_assignment](#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.

## [set\_value](#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.

## [starting\_section](#starting_section)

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

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

## [can\_ignore](#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.

## [preprocess\_line](#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.

## [handle\_unparsed\_line](#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.

## [finalize](#finalize)

```
  $reader->finalize;
```

This method is called when the reader has finished reading in every line of the file.

## [new](#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.

# [ORIGIN](#ORIGIN)

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

2026-08-26 perl v5.44.0

---

Document: Config::INI::Reader(3pm) from perl-config-ini 0.029-r3 (Chainguard OS)
Source: https://github.com/rjbs/Config-INI