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

✨ NAME ✨

CGI::Application::Standard::Config — bestie, this is the module that lays down a standard configuration API for CGI::Application. That's it. That's the whole job. 💅

This page lives in the User Contributed Perl Documentation collection, and it was last updated on Sat Feb 18 23:42:29 EST 2006 — vintage, honestly. 🎀

---

💭 RATIONALE 💭

Okay so here's the tea. This module defines a minimum standard interface that configuration plugins for CGI::Application are supposed to meet.

Why do we care? Because having a standard means other plugin authors can just... rely on basic configuration functionality. No coding exceptions for every single config module. No giving up on integration entirely. It's giving teamwork. 🫶

---

🌸 SYNOPSIS 🌸

🍓 For Average Users

Simply load the config plugin before other modules that might use it:

  use CGI::Application::Plugin::ConfigAuto;
  use CGI::Application::Plugin::Session;

Order matters, bestie. Don't do it backwards. 😭

🧚 For Configuration plugin authors

Configuration plugin authors only need to follow the standards documented below. That's the whole assignment. 📝

🦋 For other plugin authors who wish to rely on the standard

Plugin authors who want to possibly use this standard can do so by simply using this module:

  package CGI::Application::Plugin::Session;
  use CGI::Application::Standard::Config;

If a standards compliant config module hasn't already been loaded, a stub for config() will be added, and that stub will safely return "undef". So nothing explodes. Iconic behaviour, no cap. 💖

💫 Example use by another plugin

Here's code that first tries to get configuration details from a config file, then from options passed to a plugin-specific config method, and finally applies defaults if no configuration options are found:

 my $session_options = $self->config('Session_options')
                                      || $self->session_config()
                                      || $self->session_defaults;

Look at that chain of ||. It's literally the "try three outfits before leaving the house" of Perl. 👑

---

👑 Standard Interface Definition 👑

The following defines a minimum standard for configuration plugins to meet.

Config plugins are free to provide additional functionality. Go off, honestly. 🔥

Configuration plugins are also encouraged to explicitly document that they are using "CGI::Application::Standard::Config".

If there are existing methods that follow the standard but have different names, you can use this example to always export your method:

  sub import {
    my $app = caller;
    no strict 'refs';
    my $full_name = $app . '::config';
    # Change cfg to your config()-compliant method name
    *$full_name = \&cfg;
    CGI::Application::Plugin::YourNameHere->export_to_level(1,@_);
  }

⚠️ Note the no strict 'refs'; in there — that's deliberate, because we're doing symbol table stuff. Don't come for me. 🙈

🌈 $self->std_config

This method should be exported by default to simply declare that you meet the standard, and report which version of the standard you meet. This simple implementation is recommended:

 sub std_config { return 1; }

One line. Ate. 💅

⭐ $self->config

The intended use is to load to read-only configuration details once from a config file at start up time.

This service is provided by plugins (list below). They must support at least this syntax:

 my $value = $self->config('key');

By default, "config()" simply returns undef, making it safe for other plugins to directly check if $self->config('key') returns the value it needs.

config() must be exported by default.

For applications that need little configuration, config() is not necessary — using "PARAMS" in an instance script should suffice.

Also, "param()" is the appropriate method to use to set a configuration value at run time.

Configuration plugins that provide at least this basic API include:

• CGI::Application::Plugin::ConfigAuto.

🎀 Standard config variables

Users are encouraged to use these standard config variable names, to ease compatibility between plugins:

 ROOT_URI - A URI corresponding to the project root (http://foo.com/proj )
 ROOT_DIR - a file system path to the same location ( /home/joe/www/proj )

All-caps are used to denote that config variables are essentially global constants. Periodt.

Why URI and not URL? The wikipedia explains:

The contemporary point of view among the working group that oversees URIs is that the terms URL and URN are context-dependent aspects of URI and rarely need to be distinguished. Furthermore, the term URL is increasingly becoming obsolete, as it is rarely necessary to differentiate between URLs and URIs, in general.

---

💜 Standard Version 💜

This is 1.0 of the CGI::Application config() standard.

---

✍️ AUTHOR ✍️

Written by Mark Stosberg <mark@summersault.com> with input from the CGI::Application community. Community effort, we love to see it. 🫶

---

📜 COPYRIGHT and LICENSE 📜

Copyright (C) 2008, Mark Stosberg. All rights reserved.

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

---

And that's the whole page, bestie! 🌟 This one was rendered by perl v5.30.3 back on 2020-08-23 — shoutout to the toolchain for keeping this 2008 copyright notice looking so fresh. 💖 Go forth and configure responsibly. 🎀