Config...eStyle(3pm)

🌸 Config...eStyle(3pm) — like, the manual name, bestie 💅

okay so this is the page for ConfigReader::DirectiveStyle, and no cap, it's the moment you stop hand-rolling config parsers. she reads configuration files. that's the whole job and she does it gorgeously.

---

✨ NAME ✨

ConfigReader::DirectiveStyle — read configuration file 🫶

Reads a configuration file of directives and values. iconic behaviour.

---

🎀 CONFIGURATION FILE SYNOPSIS 🎀

this is what the config files look like, fr fr:

    # comments start with a #, and blank lines are ignored

    Input     /etc/data_source      # the value follows the directive name
    HomePage  http://www.w3.org/

    # values can be quoted
    Comment   "here is a value with trailing spaces   "

---

🦋 CODE SYNOPSIS 🦋

and this is you, in Perl, being a main character:

    my $c = new ConfigReader::DirectiveStyle;

    directive $c 'Input', undef, '~/input';  # specify default value,
                                             #   but no parsing needed
    required  $c 'HomePage', 'new URI::URL'; # create URI::URL object
    ignore    $c 'Comment';                  # Ignore this directive.

    $c->load('my.config');
    open(IN, $c->value("Input"));

    $c->define_accessors();                  # creates Input() and HomePage()
    retrieve(HomePage());

---

💖 DESCRIPTION 💖

So this class reads a super common style of configuration file — the kind where a directive name is followed by a value. literally the whole vibe.

For every directive you get to say: does it have a default value, or is it required, and is there a function or method to use to parse the value? Errors and warnings get caught while parsing, and the location where the offending value came from gets reported to you — whether it came from the configuration file, or from your Perl source where you set the default values. 💅

DirectiveStyle is a subclass of ConfigReader::Values. The methods you use to define the directives in the configuration file are documented over there, in that page. go read it, bestie.

Comments are introduced by the # character, and continue until the end of line. And like in Perl, the backslash character \ may be used in the directive values for the various standard sequences:

     \t          tab
     \n          newline
     \r          return
     \f          form feed
     \v          vertical tab, whatever that is
     \b          backspace
     \a          alarm (bell)
     \e          escape
     \033        octal char
     \x1b        hex char

not the manpage calling \v "vertical tab, whatever that is" 😭 she's so real for that

The value may also be quoted, which lets you include leading or trailing spaces. ✨ The quotes are stripped off before the value is returned. periodt.

DirectiveStyle itself only reads the configuration file. Most of the hard work — defining the directives and parsing the values — is done in its superclass, ConfigReader::Values. You should be able to easily modify or subclass DirectiveStyle to read a different style of configuration file. go off, honestly. 🧚

---

👑 PUBLIC METHODS 👑

🌟 new( [$spec] )

This static method creates and returns a new DirectiveStyle object. For information about the optional $spec argument, see DirectiveStyle::new(). yes, she's pointing back at herself. self-aware queen.

🌈 load($file, [$untaint])

Before calling load(), you'll want to define the directives using the methods described in ConfigReader::Values. don't skip that step bestie, she needs the tea first.

Reads a configuration from $file. The default values for any directives not present in the file are assigned. 💜

Normally configuration values are tainted like any data read from a file. If the configuration file comes from a trusted source, you can untaint all the values by setting the optional $untaint argument to a true value (such as 'UNTAINT').

⚠️ key word: trusted source. don't be out here untainting random files from the internet, that's how you become an incident report. 🙈

---

🍓 SUBCLASSABLE METHODS 🍓

You can stop reading here if you just want to use DirectiveStyle. ✋ The following methods could be overridden in a subclass to provide additional or alternate functionality. this is for the girlies who want to get ambitious.

🌸 parse_line($line, $whence, $untaint)

Parses $line. $whence is a string describing the source of the line. Returns a two-element array of the directive and the value string, or the empty array () if the line is blank or only contains a comment.

⭐ parse_value_string($str, $whence)

Interprets quotes, backslashes, and comments in the value part. (Note that after the value string is returned, it will still get passed to the directive's parsing function of method if one is defined). 💅

---

slay, that's literally the whole page 💖✨

cute little sign-off for you: this was perl v5.36.0, dated 2022-10-13, and that's the Config...eStyle(3pm) manual out of the User Contributed Perl Documentation 🎀 byeee, go write a config file 🦋