.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "YAML::AppConfig 3pm" .TH YAML::AppConfig 3pm 2024-03-08 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME YAML::AppConfig \- Manage configuration files with YAML and variable references. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use YAML::AppConfig; \& \& # An extended example. YAML can also be loaded from a file. \& my $string = <<\*(AqYAML\*(Aq; \& \-\-\- \& 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/\e$var_dir/\e\e$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 \*(Aq$root_dir/etc\*(Aq \& $conf\->get_etc_dir(1); # returns \*(Aq$root_dir/etc\*(Aq \& $conf\->config\->{etc_dir}; # returns \*(Aq$root_dir/etc\*(Aq \& \& # 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(\*(Aq/var/\*(Aq); # 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(\*(Aqcows are good: $root_dir\*(Aq); \& $config\->get_usr_dir(); # returns "cows are good: /opt" \& $config\->resolve(\*(Aqrm \-fR $root_dir\*(Aq); # returns "rm \-fR /opt" \& \& # Variables can be escaped, to avoid accidental interpolation: \& $config\->get_escape_example(); # returns "/opt/$var_dir/\e$var_dir" \& \& # Merge in other configurations: \& my $yaml =<<\*(AqYAML\*(Aq; \& \-\-\- \& 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 .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" YAML::AppConfig extends the work done in Config::YAML and YAML::ConfigFile to allow more flexible configuration files. .PP Your configuration is stored in YAML and then parsed and presented to you via YAML::AppConfig. Settings can be referenced using \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`set\*(C'\fR methods and settings can refer to one another by using variables of the form \&\f(CW$foo\fR, much in the style of \f(CW\*(C`AppConfig\*(C'\fR. See "USING VARIABLES" below for more details. .PP The underlying YAML parser is either YAML, YAML::Syck or one of your choice. See "THE YAML LIBRARY" below for more information on how a YAML parser is picked. .SH "THE YAML LIBRARY" .IX Header "THE YAML LIBRARY" At this time there are two API compatible YAML libraries for Perl. YAML and YAML::Syck. YAML::AppConfig chooses which YAML parser to use as follows: .IP yaml_class 4 .IX Item "yaml_class" If \f(CW\*(C`yaml_class\*(C'\fR is given to \f(CW\*(C`new\*(C'\fR then it used above all other considerations. You can use this to force use of YAML or YAML::Syck when YAML::AppConfig isn't using the one you'd like. You can also use it specify your own YAML parser, as long as it's API compatible with YAML and YAML::Syck. .IP "The currently loaded YAML Parser" 4 .IX Item "The currently loaded YAML Parser" If you don't specify \f(CW\*(C`yaml_class\*(C'\fR then YAML::AppConfig will default to using an already loaded YAML parser, e.g. one of YAML or YAML::Syck. If both are loaded then YAML::Syck is preferred. .IP "An installed YAML Parser." 4 .IX Item "An installed YAML Parser." If no YAML parser has already been loaded then YAML::AppConfig will attempt to load YAML::Syck and failing that it will attempt to load YAML. If both fail then YAML::AppConfig will \f(CW\*(C`croak\*(C'\fR when you create a new object instance. .SH "USING VARIABLES" .IX Header "USING VARIABLES" .SS "Variable Syntax" .IX Subsection "Variable Syntax" Variables refer to other settings inside the configuration file. YAML::AppConfig variables have the same form as scalar variables in Perl. That is they begin with a dollar sign and then start with a letter or an underscore and then have zero or more letters, numbers, or underscores which follow. For example, \f(CW$foo\fR, \f(CW$_bar\fR, and \f(CW$cat_3\fR are all valid variable names. .PP Variable names can also be contained in curly brackets so you can have a variable side-by-side with text that might otherwise be read as the name of the variable itself. For example, \f(CW\*(C`${foo}bar\*(C'\fR is the the variable \f(CW$foo\fR immediately followed by the literal text \f(CW\*(C`bar\*(C'\fR. Without the curly brackets YAML::AppConfig would assume the variable name was \f(CW$foobar\fR, which is incorrect. .PP Variables can also be escaped by using backslashes. The text \f(CW\*(C`\e$foo\*(C'\fR will resolve to the literal string \f(CW$foo\fR. Likewise \f(CW\*(C`\e\e$foo\*(C'\fR will resolve to the literal string \f(CW\*(C`\e$foo\*(C'\fR, and so on. .SS "Variable Scoping" .IX Subsection "Variable Scoping" YAML is essentially a serialization language and so it follows that your configuration file is just an easy to read serialization of some data structure. YAML::AppConfig assumes the top most data structure is a hash and that variables are keys in that hash, or in some hash contained within. .PP If every hash in the configuration file is thought of as a namespace then the variables can be said to be dynamically scoped. For example, consider the following configuration file: .PP .Vb 9 \& \-\-\- \& foo: world \& bar: hello \& baz: \& \- $foo \& \- {foo: dogs, cats: $foo} \& \- $foo $bar \& qux: \& quack: $baz .Ve .PP In this sample configuration the array contained by \f(CW$baz\fR has two elements. The first element resolves to the value \f(CW\*(C`hello\*(C'\fR, the second element resolves to the value "dogs", and the third element resolves to \f(CW\*(C`hello world\*(C'\fR. .SS "Variable Resolving" .IX Subsection "Variable Resolving" Variables can also refer to entire data structures. For example, \f(CW$quack\fR will resolve to the same three element array as \f(CW$baz\fR. However, YAML natively gives you this ability and then some. So consider using YAML's ability to take references to structures if YAML::AppConfig is not providing enough power for your use case. .PP In a YAML::AppConfig object the variables are not resolved until you retrieve the variable (e.g. using \f(CWget()\fR. This allows you to change settings which are used by other settings and update many settings at once. For example, if I call \f(CW\*(C`set("baz", "cows")\*(C'\fR then \f(CWget("quack")\fR will resolve to \f(CW\*(C`cows\*(C'\fR. .PP If a variable can not be resolved because it doesn't correspond to a key currently in scope then the variable will be left verbatim in the text. Consider this example: .PP .Vb 6 \& \-\-\- \& foo: \& bar: food \& qux: \& baz: $bar \& qix: $no_exist .Ve .PP In this example \f(CW$baz\fR resolves to the literal string \f(CW$bar\fR since \f(CW$bar\fR is not visible within the current scope where \f(CW$baz\fR is used. Likewise, \f(CW$qix\fR resolves to the literal string \f(CW$no_exist\fR since there is no key in the current scope named \f(CW\*(C`no_exist\*(C'\fR. .SH METHODS .IX Header "METHODS" .SS new(%args) .IX Subsection "new(%args)" Creates a new YAML::AppConfig object and returns it. \fBnew()\fR accepts the following key values pairs: .IP file 8 .IX Item "file" The name of the file which contains your YAML configuration. .IP string 8 .IX Item "string" A string containing your YAML configuration. .IP object 8 .IX Item "object" A YAML::AppConfig object which will be deep copied into your object. .IP no_resolve 8 .IX Item "no_resolve" If true no attempt at variable resolution is done on calls to \f(CWget()\fR. .IP yaml_class 8 .IX Item "yaml_class" The name of the class we should use to find our \f(CW\*(C`LoadFile\*(C'\fR and \f(CW\*(C`Load\*(C'\fR functions for parsing YAML files and strings, respectively. The named class should provide both \f(CW\*(C`LoadFile\*(C'\fR and \f(CW\*(C`Load\*(C'\fR as functions and should be loadable via \f(CW\*(C`require\*(C'\fR. .SS "get(key, [no_resolve])" .IX Subsection "get(key, [no_resolve])" Given \f(CW$key\fR the value of that setting is returned, same as \f(CW\*(C`get_$key\*(C'\fR. If \&\f(CW$no_resolve\fR is true then the raw value associated with \f(CW$key\fR is returned, no variable interpolation is done. .PP It is assumed that \f(CW$key\fR refers to a setting at the top level of the configuration file. .SS "set(key, value)" .IX Subsection "set(key, value)" The setting \f(CW$key\fR will have its value changed to \f(CW$value\fR. It is assumed that \f(CW$key\fR refers to a setting at the top level of the configuration file. .SS get_*([no_resolve]) .IX Subsection "get_*([no_resolve])" Convenience methods to retrieve values using a method, see \f(CW\*(C`get\*(C'\fR. For example if \f(CW\*(C`foo_bar\*(C'\fR is a configuration key in top level of your YAML file then \f(CW\*(C`get_foo_bar\*(C'\fR retrieves its value. These methods are curried versions of \f(CW\*(C`get\*(C'\fR. These functions all take a single optional argument, \&\f(CW$no_resolve\fR, which is the same as \f(CW\*(C`get()\*(Aqs\*(C'\fR \f(CW$no_resolve\fR. .SS set_*(value) .IX Subsection "set_*(value)" Convenience methods to set values using a method, see \f(CW\*(C`set\*(C'\fR and \f(CW\*(C`get_*\*(C'\fR. These methods are curried versions of \f(CW\*(C`set\*(C'\fR. .SS config .IX Subsection "config" Returns the hash reference to the raw config hash. None of the values are interpolated, this is just the raw data. .SS config_keys .IX Subsection "config_keys" Returns the keys in \f(CWconfig()\fR sorted from first to last. .SS merge(%args) .IX Subsection "merge(%args)" Merge takes another YAML configuration and merges it into this one. \f(CW%args\fR are the same as those passed to \f(CWnew()\fR, so the configuration can come from a file, string, or existing YAML::AppConfig object. .SS resolve($scalar) .IX Subsection "resolve($scalar)" \&\f(CWresolve()\fR runs the internal parser on non-reference scalars and returns the result. If the scalar is a reference then it is deep copied and a copy is returned where the non-reference leaves of the data structure are parsed and replaced as described in "USING VARIABLES". .SS dump([$file]) .IX Subsection "dump([$file])" Serializes the current configuration using the YAML parser's Dump or, if \&\f(CW$file\fR 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 \f(CW\*(C`Dump(Load($yaml))\*(C'\fR, because that is what what calling \&\f(CWdump()\fR on an instantiated object amounts to. .SH AUTHORS .IX Header "AUTHORS" Matthew O'Connor .PP Original implementations by Kirrily "Skud" Robert (as YAML::ConfigFile) and Shawn Boyette (as Config::YAML). .PP Currently maintained by Grzegorz Rożniecki . .SH "SEE ALSO" .IX Header "SEE ALSO" YAML, YAML::Syck, Config::YAML, YAML::ConfigFile .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2006 Matthew O'Connor, All Rights Reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.