| 1 | ### | ||
| 2 | ### Copyright (c) 2015 - 2026 Curtis Leach. All rights reserved. | ||
| 3 | ### | ||
| 4 | ### Module: Advanced::Config::Examples | ||
| 5 | |||
| 6 | package Advanced::Config::Examples; | ||
| 7 | |||
| 8 | 1 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 1 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | |||
| 11 | 1 | ▶ | use vars qw ( @ISA @EXPORT @EXPORT_OK $VERSION ); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 12 | 1 | ▶ | use Exporter; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 13 | |||
| 14 | 1 | ▶ | use Fred::Fish::DBUG 2.09 qw / on_if_set ADVANCED_CONFIG_FISH /; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 15 | |||
| 16 | 1 | $VERSION = "1.15"; | |
| 17 | 1 | @ISA = qw ( Exporter ); | |
| 18 | 1 | @EXPORT = qw (); | |
| 19 | 1 | @EXPORT_OK = qw (); | |
| 20 | |||
| 21 | |||
| 22 | # Required if module is included w/ require command; | ||
| 23 | 1 | 1; | |
| 24 | |||
| 25 | # ============================================================================= | ||
| 26 | # Only POD text appears below this line! | ||
| 27 | # ============================================================================= | ||
| 28 | |||
| 29 | =head1 NAME | ||
| 30 | |||
| 31 | Advanced::Config::Examples - Defines sample config files supported by this | ||
| 32 | module. Sourcing this module in does nothing for you. | ||
| 33 | |||
| 34 | =head1 SYNOPSIS | ||
| 35 | |||
| 36 | In many cases it's just easier to show an example instead of trying | ||
| 37 | to put things into words. So this module is just some POD text to document | ||
| 38 | what this module is expecting to load into memory as your config file. | ||
| 39 | |||
| 40 | Just be aware that it's possible to override many of the operators defined in | ||
| 41 | the config file. So for example the B<=> operator could be B<:=> and the | ||
| 42 | B<#> operator could have been B<CMT:>. | ||
| 43 | |||
| 44 | =head1 HISTORY | ||
| 45 | |||
| 46 | This module started out as a parser of unix shell script data files so that | ||
| 47 | shell scripts and perl programs could share the same config files. Hence the | ||
| 48 | support of shell script variables, quotes and the sourcing in of sub-files. | ||
| 49 | Allowing for limited logic in your config files. | ||
| 50 | |||
| 51 | From there it just grew to support non-unix features such as windows batch | ||
| 52 | files and more generic configuration features. Such as being able handle | ||
| 53 | various formatting of config files and the ability to obscure or encrypt values | ||
| 54 | from casual snooping. Or the addition of sections to allow the same config | ||
| 55 | file to be used on multiple servers and OS. | ||
| 56 | |||
| 57 | So today it's a powerful tool that turns your config files into objects your | ||
| 58 | perl code can reference and manipulate. | ||
| 59 | |||
| 60 | =head1 SURROUNDING A VALUE WITH QUOTES IN YOUR CONFIG FILE | ||
| 61 | |||
| 62 | If you surround a value with balanced quotes, those quotes are automatically | ||
| 63 | removed before that value is assigned to it's tag. Quotes are supported mostly | ||
| 64 | for readability and as a way to allow comment symbols in your value. Or a way | ||
| 65 | to force leading and trailing spaces to your value. Where without quotes those | ||
| 66 | spaces are stripped off. | ||
| 67 | |||
| 68 | =head1 VARIABLE SUBSTITUTIONS | ||
| 69 | |||
| 70 | All config files support variable substitution. A variable can be any B<tag> | ||
| 71 | that appears above it in the config file. If not defined there, it will check | ||
| 72 | if it's defined as an environment variable in the B<%ENV> hash instead. If | ||
| 73 | still not found it will check for several predefined special variables for this | ||
| 74 | module. If it can't find a variable it's value is always the empty string. | ||
| 75 | |||
| 76 | By default variables are in the format of B<${>...B<}>. Where ... is your | ||
| 77 | variable's name and the B<${> & B<}> strings are the default surrounding anchors | ||
| 78 | that define it as a variable. | ||
| 79 | |||
| 80 | For more on this see the following link on Parameter Expansion: | ||
| 81 | L<https://web.archive.org/web/20200309072646/https://wiki.bash-hackers.org/syntax/pe> | ||
| 82 | This module supports most of the parameter expansions listed in the link except | ||
| 83 | for those dealing with arrays. Other modifier rules may be added upon request. | ||
| 84 | |||
| 85 | Things get a bit more complex evaluating variables if you've defined sections | ||
| 86 | in your config file. | ||
| 87 | |||
| 88 | See the POD for B<lookup_one_variable>() in L<Advanced::Config> for step by step | ||
| 89 | instructions on expanding a variable's name. | ||
| 90 | |||
| 91 | For a list of special variables try calling: | ||
| 92 | S<Advanced::Config-E<gt>print_special_vars();> | ||
| 93 | |||
| 94 | =head1 SOURCING IN OTHER CONFIG FILES | ||
| 95 | |||
| 96 | It's possible to source multiple config files together as if they were one big | ||
| 97 | config file. You can either use absolute paths to each config file, or more | ||
| 98 | likely relative paths. | ||
| 99 | |||
| 100 | Sourcing in sub-config files using relative paths works a little different than | ||
| 101 | you might expect. It's the relative path from the location of the config file | ||
| 102 | doing the sourcing, not the current directory your program is running in. | ||
| 103 | |||
| 104 | This way the writer of the config file, not the programmer, controls which | ||
| 105 | config file gets sourced in. Of course the config file writer can give control | ||
| 106 | back to the programmer by using variables as part of the name of the config | ||
| 107 | file being sourced in. | ||
| 108 | |||
| 109 | If recursion is detected, this module silently refuses to reload the problem | ||
| 110 | config file and breaks the recursion. But you have the option of treating it | ||
| 111 | as a fatal error instead. Recursion is detected even if you source in a | ||
| 112 | symbolic link back to the original file. | ||
| 113 | |||
| 114 | It is always a fatal error if the requested config file doesn't exist! | ||
| 115 | |||
| 116 | =head1 SOURCING IN CONFIG FILES THAT USE DIFFERENT PARSING RULES | ||
| 117 | |||
| 118 | Normally when you source in sub-files, both files use the same parsing rules so | ||
| 119 | no additional logic is needed to handle parsing the config files. But when | ||
| 120 | both config files require different parsing rules in order to load, this module | ||
| 121 | provides two ways to do this. | ||
| 122 | |||
| 123 | The 1st way is to define a callback function using options I<source_cb> and | ||
| 124 | I<source_cb_opts> so that the callback function is called whenever another | ||
| 125 | config file is sourced into the current one. The callback function is passed | ||
| 126 | the file being sourced in and returns the updated option hashes needed when | ||
| 127 | parsing that file. How that is done is left up to the programmer. | ||
| 128 | |||
| 129 | The 2nd way is to use a rule config file that tells how to parse your config | ||
| 130 | files. You use the special constructor B<newDefineConfigRules> to load this | ||
| 131 | special config file into memory using default parsing rules. Then you later | ||
| 132 | call B<set_config_rules> to associate this rule file to your config file. | ||
| 133 | |||
| 134 | This rule config file is referenced whenever a new file is parsed. It looks up | ||
| 135 | the section named after the file being parsed and returns the options needed to | ||
| 136 | parse the config file. It 1st tries to find a section in the rule config file | ||
| 137 | that matches that filename. If no match is found it tries for a wildcard | ||
| 138 | lookup. Say you define 3 wildcard sections: B<*>, B<*.cfg> & B<tom*.cfg>. | ||
| 139 | |||
| 140 | So you try to load I<John.cfg> it will match section B<*.cfg>. | ||
| 141 | |||
| 142 | Next you load I<wendy.INC>, it will match the default wildcard section B<*>. | ||
| 143 | |||
| 144 | But loading I<Tommy.CFG> has a problem. It matches both B<*.cfg> & B<tom*.cfg>. | ||
| 145 | In this case it looks up a special tag B<__ORDER__> to see which section to use. | ||
| 146 | The tag with the smallest integer value is the section to use. If it still | ||
| 147 | matches multiple sections it is a fatal error. The reason it didn't match B<*> | ||
| 148 | is that it assumes an B<__ORDER__> of infinity for this special case. | ||
| 149 | |||
| 150 | Each section defines the options needed to parse the config file. You can only | ||
| 151 | define tags that match the options defined in L<Advanced::Config::Options> and | ||
| 152 | the special tag B<__ORDER__>. Any other tag is a fatal error. All tags are | ||
| 153 | case insensitive. | ||
| 154 | |||
| 155 | =head1 CONTROLLING THE PARSING OF YOUR CONFIG FILES | ||
| 156 | |||
| 157 | See I<The Read Options> section of L<Advanced::Config::Options> for what options | ||
| 158 | are available for customizing how your configuration files gets parsed. | ||
| 159 | |||
| 160 | While I<The Get Options> section covers options for looking up the value for | ||
| 161 | a given tag generated. | ||
| 162 | |||
| 163 | =head1 ENCRYPTING VALUES IN YOUR CONFIG FILE | ||
| 164 | |||
| 165 | This module has hooks to allow the encryption/decryption of values in your | ||
| 166 | config file. It can do it in two levels. Simple obscuring of the tag's value | ||
| 167 | or true encryption/decryption. See L<Advanced::Config::Options> for more | ||
| 168 | details on how to do this. | ||
| 169 | |||
| 170 | =head1 CONFIG FILE EXAMPLES | ||
| 171 | |||
| 172 | =over 4 | ||
| 173 | |||
| 174 | =item A VERY SIMPLE CONFIG FILE. (simple.cfg) | ||
| 175 | |||
| 176 | # This is a comment | ||
| 177 | |||
| 178 | tag1 = abc # A simple assignment. | ||
| 179 | |||
| 180 | # The balanced quotes will automatically be removed from the value ... | ||
| 181 | tag2="efg" # See we put surrounding quotes around the value. | ||
| 182 | |||
| 183 | tag3 = 'l m n' # The alternate quotes. | ||
| 184 | |||
| 185 | tag4 = p q r # See quotes are completely optional. | ||
| 186 | |||
| 187 | tag5 = ${tag1} # Performs variable substitution, same as: tag5 = "abc". | ||
| 188 | |||
| 189 | tag1 = xyz # See I've overridden tag1's original value to "xyz". | ||
| 190 | TAG1 = 123 # tag1 is still xyz, tags are case sensitive. | ||
| 191 | |||
| 192 | To load it into memory do: | ||
| 193 | |||
| 194 | my $cfg = Advanced::config->new ("simple.cfg")->load_config(); | ||
| 195 | |||
| 196 | =item A SLIGHTLY MORE COMPLEX CONFIG FILE. (complex.cfg) | ||
| 197 | |||
| 198 | # Merge in this config file. Looks in the same directory as | ||
| 199 | # this config file is in. Not the program's current directory. | ||
| 200 | . simple.cfg | ||
| 201 | |||
| 202 | # Sourcing in another config file. (contents not shown) | ||
| 203 | # Offset is from the same directory this config file is in. | ||
| 204 | # Not the program's current directory! | ||
| 205 | . ../Alt-Config/relative.cfg | ||
| 206 | |||
| 207 | # See I'm referencing variables defined in simple.cfg! | ||
| 208 | tag1 = ${tag1} ${tag3} ${tag1} # tag1 now equals: "xyz l m n xyz". | ||
| 209 | |||
| 210 | tag 6 = abc = 7 # "tag 6" now contains: "abc = 7". | ||
| 211 | tag 6 = ${TAG1} # "tag 6" is now: 123 | ||
| 212 | |||
| 213 | messy = "I have a # in my value" # See comment symbol in the value. | ||
| 214 | |||
| 215 | # A neat little trick ... | ||
| 216 | # Implements: a = $ENV{test} ? "TRUE" : "FALSE"; | ||
| 217 | a = ${test:+TRUE} # Set to TRUE if $ENV{test} is set, else undef | ||
| 218 | a = ${a:-FALSE} # Set to FALSE if ${a} is undef, else set to ${a}. | ||
| 219 | |||
| 220 | # Does variables within variables ... | ||
| 221 | # Implements: b = $ENV{test} ? $y : $z; | ||
| 222 | y = YES | ||
| 223 | z = NO | ||
| 224 | b = ${test:+${y}} # Set to ${y} if $ENV{test} is set, else undef | ||
| 225 | b = ${b:-${z}} # Set to ${z} if ${b} is undef, else set to ${b}. | ||
| 226 | |||
| 227 | # So (a,b) = (TRUE,YES) or (FALSE,NO). | ||
| 228 | |||
| 229 | # How about testing for a specific value for $ENV{test}? This can be | ||
| 230 | # done in a limited way. | ||
| 231 | message_abc = I know my abc's. | ||
| 232 | message_123 = I know my 123's | ||
| 233 | message_hello = Hello World! | ||
| 234 | msg = ${message_${test}:-Unknown Message.} | ||
| 235 | |||
| 236 | # So if test is "abc", "123" or "hello" it will use the appropriate | ||
| 237 | # value for tag msg. Otherwise it will be "Unknown Message.". | ||
| 238 | |||
| 239 | # This shows that you can put some logic in your config files so that | ||
| 240 | # your config files can be shared across platforms without having | ||
| 241 | # to have multiple versions of that config file or add complex platform | ||
| 242 | # specific logic into your perl code. | ||
| 243 | |||
| 244 | To load it into memory do: | ||
| 245 | |||
| 246 | my $cfg = Advanced::config->new ("complex.cfg")->load_config(); | ||
| 247 | |||
| 248 | =item BREAKING YOUR CONFIG FILE INTO SECTIONS (section.cfg) | ||
| 249 | |||
| 250 | abc = lmn # Has no section, so considered in section "main". | ||
| 251 | user = me | ||
| 252 | pwd = nope! | ||
| 253 | |||
| 254 | [ host 1 ] | ||
| 255 | abc = xyz | ||
| 256 | pwd = password1 | ||
| 257 | |||
| 258 | [host 2] | ||
| 259 | abc=abc | ||
| 260 | pwd = password2 | ||
| 261 | |||
| 262 | [ HOST 3 ] | ||
| 263 | abc = 123 | ||
| 264 | pwd = password3 | ||
| 265 | |||
| 266 | [ HOST 2 ] | ||
| 267 | efg = repeat # Section "host 2" has 3 tags in it. "abc", "efg" & "pwd". | ||
| 268 | |||
| 269 | [ Host 4 ] | ||
| 270 | user = you | ||
| 271 | |||
| 272 | Please note that section names are case insensitive and the tag abc's value | ||
| 273 | depends on what section of the config file you are currently looking at. This | ||
| 274 | way you may repeat tags between sections and know that each section is | ||
| 275 | independent of each other. As if each section was in its own config file. | ||
| 276 | |||
| 277 | Or you can interpret each section as overrides to tags in the main section | ||
| 278 | using the B<inherit> option. Where if a tag isn't defined in the current | ||
| 279 | section, it then looks in the main section for it. Say you're on host 1 and | ||
| 280 | you want to log into your application. You need both a user & pwd pair to do | ||
| 281 | this. When you look up the pwd, you find it in host 1, but when you try to | ||
| 282 | look up the user, it can't find it in the current section, so it looks in the | ||
| 283 | main section for it instead. In effect all 4 sections have all variables from | ||
| 284 | main included in each section. With the local tags overriding what's in main. | ||
| 285 | A neat way to handle minor differences that would otherwise require you to | ||
| 286 | have multiple config files you'd need to keep in sync. | ||
| 287 | |||
| 288 | To load it into memory do: | ||
| 289 | |||
| 290 | my $cfg = Advanced::config->new ("section.cfg")->load_config(); | ||
| 291 | or | ||
| 292 | my $cfg = Advanced::config->new ("section.cfg", {inherit => 1})->load_config(); | ||
| 293 | |||
| 294 | =item SOURCING IN FILES WITH SECTIONS (src_sect.cfg) | ||
| 295 | |||
| 296 | By default, when sourcing in another config file it's default section is | ||
| 297 | also called "B<main>". This is true even when you are sourcing in a file | ||
| 298 | inside a named section block. That name isn't inherited by default. | ||
| 299 | |||
| 300 | And if that config file also uses sections, those section names are preserved. | ||
| 301 | |||
| 302 | But sometimes you'd like to source in a sub-file as if any tag appearing | ||
| 303 | outside a section was defined in the original file's current section. In | ||
| 304 | that case follow the file name with the appropriate label. Which by default | ||
| 305 | is B<DEFAULT>. | ||
| 306 | |||
| 307 | . simple.cfg # All variables appear in the main section. | ||
| 308 | |||
| 309 | [ section 1 ] | ||
| 310 | . simple.cfg # All variables appear in the main section as well. | ||
| 311 | |||
| 312 | [ section 2 ] | ||
| 313 | . simple.cfg # DEFAULT - all variables from this config file will appear as members of "section 2". | ||
| 314 | |||
| 315 | [ section 3 ] | ||
| 316 | . section.cfg # DEFAULT - tags abc, user & pwd are now in 'section 3', while everything else stays in it's defined section. | ||
| 317 | |||
| 318 | To load it into memory do: | ||
| 319 | |||
| 320 | my $cfg = Advanced::config->new ("src_sect.cfg")->load_config(); | ||
| 321 | |||
| 322 | =item USING STRANGE LOOKING CONFIG FILES (product-1.cfg) | ||
| 323 | |||
| 324 | Sometimes you want to look at a config file owned by another product that | ||
| 325 | doesn't follow the formatting expected by this module by default. So this | ||
| 326 | module allows you a way to provide new rules for parsing a config file to | ||
| 327 | make these differences irrelevant. | ||
| 328 | |||
| 329 | Lets assume this config file used ";", not "#" as the comment char, "::", not | ||
| 330 | "=" as it's assignment operator, and finally used "include", not "." when | ||
| 331 | sourcing in another config file. So you'd get something like the following: | ||
| 332 | |||
| 333 | ; This is a comment ... | ||
| 334 | include product-2.cfg | ||
| 335 | |||
| 336 | abc :: xyz ; Tag "abc" now equals "xyz"! | ||
| 337 | |||
| 338 | The possibilities are practically endless! You can even write your own wrapper | ||
| 339 | config file and use the "source_cb" callback option to redefine the parsing | ||
| 340 | rules for a particular config file being sourced in if the parsing rules | ||
| 341 | are different! | ||
| 342 | |||
| 343 | In fact, one of the test cases does just this! (t/30-alt_symbols_cfg.t) | ||
| 344 | |||
| 345 | To load it into memory do: | ||
| 346 | |||
| 347 | my $cfg = Advanced::config->new ("product-1.cfg", | ||
| 348 | { "assign => "::", "comment" => ";", "source" => "include" } | ||
| 349 | )->load_config(); | ||
| 350 | |||
| 351 | |||
| 352 | =item ENCRYPTING/DECRYPTING CONFIG FILES | ||
| 353 | |||
| 354 | Sometimes you need to protect sensitive information inside your config files. | ||
| 355 | Such as the user names and passwords that your application requires to run. | ||
| 356 | This module allows this at the individual tag/value pair level. Not at the | ||
| 357 | file level! | ||
| 358 | |||
| 359 | The 1st example shows tags whose values are pending the encryption process. | ||
| 360 | While the 2nd example shows what happens after it's been encrypted. You can | ||
| 361 | have config files that have both pending and encrypted tags in it. As well | ||
| 362 | as tags whose values are never encrypted. It is controlled by having the | ||
| 363 | appropriate label in the comment after the tag/value pair. | ||
| 364 | |||
| 365 | # Waiting to encrypt these values ... | ||
| 366 | my_username_1 = "anonymous" # ENCRYPT | ||
| 367 | my_password_1 = "This is too much fun!" # ENCRYPT me ... | ||
| 368 | |||
| 369 | # They've already been encrypted! | ||
| 370 | my_username_2 = '4aka54D3eZ4aea5' # DECRYPT | ||
| 371 | my_password_2 = '^M^Mn1\pmeaq>n\q?Z[x537z3A' # DECRYPT me ... | ||
| 372 | |||
| 373 | # This value will never be encrypted/decrypted ... | ||
| 374 | dummy = "Just some strange value that is always in clear text." | ||
| 375 | |||
| 376 | The encrypted value is automatically decrypted for you when the config file | ||
| 377 | is loaded into memory. So it's already in clear text when C<get_value()> is | ||
| 378 | called. See L<Advanced::Config::Options> for more details on the options | ||
| 379 | used to control the encrypt/decrypt process. See C<encrypt_config_file()> in | ||
| 380 | L<Advanced::Config> for how to encrypt the contents of the config file itself. | ||
| 381 | |||
| 382 | You can use C<decrypt_config_file()> to reverse the process if needed. | ||
| 383 | |||
| 384 | =item PLUS MUCH, MUCH, MORE ... | ||
| 385 | |||
| 386 | I could go on and on with many more examples. I'll add more in the future as | ||
| 387 | I consider more significant issues to cover. In the mean time you can find | ||
| 388 | many more examples from the build under: I<t/config/*.cfg> | ||
| 389 | |||
| 390 | =back | ||
| 391 | |||
| 392 | =head1 COPYRIGHT | ||
| 393 | |||
| 394 | Copyright (c) 2015 - 2026 Curtis Leach. All rights reserved. | ||
| 395 | |||
| 396 | This program is free software. You can redistribute it and/or modify it under | ||
| 397 | the same terms as Perl itself. | ||
| 398 | |||
| 399 | =head1 SEE ALSO | ||
| 400 | |||
| 401 | L<Advanced::Config::Options> - Covers the options that allow you to modify | ||
| 402 | how a config file gets parsed. It defines the controls allowing the various | ||
| 403 | examples shown above. | ||
| 404 | |||
| 405 | L<Advanced::Config::Date> - Handles date parsing for get_date(). | ||
| 406 | |||
| 407 | L<Advanced::Config::Reader> - Handles the parsing of the config file per the | ||
| 408 | options defined above. | ||
| 409 | |||
| 410 | L<Advanced::Config> - Defines the configuration object that you wish to | ||
| 411 | manipulate. | ||
| 412 | |||
| 413 | =cut | ||
| 414 | |||