Config::Auto(3pm)

💖 NAME 💖

okay bestie, welcome to Config::Auto (3pm) — the manual page for the magical config file parser ✨ It's literally giving "I detect your config so you don't have to" and we're obsessed. No cap.

✨ SYNOPSIS ✨

Here's the vibe in code, bestie:

use Config::Auto;

### Not very magical at all.
$config = Config::Auto::parse("myprogram.conf", format => "colon");

### Considerably more magical.
$config = Config::Auto::parse("myprogram.conf");

### Highly magical.
$config = Config::Auto::parse();

### Using the OO interface
$ca     = Config::Auto->new( source => $text );
$ca     = Config::Auto->new( source => $fh );
$ca     = Config::Auto->new( source => $filename );

$href   = $ca->score;           # compute the score for various formats

$config = $ca->parse;           # parse the config

$format = $ca->format;          # detected (or provided) config format
$str    = $ca->as_string;       # config file stringified
$fh     = $ca->fh;              # config file handle
$file   = $ca->file;            # config filename
$aref   = $ca->data;            # data from your config, split by newlines

🌸 DESCRIPTION 🌸

So this module was born after someone had to write Yet Another Config File Parser for some variety of colon-separated config, and they were like "never again." Periodt. Config::Auto aims to be the most "DWIM" config parser available, by detecting configuration styles, include paths, and even config filenames automagically. 💅

If you want the implementation tea, check the "HOW IT WORKS" section below. It's giving behind-the-scenes main character energy.

🦋 ACCESSORS 🦋

🎀 @formats = Config::Auto->formats

Returns a list of supported formats for your config files. These formats are also the keys as used by the score() method. Config::Auto recognizes the following formats:

• perl => perl code
• colon => colon separated (e.g., key:value)
• space => space separated (e.g., key value)
• equal => equal separated (e.g., key=value)
• bind => bind style (not available)
• irssi => irssi style (not available)
• xml => xml (via XML::Simple)
• ini => .ini format (via Config::IniFiles)
• list => list (e.g., foo bar baz)
• yaml => yaml (via YAML.pm)

💅 METHODS 💅

🌈 $obj = Config::Auto->new( [source => $text|$fh|$filename, path => \@paths, format => FORMAT_NAME] );

$obj = Config::Auto->new( [source => $text|$fh|$filename, path => \@paths,
       format => FORMAT_NAME] );

Returns a Config::Auto object based on your config's source. This can either be:

• a filehandle — any opened filehandle, or IO::Handle/IO::String object.
• a plain text string — any plain string containing one or more newlines.
• a filename — any plain string pointing to a file on disk.
• nothing — a heuristic will be applied to find your config file, based on the name of your script; $0.

Although Config::Auto is at its most magical when called with no parameters, its behavior can be controlled explicitly by using one or two arguments. iykyk ✨

If a filename is passed as the source argument, the same paths are checked, but Config::Auto will look for a file with the passed name instead of the $0-based names.

Supplying the path parameter will add additional directories to the search paths. The current directory is searched first, then the paths specified with the path parameter. path can either be a scalar or a reference to an array of paths to check.

The format parameters forces Config::Auto to interpret the contents of the configuration file in the given format without trying to guess. No guessing, just vibes.

⭐ $rv = $obj->parse | Config::Auto::parse( [$text|$fh|$filename, path => \@paths, format => FORMAT_NAME] );

$rv = $obj->parse | Config::Auto::parse( [$text|$fh|$filename, path =>
       \@paths, format => FORMAT_NAME] );

Parses the source you provided in the new() call and returns a data structure representing your configuration file. It's literally the moment of truth. 💖

You can also call it in a procedural context (Config::Auto::parse()), where the first argument is the source, and the following arguments are named. This function is provided for backwards compatiblity with releases prior to 0.29. Old-school but iconic.

💜 $href = $obj->score;

Takes a look at the contents of your configuration data and produces a 'score' determining which format it most likely contains. It's a whole vibe check for your config. 👑

The keys are equal to formats as returned by the Config::Auto->formats and their values are a score between 1 and 100. The format with the highest score will be used to parse your configuration data, unless you provided the format option explicitly to the new() method.

🍓 $aref = $obj->data;

Returns an array ref of your configuration data, split by newlines. Slay.

🧚 $fh = $obj->fh;

Returns a filehandle, opened for reading, containing your configuration data. This works even if you provided a plain text string or filename to parse. Magic? Maybe. Iconic? Absolutely. ✨

