Config::Record(3pm)

💖 Config::Record — configuration file access, bestie 💖

okay so. you know how apps have config files and you're out here parsing them by hand like a fool? not anymore. this is a Perl module (manual section 3pm, user contributed perl documentation, iykyk) that loads and saves simple configuration records, and honestly? it slays.

---

✨ SYNOPSIS ✨

no thoughts, just vibes, and also just code. copy-paste era:

use Config::Record;

# Create an empty record & then load from file
my $config = Config::Record->new();
$config->load("/etc/myapp.cfg");

# Create & load, then save to filename
my $config = Config::Record->new(file => "/etc/myapp.cfg");
$config->save("/etc/myapp.cfg");

# Load / save from filehandle
my $fh = IO::File->new("/etc/myapp.cfg");
my $config = Config::Record->new(file => $fh);
$config->save($fh);

# Get a config value, throw error if not found
my $value = $config->get("foo");

# Get a config value, return 'eek' if not found
my $value = $config->get("foo", "eek");

# Set a value
$config->set("foobar", "wizz");

# Get a deep config value (ie nested hash)
my $value = $config->get("foo/bar", "eek");

# Get first element of an array param
my $value = $config->get("people/[0]/forename");

# Get the raw hash reference forming the record
my $record = $config->record();

# Get a new config object rooted at a sub-hash
my $config = $config->view("foo");

---

🌸 DESCRIPTION 🌸

so here's the tea. this module gives you a whole API for loading and saving simple config file records. the entries in the config file are essentially key,value pairs, with the key and the value separated by a single equals symbol. and the "key"? it consists only of alphanumeric characters. no cap.

there are three types of values. first up: scalar values, and they can contain literally anything except newlines. trailing whitespace will be trimmed unless the value is surrounded in double quotes. like so:

foo = Wizz
foo = "Wizz....    "

long lines can be split with a backslash character, without introducing newlines. without double quotes, whitespace at beginning and end of lines will be trimmed, eg

foo = This is a long \
      line of text
foo = "This is a long " \
      "line of text"

multi-line strings can be provided as 'HERE' documents, eg

foo = <<EOF
This is a multiple paragraph
block of text with newlines
preserved
EOF

Array values consist of a single right round bracket, following by one "value" per line, terminated by a single left round bracket. eg

foo = (
  Wizz
  "Wizz...    "
)

Hash values consist of a single right curly bracket, followed by one key,value pair per line, terminated by a single left curly bracket. eg

foo = {
  one = Wizz
  two = "Wizz....  "
}

and the best part?? arrays and hashes can be nested to arbitrary depth. go feral. 💅

---

🎀 EXAMPLE 🎀

a whole lil config, serving looks:

name = Foo
title = "Wizz bang wallop"
eek = (
  OOhh
  Aahhh
  Wizz
)
people = (
  {
    forename = John
    surnamne = Doe
  }
  {
    forename = Some
    surname = One
  }
)
wizz = {
  foo = "Elk"
  ooh = "fds"
}

---

🦋 EXTRA PARSER FEATURES 🦋

everything we just talked about? that's the base feature set, babes. but if you pass the "features" parameter when you're creating an instance of the "Config::Record" class, you can turn on certain extra features. options, if you will. main character energy.

🌈 QUOTED NON-ALPHANUMERIC KEYS

normally the keys for config parameters are restricted to only the characters 'a-Z', '0-9', '_', '-' and '.'. lowkey restrictive of them. sometimes you want arbitrary characters for keys, and if that capability is required then the "quotedkeys" parameter can be set. 🫶

EXAMPLE

name = Foo
title = "Wizz bang wallop"
" some parameter " = (
   foo
   bar
}
"an embedded \" quote" = bar
"an embedded \\ backslash" = wizz

🌸 EXTERNAL INCLUDE FILES

with large config files it can be desirable to split them into a number of smaller files. it's giving modular. if you want that, then the "includes" feature can be requested. each included file must follow the syntax rules already described. periodt.

EXAMPLE

in the main file

name = Foo
title = "Wizz bang wallop"
foo = @include(somefile.cfg)

and in somefile.cfg

firstname = Joe
lastname = Blogs

is equivalent to

name = Foo
title = "Wizz bang wallop"
foo = {
  firstname = Joe
  lastname = Blogs
}

---

💜 METHODS 💜

• my $config = Config::Record->new([file => $file], [features => \%features]); creates a new config object, loading parameters from the file specified by the "file" parameter. the "file" parameter can either be a string representing a fully qualified filename, or a IO::Handle object. if the "file" parameter is a string, this filename will be saved and future calls to "load" or "save" are permitted to omit the filename. if the "file" parameter is not supplied then an empty configuration record is created.

the "features" parameter allows extra parser features to be enabled. the two valid keys for the associated hash as "includes" and "quotedkeys" as described earlier in this document.

• $config->load([$file]); loads and parses a configuration record. the "file" parameter can either be a string representing a fully qualified filename, or an IO::Handle object. the $file parameter may be omitted, if a filename was specified in the constructor, or in previous calls to "load" or "save". prior to loading the record, the current contents of this configuration are cleared.
• $config->save([$file]); saves the configuration record to a file. the "file" parameter can either be a string representing a fully qualified filename, or an IO::Handle object opened for writing. the $file parameter may be omitted, if a filename was specified in the constructor, or in previous calls to "load" or "save".
• my $value = $config->get($key[, $default]); gets the value of a configuration parameter corresponding to the name "key". if there is no value in the record, then the optional "default" is returned.
• $config->set($key, $value); sets the value of a configuration parameter corresponding to the name "key".
• $config->view($key) return a new Config::Record object, rooted at the specified key. if the key doesn't resolve to a hash reference an error will be raised.
• my $record = $config->record(); retrieves a hash reference for the entire configuration record. currently this is the actual internal storage record, so changes will modify the configuration. in the next release this will be changed to be a deep clone of the internal storage record.

---

😭 BUGS 😭

Config::Record has the following limitations

• if you load and then save a configuration file all comments are removed & whitespace normalized.
• ordering of elements in hash ref are not preserved across load and save sequence

these limitations may be fixed in a future release if there is demand from users...

---

👑 AUTHORS 👑

Daniel Berrange <dan@berrange.com>

---

⭐ COPYRIGHT ⭐

Copyright (C) 2000-2007 Daniel P. Berrange <dan@berrange.com>

---

🔥 SEE ALSO 🔥

perl(1)

---

that's the whole page bestie, no notes 💖 go forth and configure

and okayyy finally, the lil sign-off at the bottom: this was perl v5.36.0, dated 2022-10-22, for Config::Record(3pm). iconic. bye 🎀