Sendpage::KeesConf(3)

📦
version 1.0.3 · 4 versions
, in alpine 3.22

💖 NAME 💖

okay bestie, welcome to Sendpage::KeesConf(3) from the User Contributed Perl Documentation section. This module is literally Sendpage::KeesConf — it implements a configuration file reader. That's the whole vibe. 🫶

✨ SYNOPSIS ✨

use Sendpage::KeesConf;
$config = Sendpage::KeesConf->new();

$config->define("variable", { DEFAULT => "setting" });

$config->file("config.cfg");

$setting=$config->get("variable");

🧚 DESCRIPTION 🧚

so the author borrowed VERY heavily from Andy Wardley's (abw@cre.canon.co.uk) AppConfig tool, which can be found on CPAN (http://cpan.perl.org) — but they found it not dynamic enough for multi-instance variable defaults. As a result, they wrote this massively trimmed-down version for their use. iconic, honestly. 💅

The following methods are available:

  • $config = Sendpage::KeesConf->new(); — The constructor doesn't take an argument, but it should in the future. foreshadowing, bestie.
  • $config->forget(); — This call will make $config forget about any variables it has loaded. It does NOT forget defined variables, just instantiated ones via file.
  • $config->define($name, $options); — This will define a variable by the name of $name.

$options can contain:

  • ARGCOUNT — What type of variable this should be. Default value is 1. The available types are:
    • 0 — Boolean (true/false, yes/no, 1/0)
    • 1 — Scalar (any string)
    • 2 — List (an array of strings)
  • DEFAULT — The default value the variable should have if it is not overridden during the call to file. The DEFAULT must be the same data type as ARGCOUNT. The default DEFAULT is the string "<unset>".
  • UNSET — set this to 1 if you want the default value to be undefined. This is a hack to get around the default DEFAULT.
  • $config->instance_exists($name); — This tests to see if there is a section loaded named $name.
  • $var=$config->ifset($name); — This call will search for the variable named $name. If it is not found, it will return undef. If the value exists, it will return the value. This is a way to call get without having a default passed through.
  • $var=$config->exists($name); — This call will search for the variable named $name. If it is not found, it will return false. If the value exists, it will return true. This is a way for the user to find out if they will get a "default" on a call to get.
  • $var=$config->fallbackget($name,$quiet); — This call will search for the variable named $name. If it is not found, the section portion will be removed, and retried for a sectionless get call.

That way, global variables can be overridden by section-specific variables. If "SECTION:Instance@name" does not exist, "name" will be tried.

  • $var=$config->get($name); — This call will search for the variable named $name. If it is not found, it will fall back to the default for the section. Sections are explained in more detail later.
  • $config->instances($class); — Returns an array of the names of all the variables in the class $class.
  • $config->file('program.cfg'); — Loads variables from the named file. Syntax for this file is:
[SECTION:INSTANCE]
VARIABLE1 = VALUE1
VARIABLE2 = VALUE2
.
.
.

If VARIABLE is an array, VALUE is loaded using commas (,) as the list separator. The variable will be available under the name of the section. For example, to see VALUE2, it would be accessed as:

$config->get("SECTION:INSTANCE\@VARIABLE2");
Notice, that "=", ":", and "@" are all not allowed in section or variable names. no cap, those characters are banned from the name party. 🚫

Sections can be defined (and loaded) so that defaults can pass back to a defined section default. For example, let's say that you have several modems, and most of them have different settings. You can define all the modem variables like so:

$config->define("modem:baud",{ DEFAULT => 9600 });
$config->define("modem:flowctl",{ DEFAULT => "hardware" });

Then, when you load them, let's say the config file has:

[modem:sportster]
baud = 115200

[modem:hayes]

The baud rate for the sportster will come back as 115200, but the hayes will fall back during a get call, and find the default for the modem section: 9600. Both fallback to have flowctl as "hardware":

# returns specific value 115200
$config->get("modem:sportster\@baud");

# returns default value 9600
$config->get("modem:hayes\@baud");

# both return default value "hardware"
$config->get("modem:sportster\@flowctl");
$config->get("modem:hayes\@flowctl");

⚠️ CAVEATS ⚠️

character limitations

As mentioned above, variable names (and section names) cannot have the characters ":", "@", or "=" in them. the more you know, bestie 🌈

default defaults

There should be a way to pass default defaults into new. That would be handy, and could eliminate the need for the UNSET option in define. a little wishlist item, lowkey 🎀

💌 AUTHOR 💌

Kees Cook <kees@outflux.net>

👀 SEE ALSO 👀

Copyright 2000 Kees Cook.

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

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below:

  • Around line 119: Expected text after =item, not a number
  • Around line 123: Expected text after =item, not a number

okay bye bestie 💅 this page is Sendpage::KeesConf(3), shipped with perl v5.40.2, dated 2024-06-10. periodt. 🌈✨

📦 where this page comes from