🔥 $filename = $obj->file;

Returns a filename containing your configuration data. This works even if you provided a plaintext string or filehandle to parse. In that case, a temporary file will be written holding your configuration data. Temporary file realness. 💅

👑 $str = $obj->as_string;

Returns a string representation of your configuration data. Stringified and serving looks.

🌟 GLOBAL VARIABLES 🌟

• $DisablePerl — Set this variable to true if you do not wish to eval perl style configuration files. Default is "false".
• $Untaint — Set this variable to true if you automatically want to untaint values obtained from a perl style configuration. See perldoc perlsec for details on tainting. Default is "false".
• $Debug — Set this variable to true to get extra debug information from Config::Auto when finding and/or parsing config files fails. Default is "false".

🔮 HOW IT WORKS 🔮

When you call Config::Auto->new or Config::Auto::parse with no arguments, we first look at $0 to determine the program's name. Let's assume that's snerk. We look for the following files:

snerkconfig
~/snerkconfig
/etc/snerkconfig
/usr/local/etc/snerkconfig

snerk.config
~/snerk.config
/etc/snerk.config
/usr/local/etc/snerk.config

snerkrc
~/snerkrc
/etc/snerkrc
/usr/local/etc/snerkrc

.snerkrc
~/.snerkrc
/etc/.snerkrc
/usr/local/etc/.snerkrc

Additional search paths can be specified with the path option.

We take the first one we find, and examine it to determine what format it's in. The algorithm used is a heuristic "which is a fancy way of saying that it doesn't work." (Mark Dominus.) We know about colon separated, space separated, equals separated, XML, Perl code, Windows INI, BIND9 and irssi style config files. If it chooses the wrong one, you can force it with the format option.

If you don't want it ever to detect and execute config files which are made up of Perl code, set $Config::Auto::DisablePerl = 1.

When using the perl format, your configuration file will be eval'd. This will cause taint errors. To avoid these warnings, set $Config::Auto::Untaint = 1. This setting will not untaint the data in your configuration file and should only be used if you trust the source of the filename.

Then the file is parsed and a data structure is returned. Since we're working magic, we have to do the best we can under the circumstances — "You rush a miracle man, you get rotten miracles." (Miracle Max) So there are no guarantees about the structure that's returned. If you have a fairly regular config file format, you'll get a regular data structure back. If your config file is confusing, so will the return structure be. Isn't life tragic? 😭

🎉 EXAMPLES 🎉

Here's what we make of some common Unix config files:

/etc/resolv.conf:

$VAR1 = {
    'nameserver' => [ '163.1.2.1', '129.67.1.1', '129.67.1.180' ],
    'search' => [ 'oucs.ox.ac.uk', 'ox.ac.uk' ]
};

/etc/passwd:

$VAR1 = {
    'root' => [ 'x', '0', '0', 'root', '/root', '/bin/bash' ],
    ...
};

/etc/gpm.conf:

$VAR1 = {
    'append' => '""',
    'responsiveness' => '',
    'device' => '/dev/psaux',
    'type' => 'ps2',
    'repeat_type' => 'ms3'
};

/etc/nsswitch.conf:

$VAR1 = {
    'netgroup' => 'nis',
    'passwd' => 'compat',
    'hosts' => [ 'files', 'dns' ],
    ...
};

🧠 MEMORY USAGE 🧠

This module is as light as possible on memory, only using modules when they are absolutely needed for configuration file parsing. Lowkey respectful of your RAM. 🫶

🚨 TROUBLESHOOTING 🚨

When using a Perl config file, the configuration is borked — give Config::Auto more hints (e.g., add #!/usr/bin/perl to beginning of file) or indicate the format in the new/parse() command. Not me giving you the cheat codes. 🙈

📝 TODO 📝

BIND9 and irssi file format parsers currently don't exist. It would be good to add support for mutt and vim style set-based RCs. Future slay, bestie.

🐛 BUG REPORTS 🐛

Please report bugs or other issues to <bug-config-auto@rt.cpan.org>. Spill the tea, but politely. 💌

💌 AUTHOR 💌

Versions 0.04 and higher of this module by Jos Boumans <kane@cpan.org>. This module originally by Simon Cozens. Legends only. 👑

⚖️ COPYRIGHT ⚖️

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

---

okay bestie, that's the whole page 💖 it was perl v5.34.0, dated 2022-06-11, and the manual name is Config::Auto(3pm) — bye, slay, and may your configs always parse on the first try ✨🦋