NAME
YAML::LoadBundle - Load a directory of YAML files as a bundle
VERSION
version v0.4.3
SYNOPSIS
use YAML::LoadBundle qw(:all);
my $hash = load_yaml_bundle( "/path/to/yaml_bundle/dir/" );DESCRIPTION
Adds additional features to YAML::XS to allow splitting a YAML file into multiple files in a common directory. This helps with readability when the file is large.
It also provides more advanced merging features than the standard YAML spec.
Export
Nothing is exported by default, but all the functions listed below are available for export.
All will be exported with :all.
Exported Functions
Load
load_yaml
load_yaml($filename)
load_yaml(\*FILEHANDLE)
load_yaml($yaml_data)Parses a YAML file (or string) with extra error-checking.
When passed a $filename, the %YAML_cache will cache a dclone'd copy of the result for later retrieval, unless the file has been modified since the last load. This can be prevented by passing anything else as a 2nd parameter, if you know that the file will never be reloaded.
When passed a string, the %YAML_cache will cache a copy of the result, using the SHA1 digest of the string as the hash key. Strings are only cached in memory, not on disk.
After loading the YAML into a Perl data structure, some postprocessing is done on specially-named keys in hash references. Each is merged into their containing hash reference, though at different times and with different strategies.
-importshallow merge (e.g.
%x = (%y, %x))-exportshallow merge
-mergedeep merge (see Hash::Merge::Simple)
-cloneclones intermediate hash keys, see "Cloning intermediate hash keys" below.
-flattensome_key: { -flatten: [*SomeArrayRef, *SomeOtherArrayRef] }Instead of doing any kind of special hash merging, this special key takes an arrayref of arrayrefs, merges all their contents into one large arrayref, then replaces its entire surrounding hash with the arrayref.
In other words, the example above would look like this in Perl:
{ some_key => [@$some_array_ref, @$some_other_array_ref] }-flattenhashsome_key: { -flattenhash: [*SomeHashRef, *SomeOtherHashRef] }Sometimes it is desirable to import more than one hash object, but cannot due to limitations of keynames like -import. If you really want this behavior, add this flag.
import and export are backwards-compatibility synonyms for -import and -export.
Like normal list assignment in Perl, the right-hand side takes precedence (pseudocode):
%hash = deep_merge(%merge, shallow_merge(%import, %export, %hash));Instead of a hash reference, any of these keys may contain an array reference of hash references, in which case those hash references are merged using whatever strategy normally applies (e.g. deep merge for -merge).
Cloning intermediate hash keys
-clone provides a way to repeat intermediate nodes in hashes:
apple:
-clone:
letters:
letters: &letters
- a
- b
d: e
f: g
numbers:
numbers:
- 1
- 2
quattro: 4
cinco: 5
golf: g
hotel: h
banana:
-clone:
letters:
letters: *letters
h: i
j: kThis results a hash with "d" and "f" keys getting cloned inside another hash using keys "a" and "b" for each cloned copy; "quattro" and "cinco" are also cloned under keys "1" and "2", together with "g" and "h" which are just along for the ride.
The same "a" and "b" keys get referenced, without duplication, and used for intermediate keys in a different part of the hash.
So the resulting hash would be:
'apple' => {
'a' => {
'd' => 'e',
'f' => 'g',
},
'b' => {
'd' => 'e',
'f' => 'g',
},
'1' => {
'quattro' => '4',
'cinco' => '5',
},
'2' => {
'quattro' => '4',
'cinco' => '5',
},
'golf' => 'g',
'hotel' => 'h',
},
'banana' => {
'a' => {
'h' => 'i',
'j' => 'k',
},
'b' => {
'h' => 'i',
'j' => 'k',
},
},Formally:
-clone itself must be a hash key, and contains a hash, the "clone" hash, with one or more keys. Each value of those keys is a subhash that must have a key with the same name as its parent key in the "clone" hash. This key's value must be a list, and the rest of the subhash gets cloned, one for each value in the list, and placed into the -clone hash, with each value in the list being its key.
This provides the means to have a single specification of a list and then repeat it (via the usual YAML "&" and "*") references but insert them as intermediate hash keys.
load_yaml_bundle
load_yaml_bundle($path, \%options)Similar to "load_yaml", but loads YAML from a bundle of configuration files. This may be a single file, a directory containing configuration files, or a whole directory tree of configuration files.
The given path names the base location for the bundle. This starts by loading a file with the given name followed by a configuration prefix (either .yml or .conf by default). It then checks to see if there is a directory with the same name as the path. It then repeats the loading process for all nested files and directories where the file and directory names become the keys into which the configuration is injected.
For example, given a directory layout like this:
conf/base.conf
conf/base/common.conf
conf/base/user.conf
conf/base/user/accounts.confA hash would be returned mapped something like this (pseudo-code):
{
common => load_yaml("conf/base/common.conf"),
user => {
accounts => load_yaml("conf/base/user/accounts.conf"),
%{ load_yaml("conf/base/user.conf") }
},
%{ load_yaml("conf/base.conf") }
}However, the actual merge will be a deep merge.
The usual semantics related to import, export, and merging apply to these files as they do in "load_yaml".
Symlinks can be used to share the data between multiple keys. By default, symlinks will be followed, but will cause an error if any of them are outside the root path of the bundle. If a symlink is permitted, this will follow symlinks to files or directories as if they were the files or directories set locally, allowing the original key to be renamed in any way desired. It also means that symlinks to files must have a correct configuraiton file suffix.
This will ignore any file starting with a period.
There are some options to modify the default behaviors:
follow_symlinks_when-
This may be set to any of the following strings:
bundled-
This is the default. Symlinks are followed, but only within the root.
never-
Do not follow symlinks.
always-
Always follow symlinks. Use this with caution.
follow_symlinks_fail-
This may be set to any of the following strings:
error-
This is the default. When symlinks are found, but not followed, croak.
warn-
When symlinks are found, but not followed, carp.
ignore-
When symlinks are found, but not followed... take no action at all.
conf_suffixes-
This routine only considers files that have the given suffxes. The default includes "conf" and "yml". The suffixes are given as an array reference of strings. (All directories will be followed, at least to the maximum depth.)
max_depth-
This defaults to 20 which is probably more than enough and mostly intended to prevent some sort of insane failure. If a directory is found at one further than the maximum depth, a warning will be issued.
Observe
add_yaml_observer
add_yaml_observer(sub {
my $filename = shift;
warn "Yaml file $filename was just loaded.";
});Adds an observer sub that will be notified just prior to a yaml file being loaded. Note that each observer is called even if the yaml file is cached and does not need to be reloaded.
_notify_yaml_observers
Called internally to notify each waiting observer that a new yaml file is being loaded.
remove_yaml_observer
remove_yaml_observer($subref);Removes an observer sub that was previously added via add_yaml_observer.
Cache
$YAML::LoadBundle::CacheDir
Set this to a path that already exists of where to cache loaded files.
$YAML::LoadBundle::CacheDir
= File::Spec->catdir( File::Spec->tmpdir, 'yaml-loadbundle' );Defaults to $ENV{YAML_LOADBUNDLE_CACHEDIR}.
If false, caching is disabled.
AUTHOR
Grant Street Group <developers@grantstreet.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2016 - 2021 by Grant Street Group.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)