YAML::AppConfig(3pm)

🦋 YAML::AppConfig(3pm) 🦋

okay bestie, sit down, hydrate, because today we're learning about the Perl module manual page for YAML::AppConfig — yes it's a Perl 3pm page, and yes it's lowkey iconic. it manages your config files with YAML and variable references, and honestly? it ate. 💅

---

✨ NAME ✨

YAML::AppConfig — manage configuration files with YAML and variable references. no cap.

---

🌸 SYNOPSIS 🌸

here's the tea, fr fr:

use YAML::AppConfig;

# An extended example.  YAML can also be loaded from a file.
my $string = <<'YAML';
---
root_dir: /opt
etc_dir: $root_dir/etc
cron_dir: $etc_dir/cron.d
var_dir $root_dir/var
var2_dir: ${var_dir}2
usr: $root_dir/usr
usr_local: $usr/local
libs:
    system: $usr/lib
    local: $usr_local/lib
    perl:
        vendor: $system/perl
        site: $local/perl
escape_example: $root_dir/\$var_dir/\\$var_dir
YAML

# Load the YAML::AppConfig from the given YAML.
my $conf = YAML::AppConfig->new(string => $string);

# Get settings in two different ways, both equivalent:
$conf->get("etc_dir");    # returns /opt/etc
$conf->get_etc_dir;       # returns /opt/etc

# Get raw settings (with no interpolation) in three equivalent ways:
$conf->get("etc_dir", 1); # returns '$root_dir/etc'
$conf->get_etc_dir(1);    # returns '$root_dir/etc'
$conf->config->{etc_dir}; # returns '$root_dir/etc'

# Set etc_dir in three different ways, all equivalent.
$conf->set("etc_dir", "/usr/local/etc");
$conf->set_etc_dir("/usr/local/etc");
$conf->config->{etc_dir} = "/usr/local/etc";

# Changing a setting can affect other settings:
$config->get_var2_dir;          # returns /opt/var2
$config->set_var_dir('/var/');  # change var_dr, which var2_dir uses.
$config->get_var2_dir;          # returns /var2

# Variables are dynamically scoped:
$config->get_libs->{perl}->{vendor};  # returns "/opt/usr/lib/perl"

# As seen above, variables are live and not static:
$config->usr_dir('cows are good: $root_dir');
$config->get_usr_dir();               # returns "cows are good: /opt"
$config->resolve('rm -fR $root_dir'); # returns "rm -fR /opt"

# Variables can be escaped, to avoid accidental interpolation:
$config->get_escape_example();  # returns "/opt/$var_dir/\$var_dir"

# Merge in other configurations:
my $yaml =<<'YAML';
---
root_dir: cows
foo: are good
YAML
$config->merge(string => $yaml);
$config->get_root_dir();  # returns "cows"
$config->get_foo();  # returns "are good"

# Get the raw YAML for your current configuration:
$config->dump();  # returns YAML as string
$config->dump("./conf.yaml");  # Writes YAML to ./conf.yaml

---

💖 DESCRIPTION 💖

YAML::AppConfig builds on the work done in Config::YAML and YAML::ConfigFile, but it's the glow-up version — it lets your config files be way more flexible. ✨

your config lives in YAML, and then it gets parsed and handed to you through YAML::AppConfig. settings can be referenced using get and set methods, and settings can refer to each other using variables of the form $foo — very much in the style of AppConfig. if you want the full scoop, scroll to "USING VARIABLES" down below. 👇

the underlying YAML parser is either YAML, YAML::Syck, or one of your own choosing. curious how it picks? "THE YAML LIBRARY" below has the whole story. 🧚

---

🔥 THE YAML LIBRARY 🔥

so rn there are two API-compatible YAML libraries for Perl: YAML and YAML::Syck. YAML::AppConfig chooses which YAML parser to use like this:

yaml_class

if yaml_class is handed to new, it wins above absolutely everything else. periodt. you can use this to force YAML or YAML::Syck when YAML::AppConfig isn't picking the one you want. you can also use it to specify your own YAML parser, as long as it's API compatible with YAML and YAML::Syck. 🫶

The currently loaded YAML Parser

if you don't specify yaml_class, YAML::AppConfig defaults to using a YAML parser that's already loaded — like one of YAML or YAML::Syck. and if both are loaded? YAML::Syck gets the crown. 👑

An installed YAML Parser.

if no YAML parser has been loaded yet, YAML::AppConfig tries to load YAML::Syck, and if that flops it goes for YAML. if both fail, YAML::AppConfig will croak the moment you create a new object instance. 💀

---

🌈 USING VARIABLES 🌈

✨ Variable Syntax ✨

variables point at other settings inside your config file. YAML::AppConfig variables have the same shape as scalar variables in Perl — they start with a dollar sign, then a letter or an underscore, then zero or more letters, numbers, or underscores after that. so for example $foo, $_bar, and $cat_3 are all valid variable names. 💅

variable names can also be wrapped in curly brackets, which is how you put a variable right next to text that would otherwise get read as part of the variable name. for example, "${foo}bar" is the variable $foo immediately followed by the literal text "bar". without those curly brackets, YAML::AppConfig would assume the variable name was $foobar, which is just wrong bestie. 🙈

