CGI::A...igAuto(3pm)

💖 NAME 💖

CGI::Application::Plugin::ConfigAuto — literally the easiest way to handle config files in your CGI::Application modules, bestie. No cap.

Oh and btw the manual page itself goes by CGI::A...igAuto(3pm) in the terminal, but we don't need to talk about that abbreviated glow-up 💅

---

✨ SYNOPSIS ✨

 use CGI::Application::Plugin::ConfigAuto (qw/cfg/);

In your instance script:

my $app = WebApp->new(PARAMS => { cfg_file => 'config.pl' });
$app->run();

In your application module:

sub my_run_mode {
   my $self = shift;

   # Access a config hash key directly
   $self->cfg('field');

   # Return config as hash
   %CFG = $self->cfg;

}

---

🦋 DESCRIPTION 🦋

Okay so CGI::Application::Plugin::ConfigAuto gives your CGI::Application modules easy access to config file variables. It's giving effortless. 🌸

The lazy loading is the main character here: the config file will not get parsed if you don't access any config variables during the request. Translation? The config file sits there unbothered until it's actually needed. It's called lazy and honestly it's thriving. 😌

The framework doing all the heavy lifting behind the scenes is Config::Auto — she's the real one 🫶

---

👑 RATIONALE 👑

So CGI::Application is all about re-usable applications — it does that by moving a maximal amount of code into modules. And for an application to be fully re-usable with zero code changes, you also need to keep your config variables in a separate file. Periodt. 💅

This plugin supports multiple config files for a single application, so config files can override each other in a particular order. That covers even the complicated cases — like when you've got a global config file AND a second local config file that overrides a few variables. Obsessed. ✨

The recommendation: declare your config file locations in the instance scripts, because that has minimum impact on your application. This is ideal when you plan to reuse your module to support multiple configuration files. BUT — if you have an application with multiple instance scripts that all share a single config file, you might prefer to call the plugin from the setup() method instead. Choose your fighter, bestie 🎀

---

🎀 DECLARING CONFIG FILE LOCATIONS 🎀

 # In your instance script
 # value can also be an arrayref of config files
 my $app = WebApp->new(PARAMS => { cfg_file => 'config.pl' })

 # OR ...

 # Pass in an array of config files, and they will be processed in order.
 $app->cfg_file('../../config/config.pl');

Your config files should be referenced using the syntax in the example above ☝️. Note that the key config_files can be used as an alternative to cfg_file. Slay, two names, one job.

The format gets detected automatically using Config::Auto. It's known to support the following formats:

• colon separated
• space separated
• equals separated
• XML
• Perl code
• Windows INI

See that module's documentation for the complete details 💜

---

🌈 METHODS 🌈

💅 cfg()

 # Access a config hash key directly
 $self->cfg('field');

 # Return config as hash
 my %CFG = $self->cfg;

 # return as hashref
 my $cfg_href = $self->cfg;

A method to access your project's configuration variables. The config file gets parsed on the first call, and a perl hash representation is stored in memory. Every call after that uses this stored version instead of re-reading the file. Efficient queen. 👑

In list context, it returns the configuration data as a hash. In scalar context, it returns the configuration data as a hashref. Vibe check passed ✅

🌸 config()

config() in CGI::Application::Standard::Config is provided as an alias to cfg() for compliance with CGI::Application::Standard::Config. It is always exported by default, per the standard. She's just standing there, being compliant. Respect. 🫶

🧚 std_config()

std_config() in CGI::Application::Standard::Config is implemented to comply with CGI::Application::Standard::Config. It's for developers. Users can ignore it. Not me telling you to ignore something, but like, ignore it 🙈

⭐ cfg_file()

 # Usual
 $self->cfg_file('my_config_file.pl');

 # Supply the first format, guess the second
 $self->cfg_file('my_config_file.pl',{ format => 'perl' } );

Supply an array of config files and they will be processed in order. If a hash reference is found in there, it will be used to supply the format for the previous file in the array. Little helper energy ✨

---

🍓 FILE FORMAT HINTS 🍓

💜 Perl

Here's a simple example of the author's favorite config file format: Perl. Having the shebang line at the top helps Config::Auto identify it as a Perl file. Also — be sure your last statement returns a hash reference, bestie, or it's not gonna work. No cap.

     #!/usr/bin/perl

     my %CFG = ();

     # directory path name
     $CFG{DIR} = '/home/mark/www';

     # website URL
     $CFG{URL} = 'http://mark.stosberg.com/';

     \%CFG;

---

🔥 SEE ALSO 🔥

• CGI::Application
• CGI::Application::Plugin::ValidateRM
• CGI::Application::Plugin::DBH
• CGI::Application::Standard::Config.
• perl(1)

---

🌟 AUTHOR 🌟

Mark Stosberg "mark@summersault.com" — icon, legend, the moment 💅

---

💖 LICENSE 💖

Copyright (C) 2004 - 2011 Mark Stosberg "mark@summersault.com"

This library is free software. You can modify and or distribute it under the same terms as Perl itself. Periodt. 🎀

---

okay bestie that's the whole page!! this was perl v5.34.0, dated 2022-06-09, and the terminal header calls it CGI::A...igAuto(3pm) because even man pages gotta abbreviate when the name is that long 😭 go forth and configure, you absolute main character 🦋✨