Config::File(3pm)

💖 Config::File 💖

okay bestie, gather round, because today we're learning about Config::File — it lives in the Perl user-contributed docs (section 3pm, for the record) and its whole job is parsing a simple configuration file. That's the name. That's the vibe. Periodt.

---

✨ NAME ✨

Config::File — parse a simple configuration file. that's it, that's the whole personality 🎀

---

🌸 SYNOPSIS 🌸

use Config::File;

my $config_hash = Config::File::read_config_file($configuration_file);

---

🦋 DESCRIPTION 🦋

read_config_file parses a simple configuration file and drops all its values into an anonymous hash reference. no cap. here's what the config file syntax looks like:

# This is a comment
VALUE_ONE = foo
VALUE_TWO = $VALUE_ONE/bar
VALUE_THREE = The value contains a \# (hash). # This is a comment.

see how VALUE_THREE is out here escaping a \# because she genuinely wanted a hash character in her value and not to end up as a comment? main character energy honestly 💅

now, options can get clustered when you're building groups:

CLUSTER_ONE[data] = data cluster one
CLUSTER_ONE[value] = value cluster one
CLUSTER_TWO[data] = data cluster two
CLUSTER_TWO[value] = value cluster two

and then you fetch those values with this syntax:

$hash_config->{CLUSTER_ONE}{data};

the way that just nests all cute like that?? obsessed. and there's literally no limit — a cluster can have as many sub-options as you need:

BIG_CLUSTER[part1][part2][part3] = data

is fetched by:

$hash_config->{BIG_CLUSTER}{part1}{part2}{part3};

okay but now the rules, because there are a couple of restrictions on key names and we do NOT get to freestyle them. first of all, every character should be alphabetic, numeric, an underscore, or a hyphen — square brackets are allowed specifically for the clustering. so basically your keys need to conform to:

/^[A-Za-z0-9_-]+$/

which also means no spaces allowed in the key part of the line. none. zero. not even one itty bitty space:

CLUSTER_ONE[data] = data cluster one      # Right
CLUSTER_ONE[ data ] = data cluster one    # Wrong

⚠️ yes bestie we're serious — that second one is Wrong. the spaces around data inside the brackets? not it. 🙈

---

💜 Function read_config_file 💜

Syntax

Config::File::read_config_file($file);

Arguments

$file is the configuration file. that's the one and only argument, she keeps it simple.

Return value

this function returns a hash reference. every key of that hash is a value defined in the configuration file. 💖

Description

read_config_file parses a configuration file and sets up some values in a hash reference. that's the whole thing, she's efficient, she ate.

---

🔥 NOTES 🔥

Not exported by default, bestie

in versions up to 1.0, the function read_config_file was exported into the calling program's namespace. but starting in version 1.1, nothing is exported by default. so you've got two options, and both are valid:

Fully qualifying read_config_file:

use Config::File;

my $config_hash = Config::File::read_config_file($configuration_file);

Explicitly importing read_config_file:

use Config::File qw(read_config_file);

my $config_hash = read_config_file($configuration_file);

pick your fighter, both slay ✨

Migrated away from ConfigFile into Config::File

as of version 1.4, our author wanted to get this module onto the CPAN, so they decided to move away from the highly unstandard name of ConfigFile and rename the module to Config::File. a small redirecting module is put in place so that current code using this module does not break — but the ConfigFile namespace usage is deprecated and will thus issue a warning. please update your code! 🫶

💀 do not be out here still using the old namespace and then acting surprised about the warning. we talked about this.

---

👑 AUTHOR 👑

development was started by Sebastien J. Gross <seb@sjgross.org>. maintained by Gunnar Wolf <gwolf@gwolf.org> until 2018, when Stockholm University (Johan Wassberg and Mikael Nordin) took over maintainance.

all rights reserved. this program is free software; you can redistribute it and/or modify it under the terms of the GPL.

---

⭐ VERSION ⭐

Version 1.54 — Copyright (c) 2002 Sebastien J. Gross. All rights reserved. Copyright (c) 2003-2018 Gunnar Wolf. All rights reserved. Copyright (c) 2018- Stockholm University. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GPL v2 (or later, at your choice).

---

and that's the tea, bestie 🍓 this page came to you courtesy of perl v5.36.0 and is dated 2022-10-16 — so go forth, parse your configs, escape your hashes, and never put a space inside a cluster bracket. mwah 💅💖