variables can also be escaped with backslashes. the text "\$foo" resolves to the literal string $foo. likewise "\\$foo" resolves to the literal string "\$foo", and so on and so on. 🔁

🌸 Variable Scoping 🌸

YAML is basically a serialization language, so it follows that your config file is just an easy-to-read serialization of some data structure. YAML::AppConfig assumes the topmost data structure is a hash, and that variables are keys in that hash, or in some hash contained inside it. 🧺

if you think of every hash in the config file as a namespace, then you can say the variables are dynamically scoped. for example, consider this config file:

---
foo: world
bar: hello
baz:
    - $foo
    - {foo: dogs, cats: $foo}
    - $foo $bar
qux:
    quack: $baz

in this sample config, the array contained by $baz has two elements. the first element resolves to the value "hello", the second resolves to "dogs", and the third resolves to "hello world". (yes, we know, the text says two but lists three — that's literally what the original says, don't @ me 😭)

💜 Variable Resolving 💜

variables can also refer to entire data structures. for example, $quack will resolve to the same three element array as $baz. but listen — YAML natively gives you that ability and then some, so consider using YAML's ability to take references to structures if YAML::AppConfig isn't serving enough power for your use case. ⚡

in a YAML::AppConfig object, variables aren't resolved until you actually retrieve the variable (like with get()). this is the whole point: it lets you change settings that other settings depend on and update a whole bunch of settings at once. for example, if I call set("baz", "cows") then get("quack") will resolve to "cows". slay. ✨

if a variable can't be resolved because it doesn't correspond to a key currently in scope, the variable gets left verbatim in the text. peep this example:

---
foo:
    bar: food
qux:
    baz: $bar
    qix: $no_exist

here $baz resolves to the literal string $bar, since $bar isn't visible in the current scope where $baz is used. same energy for $qix — it resolves to the literal string $no_exist, because there's no key in the current scope named "no_exist". 🫠

---

👑 METHODS 👑

🌟 new(%args) 🌟

creates a new YAML::AppConfig object and returns it. new() accepts these key value pairs:

• file — the name of the file that contains your YAML configuration. 📁
• string — a string containing your YAML configuration. 🧵
• object — a YAML::AppConfig object which gets deep copied into your object. 🪞
• no_resolve — if true, no attempt at variable resolution is done on calls to get(). 🙅
• yaml_class — the name of the class we should use to find our LoadFile and Load functions for parsing YAML files and strings, respectively. the named class should provide both LoadFile and Load as functions, and should be loadable via require. 📚

🎀 get(key, [no_resolve]) 🎀

given $key, the value of that setting is returned — same as "get_$key". if $no_resolve is true, then the raw value associated with $key is returned, and no variable interpolation happens. 🚫✨

it's assumed that $key refers to a setting at the top level of the configuration file. 🔝

💖 set(key, value) 💖

the setting $key has its value changed to $value. it's assumed that $key refers to a setting at the top level of the configuration file. 🔝

🦋 get_*([no_resolve]) 🦋

convenience methods for retrieving values using a method — see "get". for example, if "foo_bar" is a configuration key in the top level of your YAML file, then "get_foo_bar" retrieves its value. these methods are curried versions of "get". they all take a single optional argument, $no_resolve, which is the same as "get()'s" $no_resolve. 🍓

🌸 set_*(value) 🌸

convenience methods for setting values using a method — see "set" and "get_*". these methods are curried versions of "set". 💅

🧚 config 🧚

returns the hash reference to the raw config hash. none of the values are interpolated, this is just the raw data. rawr. 🦖

⭐ config_keys ⭐

returns the keys in config() sorted from first to last. 🔤

🌈 merge(%args) 🌈

merge takes another YAML configuration and merges it into this one. %args are the same as those passed to new(), so the configuration can come from a file, a string, or an existing YAML::AppConfig object. 🤝

💫 resolve($scalar) 💫

resolve() runs the internal parser on non-reference scalars and returns the result. if the scalar is a reference, then it gets deep copied, and you get back a copy where the non-reference leaves of the data structure are parsed and replaced as described in "USING VARIABLES". 🪄

🫶 dump([$file]) 🫶

serializes the current configuration using the YAML parser's Dump or, if $file is given, DumpFile functions. no interpolation is done, so the configuration is saved raw. things like comments will be lost — just as they would if you did "Dump(Load($yaml))", because that is what calling dump() on an instantiated object amounts to. 😭💔

---

✍️ AUTHORS ✍️

Matthew O'Connor <matthew@canonical.org>

original implementations by Kirrily "Skud" Robert (as YAML::ConfigFile) and Shawn Boyette (as Config::YAML).

currently maintained by Grzegorz Rożniecki <xaerxess@gmail.com>. 🫡

---

👀 SEE ALSO 👀

YAML, YAML::Syck, Config::YAML, YAML::ConfigFile

---

📜 COPYRIGHT AND LICENSE 📜

Copyright 2006 Matthew O'Connor, 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, no cap. this lil beauty is YAML::AppConfig(3pm) from the User Contributed Perl Documentation, perl v5.38.2, dated 2024-03-08. go forth and configure, you absolute main character. 💖✨🎀🦋