.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "YAML::AppConfig 3pm" .TH YAML::AppConfig 3pm "2014-03-14" "perl v5.18.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 \s-1YAML\s0 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 \*(L"\s-1USING VARIABLES\*(R"\s0 below for more details. .PP The underlying \s-1YAML\s0 parser is either \s-1YAML\s0, YAML::Syck or one of your choice. See \*(L"\s-1THE YAML LIBRARY\*(R"\s0 below for more information on how a \s-1YAML\s0 parser is picked. .SH "THE YAML LIBRARY" .IX Header "THE YAML LIBRARY" At this time there are two \s-1API\s0 compatible \s-1YAML\s0 libraries for Perl. \s-1YAML\s0 and YAML::Syck. YAML::AppConfig chooses which \s-1YAML\s0 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 \s-1YAML\s0 or YAML::Syck when YAML::AppConfig isn't using the one you'd like. You can also use it specify your own \s-1YAML\s0 parser, as long as it's \s-1API\s0 compatible with \s-1YAML\s0 and YAML::Syck. .IP "The currently loaded \s-1YAML\s0 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 \s-1YAML\s0 parser, e.g. one of \s-1YAML\s0 or YAML::Syck. If both are loaded then YAML::Syck is preferred. .IP "An installed \s-1YAML\s0 Parser." 4 .IX Item "An installed YAML Parser." If no \s-1YAML\s0 parser has already been loaded then YAML::AppConfig will attempt to load YAML::Syck and failing that it will attempt to load \s-1YAML\s0. 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" \&\s-1YAML\s0 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 \*(L"dogs\*(R", 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, \s-1YAML\s0 natively gives you this ability and then some. So consider using \s-1YAML\s0'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(CW\*(C`get()\*(C'\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(CW\*(C`get("quack")\*(C'\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. \fInew()\fR accepts the following key values pairs: .IP "file" 8 .IX Item "file" The name of the file which contains your \s-1YAML\s0 configuration. .IP "string" 8 .IX Item "string" A string containing your \s-1YAML\s0 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(CW\*(C`get()\*(C'\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 \s-1YAML\s0 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 \s-1YAML\s0 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(CW\*(C`config()\*(C'\fR sorted from first to last. .SS "merge(%args)" .IX Subsection "merge(%args)" Merge takes another \s-1YAML\s0 configuration and merges it into this one. \f(CW%args\fR are the same as those passed to \f(CW\*(C`new()\*(C'\fR, so the configuration can come from a file, string, or existing YAML::AppConfig object. .SS "resolve($scalar)" .IX Subsection "resolve($scalar)" \&\f(CW\*(C`resolve()\*(C'\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 \*(L"\s-1USING VARIABLES\*(R"\s0. .SS "dump([$file])" .IX Subsection "dump([$file])" Serializes the current configuration using the \s-1YAML\s0 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(CW\*(C`dump()\*(C'\fR on an instantiated object amounts to. .SH "AUTHORS" .IX Header "AUTHORS" Matthew O'Connor .PP Original implementations by Kirrily \*(L"Skud\*(R" Robert (as YAML::ConfigFile) and Shawn Boyette (as Config::YAML). .PP Currently maintained by Grzegorz RoXniecki . .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1YAML\s0, 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.