Config/Examples.pm

filter: Statementstmt 100% 20 / 20 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod n/a totaltotal 100% 25 / 25 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« Config.pm ↑ Summary
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  
« Config.pm ↑ Summary