Config...Values(3pm)

💖 ConfigReader::Values — the manual, but make it cute 💖

okay so bestie, this is the perl documentation for ConfigReader::Values (3pm), straight out of the User Contributed Perl Documentation corner of the perl world. it's a whole class that stores a set of configuration values for you. let's get into it 🫶

---

✨ NAME ✨

ConfigReader::Values — stores a set of configuration values. that's the vibe. that's the whole job. 💅

---

🌸 DESCRIPTION 🌸

so this class holds a whole set of configuration values that got read out of a configuration file. it's giving little storage unit for settings ✨. it hands you methods to define directives, to assign and retrieve values, and to create accessor subroutines.

and here's the tea: this class will usually be subclassed so it can implement a reader for some specific style of configuration file. so the docs do the user-facing methods first (those are the ones you actually touch), and the subclass-helper methods come later. periodt.

---

🎀 USER METHODS 🎀

"directive($directive, [$parser, [$default, [$whence]]])"

defines a directive named $directive for the configuration file. optionally you can hand it a parsing function or method for that directive, plus a default value. so many options, so little time 💖

if $directive is just a simple string, it gets used as both the name of the directive inside your program and the name in the configuration file. iconic, no notes.

but if you want different names, you can pass an array ref shaped like this:

['program-name', 'name1', 'name2', 'name3' ...]

and then 'program-name' is what you use inside the program, while 'name1', 'name2', 'name3' are all recognized as the name of that directive in the configuration file. multi-name realness 🌈

lowkey important: a directive will be set to undef if you don't give it a default value and it never shows up in the configuration file. so no default + no file entry = undef, bestie.

any errors or warnings that pop off while parsing the default value are normally reported as originating in the caller's module. wanna change where they get reported from? pass $whence. slay 🎀

"required($directive, [$parser, [$whence]])"

defines a directive that must be specified in the configuration file. no skipping this one, bestie, it's mandatory 💀

"ignore($directive, [$whence])"

defines a directive that will be accepted but ignored in the configuration file. yeah we see it, yeah we don't care, moving on 💅

"directives()"

returns an array of the configuration directive names. cute little list of everything ✨

"value($directive, [$whence])"

returns the value of the configuration directive $directive. the one you actually wanted 🫶

"define_accessors([$package, [@names]])"

creates subroutines in the caller's package to access configuration values. for example, if one of your configuration directives is named "Input_File", you can do:

$config->define_accessors();
...

open(IN, Input_File());

the names of the created subroutines get returned in an array. and if you'd like to export the accessor subroutines, you can say:

push @EXPORT, $config->define_accessors();

and if you wanna pick the package where the subroutines get created, use the optional $package argument. you can also specify which configuration directives to make accessor subroutines for. by default though? subroutines get created for all the directives. all of them. every single one. periodt 👑

---

🔥 IMPLEMENTATION METHODS 🔥

these next ones will probably get called by a subclass that's implementing a reader for a particular style of configuration files. this is the behind-the-scenes main character energy 👑

new( [$spec] )

the static method new() creates and returns a new ConfigReader::Values object. your new baby 🦋

unless that optional $spec argument is present, a brand new ConfigReader::Spec object gets created to store the configuration specification. and the directive(), required(), ignore(), value(), and directive() methods described above are all passed through to the spec object.

by setting $spec, you can use a different class (maybe a subclass, iykyk) to store the specification.

you can also set $spec if you want to use one specification for multiple sets of values. like, files such as /etc/termcap describe a configuration for multiple objects (terminals, in this case), but they use the same directives to describe each object. one spec, many objects, that's the flex 🌈

"values()"

returns the hash ref which actually stores the configuration directive values. the key of the hash ref is the directive name. simple, clean, iconic ✨

"spec()"

returns the internal spec object used to store the configuration specification. peek behind the curtain 🎀

"assign($directive, $value_string, $whence)"

normally called while reading the configuration file — assigns a value to the directive named $directive. the $value_string will be parsed by the directive's parsing function or method, if any. and $whence should describe the line in the configuration file that contained the value string. receipts matter, bestie 🧾

"assign_defaults($whence)"

after the configuration file is read, the assign_defaults() method gets called to assign the default values for directives that were not specified in the configuration file. and $whence should describe the name of the configuration file. the cleanup era 💖

---

⚠️ quick vibe check: directive() sets a directive to undef when there's no default and no value in the config file, and required() directives must appear in the config file or things go sideways. do not test that. just don't. 😭

---

and that's the whole page, bestie!! shoutout to perl version v5.36.0, dated 2022-10-13, for this lil manual page that lives in the User Contributed Perl Documentation collection 🫶 stay configured, stay iconic 💅✨🌸