ConfigFile(3pm)

💖 ConfigFile — Unix::ConfigFile 💖

ok so this is ConfigFile(3pm) from the User Contributed Perl Documentation bestie, and it's literally the blueprint page, iykyk ✨

---

✨ NAME ✨

Unix::ConfigFile — a Perl interface to various Unix configuration files 🎀

---

🌸 SYNOPSIS 🌸

use Unix::ConfigFile;

---

🦋 DESCRIPTION 🦋

ok so the tea: Unix::ConfigFile is the base class that all the other Unix::*File modules inherit from. It handles the boring-but-essential stuff — file opening, locking, and closing — so the submodules don't have to. 🫶

Now, do you need to use this module directly? Lowkey no, unless you're out here developing a derived module for a configuration file that doesn't have one yet. But listen — some of the methods documented here are genuinely meant for public use by people using Unix::ConfigFile submodules, so even if you're not writing your own module, this doc is still gonna be useful to you. no cap 💅

The ConfigFile object also comes with a sequencing API for modules that wanna preserve the order of the config file they read and write. The sequencer keeps a list of arbitrary data that a submodule can append to, insert into, and delete from. Using the sequencer is completely optional — no pressure, bestie.

Here's the thing though: any module that subclasses from Unix::ConfigFile must, at minimum, provide two methods, called read and write. 📝

• read and write both receive a filehandle as a parameter (on top of the regular object parameter, obvi).
• read gets called after the file is opened. It's expected to read in the config file and initialize the subclass-specific data structures tied to the object.
• write gets called when an object is committed, and it's expected to write out the new configuration to the filehandle it was handed.

---

👑 USER METHODS 👑

commit( [%OPTIONS] )

This one writes all the changes you made to the object back to disk. ⚠️ And fr fr, if you don't call commit, none of your changes will show up in the file you're modifying. It's giving "did I save?" energy.

commit may not be called on files opened in read-only mode. periodt.

There are some optional parameters you can pass, and they go in as key => value pairs:

• the backup option — lets you specify a file extension that'll be used to save a backup of the original file 💾
• the writeopts option — passes module-specific options through to the write method. It'll accept any scalar for its value; typically this is gonna be a list or hash reference.

commit returns 1 on success and 0 on failure. 🎀

encpass( PASSWORD )

This method encrypts the plaintext password you hand it, using a random salt, and returns the encrypted password. 🔐

ngl there's a fun little quirk here: this method doesn't actually make any use of the object it's invoked on, so you could call it as a class method. iconic.

new( FILENAME [,%OPTIONS] )

The new method constructs a new ConfigFile (or subclass) object using the FILENAME you specify. 🆕

There are several optional parameters you can pass. Options must be passed as keyed pairs in the form of option => value. The valid options are locking, lockfile, mode, and readopts. Let's break it down bestie:

• locking — determines what style of file locking gets used. Available styles are dotlock, flock, and none. The default locking style is dotlock. The none style means no locking happens at all, and all lock and unlock requests will return success. 🔒
• lockfile — lets you specify the lock filename used with dotlocking. The default is FILENAME.lock, where FILENAME is the name of the file being opened.
• mode — lets you specify the file open mode. The default mode is r+ (read/write), but r and w are accepted as well.
• readopts — lets module-specific options be passed through to the read method. It'll accept any scalar for its value; typically this is gonna be a list or hash reference.

---

🧚 DEVELOPER METHODS 🧚

joinwrap( LENGTH, HEAD, INDENT, DELIM, TAIL, @LIST )

ok this is a utility function that you can call as an object or class method. As the name suggests (slay, descriptive naming 💅), this is basically a version of the join function that also does line wrapping.

• The list you specify gets joined together, with each list element separated by the specified delimiter.
• The first line of output gets prefixed with the HEAD parameter.
• If a line exceeds the length parameter, output gets wrapped to the next line, and the INDENT parameter is used to prefix that line.
• Also, the TAIL parameter gets added to the end of every line generated, except the final one.

Now, there's one case where the resulting string can actually exceed the specified line length — if a single list element, plus HEAD or INDENT, exceeds that length. Just so you know. 🙈

And one final feature: if the HEAD or INDENT parameters contain the text %n, it gets replaced with the current line number, beginning at 0. 🔥

sequence( )

Returns the current sequence list associated with the object. This is a list of arbitrary data maintained by a ConfigFile submodule — and the ConfigFile module genuinely does not care what's in that list. zero opinions, we love that for it. 🦋

seq_append( @DATA )

Appends the specified data to the end of the sequence list. ➕

seq_insert( KEY, @DATA )

Inserts the data into the sequence list, before the data that matches the specified key. 📥

seq_remove( KEY )

Removes the data from the sequence list that matches the specified key. 🗑️

---

💜 AUTHOR 💜

Steve Snodgrass, ssnodgra@fore.com ✨

---

🌈 SEE ALSO 🌈

• Unix::AliasFile
• Unix::AutomountFile
• Unix::GroupFile
• Unix::PasswdFile

---

and that's the whole page bestie, go off 💖 ok one last thing before you close this tab — this was written for perl v5.32.1 and dated 2021-08-21. mwah, take care of her 🫶🎀