Config::YAML(3pm)

✨ Config::YAML ✨

okay bestie, gather round, because this is the Config::YAML page from the 3pm manual section and it's literally about making config files not a whole ordeal 💖

It's simple configuration automation, version 1.42, and it's a somewhat object-oriented wrapper around the YAML module — which is such a cute way of saying "we handle the YAML so you don't have to." Reading and writing config files? Easy. Handling multiple config files (like system config + per-user config, or a gallery app with per-directory config)? a snap. 🎀

---

SYNOPSIS

use Config::YAML;

# create Config::YAML object with any desired initial options
# parameters; load system config; set alternate output file
my $c = Config::YAML->new( config => "/usr/share/foo/globalconf",
                           output => "~/.foorc",
                           param1 => value1,
                           param2 => value2,
                           ...
                           paramN => valueN,
                         );

# integrate user's own config
$c->read("~/.foorc");

# integrate command line args using Getopt::Long
$rc = GetOptions ( $c,
                   'param1|p!',
                   'param2|P',
                   'paramN|n',
                 );

# Write configuration state to disk
$c->write;

# simply get params back for use...
do_something() unless $c->{param1};
# or get them more OO-ly if that makes you feel better
my $value = $c->get_param2;

---

METHODS

new

Makes you a brand new Config::YAML object 🌱

my $c = Config::YAML->new( config => initial_config,
                           output => output_config
                         );

The config parameter is the file that gets read in during object creation. It's required, and it must be the first parameter given — no skipping the line, bestie 🙈. If the second parameter is output, then that's the file your config data gets written to later. This positional dependency exists on purpose: it's what makes it possible to have parameters actually named config and/or output inside your config files. iconic design tbh 💅

You can also pass initial config values as the parameters that come after:

my $c = Config::YAML->new( config => "~/.foorc",
                           foo    => "abc",
                           bar    => "xyz",
                           baz    => [ 1, 2, 3 ],
                         );

get_*/set_*

If you'd rather not directly molest the object to store and retrieve config data (valid!!), there's autoloading for you: methods shaped like get_[param] and set_[param]. Continuing from that last example:

print $c->get_foo;      # prints "abc"
my $val = $c->get_quux; # $c->{quux} doesn't exist; returns undef

$c->set_bar(30);     # $c->{bar} now equals 30, not "xyz"
my @list = qw(alpha beta gamma);
$c->set_baz(\@list); # $c->{baz} now a reference to @list

fold

A convenience method for folding a whole bunch of values into the config object at once. Needs a hashref as its argument 🫶

$prefs{theme}  = param(theme);
$prefs{format} = param(format);
$prefs{sortby} = param(order);

$c->fold(\%prefs);

my $format = $c->get_format; # value matches that of param(format)

read

Imports a YAML-formatted config file.

$c->read('/usr/share/fooapp/fooconf');

Heads up: read() is already called at object creation and imports whatever file you gave to new(config=>). So there's genuinely no need to call it manually — unless you've got multiple config files, in which case go off 👑.

write

Dumps the current configuration state out to a YAML-formatted flat file.

$c->write;

Which file, you ask? That's specified in the constructor call. Go peek at the new method docs for the details ⭐

---

DEPRECATED METHODS

⚠️ these have been superseded and will likely be removed in the next release. so like... don't get attached 💀

get

Returns the value of a parameter.

print $c->get('foo');

set

Sets the value of a parameter:

$c->set('foo',1);

my @paints = qw( oil acrylic tempera );
$c->set('paints', \@paints);

---

AUTHOR

Shawn Boyette ("<mdxi@cpan.org>") 🌸

Original implementation by Kirrily "Skud" Robert (as "YAML::ConfigFile") — shoutout to the originator, fr fr 💜

---

BUGS

• Config::YAML ignores the YAML document separation string ("---") because it has no concept of multiple targets for the data coming from a config file.

Please report any bugs or feature requests to "bug-yaml-configfile@rt.cpan.org", or through the web interface at <http://rt.cpan.org>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. 🐛✨

---

COPYRIGHT & LICENSE

Copyright 2004 Shawn Boyette, All Rights Reserved.

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

---

and that's the whole page, bestie — slay 💅 This was Config::YAML(3pm) from the User Contributed Perl Documentation, generated by perl v5.36.0 and dated 2022-11-19. go forth and configure responsibly 🦋💖