Config.pm

filter: Statementstmt 83.7% 1111 / 1327 Branchbran 67.7% 381 / 562 Conditioncond 47.0% 137 / 291 MC/DCmcdc 17.1% 32 / 187 Subroutinesub 97.6% 84 / 86 Podpod 98.1% 53 / 54 totaltotal 71.7% 1798 / 2507 CC 419 SCAR 33.4
CC
419
Cov
75%
print_special_vars
272.0
find_values
156.0
move_tag
85.7
CRAP 28.1
« Config/Reader.pm ↑ Summary Config/Examples.pm »
1 ###
2 ### Copyright (c) 2007 - 2026 Curtis Leach. All rights reserved.
3 ###
4 ### Module: Advanced::Config
5  
6 =head1 NAME
7  
8 Advanced::Config - Perl module reads configuration files from various sources.
9  
10 =head1 SYNOPSIS
11  
12 use Advanced::Config;
13 or
14 require Advanced::Config;
15  
16 =head1 DESCRIPTION
17  
18 F<Advanced::Config> is an enhanced implementation of a config file manager
19 that allows you to manage almost any config file as a true object with a common
20 interface. It allows you to configure for almost any look and feel inside your
21 config files.
22  
23 You will need to create one object per configuration file that you wish to
24 manipulate. And any updates you make to the object in memory will not make it
25 back into the config file itself.
26  
27 It also has options for detecting if the data in the config file has been
28 updated since you loaded it into memory and allows you to refresh the
29 configuration object. So that your long running programs never have to execute
30 against stale configuration data.
31  
32 This module supports config file features such as variable substitution,
33 sourcing in other config files, comments, breaking your configuration data
34 up into sections, encrypting/decrypting individual tag values, and even more ...
35  
36 So feel free to experiment with this module on the best way to access your
37 data in your config files. And never have to worry about having multiple
38 versions of your config files again for Production vs Development vs QA vs
39 different OS, etc.
40  
41 =head1 NOTES ON FUNCTIONS WITH MULTIPLE RETURN VALUES
42  
43 Whenever a function in this module or one if it's helper modules says it can
44 have multiple return values and you ask for them in scalar mode, it only returns
45 the first return value. The other return values are tossed. Not the count of
46 return values as some might expect.
47  
48 This is because in most cases these secondary return values only have meaning
49 in special cases. So usually there's no need to grab them unless you plan on
50 using them.
51  
52 For a list of the related helper modules see the B<SEE ALSO> section at the
53 end of this POD. These helper modules are not intended for general use.
54  
55 =cut
56  
57 # ---------------------------------------------------------------
58  
59 package Advanced::Config;
60  
61 27 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
62 27 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
63  
64 # The version of this module!
65 27 our $VERSION = "1.15";
66  
67 27 ▶use File::Basename;
Subroutine BEGIN: called CC=1 SCAR=0.0
68 27 ▶use File::Copy;
Subroutine BEGIN: called CC=1 SCAR=0.0
69 27 ▶use Sys::Hostname;
Subroutine BEGIN: called CC=1 SCAR=0.0
70 27 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
71 27 ▶use Perl::OSType ':all';
Subroutine BEGIN: called CC=1 SCAR=0.0
72 27 ▶use Cwd 'abs_path';
Subroutine BEGIN: called CC=1 SCAR=0.0
73  
74 27 ▶use Advanced::Config::Date;
Subroutine BEGIN: called CC=1 SCAR=0.0
75 27 ▶use Advanced::Config::Options;
Subroutine BEGIN: called CC=1 SCAR=0.0
76 27 ▶use Advanced::Config::Reader;
Subroutine BEGIN: called CC=1 SCAR=0.0
77 27 ▶use Fred::Fish::DBUG 2.09 qw / on_if_set ADVANCED_CONFIG_FISH /;
Subroutine BEGIN: called CC=1 SCAR=0.0
78  
79 # The name of the default section ... (even if no sections are defined!)
80 27 ▶use constant DEFAULT_SECTION => Advanced::Config::Options::DEFAULT_SECTION_NAME;
Subroutine BEGIN: called CC=1 SCAR=0.0
81  
82 # Should only be modifiable via BEGIN ...
83 27 my %begin_special_vars;
84 my $secret_tag;
85 27 my $fish_tag;
86  
87  
88 # This begin block initializes the special variables used
89 # for "rule 5" & "rule 6" in lookup_one_variable()
90 # and _find_variables()!
91 BEGIN
92 27 ▶{
Subroutine BEGIN: called CC=10 SCAR=28.3
93 27 DBUG_ENTER_FUNC ();
94  
95 # -----------------------------------------------
96 # These are the "Rule 5" special perl varibles.
97 # Done this way to avoid having to support
98 # indirect "eval" logic.
99 # -----------------------------------------------
100 27 ▶ $begin_special_vars{'0'} = ($0 eq "-e") ? "perl" : $0;
Branch: 1 branch
BranchTrueFalseTotal
$0 eq '-e' ? : 0 27 27
101 27 $begin_special_vars{'$'} = $$;
102 27 $begin_special_vars{'^O'} = $^O; # MSWin32, aix, etc ...
103  
104 # ---------------------------------------------
105 # Start of the "rule 6" initialization ...
106 # ---------------------------------------------
107 27 $begin_special_vars{PID} = $$;
108 27 $begin_special_vars{user} = Advanced::Config::Options::_get_user_id ();
109 27 $begin_special_vars{hostname} = hostname ();
110 27 $begin_special_vars{flavor} = os_type (); # Windows, Unix, etc...
111  
112 # ---------------------------------------------
113 # Get the Parent PID if available ... (PPID)
114 # ---------------------------------------------
115 27 eval {
116 27 $begin_special_vars{PPID} = getppid ();
117 };
118 27 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 27 27
119 0 DBUG_PRINT ("INFO", "Cheating to get the PPID. It may be wrong!");
120 # We can't easily get the parent process id for Windows.
121 # So we're going to cheat a bit. We'll ask if any parent
122 # or grandparent process used this module before and call it
123 # the parent process!
124 0 $secret_tag = "_ADVANCED_CONFIG_PPID_";
125  
126 0 ▶ if ( $ENV{$secret_tag} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ENV{$secret_tag}) { } 0 0 0
127 0 $begin_special_vars{PPID} = $ENV{$secret_tag};
128 } else {
129 0 $begin_special_vars{PPID} = -1; # Can't figure out the PPID.
130 }
131 0 $ENV{$secret_tag} = $$;
132 }
133  
134 # -----------------------------------------------------
135 # Calculate the separator used by the current OS
136 # when constructing a directory tree. (sep)
137 # -----------------------------------------------------
138 27 my ($a, $b) = ("one", "two");
139 27 my $p = File::Spec->catfile ($a, $b);
140 27 ▶ if ( $p =~ m/^${a}(.+)${b}$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($p =~ /^$a(.+)$b$/) { } 27 0 27
141 27 $begin_special_vars{sep} = $1; # We have it!
142 } else {
143 0 warn "Unknown separator for current OS!\n";
144 0 $begin_special_vars{sep} = ""; # Unknown value!
145 }
146  
147 # -----------------------------------------------------
148 # Calculate the program name minus any path info or
149 # certain file extensions.
150 # -----------------------------------------------------
151 27 ▶ if ( $0 eq "-e" ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($0 eq '-e') { } 0 27 27
152 0 $begin_special_vars{program} = "perl"; # Perl add hock script!
153 } else {
154 27 $begin_special_vars{program} = basename ($0);
155  
156 # Remove only certain file extensions from the program's name!
157 27 ▶ if ( $begin_special_vars{program} =~ m/^(.+)[.]([^.]*)$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($begin_special_vars{"program"} =~ /^(.+)[.]([^.]*)$/) 27 0 27
158 27 my ($f, $ext) = ($1, lc ($2));
159 27 ▶ if ( $ext eq "" || $ext eq "pl" || $ext eq "t" ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ext eq "" or $ext eq "pl" or $ext eq "t") 27 0 27
Condition33%2/6
$ext eq "" or $ext eq "pl" or $ext eq "t"
l!l&&r!l&&!r
0270
$ext eq "" or $ext eq "pl"
l!l&&r!l&&!r
0027
MC/DC0%0/3
$ext eq "" or $ext eq "pl" or $ext eq "t"
$ext eq "" $ext eq "pl" $ext eq "t"
Truth table25%1/4
A or B or C
A= $ext eq ""B= $ext eq "pl"C= $ext eq "t"
ABCresult
1XX1
01X1
0011
0000
160 27 $begin_special_vars{program} = $f;
161 }
162 }
163 }
164  
165 27 DBUG_VOID_RETURN ();
166 }
167  
168 # Called automatically when this module goes out of scope ...
169 # At times this might be called before DESTROY ...
170 END
171 27 ▶{
Subroutine END: called CC=1 SCAR=0.0
172 27 DBUG_ENTER_FUNC ();
173 27 DBUG_VOID_RETURN ();
174 }
175  
176 # Called automatically when the current instance of module goes out of scope.
177 # Only called if new() was successfull!
178 # At times this might be called after END ...
179 DESTROY
180 59 ▶{
Subroutine DESTROY: called CC=1 SCAR=0.0
181 59 DBUG_ENTER_FUNC ();
182 59 DBUG_VOID_RETURN ();
183 }
184  
185  
186 # ----------------------------------------------------------------------------
187 # Helper functions that won't appear in the POD.
188 # They will all start with "_" in their name.
189 # But they are still considered members of the object.
190 # These functions can appear throughout this file.
191 # ----------------------------------------------------------------------------
192  
193 # Using Cwd's abs_path() bombs on Windows if the file doesn't exist!
194 # So I'm doing this conversion myself.
195 # This function doesn't care if the file actually exists or not!
196 # It just converts a relative path into an absolute path!
197 sub _fix_path
198 278 ▶{
Subroutine _fix_path: called CC=7 SCAR=19.5
199 278 DBUG_ENTER_FUNC ( @_ );
200 278 my $self = shift;
201 278 ▶ my $file = shift || "";
Condition100%2/2
shift() || ''
l!l
25226
MC/DC100%1/1
shift() || ''
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
202 278 my $dir = shift; # If not provided uses current directory!
203  
204 278 ▶ if ( $file ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file) 252 26 278
205 # Convert relative paths to absolute path names.
206 # Removes internal ".", but not ".." in the path info ...
207 # It also doesn't resolve symbolic links.
208 252 ▶ unless ( File::Spec->file_name_is_absolute ( $file ) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ("File::Spec"->file_name_is_absolute($file)) 160 92 252
209 160 ▶ if ( $dir ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($dir) { } 54 106 160
210 54 $file = File::Spec->rel2abs ( File::Spec->catfile ( $dir, $file ) );
211 } else {
212 106 $file = File::Spec->rel2abs ( $file );
213 }
214 }
215  
216 # Now let's remove any relative path info (..) from the new absolute path.
217 # Still not resolving any symbolic links on purpose!
218 # I don't agree with File::Spec->canonpath()'s reasoning for not doing it
219 # that way. So I need to resolve it myself.
220 252 my @parts = File::Spec->splitdir ( $file );
221 252 foreach ( 1..$#parts ) {
222 2030 ▶ if ( $parts[$_] eq ".." ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($parts[$_] eq "..") 7 2023 2030
223 7 $parts[$_] = $parts[$_ - 1] = "";
224 }
225 }
226  
227 # It's smart enough to ignore "" in the array!
228 252 $file = File::Spec->catdir (@parts);
229 }
230  
231 278 DBUG_RETURN ( $file );
232 }
233  
234  
235 # ----------------------------------------------------------------------------
236 # Start of the exposed methods in the module ...
237 # ----------------------------------------------------------------------------
238  
239 =head1 CONSTRUCTORS
240  
241 To use this module, you must call C<B<new>()> to create the I<Advanced::Config>
242 object you wish to work with. All it does is create an empty object for you to
243 reference and returns the C<Advanced::Config> object created. Once you
244 have this object reference you are good to go! You can either load an existing
245 config file into memory or dynamically build your own virtual config file or
246 even do a mixure of both!
247  
248 =over
249  
250 =item $cfg = Advanced::Config->new( [$filename[, \%read_opts[, \%get_opts[, \%date_var_opts]]]] );
251  
252 It takes four arguments, any of which can be omitted or B<undef> during object
253 creation!
254  
255 F<$filename> is the optional name of the config file to read in. It can be a
256 relative path. The absolute path to it will be calculated for you if a relative
257 path was given.
258  
259 F<\%read_opts> is an optional hash reference that controls the default parsing
260 of the config file as it's being read into memory. Feel free to leave as
261 B<undef> if you're satisfied with this module's default behavior.
262  
263 F<\%get_opts> is an optional hash reference that defines the default behavior
264 when this module looks something up in the config file. Feel free to leave as
265 B<undef> if you're satisfied with this module's default behavior.
266  
267 F<\%date_var_opts> is an optional hash reference that defines the default
268 formatting of the special predefined date variables. Feel free to leave as
269 B<undef> if you're satisfied with the default formatting rules.
270  
271 See the POD under L<Advanced::Config::Options> for more details on what options
272 these three hash references support! Look under the S<I<The Read Options>>,
273 S<I<The Get Options>>, and S<I<The Special Date Variable Formatting Options>>
274 sections of the POD.
275  
276 It returns the I<Advanced::Config> object created.
277  
278 Here's a few examples:
279  
280 # Sets up an empty object with default options ...
281 $cfg = Advanced::Config->new();
282  
283 # Just specifies the config file to use with default options ...
284 $cfg = Advanced::Config->new("MyFile.cfg");
285  
286 # Overrides some of the default featurs of the module ...
287 $cfg = Advanced::Config->new("MyFile.cfg",
288 { "assign" => ":=", "comment" => ";" },
289 { "required" => 1, "date_language" => "German" },
290 { "month_type" => 2, "month_language" => "German" } );
291  
292 =cut
293  
294 sub new
295 91 ▶{
Subroutine new: called CC=2 SCAR=6.9
Pod documented
296 91 DBUG_ENTER_FUNC ( @_ );
297 91 my $prototype = shift;
298 91 my $filename = shift;
299 91 my $read_opts = shift; # A hash ref of "read" options ...
300 91 my $get_opts = shift; # Another hash ref of "get" options ...
301 91 my $date_opts = shift; # Another hash ref of "date" formatting options ...
302  
303 91 ▶ my $class = ref ( $prototype ) || $prototype;
Condition33%1/3
ref $prototype || $prototype
l!l&&r!l&&!r
0910
MC/DC0%0/2
ref $prototype || $prototype
ref $prototype $prototype
Truth table33%1/3
A || B
A= ref $prototypeB= $prototype
ABresult
1X1
011
000
304 91 my $self = {};
305  
306 # Create an empty object ...
307 91 bless ( $self, $class );
308  
309 # Creating a new object ... (The main section)
310 91 my %control;
311  
312 # Initialize what options were selected ...
313 91 $control{filename} = $self->_fix_path ($filename);
314 91 $control{read_opts} = get_read_opts ( $read_opts );
315 91 $control{get_opts} = get_get_opts ( $get_opts );
316 91 $control{date_opts} = get_date_opts ( $date_opts );
317  
318 91 $control{read_only} = 0; # not created via newDefineConfigRules().
319 91 $control{ConfigRuleObj} = undef; # not set by set_config_rules ().
320  
321 91 my ( %dates, %empty, %mods, %ropts, %rec, @lst );
322  
323 # Special Date Variables ...
324 91 set_special_date_vars ($control{date_opts}, \%dates);
325 91 $control{DATES} = \%dates;
326 91 $control{DATE_USED} = 0;
327  
328 # Environment variables referenced ...
329 91 $control{ENV} = \%empty;
330  
331 # Timestamps & options used for each config file loaded into memory ...
332 # Controls the refesh logic.
333 91 $control{REFRESH_MODIFY_TIME} = \%mods;
334 91 $control{REFRESH_READ_OPTIONS} = \%ropts;
335  
336 # Used to detect recursion ...
337 91 $control{RECURSION} = \%rec;
338  
339 # Used to detect recursion ...
340 91 $control{MERGE} = \@lst;
341  
342 # The count for sensitive entries ...
343 91 $control{SENSITIVE_CNT} = sensitive_cnt ();
344  
345 # Assume not allowing utf8/Unicode/Wide Char dates ...
346 # Or inside the config file itself.
347 91 $control{ALLOW_UTF8} = 0;
348  
349 # Controls the behavior of this module.
350 # Only exists in the parent object.
351 91 $self->{CONTROL} = \%control;
352  
353 91 my $key = $self->{SECTION_NAME} = DEFAULT_SECTION;
354  
355 91 my %sections;
356 91 $sections{$key} = $self;
357 91 $self->{SECTIONS} = \%sections;
358  
359 # Holds all the tag data for the main section in the config file.
360 91 my %data;
361 91 $self->{DATA} = \%data;
362  
363 # Is the data all sensitive?
364 91 $self->{SENSITIVE_SECTION} = 0; # No for the default section ...
365  
366 91 DBUG_RETURN ( $self );
367 }
368  
369 # Only called by Advanced::Config::Reader::read_config() ...
370 # So not exposed in the POD!
371 # Didn't rely on read option 'use_utf8' since in many cases
372 # the option is misleading or just plain wrong!
373 sub _allow_utf8
374 3 ▶{
Subroutine _allow_utf8: called CC=2 SCAR=7.2
375 3 DBUG_ENTER_FUNC ( @_ );
376 3 my $self = shift;
377  
378 # Tells calls to Advanced::Config::Options::apply_get_rules() that
379 # it's ok to use Wide Char Languages like Greek.
380 3 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
030
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
381 3 $pcfg->{CONTROL}->{ALLOW_UTF8} = 1;
382  
383 3 DBUG_VOID_RETURN ();
384 }
385  
386 # This private method preps for a clean refresh of the objects contents.
387 # Kept after the consructor so I can remember to add any new hashes to
388 # the list below.
389 sub _wipe_internal_data
390 100 ▶{
Subroutine _wipe_internal_data: called CC=2 SCAR=6.9
391 100 DBUG_ENTER_FUNC ( @_ );
392 100 my $self = shift;
393 100 my $file = shift; # The main config file
394  
395 # Wiping the main section automatically wipes everything else ...
396 100 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
01000
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
397  
398 100 my ( %env, %mods, %rOpts, %rec, @lst, %sect, %data );
399  
400 100 my $key = DEFAULT_SECTION;
401 100 $sect{$key} = $self;
402  
403 100 $self->{CONTROL}->{filename} = $file;
404 100 $self->{CONTROL}->{ENV} = \%env;
405 100 $self->{CONTROL}->{REFRESH_MODIFY_TIME} = \%mods;
406 100 $self->{CONTROL}->{REFRESH_READ_OPTIONS} = \%rOpts;
407 100 $self->{CONTROL}->{RECURSION} = \%rec;
408 100 $self->{CONTROL}->{MERGE} = \@lst;
409 100 $self->{CONTROL}->{SENSITIVE_CNT} = sensitive_cnt ();
410 100 $self->{CONTROL}->{ALLOW_UTF8} = 0;
411  
412 100 $self->{SECTIONS} = \%sect;
413 100 $self->{DATA} = \%data;
414  
415 100 $self->{SENSITIVE_SECTION} = 0; # Not a sensitive section name!
416  
417 100 DBUG_VOID_RETURN ();
418 }
419  
420  
421 #######################################
422  
423 =item $ruleCfg = Advanced::Config->newDefineConfigRules ( $filename );
424  
425 This special case constructor creates a new B<Advanced::Config> object, loads
426 it into memory and validates the resulting config file meets the requirements
427 for using this method and calls B<die> on any unexpected issues.
428  
429 The resulting I<$ruleCfg> object is used to replace the 3 B<opts> hashes in the
430 call to I<new()>, so that all your programs don't have to be modified whenever a
431 vendor modifies how to parse their config files. You just need to modify this
432 configutation file and all your programs using it are updated all at once.
433  
434 Example:
435  
436 my $ruleCfg = Advanced::Config->newDefineConfigRules ( "VendorRules.cfg" );
437 my $cfg = Advanced::Config->new ( "vendor.cfg" )->
438 set_config_rules ($ruleCfg)->load_config ();
439  
440 The B<VendorRules.cfg> assumes that any options not defined in this config file
441 defaults to the module's settings in L<Advanced::Config::Options>. So you only
442 need to enter your overrides. Meaning an empty config file just uses the
443 default rules. Any tag that doesn't match one of the option hash values is a
444 fatal error.
445  
446 See I<set_config_rules()> for more information for what to expect inside this
447 rule config file and how it's used.
448  
449 =cut
450  
451 sub newDefineConfigRules
452 3 ▶{
Subroutine newDefineConfigRules: called CC=27 SCAR=33.1
Pod documented
453 3 DBUG_ENTER_FUNC ( @_ );
454 3 my $prototype = shift;
455 3 my $filename = shift;
456 3 ▶ my $refresh = shift || 0; # undocumented arg requsting refresh not new obj
Condition100%2/2
shift() || 0
l!l
12
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
457  
458 3 my $cfg;
459 3 ▶ unless ( $refresh ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($refresh) { } 1 2 3
460 2 $cfg = Advanced::Config->new ( $filename,
461 { croak => 1, disable_variables => 1, tag_case => 1, source => 'x'x40 },
462 { inherit => 1, required => 1 }
463 );
464  
465 # Mark as created by this special constructor.
466 2 $cfg->{CONTROL}->{read_only} = 1;
467  
468 } else {
469 # Requesting the reload of an existing rule cfg object
470 1 ▶ $cfg = $prototype->{PARENT} || $prototype;
Condition33%1/3
$prototype->{'PARENT'} || $prototype
l!l&&r!l&&!r
010
MC/DC0%0/2
$prototype->{'PARENT'} || $prototype
$prototype->{'PARENT'} $prototype
Truth table33%1/3
A || B
A= $prototype->{'PARENT'}B= $prototype
ABresult
1X1
011
000
471 1 ▶ unless ($cfg->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($cfg->_chk_if_read_only) 0 1 1
472 0 die "This isn't a rule config object!\n";
473 }
474 1 $cfg->_wipe_internal_data ( $filename );
475 }
476  
477 # Temp disable read-only setting so the data can be loaded!
478 3 local $cfg->{CONTROL}->{read_only} = 0;
479
480  
481 # Load all the default Read, Get & Special date options.
482 3 my $rOpts = get_read_opts ();
483 3 my $gOpts = get_get_opts ();
484 3 my $sOpts = get_date_opts ();
485  
486 # My special lists for what is possible per option hash.
487 3 my %extra = ( ___list_read___ => 1, ___list_get___ => 1,
488 ___list_spec___ => 1 );
489  
490 3 my @read_list = keys %{$rOpts};
491 3 my @get_list = keys %{$gOpts};
492 3 my @spec_list = keys %{$sOpts};
493  
494 3 foreach my $k (@read_list, @get_list, @spec_list, keys %extra) {
495 my $cnt = (exists $rOpts->{$k} ? 1 : 0) +
496 (exists $gOpts->{$k} ? 1 : 0) +
497 (exists $sOpts->{$k} ? 1 : 0) +
498 171 ▶ (exists $extra{$k} ? 1 : 0);
Branch: 4 branches
BranchTrueFalseTotal
exists $rOpts->{$k} ? : 99 72 171
exists $gOpts->{$k} ? : 48 123 171
exists $sOpts->{$k} ? : 15 156 171
exists $extra{$k} ? : 9 162 171
499 171 ▶ $cnt = 5 if ($k eq "__order__"); # always bad.
Branch: 1 branch
BranchTrueFalseTotal
if $k eq "__order__" 0 171 171
500  
501 171 ▶ if ($cnt != 1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cnt != 1) 0 171 171
502 0 die ("Option '$k' may not be shared between the 3 option hashes!\n");
503 }
504 }
505  
506 # Add all the default values to the default section so they can be overriden
507 3 $cfg->_base_set ("___list_read___", \@read_list);
508 3 $cfg->_base_set ("___list_get___", \@get_list);
509 3 $cfg->_base_set ("___list_spec___", \@spec_list);
510  
511 3 $cfg->_base_set ("__order__", 9999999999999999);
512  
513 3 foreach my $r ( @read_list ) { $cfg->_base_set ( $r, $rOpts->{$r} ); }
514 3 foreach my $g ( @get_list ) { $cfg->_base_set ( $g, $gOpts->{$g} ); }
515 3 foreach my $p ( @spec_list ) { $cfg->_base_set ( $p, $sOpts->{$p} ); }
516  
517 # Load what's in the config file.
518 3 my $bool = $cfg->merge_config ();
519  
520 # Validate that it built ok.
521 3 foreach my $s ( $cfg->find_sections () ) {
522 15 my $sect = $cfg->get_section ($s, 1);
523 15 my $name = $sect->section_name ();
524 15 my @tags = $sect->find_tags ( undef, 0 ); # Search current section only.
525 15 foreach my $t ( @tags ) {
526 my $cnt = (exists $rOpts->{$t} ? 1 : 0) +
527 (exists $gOpts->{$t} ? 1 : 0) +
528 147 ▶ (exists $sOpts->{$t} ? 1 : 0);
Branch: 3 branches
BranchTrueFalseTotal
exists $rOpts->{$t} ? : 88 59 147
exists $gOpts->{$t} ? : 32 115 147
exists $sOpts->{$t} ? : 10 137 147
529 147 ▶ $cnt = 1 if ( $cnt == 0 && $name eq DEFAULT_SECTION && $extra{$t} );
Branch: 1 branch
BranchTrueFalseTotal
if $cnt == 0 and $name eq "main" and $extra{$t} 6 141 147
Condition100%6/6
$cnt == 0 and $name eq "main" and $extra{$t}
!ll&&!rl&&r
13926
$cnt == 0 and $name eq "main"
!ll&&!rl&&r
13098
MC/DC100%3/3
$cnt == 0 and $name eq "main" and $extra{$t}
$cnt == 0 $name eq "main" $extra{$t}
Truth table100%4/4
A and B and C
A= $cnt == 0B= $name eq "main"C= $extra{$t}
ABCresult
0XX0
10X0
1100
1111
530 147 ▶ $cnt = 1 if ( $cnt == 0 && $name ne "*" && $t eq "__order__" );
Branch: 1 branch
BranchTrueFalseTotal
if $cnt == 0 and $name ne "*" and $t eq "__order__" 10 137 147
Condition83%5/6
$cnt == 0 and $name ne "*" and $t eq "__order__"
!ll&&!rl&&r
136110
$cnt == 0 and $name ne "*"
!ll&&!rl&&r
136011
MC/DC66%2/3
$cnt == 0 and $name ne "*" and $t eq "__order__"
$cnt == 0 $name ne "*" $t eq "__order__"
Truth table75%3/4
A and B and C
A= $cnt == 0B= $name ne "*"C= $t eq "__order__"
ABCresult
0XX0
10X0
1100
1111
531 147 ▶ if ( $cnt == 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cnt == 0) 1 146 147
532 1 die "Tag '$t' is not a valid option hash value in section $name!\n";
533 }
534 }
535 }
536  
537 2 DBUG_RETURN ( $cfg );
538 }
539  
540 #######################################
541 # Returns the rule object linked via set_config_rules ().
542  
543 sub _get_rule_object
544 54 ▶{
Subroutine _get_rule_object: called CC=2 SCAR=7.0
545 54 my $self = shift;
546  
547 54 ▶ $self = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
14400
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
548
549 54 return ( $self->{CONTROL}->{ConfigRuleObj} );
550 }
551  
552 #######################################
553 # Checks if the object was created by newDefineConfigRules ().
554  
555 sub _chk_if_read_only
556 705 ▶{
Subroutine _chk_if_read_only: called CC=2 SCAR=7.0
557 705 my $self = shift;
558  
559 705 ▶ $self = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
136920
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
560
561 705 return ( $self->{CONTROL}->{read_only} );
562 }
563  
564 #######################################
565  
566 # =item $cfg = Advanced::Config->new_section ( $cfg_obj, $section );
567  
568 # This special case constructor creates a new B<Advanced::Config> object and
569 # relates it to the given I<$cfg_obj> as a new section named I<$section>.
570  
571 # It will call die if I<$cfg_obj> is not a valid B<Advanced::Config> object or
572 # the I<$section> is missing or already in use.
573  
574 # Returns a reference to this new object.
575  
576 # =cut
577  
578 # Stopped exposing to public on 12/30/2019 ... but still used internally.
579 # In most cases 'create_section' should be called instead!
580 sub new_section
581 352 ▶{
Subroutine new_section: called CC=7 SCAR=20.9
Pod undocumented
582 352 DBUG_ENTER_FUNC ( @_ );
583 352 my $prototype = shift;
584 352 my $parent = shift;
585 352 my $section = shift;
586  
587 352 ▶ my $class = ref ( $prototype ) || $prototype;
Condition33%1/3
ref $prototype || $prototype
l!l&&r!l&&!r
35200
MC/DC0%0/2
ref $prototype || $prototype
ref $prototype $prototype
Truth table33%1/3
A || B
A= ref $prototypeB= $prototype
ABresult
1X1
011
000
588 352 my $self = {};
589  
590 # Create an empty object ...
591 352 bless ( $self, $class );
592  
593 352 ▶ if ( ref ( $parent ) ne __PACKAGE__ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $parent ne __PACKAGE__) 0 352 352
594 0 die ("You must provide an ", __PACKAGE__, " object as an argument!\n");
595 }
596  
597 # Make sure it's really the parent object ...
598 352 ▶ $parent = $parent->{PARENT} || $parent;
Condition33%1/3
$parent->{'PARENT'} || $parent
l!l&&r!l&&!r
03520
MC/DC0%0/2
$parent->{'PARENT'} || $parent
$parent->{'PARENT'} $parent
Truth table33%1/3
A || B
A= $parent->{'PARENT'}B= $parent
ABresult
1X1
011
000
599  
600 # Trim so we can check if unique ...
601 352 ▶ if ( $section ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($section) 352 0 352
602 352 $section =~ s/^\s+//; $section =~ s/\s+$//;
603 352 $section = lc ($section);
604 }
605  
606 352 ▶ unless ( $section ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($section) 0 352 352
607 0 die ("You must provide a section name to use this constructor.\n");
608 }
609  
610 # Creating a new section for the parent object ...
611 352 ▶ if ( exists $parent->{SECTIONS}->{$section} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $parent->{"SECTIONS"}{$section}) 0 352 352
612 0 die ("Section \"${section}\" already exists!\n");
613 }
614  
615 # Links the parent & child objects together ...
616 352 $parent->{SECTIONS}->{$section} = $self;
617 352 $self->{SECTION_NAME} = $section;
618 352 $self->{PARENT} = $parent;
619  
620 # Holds all the tag data for this section in the config file.
621 352 my %data;
622 352 $self->{DATA} = \%data;
623  
624 # Does this section have a sinsitive name?
625 # If so, all tags in this section are sensitive!
626 352 $self->{SENSITIVE_SECTION} = should_we_hide_sensitive_data ($section, 1);
627  
628 352 DBUG_RETURN ( $self );
629 }
630  
631 #######################################
632  
633 =back
634  
635 =head1 THE OPTIONAL CONSTRUCTOR MODIFIERS
636  
637 The next 2 methods provide optional ways to provide confuguration info to the
638 objects created via a call to I<new()>. They completely override the 3 opts
639 hash arguments.
640  
641 These methods should only rarely be needed.
642  
643 =over 4
644  
645 =item $cfg = $cfg->copy_opts_from_cfg ( $otherCfg )
646  
647 When 2 or more config files share the exact same configuration settings you
648 only need to provide the option hashes to the 1st config file created via
649 I<new()>.
650  
651 my $cfg = Advanced::Config->new ()->
652 copy_opts_from_cfg ( $otherCfg );
653  
654 This call creates a new config object and configures it to use the same options
655 used to set up the B<$otherCfg> object. Tossing any options provided by this
656 call to I<new()>. If B<$otherCfg> used a rule file it is only used when
657 sourcing in other config files.
658  
659 =cut
660  
661 sub copy_opts_from_cfg
662 1 ▶{
Subroutine copy_opts_from_cfg: called CC=7 SCAR=20.3
Pod documented
663 1 DBUG_ENTER_FUNC ( @_ );
664 1 my $self = shift;
665 1 my $otherCfg = shift;
666  
667 1 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
010
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
668 1 ▶ $otherCfg = $otherCfg->{PARENT} || $otherCfg;
Condition33%1/3
$otherCfg->{'PARENT'} || $otherCfg
l!l&&r!l&&!r
010
MC/DC0%0/2
$otherCfg->{'PARENT'} || $otherCfg
$otherCfg->{'PARENT'} $otherCfg
Truth table33%1/3
A || B
A= $otherCfg->{'PARENT'}B= $otherCfg
ABresult
1X1
011
000
669  
670 1 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 0 1 1
671 0 die "You may not override rules for object created by newDefineConfigRules ()\n";
672 }
673  
674 1 foreach (keys %{$otherCfg->{CONTROL}->{read_opts}} ) {
675 $self->{CONTROL}->{read_opts}->{$_} =
676 33 $otherCfg->{CONTROL}->{read_opts}->{$_};
677 }
678  
679 1 foreach (keys %{$otherCfg->{CONTROL}->{get_opts}} ) {
680 $self->{CONTROL}->{get_opts}->{$_} =
681 16 $otherCfg->{CONTROL}->{get_opts}->{$_};
682 }
683  
684 1 foreach (keys %{$otherCfg->{CONTROL}->{date_opts}} ) {
685 $self->{CONTROL}->{date_opts}->{$_} =
686 5 $otherCfg->{CONTROL}->{date_opts}->{$_};
687 }
688  
689 # Copy the optional rule config file for sourcing in other config files.
690 1 $self->{CONTROL}->{ConfigRuleObj} = $otherCfg->{CONTROL}->{ConfigRuleObj};
691  
692 1 DBUG_RETURN ( $self );
693 }
694  
695 #######################################
696  
697 =item $cfg = $cfg->set_config_rules ( $ruleCfg )
698  
699 With this method instead of defining the options used in your perl code, you
700 decided to set up the rules to follow inside another config file which you
701 loaded into memory via a call to I<newDefineConfigRules()> via B<$ruleCfg>.
702 In this case the filename option in the call to I<new()> is required.
703  
704 This method overrides any B<opts> settings to I<new()> and any callback read
705 options used when sourcing in other config files.
706  
707 This method becomes usefull when the passed config file sources in other
708 config files requiring different options to load properly.
709  
710 my $cfg = Advanced::Config->new ( "config/myData.cfg" )->
711 set_config_rules ($ruleCfg);
712  
713 For example, let's say that B<$ruleCfg> was set up with 4 sections, myData.cfg,
714 *.cfg, tom*.cfg and *. And myData.cfg sources in the following 3 files.
715 bob.cfg, sue.config, and tomfile.cfg.
716  
717 During the call to I<set_config_rules()> it finds the basename of the passed
718 filename, myData.cfg, and finds the section named after it and takes the rules
719 defined in that section and applies it to the congig object. Had this section
720 not existed, it would have followed the wildcard rules below.
721  
722 Later on when sourcing in bob.cfg it doesn't find a section called bob.cfg, so
723 it attempts to lookup the section to use via wildcards and finds section
724 B<*.cfg>
725  
726 Next when sourcing in sue.config there is no section called that and it doesn't
727 match wildcard sections B<*.cfg> or B<tom*.cfg>, so it uses the default section
728 B<*> to gather the rules from.
729  
730 Finally for tomfile.cfg it matches both B<*.cfg> and B<tom*.cfg> which is a
731 fatal error. To get arround this error you must define a special tag called
732 B<__order__> and assign it an integer value. The one with the smallest value
733 is the name that will match. So set to 100 for B<tom*.cfg> and 654321 for
734 B<*.cfg> and it will match B<tom*.cfg>. It will never match B<*> since it has
735 an assumed B<__order__> of infinity.
736  
737 =cut
738  
739 sub set_config_rules
740 1 ▶{
Subroutine set_config_rules: called CC=5 SCAR=18.0
Pod documented
741 1 DBUG_ENTER_FUNC ( @_ );
742 1 my $self = shift;
743 1 my $ruleCfg = shift;
744  
745 1 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
010
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
746 1 ▶ $ruleCfg = $ruleCfg->{PARENT} || $ruleCfg;
Condition33%1/3
$ruleCfg->{'PARENT'} || $ruleCfg
l!l&&r!l&&!r
010
MC/DC0%0/2
$ruleCfg->{'PARENT'} || $ruleCfg
$ruleCfg->{'PARENT'} $ruleCfg
Truth table33%1/3
A || B
A= $ruleCfg->{'PARENT'}B= $ruleCfg
ABresult
1X1
011
000
747  
748 1 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 0 1 1
749 0 die "You may not override rules for object created by newDefineConfigRules ()\n";
750 }
751  
752 1 ▶ unless ( $ruleCfg->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ruleCfg->_chk_if_read_only) 0 1 1
753 0 die "The ruleCfg argument must be created via newDefineConfigRules ()\n";
754 }
755  
756 1 my $rule = $ruleCfg->_get_rule_section ( $self->filename () );
757  
758 ( $self->{CONTROL}->{read_opts},
759 $self->{CONTROL}->{get_opts},
760 1 $self->{CONTROL}->{date_opts} ) = $rule->_get_rules_from_cfg ();
761  
762 1 $self->{CONTROL}->{ConfigRuleObj} = $ruleCfg;
763  
764 1 DBUG_RETURN ( $self );
765 }
766  
767 #######################################
768 # Get all rules from the config file & validate them.
769  
770 sub _get_rules_from_cfg
771 9 ▶{
Subroutine _get_rules_from_cfg: called CC=5 SCAR=16.1
772 9 DBUG_ENTER_FUNC ( @_ );
773 9 my $ruleCfg = shift;
774  
775 9 ▶ unless ( $ruleCfg->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ruleCfg->_chk_if_read_only) 0 9 9
776 0 die "This object must be created by newDefineConfigRules ()\n";
777 }
778  
779 9 DBUG_PRINT ("DBUG", "Rule Sectoon: %s", $ruleCfg->section_name () );
780  
781 9 my ($read_opts, $get_opts, $date_opts);
782 9 my (%read, %get, %date);
783  
784 9 foreach ( @{$ruleCfg->get_value ( "___list_read___" )} ) {
785 297 $read{$_} = ( $ruleCfg->_base_get2 ($_) )[0];
786 }
787 9 $read_opts = get_read_opts ( \%read );
788  
789 9 foreach ( @{$ruleCfg->get_value ( "___list_get___" )} ) {
790 144 $get{$_} = ( $ruleCfg->_base_get2 ($_) )[0];
791 }
792 9 $get_opts = get_get_opts ( \%get );
793  
794 9 foreach ( @{$ruleCfg->get_value ( "___list_spec___" )} ) {
795 45 $date{$_} = ( $ruleCfg->_base_get2 ($_) )[0];
796 }
797 9 $date_opts = get_date_opts ( \%date );
798  
799 9 DBUG_RETURN ( $read_opts, $get_opts, $date_opts );
800 }
801  
802 #######################################
803  
804 sub _get_rule_section
805 24 ▶{
Subroutine _get_rule_section: called CC=14 SCAR=26.6
806 24 DBUG_ENTER_FUNC ( @_ );
807 24 my $ruleCfg = shift;
808 24 my $name = shift;
809  
810 24 ▶ if ((! defined $name) || $name =~ m/^\s+$/) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $name or $name =~ /^\s+$/) 0 24 24
Condition33%1/3
not defined $name or $name =~ /^\s+$/
l!l&&r!l&&!r
0024
MC/DC0%0/2
not defined $name or $name =~ /^\s+$/
not defined $name $name =~ /^\s+$/
Truth table33%1/3
not(A) or B
A= not defined $nameB= $name =~ /^\s+$/
ABresult
1X1
011
000
811 0 die ("Missing filename argument!\n");
812 }
813 24 ▶ unless ( $ruleCfg->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ruleCfg->_chk_if_read_only) 0 24 24
814 0 die "This object must be created by newDefineConfigRules ()\n";
815 }
816  
817 24 my $bName = basename ($name);
818 24 my $cfg = $ruleCfg->get_section ($bName, 0);
819  
820 24 ▶ if (defined $cfg) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $cfg) 2 22 24
821 2 return DBUG_RETURN ($cfg);
822 }
823  
824 22 my @wild_names = $ruleCfg->find_sections ( "\\*" );
825 22 my @match_names;
826 my $default_name;
827 22 foreach my $s (@wild_names) {
828 88 ▶ if ( $s eq "*" ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($s eq '*') { } 22 66 88
829 22 $default_name = "*";
830 } else {
831 66 my $n = $s;
832 66 $n =~ s/\./\\./g;
833 66 $n =~ s/\*/.*/g;
834 66 ▶ if ( $bName =~ m/^${n}$/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($bName =~ /^$n$/i) 31 35 66
835 31 DBUG_PRINT ("MATCH", "Found a wildcad match with %s for %s",
836 $s, $bName);
837 31 push (@match_names, $s);
838 }
839 }
840 }
841  
842 22 my $cnt = @match_names;
843 22 ▶ if ( $cnt >= 2 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($cnt >= 2) { } 11 11 22
elsif ($cnt == 1) { } 7 4 11
844 11 $cfg = $ruleCfg->get_section ($match_names[0], 1);
845 11 my $order = $cfg->get_integer ( "__order__", 1);
846 11 my $total = 1;
847 11 for (1..$#match_names) {
848 13 my $c = $ruleCfg->get_section ($match_names[$_], 1);
849 13 my $o = $c->get_integer ( "__order__", 1);
850 13 ▶ if ( $o < $order ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($o < $order) { } 11 2 13
elsif ($o == $order) { } 2 0 2
851 11 $total = 1;
852 11 $cfg = $c;
853 11 $order = $o;
854 } elsif ( $o == $order ) {
855 2 ++$total;
856 }
857 }
858 11 ▶ if ( $total != 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($total != 1) 2 9 11
859 2 die "File '$bName' matches $total wildcard sections with the same __order__ setting of $order.\n";
860 }
861  
862 } elsif ( $cnt == 1 ) {
863 7 $cfg = $ruleCfg->get_section ($match_names[0], 1);
864 } else {
865 4 $cfg = $ruleCfg->get_section ($default_name, 1);
866 }
867  
868 20 DBUG_RETURN ( $cfg );
869 }
870  
871 #######################################
872  
873 =back
874  
875 =head1 THE METHODS
876  
877 Once you have your B<Advanced::Config> object initialized, you can manipulate
878 your object in many ways. You can access individual components of your config
879 file, modify its contents, refresh its contents and even organize it in
880 different ways.
881  
882 Here are your exposed methods to help with this manipulation.
883  
884 =head2 Loading the Config file into memory.
885  
886 These methods are used to initialize the contents of an B<Advanced::Config>
887 object.
888  
889 =over 4
890  
891 =item $cfg = $cfg->load_config ( [$filename[, %override_read_opts]] );
892  
893 This method reads the current I<$filename> into memory and converts it into an
894 object so that you may reference its contents. The I<$filename> must be defined
895 either here or in the call to B<new()>.
896  
897 Each time you call this method, it wipes the contents of the object and starts
898 you from a clean slate again. Making it safe to call multiple times if needed.
899  
900 The I<%override_read_opts> options apply just to the current call to
901 I<load_config> and will be forgotten afterwards. If you want these options
902 to persist between calls, set the option via the call to B<new()>. This
903 argument can be passed either by value or by reference. Either way will work.
904 See L<Advanced::Config::Options> for more details.
905  
906 On success, it returns a reference to itself so that it can be initialized
907 separately or as a single unit.
908  
909 Ex: $cfg = Advanced::Config->new(...)->load_config (...);
910  
911 On failure it returns I<undef> or calls B<die> if option I<croak> is set!
912  
913 WARNING: If basename(I<$filename>) is a symbolic link and your config file
914 contains encrypted data, please review the encryption options about special
915 considerations.
916  
917 =cut
918  
919 sub load_config
920 188 ▶{
Subroutine load_config: called CC=19 SCAR=31.9
Pod documented
921 188 DBUG_ENTER_FUNC ( @_ );
922 188 my $self = shift;
923 188 my $filename = shift;
924 188 my $read_opts = $_[0]; # Don't pop from the stack yet ...
925  
926 188 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
01880
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
927  
928 188 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 2 186 188
929 2 die "You may not override rules for object created by newDefineConfigRules ()\n";
930 }
931  
932 # Get the filename to read ...
933 186 ▶ if ( $filename ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($filename) { } 115 71 186
934 115 $filename = $self->_fix_path ($filename);
935 } else {
936 71 $filename = $self->{CONTROL}->{filename};
937 }
938  
939 # Get the read options ...
940 186 my $new_opts;
941 186 ▶ if ( ! defined $read_opts ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $read_opts) { } 97 89 186
942 97 my %none;
943 97 $new_opts = \%none;
944 } else {
945 89 ▶ $read_opts = {@_} if ( ref ($read_opts) ne "HASH" );
Branch: 1 branch
BranchTrueFalseTotal
if ref $read_opts ne "HASH" 0 89 89
946 89 $new_opts = $read_opts;
947 }
948 186 $read_opts = get_read_opts ( $read_opts, $self->{CONTROL}->{read_opts} );
949  
950 186 ▶ unless ( $filename ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($filename) 5 181 186
951 5 my $msg = "You must provide a file name to load!";
952 5 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
953 }
954  
955 181 ▶ unless ( -f $filename ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $filename) 0 181 181
956 0 my $msg = "No such file or it's unreadable! -- $filename";
957 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
958 }
959  
960 181 DBUG_PRINT ("READ", "Reading a config file into memory ... %s", $filename);
961  
962 181 ▶ unless ( -f $filename && -r _ ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $filename and -r _) 0 181 181
Condition33%1/3
-f $filename and -r _
!ll&&!rl&&r
00181
MC/DC0%0/2
-f $filename and -r _
-f $filename -r _
Truth table33%1/3
A and B
A= -f $filenameB= -r _
ABresult
0X0
100
111
963 0 my $msg = "Your config file name doesn't exist or isn't readable.";
964 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
965 }
966  
967 # Behaves diferently based on who calls us ...
968 181 ▶ my $c = (caller(1))[3] || "";
Condition50%1/2
(caller 1)[3] || ''
l!l
1810
MC/DC0%0/1
(caller 1)[3] || ''
(caller 1)[3]
Truth table50%1/2
A
A= (caller 1)[3]
Aresult
11
00
969 181 my $by = __PACKAGE__ . "::merge_config";
970 181 my $by2 = __PACKAGE__ . "::_load_config_with_new_date_opts";
971 181 ▶ if ( $c eq $by ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($c eq $by) { } 44 137 181
elsif ($c eq $by2) { } 52 85 137
972 # Manually merging in another config file.
973 44 push (@{$self->{CONTROL}->{MERGE}}, $filename);
974 } elsif ( $c eq $by2 ) {
975 # Sourcing in a file says to remove these old decryption opts.
976 52 ▶ delete $read_opts->{alias} unless ( $new_opts->{alias} );
Branch: 1 branch
BranchTrueFalseTotal
unless $new_opts->{"alias"} 50 2 52
977 52 ▶ delete $read_opts->{pass_phrase} unless ( $new_opts->{pass_phrase} );
Branch: 1 branch
BranchTrueFalseTotal
unless $new_opts->{"pass_phrase"} 52 0 52
978 52 ▶ delete $read_opts->{encrypt_by_user} unless ( $new_opts->{encrypt_by_user} );
Branch: 1 branch
BranchTrueFalseTotal
unless $new_opts->{"encrypt_by_user"} 52 0 52
979 } else {
980 # Loading the original file ...
981 85 $self->_wipe_internal_data ( $filename );
982 }
983  
984 # Auto add the alias if it's a symbolic link & there isn't an alias.
985 # Otherwise decryption won't work!
986 181 ▶ if ( -l $filename && ! $read_opts->{alias} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (-l $filename and not $read_opts->{"alias"}) 0 181 181
Condition33%1/3
-l $filename and not $read_opts->{"alias"}
!ll&&!rl&&r
18100
MC/DC0%0/2
-l $filename and not $read_opts->{"alias"}
-l $filename not $read_opts->{"alias"}
Truth table33%1/3
A and not(B)
A= -l $filenameB= not $read_opts->{"alias"}
ABresult
0X0
100
111
987 0 $read_opts->{alias} = abs_path( $filename );
988 }
989  
990 # So refresh logic will work ...
991 181 $self->{CONTROL}->{REFRESH_MODIFY_TIME}->{$filename} = (stat( $filename ))[9];
992 181 $self->{CONTROL}->{REFRESH_READ_OPTIONS}->{$filename} = get_read_opts ($read_opts);
993  
994 # So will auto-clear if die is called!
995 181 local $self->{CONTROL}->{RECURSION}->{$filename} = 1;
996  
997 # Temp override of the default read options ...
998 181 local $self->{CONTROL}->{read_opts} = $read_opts;
999  
1000 181 ▶ unless ( read_config ( $filename, $self ) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (read_config($filename, $self)) 0 181 181
1001 0 my $msg = "Reading the config file had serious issues!";
1002 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
1003 }
1004  
1005 181 DBUG_RETURN ( $self );
1006 }
1007  
1008 #######################################
1009  
1010 =item $cfg = $cfg->load_string ( $string[, %override_read_opts] );
1011  
1012 This method takes the passed I<$string> and treats it's value as the contents of
1013 a config file. Modifying the I<$string> afterwards will not affect things. You
1014 can use this as an alternative to F<load_config>.
1015  
1016 Each time you call this method, it wipes the contents of the object and starts
1017 you from a clean slate again. Making it safe to call multiple times if needed.
1018  
1019 The I<%override_read_opts> options apply just to the current call to
1020 I<load_string> and will be forgotten afterwards. If you want these options
1021 to persist between calls, set the option via the call to B<new()>. This
1022 argument can be passed either by value or by reference. Either way will work.
1023 See L<Advanced::Config::Options> for more details.
1024  
1025 If you plan on decrypting any values in the string, you must use the B<alias>
1026 option in order for them to be successfully decrypted.
1027  
1028 On success, it returns a reference to itself so that it can be initialized
1029 separately or as a single unit.
1030  
1031 =cut
1032  
1033 sub load_string
1034 20 ▶{
Subroutine load_string: called CC=10 SCAR=23.9
Pod documented
1035 20 DBUG_ENTER_FUNC ( @_ );
1036 20 my $self = shift;
1037 20 my $string = shift; # The string to treat as a config file's contents.
1038 20 my $read_opts = $_[0]; # Don't pop from the stack yet ...
1039  
1040 20 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
0200
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
1041  
1042 20 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 2 18 20
1043 2 die "You may not override rules for object created by newDefineConfigRules ()\n";
1044 }
1045  
1046 # Get the read options ...
1047 18 ▶ $read_opts = {@_} if ( ref ($read_opts) ne "HASH" );
Branch: 1 branch
BranchTrueFalseTotal
if ref $read_opts ne "HASH" 2 16 18
1048 18 $read_opts = get_read_opts ( $read_opts, $self->{CONTROL}->{read_opts} );
1049  
1050 18 ▶ unless ( $string ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($string) 0 18 18
1051 0 my $msg = "You must provide a string to use this method!";
1052 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
1053 }
1054  
1055 # The filename is a reference to the string passed to this method!
1056 18 my $filename = \$string;
1057  
1058 # If there's no alias provided, use a default value for it ...
1059 # There is no filename to use for decryption purposes without it.
1060 18 ▶ $read_opts->{alias} = "STRING" unless ( $read_opts->{alias} );
Branch: 1 branch
BranchTrueFalseTotal
unless $read_opts->{"alias"} 12 6 18
1061  
1062 # Dynamically correct based on type of string ...
1063 18 ▶ $read_opts->{use_utf8} = ( $string =~ m/[^\x00-\xff]/ ) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$string =~ /[^\x00-\xff]/ ? : 0 18 18
1064  
1065 # Behaves diferently based on who calls us ...
1066 18 ▶ my $c = (caller(1))[3] || "";
Condition50%1/2
(caller 1)[3] || ''
l!l
180
MC/DC0%0/1
(caller 1)[3] || ''
(caller 1)[3]
Truth table50%1/2
A
A= (caller 1)[3]
Aresult
11
00
1067 18 my $by = __PACKAGE__ . "::merge_string";
1068 18 ▶ if ( $c eq $by ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($c eq $by) { } 4 14 18
1069 # Manually merging in another string as a config file.
1070 4 push (@{$self->{CONTROL}->{MERGE}}, $filename);
1071 } else {
1072 # Loading the original string ...
1073 14 $self->_wipe_internal_data ( $filename );
1074 }
1075  
1076 # So refresh logic will work ...
1077 18 $self->{CONTROL}->{REFRESH_MODIFY_TIME}->{$filename} = 0; # No timestamp!
1078 18 $self->{CONTROL}->{REFRESH_READ_OPTIONS}->{$filename} = get_read_opts ($read_opts);
1079  
1080 # So will auto-clear if die is called!
1081 18 local $self->{CONTROL}->{RECURSION}->{$filename} = 1;
1082  
1083 # Temp override of the default read options ...
1084 18 local $self->{CONTROL}->{read_opts} = $read_opts;
1085  
1086 18 ▶ unless ( read_config ( $filename, $self ) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (read_config($filename, $self)) 0 18 18
1087 0 my $msg = "Reading the config file had serious issues!";
1088 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
1089 }
1090  
1091 18 DBUG_RETURN ( $self );
1092 }
1093  
1094  
1095 #######################################
1096 # No POD on purpose ...
1097 # For use by Advanced::Config::Reader only.
1098 # Purpose is to allow source_file() a way to modify the date options.
1099  
1100 sub _load_config_with_new_date_opts
1101 52 ▶{
Subroutine _load_config_with_new_date_opts: called CC=3 SCAR=11.0
1102 52 DBUG_ENTER_FUNC ( @_ );
1103 52 my $self = shift;
1104 52 my $filename = shift;
1105 52 my $read_opts = shift;
1106 52 my $date_opts = shift;
1107  
1108 52 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
0520
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
1109  
1110 52 my $res;
1111 52 ▶ if ( $date_opts ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($date_opts) { } 9 43 52
1112 9 my %dates;
1113 9 $date_opts = get_date_opts ( $date_opts, $self->{CONTROL}->{date_opts} );
1114 change_special_date_vars ( $self->{CONTROL}->{DATES}->{timestamp},
1115 9 $date_opts, \%dates );
1116  
1117 # Temp override of the default date info ...
1118 9 local $self->{CONTROL}->{date_opts} = $date_opts;
1119 9 local $self->{CONTROL}->{DATES} = \%dates;
1120  
1121 9 $res = $self->load_config ( $filename, $read_opts );
1122 } else {
1123 43 $res = $self->load_config ( $filename, $read_opts );
1124 }
1125  
1126 52 DBUG_RETURN ( $res );
1127 }
1128  
1129 #######################################
1130  
1131 =item $boolean = $cfg->merge_config ( $filename[, %override_read_opts] );
1132  
1133 Provides a way to merge multiple config files into a single B<Advanced::Config>
1134 object. Useful when the main config file can't source in the passed config
1135 file due to different I<%read_opts> settings, or when a shared config file
1136 can't be modified to source in a sub-config file, or if for some reason you
1137 can't use the I<source_cb> Read Option during the initial load.
1138  
1139 Be aware that any tags in common with what's in this file will override the
1140 tag/value pairs from any previous calls to I<load_config> or I<merge_config>.
1141 You may also reference any tags in the previous loads as variables during this
1142 load. And if you have sections in common, it will merge each section's
1143 tag/value pairs as well.
1144  
1145 Just be aware that I<%override_read_opts> is overriding the default options set
1146 during the call to B<new>, not necessarily the same options being used by
1147 I<load_config>. See L<Advanced::Config::Options> for more details on what
1148 options are available.
1149  
1150 And finally if I<$filename> is a relative path, it's relative to the current
1151 directory, not relative to the location of the config file its being merged
1152 into.
1153  
1154 Returns B<1> if the config file was loaded and merged. Else B<0>.
1155  
1156 =cut
1157  
1158 sub merge_config
1159 45 ▶{
Subroutine merge_config: called CC=2 SCAR=7.0
Pod documented
1160 45 DBUG_ENTER_FUNC ( @_ );
1161 45 my $self = shift;
1162 45 my $file = shift; # Can be a relative path name if called directly ...
1163 # my $rOpts = shift; # The read options to use ...
1164  
1165 45 my $res = $self->load_config ( $file, @_ );
1166  
1167 44 ▶ DBUG_RETURN ( (defined $res) ? 1 : 0 );
Branch: 1 branch
BranchTrueFalseTotal
defined $res ? : 44 0 44
1168 }
1169  
1170  
1171 #######################################
1172  
1173 =item $boolean = $cfg->merge_string ( $string[, %override_read_opts] );
1174  
1175 Provides a way to merge multiple strings into a single B<Advanced::Config>
1176 object. Modifying the I<$string> afterwards will not affect this object.
1177  
1178 Be aware that any tags in common with what's in this string will override the
1179 tag/value pairs from any previous calls to load things into this object.
1180  
1181 Just be aware that I<%override_read_opts> is overriding the default options set
1182 during the call to B<new>, not necessarily the same options being used by
1183 I<load_config> or I<load_string>. See L<Advanced::Config::Options> for more
1184 details on what options are available.
1185  
1186 Returns B<1> if the string was merged into the object. Else B<0>.
1187  
1188 =cut
1189  
1190 sub merge_string
1191 5 ▶{
Subroutine merge_string: called CC=2 SCAR=7.0
Pod documented
1192 5 DBUG_ENTER_FUNC ( @_ );
1193 5 my $self = shift;
1194 5 my $string = shift; # The string to treat as a config file's contents.
1195 # my $rOpts = shift; # The read options to use ...
1196  
1197 5 my $res = $self->load_string ( $string, @_ );
1198  
1199 4 ▶ DBUG_RETURN ( (defined $res) ? 1 : 0 );
Branch: 1 branch
BranchTrueFalseTotal
defined $res ? : 4 0 4
1200 }
1201  
1202 #######################################
1203  
1204 =item $boolean = $cfg->refresh_config ( %refresh_opts );
1205  
1206 This boolean function detects if your config file or one of it's dependencies
1207 has been updated. If your config file sources in other config files, those
1208 config files are checked for changes as well.
1209  
1210 These changes could be to the config file itself or to any referenced variables
1211 in your config file whose value has changed.
1212  
1213 If it detects any updates, then it will reload the config file into memory,
1214 tossing any customizations you may have added via calls to B<set_value()>. It
1215 will keep the current B<Read> options unchanged.
1216  
1217 =over 4
1218  
1219 =item Supported Refresh Options Are:
1220  
1221 "test_only => 1" - It will skip the reloading of the config file even if it
1222 detects something changed. And just tell you if it detected any changes.
1223  
1224 "force => 1" - It will assume you know better and that something was updated.
1225 It will almost always return true (B<1>) when used.
1226  
1227 =back
1228  
1229 It returns true (B<1>) if any updates were detected or the B<force> option was
1230 used. It will return false (B<0>) otherwise.
1231  
1232 It will also return false (B<0>) if you never called B<load_conifg()> or
1233 B<load_string()> against this configuration object. In which case there is
1234 nothing to refresh.
1235  
1236 =cut
1237  
1238 sub refresh_config
1239 52 ▶{
Subroutine refresh_config: called CC=30 SCAR=37.9
Pod documented
1240 52 DBUG_ENTER_FUNC (@_);
1241 52 my $self = shift;
1242 0 ▶ my %opts = (ref ($_[0]) eq "HASH" ) ? %{$_[0]} : @_;
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] eq 'HASH' ? : 0 52 52
1243  
1244 52 my $updated = 0; # Assume no updates ...
1245 52 my $skip = 0;
1246  
1247 # Do a case insensitive lookup of the options hash ...
1248 52 foreach my $k ( keys %opts ) {
1249 50 ▶ next unless ( $opts{$k} ); # Skip if set to false ...
Branch: 1 branch
BranchTrueFalseTotal
unless $opts{$k} 11 39 50
1250  
1251 39 ▶ if ( $k =~ m/^force$/i ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($k =~ /^force$/i) { } 28 11 39
elsif ($k =~ /^test_only$/i) { } 11 0 11
1252 28 $updated = 1; # Force an update ...
1253 } elsif ( $k =~ m/^test_only$/i ) {
1254 11 $skip = 1; # Skip any refresh of the config file ...
1255 }
1256 }
1257  
1258 52 ▶ $self = $self->{PARENT} || $self; # Force to the "main" section ...
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
0520
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
1259  
1260 52 ▶ if ( $self->{CONTROL}->{SENSITIVE_CNT} != sensitive_cnt () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"CONTROL"}{"SENSITIVE_CNT"} != sensitive_cnt()) 1 51 52
1261 1 $updated = 1;
1262 }
1263  
1264 # If not forcing an update, try to detect any changes to the %ENV hash ...
1265 52 ▶ unless ( $updated ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($updated) 23 29 52
1266 23 DBUG_PRINT ("INFO", "Checking for changes to %ENV ...");
1267 23 foreach my $k ( sort keys %{$self->{CONTROL}->{ENV}} ) {
1268 0 ▶ if ( ! defined $ENV{$k} ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $ENV{$k}) { } 0 0 0
elsif ($ENV{$k} ne $self->{'CONTROL'}{'ENV'}{$k}) { } 0 0 0
1269 0 $updated = 1; # Env. Var. was removed from the environment.
1270 } elsif ( $ENV{$k} ne $self->{CONTROL}->{ENV}->{$k} ) {
1271 0 $updated = 1; # Env. Var. was modified ...
1272 }
1273  
1274 0 ▶ if ( $updated ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($updated) 0 0 0
1275 0 DBUG_PRINT ("WARN", "ENV{%s} changed it's value!", $k);
1276 0 last;
1277 }
1278 }
1279 }
1280  
1281 # If any of the special date vars were referenced in the config file,
1282 # assume the program's been running long enough for one of them to change!
1283 52 my %dates;
1284 52 ▶ if ( $self->{CONTROL}->{DATE_USED} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"CONTROL"}{"DATE_USED"}) 40 12 52
1285 40 DBUG_PRINT ("INFO", "Checking the special date variables for changes ...");
1286 my $res = set_special_date_vars ($self->{CONTROL}->{date_opts},
1287 40 \%dates, $self->{CONTROL}->{DATES});
1288 40 ▶ if ( $res >= $self->{CONTROL}->{DATE_USED} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($res >= $self->{'CONTROL'}{'DATE_USED'}) { } 0 40 40
1289 0 DBUG_PRINT ("WARN", "A referenced special date variable's value changed!");
1290 0 $updated = 1;
1291 } else {
1292 40 $dates{timestamp} = $self->{CONTROL}->{DATES}->{timestamp};
1293 }
1294 }
1295  
1296 # Try to detect if any config files were modified ...
1297 52 ▶ unless ( $updated ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($updated) 23 29 52
1298 23 DBUG_PRINT ("INFO", "Checking the file timestamps ...");
1299 23 foreach my $f ( sort keys %{$self->{CONTROL}->{REFRESH_MODIFY_TIME}} ) {
1300 # Can't do ref($f) since key is stored as a string here.
1301 35 ▶ my $modify_time = ( $f =~ m/^SCALAR[(]0x[0-9a-f]+[)]$/ ) ? 0 : (stat( $f ))[9];
Branch: 1 branch
BranchTrueFalseTotal
$f =~ /^SCALAR[(]0x[0-9a-f]+[)]$/ ? : 3 32 35
1302  
1303 35 ▶ if ( $modify_time > $self->{CONTROL}->{REFRESH_MODIFY_TIME}->{$f} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($modify_time > $self->{"CONTROL"}{"REFRESH_MODIFY_TIME"}{$f}) 0 35 35
1304 0 DBUG_PRINT ("WARN", "File was modified: %s", $f);
1305 0 $updated = 1;
1306 0 last;
1307 }
1308 }
1309 }
1310  
1311 # Check if it's a rule config file that was updated.
1312 52 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 1 51 52
1313 1 ▶ if ( $updated && $skip == 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($updated and $skip == 0) 1 0 1
Condition33%1/3
$updated and $skip == 0
!ll&&!rl&&r
001
MC/DC0%0/2
$updated and $skip == 0
$updated $skip == 0
Truth table33%1/3
A and B
A= $updatedB= $skip == 0
ABresult
0X0
100
111
1314 1 $self->newDefineConfigRules ( $self->filename(), 1 );
1315 }
1316 1 return DBUG_RETURN ( $updated );
1317 }
1318  
1319 # Refresh the config file's contents in memory ...
1320 51 ▶ if ( $updated && $skip == 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($updated and $skip == 0) 28 23 51
Condition66%2/3
$updated and $skip == 0
!ll&&!rl&&r
23028
MC/DC50%1/2
$updated and $skip == 0
$updated $skip == 0
Truth table66%2/3
A and B
A= $updatedB= $skip == 0
ABresult
0X0
100
111
1321 28 my $f = $self->{CONTROL}->{filename};
1322 28 my @mlst = @{$self->{CONTROL}->{MERGE}};
1323 28 my $opts = $self->{CONTROL}->{REFRESH_READ_OPTIONS};
1324  
1325 # Update date info gathered earlier only if these vars are used.
1326 28 ▶ if ( $self->{CONTROL}->{DATE_USED} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"CONTROL"}{"DATE_USED"}) 22 6 28
1327 22 $self->{CONTROL}->{DATES} = \%dates;
1328 22 $self->{CONTROL}->{DATE_USED} = 0;
1329 }
1330  
1331 # Always reload rule config file if there is one & refresh detected.
1332 28 ▶ if ( $self->{CONTROL}->{ConfigRuleObj} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"CONTROL"}{"ConfigRuleObj"}) 0 28 28
1333 0 DBUG_PRINT ("LOG", "Refreshing the RuleCfg file ... %s", ref ($f));
1334 $self->{CONTROL}->{ConfigRuleObj}->newDefineConfigRules (
1335 $self->{CONTROL}->{ConfigRuleObj}->{CONTROL}->{filename},
1336 0 1 );
1337 }
1338  
1339 28 my $reload;
1340 28 DBUG_PRINT ("LOG", "Calling Load Function ... %s", ref ($f));
1341 28 ▶ if ( ref ( $f ) eq "SCALAR" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $f eq 'SCALAR') { } 1 27 28
1342 1 $reload = $self->load_string ( ${$f}, $opts->{$f} );
1343 } else {
1344 27 $reload = $self->load_config ( $f, $opts->{$f} );
1345 }
1346 26 ▶ return DBUG_RETURN ( 0 ) unless ( defined $reload ); # Load failed ???
Branch: 1 branch
BranchTrueFalseTotal
unless defined $reload 3 23 26
1347  
1348 23 foreach my $m (@mlst) {
1349 20 DBUG_PRINT ("LOG", "Calling Merge Function ... %s", ref ($m));
1350 20 ▶ if ( ref ( $m ) eq "SCALAR" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $m eq 'SCALAR') { } 2 18 20
1351 2 $self->merge_string ( ${$m}, $opts->{$m} );
1352 } else {
1353 18 $self->merge_config ( $m, $opts->{$m} );
1354 }
1355 }
1356 }
1357  
1358 46 DBUG_RETURN ( $updated );
1359 }
1360  
1361 #######################################
1362  
1363 # Private method ...
1364 # Checks for recursion while sourcing in sub-files.
1365 # Returns: 1 (yes) or 0 (no)
1366  
1367 sub _recursion_check
1368 54 ▶{
Subroutine _recursion_check: called CC=3 SCAR=11.0
1369 54 DBUG_ENTER_FUNC (@_);
1370 54 my $self = shift;
1371 54 my $file = shift;
1372  
1373 # Get the main/parent section to work against!
1374 54 ▶ $self = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
14400
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
1375  
1376 54 ▶ DBUG_RETURN ( exists $self->{CONTROL}->{RECURSION}->{$file} ? 1 : 0 );
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'CONTROL'}{'RECURSION'}{$file} ? : 2 52 54
1377 }
1378  
1379 #######################################
1380  
1381 # Private method ...
1382 # Gets the requested tag from the current section.
1383 # And then apply the required rules against the returned value.
1384 # The {required} option isn't reliable until in this method!
1385 # Returns: The tag hash ... (undef if it doesn't exist)
1386 sub _base_get
1387 68564 ▶{
Subroutine _base_get: called CC=7 SCAR=19.6
1388 68564 my $self = shift;
1389 68564 my $tag = shift;
1390 68564 my $opts = shift;
1391 68564 my $disable_req = shift;
1392  
1393 # Get the main/parent section to work against!
1394 68564 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
53273152910
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
1395  
1396 # Determine what the "get" options must be ...
1397 68564 my $get_opts = $pcfg->{CONTROL}->{get_opts};
1398 68564 ▶ $get_opts = get_get_opts ( $opts, $get_opts ) if ( $opts );
Branch: 1 branch
BranchTrueFalseTotal
if $opts 3280 65284 68564
1399  
1400 # Check if a case insensitive lookup was requested ...
1401 68564 ▶ my $t = ( $pcfg->{CONTROL}->{read_opts}->{tag_case} && $tag ) ? lc ($tag) : $tag;
Branch: 1 branch
BranchTrueFalseTotal
$pcfg->{'CONTROL'}{'read_opts'}{'tag_case'} && $tag ? : 604 67960 68564
Condition66%2/3
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag
!ll&&!rl&&r
679600604
MC/DC50%1/2
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} $tag
Truth table66%2/3
A and B
A= $pcfg->{"CONTROL"}{"read_opts"}{"tag_case"}B= $tag
ABresult
0X0
100
111
1402  
1403 # Check if we're overriding the required flag ...
1404 68564 my $req = $get_opts->{required};
1405 68564 ▶ local $get_opts->{required} = $disable_req ? 0 : $req;
Branch: 1 branch
BranchTrueFalseTotal
$disable_req ? : 38 68526 68564
1406  
1407 # Returns a hash reference to a local copy of the tag's data ... (or undef)
1408 # Handles the inherit option if used.
1409 my $data_ref =apply_get_rules ( $tag, $self->{SECTION_NAME},
1410 $self->{DATA}->{$t}, $pcfg->{DATA}->{$t},
1411 $pcfg->{CONTROL}->{ALLOW_UTF8},
1412 68564 $get_opts );
1413  
1414 68564 ▶ return ( wantarray ? ($data_ref, $req) : $data_ref );
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 68564 0 68564
1415 }
1416  
1417  
1418 # Private method ...
1419 # Gets the requested tag value from the current section.
1420 # Returns: All 5 of the hash members individually ... + required flag setting.
1421 sub _base_get2
1422 68496 ▶{
Subroutine _base_get2: called CC=2 SCAR=6.9
1423 68496 my $self = shift;
1424 68496 my $tag = shift;
1425 68496 my $opts = shift;
1426  
1427 68496 my ($data, $req) = $self->_base_get ( $tag, $opts, 0 );
1428  
1429 68496 ▶ if ( defined $data ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data) { } 59439 9057 68496
1430 59439 return ( $data->{VALUE}, $data->{MASK_IN_FISH}, $data->{FILE}, $data->{ENCRYPTED}, $data->{VARIABLE}, $req );
1431 } else {
1432 9057 return ( undef, 0, "", 0, 0, $req ); # No such tag ...
1433 }
1434 }
1435  
1436  
1437 # Private method ...
1438 # Gets the requested tag date value from the current section.
1439 # or treat the tag name as the date if the tag doesn't exist!
1440 # Returns: All 5 of the hash members individually ... + required flag setting.
1441 sub _base_get3_date_str
1442 38 ▶{
Subroutine _base_get3_date_str: called CC=10 SCAR=23.2
1443 38 my $self = shift;
1444 38 my $tag = shift;
1445 38 my $opts = shift;
1446 38 my $hyd_flg = shift; # Is it OK to return a HYD as HYD?
1447 38 my $cvt_hyd_flg = shift; # Is it OK to convert a HYD into a date str?
1448  
1449 38 ▶ if ($hyd_flg && $cvt_hyd_flg) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hyd_flg and $cvt_hyd_flg) 0 38 38
Condition66%2/3
$hyd_flg and $cvt_hyd_flg
!ll&&!rl&&r
24140
MC/DC0%0/2
$hyd_flg and $cvt_hyd_flg
$hyd_flg $cvt_hyd_flg
Truth table66%2/3
A and B
A= $hyd_flgB= $cvt_hyd_flg
ABresult
0X0
100
111
1450 0 local $opts->{required} = 1;
1451 0 croak_helper ($opts, "Programming error! Can't set both hyd flags to true.", undef);
1452 }
1453  
1454 38 my ($data, $req);
1455 {
1456 38 local $opts->{date_active} = 0;
1457 38 ($data, $req) = $self->_base_get ( $tag, $opts, 1 ); # Does tag exist?
1458 }
1459  
1460 # If the tag doesn't exist, use $tag as a date string instead.
1461 38 ▶ unless ( defined $data ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $data) 8 30 38
1462 8 my $yr = _validate_date_str ($tag);
1463 8 ▶ if ( defined $yr ) {
Branch: 3 branches
BranchTrueFalseTotal
if (defined $yr) { } 4 4 8
elsif ($hyd_flg and $tag =~ /^[-]?\d+$/) { } 1 3 4
elsif ($cvt_hyd_flg and $tag =~ /^[-]?\d+$/) { } 1 2 3
1464 4 return ( $tag, 0, "", 0, 0, $req ); # We have a valid date string!
1465 ▶ } elsif ( $hyd_flg && $tag =~ m/^[-]?\d+$/ ) {
Condition66%2/3
$hyd_flg and $tag =~ /^[-]?\d+$/
!ll&&!rl&&r
301
MC/DC50%1/2
$hyd_flg and $tag =~ /^[-]?\d+$/
$hyd_flg $tag =~ /^[-]?\d+$/
Truth table66%2/3
A and B
A= $hyd_flgB= $tag =~ /^[-]?\d+$/
ABresult
0X0
100
111
1466 1 return ( $tag, 0, "", 0, 0, $req ); # We have a valid HYD string!
1467 ▶ } elsif ( $cvt_hyd_flg && $tag =~ m/^[-]?\d+$/ ) {
Condition66%2/3
$cvt_hyd_flg and $tag =~ /^[-]?\d+$/
!ll&&!rl&&r
201
MC/DC50%1/2
$cvt_hyd_flg and $tag =~ /^[-]?\d+$/
$cvt_hyd_flg $tag =~ /^[-]?\d+$/
Truth table66%2/3
A and B
A= $cvt_hyd_flgB= $tag =~ /^[-]?\d+$/
ABresult
0X0
100
111
1468 1 my $dt = convert_hyd_to_date_str ($tag);
1469 1 return ( $dt, 0, "", 0, 0, $req ); # We have a valid date string!
1470 } else {
1471 2 local $opts->{required} = $req;
1472 2 croak_helper ($opts, "No such tag ($tag), nor is it a date string.", undef);
1473 2 return ( undef, 0, "", 0, 0, $req ); # No such tag/date ...
1474 }
1475 }
1476  
1477 # The tag exists, then it must reference a date!
1478 30 local $opts->{date_active} = 1;
1479 30 ($data, $req) = $self->_base_get ( $tag, $opts, 0 );
1480  
1481 30 ▶ if ( defined $data ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $data) { } 18 12 30
1482 18 return ( $data->{VALUE}, $data->{MASK_IN_FISH}, $data->{FILE}, $data->{ENCRYPTED}, $data->{VARIABLE}, $req );
1483 } else {
1484 12 return ( undef, 0, "", 0, 0, $req ); # Not a date ...
1485 }
1486 }
1487  
1488  
1489 #######################################
1490  
1491 =back
1492  
1493 =head2 Accessing the contents of an Advanced::Config object.
1494  
1495 These methods allow you to access the data loaded into this object.
1496  
1497 They all look in the current section for the B<tag> and if the B<tag> couldn't
1498 be found in this section and the I<inherit> option was also set, it will then
1499 look in the parent/main section for the B<tag>. But if the I<inherit> option
1500 wasn't set it wouldn't look there.
1501  
1502 If the requested B<tag> couldn't be found, they return B<undef>. But if the
1503 I<required> option was used, it may call B<die> instead!
1504  
1505 But normally they just return the requested B<tag>'s value.
1506  
1507 They all use F<%override_get_opts>, passed by value or by reference, as an
1508 optional argument that overrides the default options provided in the call
1509 to F<new()>. The I<inherit> and I<required> options discussed above are two
1510 such options. In most cases this hash argument isn't needed. So leave it off
1511 if you are happy with the current defaults!
1512  
1513 See the POD under L<Advanced::Config::Options>, I<The Get Options> for more
1514 details on what options you may override.
1515  
1516 Only the B<L<get_value>> function was truly needed. But the other I<get>
1517 methods were added for a couple of reasons. First to make it clear in your code
1518 what type of value is being returned and provide the ability to do validation of
1519 the B<tag>'s value without having to validate it yourself! Another benefit was
1520 that it drastically reduced the number of exposed I<Get Options> needed for this
1521 module. Making it easier to use.
1522  
1523 Finally when these extra methods apply their validation, if the B<tag>'s value
1524 fails the test, it treats it as a I<B<tag> not found> situation as described
1525 above.
1526  
1527 =over
1528  
1529 =item $value = $cfg->get_value ( $tag[, %override_get_opts] );
1530  
1531 This function looks up the requested B<tag>'s value and returns it.
1532 See common details above.
1533  
1534 =cut
1535  
1536 sub get_value
1537 50099 ▶{
Subroutine get_value: called CC=3 SCAR=11.0
Pod documented
1538 50099 DBUG_ENTER_FUNC ( @_ );
1539 50099 my $self = shift; # Reference to the current section.
1540 50099 my $tag = shift; # The tag to look up ...
1541 50099 my $opt_ref = $_[0]; # The override options ...
1542  
1543 50099 ▶ $opt_ref = $self->_get_opt_args ( @_ ) if ( defined $opt_ref );
Branch: 1 branch
BranchTrueFalseTotal
if defined $opt_ref 184 49915 50099
1544  
1545 50099 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
1546 50099 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 787 49312 50099
1547  
1548 50099 DBUG_RETURN ( $value );
1549 }
1550  
1551 #######################################
1552 # A helper function to handle the various ways to find a hash as an argument!
1553 # Handles all 3 cases.
1554 # undef - No arguments
1555 # hash ref - passed by reference
1556 # something else - passed by value. (array)
1557  
1558 sub _get_opt_args
1559 3323 ▶{
Subroutine _get_opt_args: called CC=3 SCAR=11.0
1560 3323 my $self = shift; # Reference to the current section.
1561 3323 my $opt_ref = $_[0]; # May be undef, a hash ref, or start of a hash ...
1562  
1563 # Convert the parameter array into a regular old hash reference ...
1564 3323 my %opts;
1565 3323 ▶ unless ( defined $opt_ref ) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $opt_ref) { } 2996 327 3323
if (do { ref $opt_ref ne "HASH" }) 2717 279 2996
1566 327 $opt_ref = \%opts;
1567 0 } elsif ( ref ($opt_ref) ne "HASH" ) {
1568 2717 %opts = @_;
1569 2717 $opt_ref = \%opts;
1570 }
1571  
1572 3323 return ( $opt_ref ); # The hash reference to use ...
1573 }
1574  
1575 #######################################
1576 # Another helper function to help with evaluating which value to use ...
1577 # Does a 4 step check.
1578 # 1) Use the $value if provided.
1579 # 2) If the key exists in the hash returned by _get_opt_args(), use it.
1580 # 3) Look it up in the default "Get Options" set via call to new().
1581 # 4) undef if all the above fail.
1582  
1583 sub _evaluate_hash_values
1584 522 ▶{
Subroutine _evaluate_hash_values: called CC=6 SCAR=18.9
1585 522 my $self = shift; # References the current section.
1586 522 my $key = shift; # The hash key to look up ...
1587 522 my $ghash = shift; # A hash ref returned by _get_opt_args().
1588 522 my $value = shift; # Use only if explicitly set ...
1589  
1590 522 ▶ unless ( defined $value ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $value) 168 354 522
1591 168 ▶ if ( defined $ghash && exists $ghash->{$key} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $ghash and exists $ghash->{$key}) { } 0 168 168
Condition33%1/3
defined $ghash and exists $ghash->{$key}
!ll&&!rl&&r
01680
MC/DC0%0/2
defined $ghash and exists $ghash->{$key}
defined $ghash exists $ghash->{$key}
Truth table33%1/3
A and B
A= defined $ghashB= exists $ghash->{$key}
ABresult
0X0
100
111
1592 0 $value = $ghash->{$key}; # Passed via the get options hash ...
1593 } else {
1594 # Use the default from the call to new() ...
1595 168 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
541140
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
1596 168 ▶ if ( exists $pcfg->{CONTROL}->{get_opts}->{$key} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $pcfg->{"CONTROL"}{"get_opts"}{$key}) 168 0 168
1597 168 $value = $pcfg->{CONTROL}->{get_opts}->{$key};
1598 }
1599 }
1600 }
1601  
1602 522 return ( $value ); # The value to use ...
1603 }
1604  
1605 #######################################
1606  
1607 =item $value = $cfg->get_integer ( $tag[, $rt_flag[, %override_get_opts]] );
1608  
1609 This function looks up the requested B<tag>'s value and returns it if its an
1610 integer. If the B<tag>'s value is a floating point number (ex 3.6), then the
1611 value is either truncated or rounded up based on the setting of the I<rt_flag>.
1612  
1613 If I<rt_flag> is set, it will perform truncation, so 3.6 becomes B<3>. If the
1614 flag is B<undef> or zero, it does rounding, so 3.6 becomes B<4>. Meaning the
1615 default is rounding.
1616  
1617 Otherwise if the B<tag> doesn't exist or its value is not numeric it will
1618 return B<undef> unless it's been marked as I<required>. In that case B<die>
1619 may be called instead.
1620  
1621 =cut
1622  
1623 sub get_integer
1624 111 ▶{
Subroutine get_integer: called CC=3 SCAR=11.0
Pod documented
1625 111 DBUG_ENTER_FUNC ( @_ );
1626 111 my $self = shift; # Reference to the current section.
1627 111 my $tag = shift; # The tag to look up ...
1628 111 my $rt_flag = shift; # 1 - truncate, 0 - rounding.
1629 111 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1630  
1631 # Flag if we should use truncation (2) or rounding (1) if needed ...
1632 111 ▶ local $opt_ref->{numeric} = $rt_flag ? 2 : 1;
Branch: 1 branch
BranchTrueFalseTotal
$rt_flag ? : 74 37 111
1633  
1634 111 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
1635 111 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 111 111
1636  
1637 111 DBUG_RETURN ( $value );
1638 }
1639  
1640  
1641 #######################################
1642  
1643 =item $value = $cfg->get_numeric ( $tag[, %override_get_opts] );
1644  
1645 This function looks up the requested B<tag>'s value and returns it if its
1646 value is numeric. Which means any valid integer or floating point number!
1647  
1648 If the B<tag> doesn't exist or its value is not numeric it will return B<undef>
1649 unless it's been marked as I<required>. In that case B<die> may be called
1650 instead.
1651  
1652 =cut
1653  
1654 sub get_numeric
1655 37 ▶{
Subroutine get_numeric: called CC=2 SCAR=7.0
Pod documented
1656 37 DBUG_ENTER_FUNC ( @_ );
1657 37 my $self = shift; # Reference to the current section.
1658 37 my $tag = shift; # The tag to look up ...
1659 37 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1660  
1661 # Asking for a floating point number ...
1662 37 local $opt_ref->{numeric} = 3;
1663  
1664 37 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
1665 37 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 37 37
1666  
1667 37 DBUG_RETURN ( $value );
1668 }
1669  
1670  
1671 #######################################
1672  
1673 =item $value = $cfg->get_boolean ( $tag[, %override_get_opts] );
1674  
1675 Treats the B<tag>'s value as a boolean value and returns I<undef>,
1676 B<0> or B<1>.
1677  
1678 Sometimes you just want to allow for basically a true/false answer
1679 without having to force a particular usage in the config file.
1680 This function converts the B<tag>'s value accordingly.
1681  
1682 So it handles pairs like: Yes/No, True/False, Good/Bad, Y/N, T/F, G/B, 1/0,
1683 On/Off, etc. and converts them into a boolean value. This test is case
1684 insensitive. It never returns what's actually in the config file.
1685  
1686 If it doesn't recognize something it always returns B<0>.
1687  
1688 =cut
1689  
1690 sub get_boolean
1691 32 ▶{
Subroutine get_boolean: called CC=2 SCAR=7.0
Pod documented
1692 32 DBUG_ENTER_FUNC ( @_ );
1693 32 my $self = shift; # Reference to the current section.
1694 32 my $tag = shift; # The tag to look up ...
1695 32 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1696  
1697 # Turns on the treat as a boolean option ...
1698 32 local $opt_ref->{auto_true} = 1;
1699  
1700 32 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
1701 32 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 32 32
1702  
1703 32 DBUG_RETURN ( $value );
1704 }
1705  
1706  
1707 #######################################
1708  
1709 =item $date = $cfg->get_date ( $tag[, $language[, %override_get_opts]] );
1710  
1711 This function looks up the requested B<tag>'s value and returns it if its
1712 value contains a valid date. The returned value will always be in I<YYYY-MM-DD>
1713 format no matter what format or language was actually used in the config file
1714 for the date.
1715  
1716 If the B<tag> doesn't exist or its value is not a date it will return B<undef>
1717 unless it's been marked as I<required>. In that case B<die> may be called
1718 instead.
1719  
1720 If I<$language> is undefined, it will use the default language defined in the
1721 call to I<new> for parsing the date. (B<English> if not overridden.) Otherwise
1722 it must be a valid language defined by B<Date::Language>. If it's a wrong or
1723 bad language, your date might not be recognized as valid.
1724  
1725 Unlike most other B<get> options, when parsing the B<tag>'s value, it's not
1726 looking to match the entire string. It's looking for a date portion inside the
1727 value and ignores any miscellaneous information. There was just too many
1728 semi-valid potential surrounding data to worry about parsing that info as well.
1729  
1730 So B<Tues "January 3rd, 2017" at 6:00 PM> returns "2017-01-03".
1731  
1732 There are also a few date related options for I<%override_get_opts> to use that
1733 you may find useful.
1734  
1735 See L<Advanced::Config::Date> for more details.
1736  
1737 =cut
1738  
1739 sub get_date
1740 2616 ▶{
Subroutine get_date: called CC=3 SCAR=11.0
Pod documented
1741 2616 DBUG_ENTER_FUNC ( @_ );
1742 2616 my $self = shift; # Reference to the current section.
1743 2616 my $tag = shift; # The tag to look up ...
1744 2616 my $language = shift; # The language the date appears in ...
1745 2616 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1746  
1747 2616 local $opt_ref->{date_active} = 1;
1748 2616 ▶ local $opt_ref->{date_language} = $language if ( defined $language );
Branch: 1 branch
BranchTrueFalseTotal
if defined $language 2592 24 2616
1749  
1750 2616 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
1751 2616 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 2616 2616
1752  
1753 2616 DBUG_RETURN ( $value );
1754 }
1755  
1756  
1757 #######################################
1758  
1759 =item $hyd = $cfg->get_hyd_date ( $tag[, $language[, %override_get_opts]] );
1760  
1761 Behaves the same as B<get_date> except that it returns the date in the Hundred
1762 Year Date (I<hyd>) format. Which is defined as the number of days since
1763 B<Jan 1, 1900>. Which has the I<$hyd> of B<1>.
1764  
1765 But if the tag B<$tag> doesn't exist in the config file, and it's name is in the
1766 format of I<YYYY-MM-DD>, it will return the I<hyd> for that date instead.
1767  
1768 This date format makes it very easy to do math against dates,
1769  
1770 See L<Advanced::Config::Date> for more details.
1771  
1772 =cut
1773  
1774 sub get_hyd_date
1775 8 ▶{
Subroutine get_hyd_date: called CC=4 SCAR=14.2
Pod documented
1776 8 DBUG_ENTER_FUNC ( @_ );
1777 8 my $self = shift; # Reference to the current section.
1778 8 my $tag = shift; # The tag to look up ...
1779 8 my $language = shift; # The language the date appears in ...
1780 8 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1781  
1782 8 local $opt_ref->{date_active} = 1;
1783 8 ▶ local $opt_ref->{date_language} = $language if ( defined $language );
Branch: 1 branch
BranchTrueFalseTotal
if defined $language 0 8 8
1784  
1785 8 my ( $value, $sensitive, $required ) = ($self->_base_get3_date_str ( $tag, $opt_ref, 0, 0 ))[0,1,5];
1786 8 ▶ if ( $sensitive ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sensitive) 0 8 8
1787 0 DBUG_MASK (0);
1788 0 DBUG_MASK_NEXT_FUNC_CALL (-1);
1789 }
1790 8 ▶ return DBUG_RETURN (undef) unless (defined $value);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 4 4 8
1791  
1792 4 $value = calc_hundred_year_date ( $value );
1793  
1794 4 DBUG_RETURN ( $value );
1795 }
1796  
1797  
1798 #######################################
1799  
1800 =item $dow = $cfg->get_dow_date ( $tag[, $language[, $mode[, %override_get_opts]]] );
1801  
1802 Behaves the same as B<get_date> except that it returns the Day of Week (I<dow>)
1803 that the date falls on. The I<dow>'s format depends on the value of B<$mode>.
1804  
1805 If B<$mode> is B<2> it returns the full name in the requested language.
1806 ex: I<Monday>.
1807  
1808 If B<$mode> is B<1> it returns the abbreviated name in the requested language.
1809 ex: I<Mon>.
1810  
1811 Otherwise it returns the I<dow> as a number between B<0> and B<6>. For Sunday
1812 to Saturday.
1813  
1814 But if the tag B<$tag> doesn't exist in the config file, and the tag's name is
1815 in the format of I<YYYY-MM-DD>, it will return the I<dow> for that date instead.
1816  
1817 Finally if B<$tag> still didn't match it checks if it's an integer and it
1818 assumes you want the I<dow> for a I<hyd> date.
1819  
1820 See L<Advanced::Config::Date> for more details.
1821  
1822 =cut
1823  
1824 sub get_dow_date
1825 14 ▶{
Subroutine get_dow_date: called CC=13 SCAR=28.7
Pod documented
1826 14 DBUG_ENTER_FUNC ( @_ );
1827 14 my $self = shift; # Reference to the current section.
1828 14 my $tag = shift; # The tag to look up ...
1829 14 my $language = shift; # The language the date appears in ...
1830 14 my $mode; # Determines format of return value. 0, 1 or 2. (new arg)
1831 my $opt_ref; # Must keep this arg last. The override options.
1832  
1833 # Messy to make backwards compatible.
1834 # Since the order of args changed since func 1st defined in previous release.
1835 14 my $c = @_;
1836 14 ▶ if ( $c == 0 || ref ($_[0]) eq "HASH" ) {
Branch: 3 branches
BranchTrueFalseTotal
if ($c == 0 or ref $_[0] eq 'HASH') { } 8 6 14
elsif (ref $_[1] eq 'HASH') { } 0 6 6
elsif ($c % 2 == 1) { } 6 0 6
Condition66%2/3
$c == 0 or ref $_[0] eq "HASH"
l!l&&r!l&&!r
806
MC/DC50%1/2
$c == 0 or ref $_[0] eq "HASH"
$c == 0 ref $_[0] eq "HASH"
Truth table66%2/3
A or B
A= $c == 0B= ref $_[0] eq "HASH"
ABresult
1X1
011
000
1837 8 $mode = 0;
1838 8 $opt_ref = $self->_get_opt_args ( @_ );
1839 } elsif ( ref ($_[1]) eq "HASH" ) {
1840 0 ▶ $mode = shift || 0;
Condition0%0/2
shift() || 0
l!l
00
MC/DC0%0/1
shift() || 0
shift()
Truth table0%0/2
A
A= shift()
Aresult
11
00
1841 0 $opt_ref = $self->_get_opt_args ( @_ );
1842 } elsif ( ($c % 2) == 1 ) {
1843 6 ▶ $mode = shift || 0;
Condition50%1/2
shift() || 0
l!l
60
MC/DC0%0/1
shift() || 0
shift()
Truth table50%1/2
A
A= shift()
Aresult
11
00
1844 6 $opt_ref = $self->_get_opt_args ( @_ );
1845 } else {
1846 0 $mode = 0;
1847 0 $opt_ref = $self->_get_opt_args ( @_ );
1848 }
1849  
1850  
1851 14 local $opt_ref->{date_active} = 1;
1852 14 ▶ local $opt_ref->{date_language} = $language if ( defined $language );
Branch: 1 branch
BranchTrueFalseTotal
if defined $language 0 14 14
1853  
1854 14 my ( $value, $sensitive, $required ) = ($self->_base_get3_date_str ( $tag, $opt_ref, 1, 0 ))[0,1,5];
1855 14 ▶ if ( $sensitive ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sensitive) 0 14 14
1856 0 DBUG_MASK (0);
1857 0 DBUG_MASK_NEXT_FUNC_CALL (-1);
1858 }
1859 14 ▶ return DBUG_RETURN (undef) unless (defined $value);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 3 11 14
1860  
1861 11 $value = calc_day_of_week ( $value ); # 0 .. 6
1862  
1863 11 ▶ if ($mode =~ m/^[12]$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($mode =~ /^[12]$/) 6 5 11
1864 6 ▶ DBUG_MASK_NEXT_FUNC_CALL (-1) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 6 6
1865 my ($m, $dow_ref) = init_special_date_arrays ($opt_ref->{date_language},
1866 6 $mode, 0, 1);
1867 6 ▶ $value = $dow_ref->[$value] if ( defined $dow_ref );
Branch: 1 branch
BranchTrueFalseTotal
if defined $dow_ref 6 0 6
1868 }
1869  
1870 11 DBUG_RETURN ( $value );
1871 }
1872  
1873 #######################################
1874  
1875 =item $doy = $cfg->get_doy_date ( $tag[, $language[, %override_get_opts]] );
1876  
1877 Behaves the same as B<get_date> except that it returns the Day of Year (I<doy>)
1878 that the date falls on. It returns the I<doy> as a number between B<1> and
1879 B<366>. With Jan 1st being B<1> and Dec 31st being B<365> or B<366>.
1880  
1881 But if the tag B<$tag> doesn't exist in the config file, and it's name is in the
1882 format of I<YYYY-MM-DD>, it will return the I<doy> for that date instead.
1883  
1884 See L<Advanced::Config::Date> for more details.
1885  
1886 =cut
1887  
1888 sub get_doy_date
1889 8 ▶{
Subroutine get_doy_date: called CC=4 SCAR=14.2
Pod documented
1890 8 DBUG_ENTER_FUNC ( @_ );
1891 8 my $self = shift; # Reference to the current section.
1892 8 my $tag = shift; # The tag to look up ...
1893 8 my $language = shift; # The language the date appears in ...
1894 8 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1895  
1896 8 local $opt_ref->{date_active} = 1;
1897 8 ▶ local $opt_ref->{date_language} = $language if ( defined $language );
Branch: 1 branch
BranchTrueFalseTotal
if defined $language 0 8 8
1898  
1899 8 my ( $value, $sensitive, $required ) = ($self->_base_get3_date_str ( $tag, $opt_ref, 0, 0 ))[0,1,5];
1900 8 ▶ if ( $sensitive ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sensitive) 0 8 8
1901 0 DBUG_MASK (0);
1902 0 DBUG_MASK_NEXT_FUNC_CALL (-1);
1903 }
1904 8 ▶ return DBUG_RETURN (undef) unless (defined $value);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 4 4 8
1905  
1906 4 $value = calc_day_of_year ( $value );
1907  
1908 4 DBUG_RETURN ( $value );
1909 }
1910  
1911  
1912 #######################################
1913  
1914 =item $newDate = $cfg->get_adjusted_date ( $tag, $adjYr, $adjMon[, $language[, %override_get_opts]] );
1915  
1916 Behaves the same as B<get_date> except that it returns an offsetted date.
1917 Where both I<$adjYr> & I<$adjMon> are integers.
1918 It correctly handles leap years and the proper number of days per month.
1919  
1920 But if the tag B<$tag> doesn't exist in the config file, and it's name is in the
1921 format of I<YYYY-MM-DD>, it will return the offset to that date instead.
1922  
1923 Example:
1924  
1925 B<2020-02-15> = get_adjusted_date ("2024-01-15", -4, 1);
1926  
1927 Finally if B<$tag> still didn't match it checks if it's an integer and it
1928 assumes you want the offset to be against the I<hyd> instead. You can use this
1929 option to convert a I<hyd> into a I<date string> as follows:
1930  
1931 B<$date_str> = get_adjusted_date (I<$hyd>, 0, 0);
1932  
1933 See L<Advanced::Config::Date> for more details.
1934  
1935 =cut
1936  
1937 sub get_adjusted_date
1938 8 ▶{
Subroutine get_adjusted_date: called CC=5 SCAR=16.9
Pod documented
1939 8 DBUG_ENTER_FUNC ( @_ );
1940 8 my $self = shift; # Reference to the current section.
1941 8 my $tag = shift; # The tag to look up ...
1942 8 my $adjYrs = shift; # Number of years to adjust.
1943 8 my $adjMons = shift; # Number of months to adjust.
1944 8 my $language = shift; # The language the date appears in ...
1945 8 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1946  
1947 8 local $opt_ref->{date_active} = 1;
1948 8 ▶ local $opt_ref->{date_language} = $language if ( defined $language );
Branch: 1 branch
BranchTrueFalseTotal
if defined $language 0 8 8
1949  
1950 8 my ( $value, $sensitive, $required ) = ($self->_base_get3_date_str ( $tag, $opt_ref, 0, 1 ))[0,1,5];
1951 8 ▶ if ( $sensitive ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sensitive) 0 8 8
1952 0 DBUG_MASK (0);
1953 0 DBUG_MASK_NEXT_FUNC_CALL (-1);
1954 }
1955 8 ▶ return DBUG_RETURN (undef) unless (defined $value);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $value 3 5 8
1956  
1957 5 $value = adjust_date_str ( $value, $adjYrs, $adjMons );
1958 5 ▶ unless (defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $value) 0 5 5
1959 0 local $opt_ref->{required} = $required;
1960 0 croak_helper ($opt_ref, "usage errror", undef);
1961 }
1962  
1963 5 DBUG_RETURN ( $value );
1964 }
1965  
1966  
1967 #######################################
1968  
1969 =item $value = $cfg->get_filename ( $tag[, $access[, %override_get_opts]] );
1970  
1971 Treats the B<tag>'s value as a filename. If the referenced file doesn't exist
1972 it returns I<undef> instead, as if the B<tag> didn't exist.
1973  
1974 B<access> defines the minimum access required. If that minimum access isn't
1975 met it returns I<undef> instead, as if the B<tag> didn't exist. B<access>
1976 may be I<undef> to just check for existence.
1977  
1978 The B<access> levels are B<r> for read, B<w> for write and B<x> for execute.
1979 You may also combine them if you wish in any order.
1980 Ex: B<rw>, B<xwr>, B<rx> ...
1981  
1982 =cut
1983  
1984 sub get_filename
1985 15 ▶{
Subroutine get_filename: called CC=6 SCAR=23.0
Pod documented
1986 15 DBUG_ENTER_FUNC ( @_ );
1987 15 my $self = shift; # Reference to the current section.
1988 15 my $tag = shift; # The tag to look up ...
1989 15 my $access = shift; # undef or contains "r", "w" and/or "x" ...
1990 15 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
1991  
1992 # Verify that the tag's value points to an existing filename ...
1993 15 local $opt_ref->{filename} = 1; # Existance ...
1994 15 ▶ if ( defined $access ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $access) 0 15 15
1995 0 ▶ $opt_ref->{filename} |= 2 if ( $access =~ m/[rR]/ ); # -r--
Branch: 1 branch
BranchTrueFalseTotal
if $access =~ /[rR]/ 0 0 0
1996 0 ▶ $opt_ref->{filename} |= 4 if ( $access =~ m/[wW]/ ); # --w-
Branch: 1 branch
BranchTrueFalseTotal
if $access =~ /[wW]/ 0 0 0
1997 0 ▶ $opt_ref->{filename} |= 2 | 8 if ( $access =~ m/[xX]/ ); # -r-x
Branch: 1 branch
BranchTrueFalseTotal
if $access =~ /[xX]/ 0 0 0
1998 }
1999  
2000 15 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
2001 15 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 15 15
2002  
2003 15 DBUG_RETURN ( $value );
2004 }
2005  
2006  
2007 #######################################
2008  
2009 =item $value = $cfg->get_directory ( $tag[, $access[, %override_get_opts]] );
2010  
2011 Treats the B<tag>'s value as a directory. If the referenced directory doesn't
2012 exist it returns I<undef> instead, as if the B<tag> didn't exist.
2013  
2014 B<access> defines the minimum access required. If that minimum access isn't met
2015 it returns I<undef> instead, as if the B<tag> didn't exist. B<access> may be
2016 I<undef> to just check for existence.
2017  
2018 The B<access> levels are B<r> for read and B<w> for write. You may also combine
2019 them if you wish in any order. Ex: B<rw> or B<wr>.
2020  
2021  
2022 =cut
2023  
2024 sub get_directory
2025 16 ▶{
Subroutine get_directory: called CC=5 SCAR=16.1
Pod documented
2026 16 DBUG_ENTER_FUNC ( @_ );
2027 16 my $self = shift; # Reference to the current section.
2028 16 my $tag = shift; # The tag to look up ...
2029 16 my $access = shift; # undef or contains "r" and/or "w" ...
2030 16 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2031  
2032 # Verify that the tag's value points to an existing directory ...
2033 # Execute permission is always required to reference a directory's contents.
2034 16 local $opt_ref->{directory} = 1; # Existance ...
2035 16 ▶ if ( defined $access ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $access) 4 12 16
2036 4 ▶ $opt_ref->{directory} |= 2 | 8 if ( $access =~ m/[rR]/ ); # dr-x
Branch: 1 branch
BranchTrueFalseTotal
if $access =~ /[rR]/ 4 0 4
2037 4 ▶ $opt_ref->{directory} |= 4 | 8 if ( $access =~ m/[wW]/ ); # d-wx
Branch: 1 branch
BranchTrueFalseTotal
if $access =~ /[wW]/ 1 3 4
2038 }
2039  
2040 16 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
2041 16 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 16 16
2042  
2043 16 DBUG_RETURN ( $value );
2044 }
2045  
2046 #######################################
2047  
2048 =back
2049  
2050 =head2 Accessing the contents of an Advanced::Config object in LIST mode.
2051  
2052 These methods allow you to access the data loaded into each B<tag> in list mode.
2053 Splitting the B<tag>'s data up into arrays and hashes. Otherwise these
2054 functions behave similarly to the one's above.
2055  
2056 Each function asks for a I<pattern> used to split the B<tag>'s value into an
2057 array of values. If the pattern is B<undef> it will use the default
2058 I<split_pattern> specified during he call to F<new()>. Otherwise it can be
2059 either a string or a RegEx. See Perl's I<split> function for more details.
2060 After the value has been split, it will perform any requested validation and
2061 most functions will return B<undef> if even one element in the list fails it's
2062 edits. It was added as its own argument, instead of just relying on the
2063 override option hash, since this option is probably the one that gets overridden
2064 most often.
2065  
2066 They also support the same I<inherit> and I<required> options described for the
2067 scalar functions as well.
2068  
2069 They also all allow F<%override_get_opts>, passed by value or by reference, as
2070 an optional argument that overrides the default options provided in the call
2071 to F<new()>. If you should use both option I<split_pattern> and the I<pattern>
2072 argument, the I<pattern> argument takes precedence. So leave this optional
2073 hash argument off if you are happy with the current defaults.
2074  
2075 =over
2076  
2077 =item $array_ref = $cfg->get_list_values ( $tag[, $pattern[, $sort[, %override_get_opts ]]] );
2078  
2079 This function looks up the requested B<tag>'s value and then splits it up into
2080 an array and returns a reference to it.
2081  
2082 If I<sort> is 1 it does an ascending sort. If I<sort> is -1, it will do a
2083 descending sort instead. By default it will do no sort.
2084  
2085 See the common section above for more details.
2086  
2087 =cut
2088  
2089 sub get_list_values
2090 177 ▶{
Subroutine get_list_values: called CC=2 SCAR=6.9
Pod documented
2091 177 DBUG_ENTER_FUNC ( @_ );
2092 177 my $self = shift; # Reference to the current section.
2093 177 my $tag = shift; # The tag to look up ...
2094 177 my $split_ptrn = shift; # The split pattern to use to call to split().
2095 177 my $sort = shift; # The sort order.
2096 177 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2097  
2098 # Tells us to split the tag's value up into an array ...
2099 177 local $opt_ref->{split} = 1;
2100  
2101 # Tells how to spit up the tag's value ...
2102 local $opt_ref->{split_pattern} =
2103 177 $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);
2104  
2105 # Tells how to sort the resulting array ...
2106 local $opt_ref->{sort} =
2107 177 $self->_evaluate_hash_values ("sort", $opt_ref, $sort);
2108  
2109 177 my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
2110 177 ▶ DBUG_MASK (0) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 0 177 177
2111  
2112 177 DBUG_RETURN ( $value ); # An array ref or undef.
2113 }
2114  
2115  
2116 #######################################
2117  
2118 =item $hash_ref = $cfg->get_hash_values ( $tag[, $pattern[, $value[, \%merge[, %override_get_opts]]]] );
2119  
2120 This method is a bit more complex than L<get_list_values>. Like that method it
2121 splits up the B<tag>'s value into an array. But it then converts that array
2122 into the keys of a hash whose value for each entry is set to I<value>.
2123  
2124 Then if the optional I<merge> hash reference was provided, and that key isn't
2125 present in that hash, it adds the missing value to the I<merge> hash. It never
2126 overrides any existing entries in the I<merge> hash!
2127  
2128 It always returns the hash reference based on the B<tag>'s split value or an
2129 empty hash if the B<tag> doesn't exist or has no value.
2130  
2131 =cut
2132  
2133 sub get_hash_values
2134 17 ▶{
Subroutine get_hash_values: called CC=7 SCAR=19.5
Pod documented
2135 17 DBUG_ENTER_FUNC ( @_ );
2136 17 my $self = shift; # Reference to the current section.
2137 17 my $tag = shift; # The tag to look up ...
2138 17 my $split_ptrn = shift; # The split pattern to use to call to split().
2139 17 my $hash_value = shift; # Value to assign to each hash member.
2140 17 my $merge_ref = shift; # A hash to merge the results into
2141 # my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2142  
2143 17 my $key_vals = $self->get_list_values ($tag, $split_ptrn, 0, @_);
2144  
2145 17 my %my_hash;
2146 17 ▶ if ( $key_vals ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($key_vals) 17 0 17
2147 # Will we be merging the results into a different hash?
2148 17 ▶ my $m_flg = ( $merge_ref && ref ($merge_ref) eq "HASH" ) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$merge_ref && ref $merge_ref eq 'HASH' ? : 5 12 17
Condition66%2/3
$merge_ref and ref $merge_ref eq "HASH"
!ll&&!rl&&r
1205
MC/DC50%1/2
$merge_ref and ref $merge_ref eq "HASH"
$merge_ref ref $merge_ref eq "HASH"
Truth table66%2/3
A and B
A= $merge_refB= ref $merge_ref eq "HASH"
ABresult
0X0
100
111
2149  
2150 # Build the hash(s) from the array ...
2151 17 foreach ( @{$key_vals} ) {
2152 106 $my_hash{$_} = $hash_value;
2153 106 ▶ if ( $m_flg && ! exists $merge_ref->{$_} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($m_flg and not exists $merge_ref->{$_}) 11 95 106
Condition100%3/3
$m_flg and not exists $merge_ref->{$_}
!ll&&!rl&&r
90511
MC/DC100%2/2
$m_flg and not exists $merge_ref->{$_}
$m_flg not exists $merge_ref->{$_}
Truth table100%3/3
A and not(B)
A= $m_flgB= not exists $merge_ref->{$_}
ABresult
0X0
100
111
2154 11 $merge_ref->{$_} = $hash_value;
2155 }
2156 }
2157 }
2158  
2159 17 DBUG_RETURN ( \%my_hash );
2160 }
2161  
2162  
2163 #######################################
2164  
2165 =item $array_ref = $cfg->get_list_integer ( $tag[, $rt_flag[, $pattern[, $sort[, %override_get_opts]]]] );
2166  
2167 This is the list version of F<get_integer>. See that function for the meaning
2168 of I<$rt_flag>. See F<get_list_values> for the meaning of I<$pattern> and
2169 I<$sort>.
2170  
2171 =cut
2172  
2173 sub get_list_integer
2174 54 ▶{
Subroutine get_list_integer: called CC=1 SCAR=0.0
Pod documented
2175 54 DBUG_ENTER_FUNC ( @_ );
2176 54 my $self = shift; # Reference to the current section.
2177 54 my $tag = shift; # The tag to look up ...
2178 54 my $rt_flag = shift; # 1 - truncate, 0 - rounding.
2179 54 my $split_ptrn = shift; # The split pattern to use to call to split().
2180 54 my $sort = shift; # The sort order.
2181 54 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2182  
2183 # Tells us to split the tag's value up into an array ...
2184 54 local $opt_ref->{split} = 1;
2185  
2186 # Tells how to spit up the tag's value ...
2187 local $opt_ref->{split_pattern} =
2188 54 $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);
2189  
2190 # Tells how to sort the resulting array ...
2191 local $opt_ref->{sort} =
2192 54 $self->_evaluate_hash_values ("sort", $opt_ref, $sort);
2193  
2194 54 my $value = $self->get_integer ( $tag, $rt_flag, $opt_ref );
2195  
2196 54 DBUG_RETURN ( $value ); # An array ref or undef.
2197 }
2198  
2199  
2200 #######################################
2201  
2202 =item $array_ref = $cfg->get_list_numeric ( $tag[, $pattern[, $sort[, %override_get_opts]]] );
2203  
2204 This is the list version of F<get_numeric>. See F<get_list_values> for the
2205 meaning of I<$pattern> and I<$sort>.
2206  
2207 =cut
2208  
2209 sub get_list_numeric
2210 27 ▶{
Subroutine get_list_numeric: called CC=1 SCAR=0.0
Pod documented
2211 27 DBUG_ENTER_FUNC ( @_ );
2212 27 my $self = shift; # Reference to the current section.
2213 27 my $tag = shift; # The tag to look up ...
2214 27 my $split_ptrn = shift; # The split pattern to use to call to split().
2215 27 my $sort = shift; # The sort order.
2216 27 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2217  
2218 # Tells us to split the tag's value up into an array ...
2219 27 local $opt_ref->{split} = 1;
2220  
2221 # Tells how to spit up the tag's value ...
2222 local $opt_ref->{split_pattern} =
2223 27 $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);
2224  
2225 # Tells how to sort the resulting array ...
2226 local $opt_ref->{sort} =
2227 27 $self->_evaluate_hash_values ("sort", $opt_ref, $sort);
2228  
2229 27 my $value = $self->get_numeric ( $tag, $opt_ref );
2230  
2231 27 DBUG_RETURN ( $value ); # An array ref or undef.
2232 }
2233  
2234  
2235 #######################################
2236  
2237 =item $array_ref = $cfg->get_list_boolean ( $tag[, $pattern[, %override_get_opts]] );
2238  
2239 This is the list version of F<get_boolean>. See F<get_list_values> for the
2240 meaning of I<$pattern>.
2241  
2242 =cut
2243  
2244 sub get_list_boolean
2245 2 ▶{
Subroutine get_list_boolean: called CC=1 SCAR=0.0
Pod documented
2246 2 DBUG_ENTER_FUNC ( @_ );
2247 2 my $self = shift; # Reference to the current section.
2248 2 my $tag = shift; # The tag to look up ...
2249 2 my $split_ptrn = shift; # The split pattern to use to call to split().
2250 2 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2251  
2252 # Tells us to split the tag's value up into an array ...
2253 2 local $opt_ref->{split} = 1;
2254  
2255 # Tells how to spit up the tag's value ...
2256 local $opt_ref->{split_pattern} =
2257 2 $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);
2258  
2259 2 my $value = $self->get_boolean ( $tag, $opt_ref );
2260  
2261 2 DBUG_RETURN ( $value ); # An array ref or undef.
2262 }
2263  
2264  
2265 #######################################
2266  
2267 =item $array_ref = $cfg->get_list_date ( $tag, $pattern[, $language[, %override_get_opts]] );
2268  
2269 This is the list version of F<get_date>. See F<get_list_values> for the
2270 meaning of I<$pattern>. In this case I<$pattern> is a required option since
2271 dates bring unique parsing challenges and the default value usually isn't good
2272 enough.
2273  
2274 =cut
2275  
2276 sub get_list_date
2277 2 ▶{
Subroutine get_list_date: called CC=3 SCAR=11.3
Pod documented
2278 2 DBUG_ENTER_FUNC ( @_ );
2279 2 my $self = shift; # Reference to the current section.
2280 2 my $tag = shift; # The tag to look up ...
2281 2 my $split_ptrn = shift; # The split pattern to use to call to split().
2282 2 my $language = shift; # The languate the date appears in ...
2283 2 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2284  
2285 # Tells us to split the tag's value up into an array ...
2286 2 local $opt_ref->{split} = 1;
2287  
2288 # Tells how to spit up the tag's value ... (it's required this time!)
2289 # So allow in either place, argument or option.
2290 2 ▶ $split_ptrn = $opt_ref->{split_pattern} unless ( defined $split_ptrn );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $split_ptrn 0 2 2
2291 2 ▶ unless ( defined $split_ptrn ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $split_ptrn) 0 2 2
2292 0 my $msg = "Missing required \$pattern argument in call to get_list_date()!\n";
2293 0 die ( $msg );
2294 }
2295  
2296 2 local $opt_ref->{split_pattern} = $split_ptrn;
2297  
2298 2 my $value = $self->get_date ( $tag, $language, $opt_ref );
2299  
2300 2 DBUG_RETURN ( $value ); # An array ref or undef.
2301 }
2302  
2303  
2304 #######################################
2305  
2306 =item $array_ref = $cfg->get_list_filename ( $tag[, $access[, $pattern[, %override_get_opts]]] );
2307  
2308 This is the list version of F<get_filename>. See that function for the meaning
2309 of I<$access>. See F<get_list_values> for the meaning of I<$pattern>.
2310  
2311 =cut
2312  
2313 sub get_list_filename
2314 2 ▶{
Subroutine get_list_filename: called CC=1 SCAR=0.0
Pod documented
2315 2 DBUG_ENTER_FUNC ( @_ );
2316 2 my $self = shift; # Reference to the current section.
2317 2 my $tag = shift; # The tag to look up ...
2318 2 my $access = shift; # undef or contains "r", "w" and/or "x" ...
2319 2 my $split_ptrn = shift; # The split pattern to use to call to split().
2320 2 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2321  
2322 # Tells us to split the tag's value up into an array ...
2323 2 local $opt_ref->{split} = 1;
2324  
2325 # Tells how to spit up the tag's value ...
2326 local $opt_ref->{split_pattern} =
2327 2 $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);
2328  
2329 2 my $value = $self->get_filename ( $tag, $access, $opt_ref );
2330  
2331 2 DBUG_RETURN ( $value ); # An array ref or undef.
2332 }
2333  
2334  
2335 #######################################
2336  
2337 =item $array_ref = $cfg->get_list_directory ( $tag[, $access[, $pattern[, %override_get_opts]]] );
2338  
2339 This is the list version of F<get_directory>. See that function for the meaning
2340 of I<$access>. See F<get_list_values> for the meaning of I<$pattern>.
2341  
2342 =cut
2343  
2344 sub get_list_directory
2345 2 ▶{
Subroutine get_list_directory: called CC=1 SCAR=0.0
Pod documented
2346 2 DBUG_ENTER_FUNC ( @_ );
2347 2 my $self = shift; # Reference to the current section.
2348 2 my $tag = shift; # The tag to look up ...
2349 2 my $access = shift; # undef or contains "r", "w" and/or "x" ...
2350 2 my $split_ptrn = shift; # The split pattern to use to call to split().
2351 2 my $opt_ref = $self->_get_opt_args ( @_ ); # The override options ...
2352  
2353 # Tells us to split the tag's value up into an array ...
2354 2 local $opt_ref->{split} = 1;
2355  
2356 # Tells how to spit up the tag's value ...
2357 local $opt_ref->{split_pattern} =
2358 2 $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);
2359  
2360 2 my $value = $self->get_directory ( $tag, $access, $opt_ref );
2361  
2362 2 DBUG_RETURN ( $value ); # An array ref or undef.
2363 }
2364  
2365  
2366 #######################################
2367 # Private method ...
2368 # Returns (Worked, Hide)
2369 # Caller either wants both values or none of them.
2370 # Should never write to fish ...
2371 sub _base_set
2372 34144 ▶{
Subroutine _base_set: called CC=17 SCAR=28.4
2373 34144 my $self = shift;
2374 34144 my $tag = shift;
2375 34144 my $value = shift;
2376 34144 ▶ my $file = shift || ""; # The file the tag was defined in.
Condition100%2/2
shift() || ''
l!l
33943201
MC/DC100%1/1
shift() || ''
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
2377 34144 ▶ my $force_sensitive = shift || 0;
Condition100%2/2
shift() || 0
l!l
85933285
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
2378 34144 ▶ my $still_encrypted = shift || 0;
Condition100%2/2
shift() || 0
l!l
1434130
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
2379 34144 ▶ my $has_variables = shift || 0;
Condition100%2/2
shift() || 0
l!l
11334031
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
2380  
2381 # Get the main/parent section to work against!
2382 # my $pcfg = $self->get_section();
2383 34144 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
2973244120
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2384  
2385 # Check if case insensitive handling was requested ...
2386 34144 ▶ $tag = lc ($tag) if ( $pcfg->{CONTROL}->{read_opts}->{tag_case} );
Branch: 1 branch
BranchTrueFalseTotal
if $pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} 225 33919 34144
2387  
2388 34144 ▶ if ( $tag =~ m/^shft3+$/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag =~ /^shft3+$/i) 0 34144 34144
2389 0 return ( 0, 0 ); # Set failed ... tag name not allowed.
2390 }
2391  
2392 34144 ▶ my $hide = ($force_sensitive || $self->{SENSITIVE_SECTION}) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$force_sensitive || $self->{'SENSITIVE_SECTION'} ? : 860 33284 34144
Condition100%3/3
$force_sensitive or $self->{"SENSITIVE_SECTION"}
l!l&&r!l&&!r
859133284
MC/DC100%2/2
$force_sensitive or $self->{"SENSITIVE_SECTION"}
$force_sensitive $self->{"SENSITIVE_SECTION"}
Truth table100%3/3
A or B
A= $force_sensitiveB= $self->{"SENSITIVE_SECTION"}
ABresult
1X1
011
000
2393  
2394 34144 ▶ if ( exists $self->{DATA}->{$tag} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{'DATA'}{$tag}) { } 1568 32576 34144
2395 1568 ▶ $hide = 1 if ( $self->{DATA}->{$tag}->{MASK_IN_FISH} );
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"DATA"}{$tag}{"MASK_IN_FISH"} 56 1512 1568
2396 } else {
2397 32576 my %data;
2398 32576 $self->{DATA}->{$tag} = \%data;
2399 32576 ▶ unless ( $hide ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($hide) 31782 794 32576
2400 31782 ▶ $hide = 1 if ( should_we_hide_sensitive_data ($tag, 1) );
Branch: 1 branch
BranchTrueFalseTotal
if should_we_hide_sensitive_data($tag, 1) 7 31775 31782
2401 }
2402 }
2403  
2404 # The value must never be undefined!
2405 34144 ▶ $self->{DATA}->{$tag}->{VALUE} = (defined $value) ? $value : "";
Branch: 1 branch
BranchTrueFalseTotal
defined $value ? : 34144 0 34144
2406  
2407 # What file the tag was found in ...
2408 34144 $self->{DATA}->{$tag}->{FILE} = $file;
2409  
2410 # Must it be hidden in the fish logs?
2411 34144 $self->{DATA}->{$tag}->{MASK_IN_FISH} = $hide;
2412  
2413 # Is the value still encrypted?
2414 34144 ▶ $self->{DATA}->{$tag}->{ENCRYPTED} = $still_encrypted ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$still_encrypted ? : 14 34130 34144
2415  
2416 # Does the value still reference variables?
2417 34144 ▶ $self->{DATA}->{$tag}->{VARIABLE} = $has_variables ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$has_variables ? : 113 34031 34144
2418  
2419 34144 return ( 1, $hide );
2420 }
2421  
2422  
2423 #######################################
2424  
2425 =back
2426  
2427 =head2 Manipulating the contents of an Advanced::Config object.
2428  
2429 These methods allow you to manipulate the contents of an B<Advanced::Config>
2430 object in many ways. They all just update what's in memory and not the contents
2431 of the config file itself.
2432  
2433 So should the contents of this module get refreshed, you will loose any changes
2434 made by these B<4> methods.
2435  
2436 =over
2437  
2438 =item $ok = $cfg->set_value ( $tag, $value );
2439  
2440 Adds the requested I<$tag> and it's I<$value> to the current section in the
2441 I<Advanced::Config> object.
2442  
2443 If the I<$tag> already exists, it will be overridden with its new I<$value>.
2444  
2445 It returns B<1> on success or B<0> if your request was rejected!
2446 It will also print a warning if it was rejected.
2447  
2448 =cut
2449  
2450 sub set_value
2451 28 ▶{
Subroutine set_value: called CC=4 SCAR=14.0
Pod documented
2452 28 my $self = shift; # Reference to the current section of the object.
2453 28 my $tag = shift; # The tag set to value ...
2454 28 my $value = shift;
2455  
2456 28 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 1 27 28
2457 1 die ("You may not modify a rules config file!\n");
2458 0 return (0);
2459 }
2460  
2461 27 my ( $worked, $sensitive ) = $self->_base_set ($tag, $value, undef);
2462  
2463 27 ▶ DBUG_MASK_NEXT_FUNC_CALL (2) if ( $sensitive );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive 2 25 27
2464 27 DBUG_ENTER_FUNC ( $self, $tag, $value, @_ );
2465  
2466 27 ▶ unless ( $worked ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($worked) 0 27 27
2467 0 warn ("You may not use \"${tag}\" as your tag name!\n");
2468 }
2469  
2470 27 DBUG_RETURN ($worked);
2471 }
2472  
2473 #######################################
2474  
2475 =item $bool = $cfg->rename_tag ( $old_tag, $new_tag );
2476  
2477 Renames the tag found in the current section to it's new name. If the
2478 I<$new_tag> already exists it is overwriting by I<$old_tag>. If I<$old_tag>
2479 doesn't exist the rename fails.
2480  
2481 Returns B<1> on success, B<0> on failure.
2482  
2483 =cut
2484  
2485 sub rename_tag
2486 25 ▶{
Subroutine rename_tag: called CC=11 SCAR=32.3
Pod documented
2487 25 DBUG_ENTER_FUNC (@_);
2488 25 my $self = shift;
2489 25 my $old_tag = shift;
2490 25 my $new_tag = shift;
2491  
2492 25 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 1 24 25
2493 1 die ("You may not modify a rules config file!\n");
2494 0 return DBUG_RETURN (0);
2495 }
2496  
2497 24 ▶ unless ( defined $old_tag && defined $new_tag ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $old_tag and defined $new_tag) 0 24 24
Condition33%1/3
defined $old_tag and defined $new_tag
!ll&&!rl&&r
0024
MC/DC0%0/2
defined $old_tag and defined $new_tag
defined $old_tag defined $new_tag
Truth table33%1/3
A and B
A= defined $old_tagB= defined $new_tag
ABresult
0X0
100
111
2498 0 warn ("All arguments to rename_tag() are required!\n");
2499 0 return DBUG_RETURN (0);
2500 }
2501  
2502 24 ▶ if ( $new_tag =~ m/^shft3+$/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($new_tag =~ /^shft3+$/i) 0 24 24
2503 0 warn ("You may not use \"${new_tag}\" as your new tag name!\n");
2504 0 return DBUG_RETURN (0);
2505 }
2506  
2507 # Get the main/parent section to work against!
2508 24 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
0240
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2509  
2510 # Check if a case insensitive lookup was requested ...
2511 24 ▶ if ( $pcfg->{CONTROL}->{read_opts}->{tag_case} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pcfg->{"CONTROL"}{"read_opts"}{"tag_case"}) 0 24 24
2512 0 ▶ $old_tag = lc ($old_tag) if ( $old_tag );
Branch: 1 branch
BranchTrueFalseTotal
if $old_tag 0 0 0
2513 0 ▶ $new_tag = lc ($new_tag) if ( $new_tag );
Branch: 1 branch
BranchTrueFalseTotal
if $new_tag 0 0 0
2514 }
2515  
2516 24 ▶ if ( $old_tag eq $new_tag ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($old_tag eq $new_tag) 0 24 24
2517 0 warn ("The new tag name must be different from the old tag name!\n");
2518 0 return DBUG_RETURN (0);
2519 }
2520  
2521 # Was there something to rename ???
2522 24 ▶ if ( exists $self->{DATA}->{$old_tag} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{"DATA"}{$old_tag}) 24 0 24
2523 24 $self->{DATA}->{$new_tag} = $self->{DATA}->{$old_tag};
2524 24 delete ( $self->{DATA}->{$old_tag} );
2525 24 return DBUG_RETURN (1);
2526 }
2527  
2528 0 DBUG_RETURN (0);
2529 }
2530  
2531 #######################################
2532  
2533 =item $bool = $cfg->move_tag ( $tag, $new_section[, $new_tag] );
2534  
2535 This function moves the tag from the current section to the specified new
2536 section. If I<$new_tag> was provided that will be the tag's new name in
2537 the new section. If the tag already exists in the new section it will be
2538 overwritten.
2539  
2540 If the tag or the new section doesn't exist, the move will fail! It will also
2541 fail if the new section is the current section.
2542  
2543 Returns B<1> on success, B<0> on failure.
2544  
2545 =cut
2546  
2547 sub move_tag
2548 1 ▶{
Subroutine move_tag: called CC=12 SCAR=44.5
Pod documented
2549 1 DBUG_ENTER_FUNC (@_);
2550 1 my $self = shift;
2551 1 my $tag = shift;
2552 1 my $new_section = shift;
2553 1 my $new_tag = shift;
2554  
2555 1 ▶ $new_tag = $tag unless ( defined $new_tag );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $new_tag 1 0 1
2556  
2557 1 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 1 0 1
2558 1 die ("You may not modify a rules config file!\n");
2559 0 return DBUG_RETURN (0);
2560 }
2561  
2562 0 ▶ unless ( defined $tag && defined $new_section ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $tag and defined $new_section) 0 0 0
Condition0%0/3
defined $tag and defined $new_section
!ll&&!rl&&r
000
MC/DC0%0/2
defined $tag and defined $new_section
defined $tag defined $new_section
Truth table0%0/3
A and B
A= defined $tagB= defined $new_section
ABresult
0X0
100
111
2563 0 warn ("Both \$tag and \$new_section are required for move_tag()!\n");
2564 0 return DBUG_RETURN (0);
2565 }
2566  
2567 0 ▶ if ( $new_tag =~ m/^shft3+$/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($new_tag =~ /^shft3+$/i) 0 0 0
2568 0 warn ("You may not use \"${new_tag}\" as your new tag name!\n");
2569 0 return DBUG_RETURN (0);
2570 }
2571  
2572 # Get the main/parent section to work against!
2573 0 ▶ my $pcfg = $self->{PARENT} || $self;
Condition0%0/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table0%0/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2574  
2575 # Check if a case insensitive lookup was requested ...
2576 0 ▶ $tag = lc ($tag) if ( $pcfg->{CONTROL}->{read_opts}->{tag_case} && $tag );
Branch: 1 branch
BranchTrueFalseTotal
if $pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag 0 0 0
Condition0%0/3
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag
!ll&&!rl&&r
000
MC/DC0%0/2
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} $tag
Truth table0%0/3
A and B
A= $pcfg->{"CONTROL"}{"read_opts"}{"tag_case"}B= $tag
ABresult
0X0
100
111
2577  
2578 0 ▶ my $cfg = $self->get_section ( $new_section ) || $self;
Condition0%0/3
$self->get_section($new_section) || $self
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->get_section($new_section) || $self
$self->get_section($new_section) $self
Truth table0%0/3
A || B
A= $self->get_section($new_section)B= $self
ABresult
1X1
011
000
2579  
2580 0 ▶ if ( $self ne $cfg && exists $self->{DATA}->{$tag} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self ne $cfg and exists $self->{"DATA"}{$tag}) 0 0 0
Condition0%0/3
$self ne $cfg and exists $self->{"DATA"}{$tag}
!ll&&!rl&&r
000
MC/DC0%0/2
$self ne $cfg and exists $self->{"DATA"}{$tag}
$self ne $cfg exists $self->{"DATA"}{$tag}
Truth table0%0/3
A and B
A= $self ne $cfgB= exists $self->{"DATA"}{$tag}
ABresult
0X0
100
111
2581 0 $cfg->{DATA}->{$new_tag} = $self->{DATA}->{$tag};
2582 0 delete ( $self->{DATA}->{$tag} );
2583 0 return DBUG_RETURN (1);
2584 }
2585  
2586 0 DBUG_RETURN (0);
2587 }
2588  
2589 #######################################
2590  
2591 =item $bool = $cfg->delete_tag ( $tag );
2592  
2593 This function removes the requested I<$tag> found in the current section from
2594 the configuration data in memory.
2595  
2596 Returns B<1> on success, B<0> if the I<$tag> didn't exist.
2597  
2598 =cut
2599  
2600 sub delete_tag
2601 1 ▶{
Subroutine delete_tag: called CC=7 SCAR=34.3
Pod documented
2602 1 DBUG_ENTER_FUNC (@_);
2603 1 my $self = shift;
2604 1 my $tag = shift;
2605  
2606 1 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 1 0 1
2607 1 die ("You may not modify a rules config file!\n");
2608 0 return DBUG_RETURN (0);
2609 }
2610  
2611 0 ▶ unless ( defined $tag ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $tag) 0 0 0
2612 0 return DBUG_RETURN (0); # Nothing to delete!
2613 }
2614  
2615 # Get the main/parent section to work against!
2616 0 ▶ my $pcfg = $self->{PARENT} || $self;
Condition0%0/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table0%0/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2617  
2618 # Check if a case insensitive lookup was requested ...
2619 0 ▶ $tag = lc ($tag) if ( $pcfg->{CONTROL}->{read_opts}->{tag_case} && $tag );
Branch: 1 branch
BranchTrueFalseTotal
if $pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag 0 0 0
Condition0%0/3
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag
!ll&&!rl&&r
000
MC/DC0%0/2
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} and $tag
$pcfg->{"CONTROL"}{"read_opts"}{"tag_case"} $tag
Truth table0%0/3
A and B
A= $pcfg->{"CONTROL"}{"read_opts"}{"tag_case"}B= $tag
ABresult
0X0
100
111
2620  
2621 # Was there something to delete ???
2622 0 ▶ if ( exists $self->{DATA}->{$tag} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{"DATA"}{$tag}) 0 0 0
2623 0 delete ( $self->{DATA}->{$tag} );
2624 0 return DBUG_RETURN (1);
2625 }
2626  
2627 0 DBUG_RETURN (0);
2628 }
2629  
2630 #######################################
2631  
2632 =back
2633  
2634 =head2 Breaking your Advanced::Config object into Sections.
2635  
2636 Defining sections allow you to break up your configuration files into multiple
2637 independent parts. Or in advanced configurations using sections to override
2638 default values defined in the main/unlabled section.
2639  
2640 =over
2641  
2642 =item $section = $cfg->get_section ( [$section_name[, $required]] );
2643  
2644 Returns the I<Advanced::Config> object for the requested section in your config
2645 file. If the I<$section_name> doesn't exist, it will return I<undef>. If
2646 I<$required> is set, it will call B<die> instead.
2647  
2648 If no I<$section_name> was provided, it returns the default I<main> section.
2649  
2650 =cut
2651  
2652 sub get_section
2653 73653 ▶{
Subroutine get_section: called CC=7 SCAR=19.5
Pod documented
2654 73653 DBUG_ENTER_FUNC ( @_ );
2655 73653 my $self = shift;
2656 73653 my $section = shift;
2657 73653 ▶ my $required = shift || 0;
Condition100%2/2
shift() || 0
l!l
3425339400
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
2658  
2659 73653 ▶ $self = $self->{PARENT} || $self; # Force to parent section ...
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
31696419570
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2660  
2661 73653 ▶ unless ( defined $section ) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $section) { } 37954 35699 73653
if (do { $section =~ /^\s*$/ }) { } 179 37775 37954
2662 35699 $section = DEFAULT_SECTION;
2663 } elsif ( $section =~ m/^\s*$/ ) {
2664 179 $section = DEFAULT_SECTION;
2665 } else {
2666 37775 $section = lc ($section);
2667 37775 $section =~ s/^\s+//;
2668 37775 $section =~ s/\s+$//;
2669 }
2670  
2671 73653 ▶ if ( exists $self->{SECTIONS}->{$section} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{"SECTIONS"}{$section}) 72914 739 73653
2672 DBUG_PRINT ("DBUG", "The section name is '%s'",
2673 72914 $self->{SECTIONS}->{$section}->{SECTION_NAME});
2674 72914 return DBUG_RETURN ( $self->{SECTIONS}->{$section} );
2675 }
2676  
2677 739 ▶ if ( $required ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($required) 0 739 739
2678 0 die ("Section \"$section\" doesn't exist in this ", __PACKAGE__,
2679 " class!\n");
2680 }
2681  
2682 739 DBUG_RETURN (undef);
2683 }
2684  
2685 #######################################
2686  
2687 =item $name = $cfg->section_name ( );
2688  
2689 This function returns the name of the current section I<$cfg> points to.
2690  
2691 =cut
2692  
2693 sub section_name
2694 901 ▶{
Subroutine section_name: called CC=1 SCAR=0.0
Pod documented
2695 901 DBUG_ENTER_FUNC ( @_ );
2696 901 my $self = shift;
2697 901 DBUG_RETURN ( $self->{SECTION_NAME} );
2698 }
2699  
2700 #######################################
2701  
2702 =item $scfg = $cfg->create_section ( $name );
2703  
2704 Creates a new section called I<$name> within the current Advanced::Config object
2705 I<$cfg>. It returns the I<Advanced::Config> object that it created. If a
2706 section of that same name already exists it will return B<undef>.
2707  
2708 There is no such thing as sub-sections, so if I<$cfg> is already points to a
2709 section, then it looks up the parent object and associates the new section with
2710 the parent object instead.
2711  
2712 =cut
2713  
2714 sub create_section
2715 353 ▶{
Subroutine create_section: called CC=3 SCAR=11.3
Pod documented
2716 353 DBUG_ENTER_FUNC ( @_ );
2717 353 my $self = shift;
2718 353 my $name = shift;
2719  
2720 353 ▶ if ( $self->_chk_if_read_only () ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_chk_if_read_only) 1 352 353
2721 1 die ("You may not modify a rules config file!\n");
2722 0 return DBUG_RETURN (0);
2723 }
2724  
2725 # This test bypasses all the die logic in the special case constructor!
2726 # That constructor is no longer exposed in the POD.
2727 352 ▶ if ( $self->get_section ( $name ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->get_section($name)) 0 352 352
2728 0 return DBUG_RETURN (undef); # Name is already in use ...
2729 }
2730  
2731 352 DBUG_RETURN ( $self->new_section ( $self, $name ) );
2732 }
2733  
2734 #######################################
2735  
2736 =back
2737  
2738 =head2 Searching the contents of an Advanced::Config object.
2739  
2740 This section deals with the methods available for searching for content within
2741 your B<Advanced::Config> object.
2742  
2743 =over
2744  
2745 =item @list = $cfg->find_tags ( $pattern[, $override_inherit] );
2746  
2747 It returns a list of all tags whose name contains the passed pattern.
2748  
2749 If the pattern is B<undef> or the empty string, it will return all tags in
2750 the current section. Otherwise it does a case insensitive comparison of the
2751 pattern against each tag to see if it should be returned or not.
2752  
2753 If I<override_inherit> is provided it overrides the current I<inherit> option's
2754 setting. If B<undef> it uses the current I<inherit> setting. If I<inherit>
2755 evaluates to true, it looks in the current section I<and> the main section for
2756 a match. Otherwise it just looks in the current section.
2757  
2758 The returned list of tags will be sorted in alphabetical order.
2759  
2760 =cut
2761  
2762 sub find_tags
2763 1052 ▶{
Subroutine find_tags: called CC=12 SCAR=25.3
Pod documented
2764 1052 DBUG_ENTER_FUNC (@_);
2765 1052 my $self = shift;
2766 1052 my $pattern = shift;
2767 1052 my $inherit = shift; # undef, 0, or 1.
2768  
2769 1052 my @lst; # The list of tags found ...
2770  
2771 1052 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
8522000
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2772  
2773 1052 ▶ $inherit = $pcfg->{CONTROL}->{get_opts}->{inherit} unless (defined $inherit);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $inherit 618 434 1052
2774  
2775 1052 foreach my $tag ( sort keys %{$self->{DATA}} ) {
2776 92971 ▶ unless ( $pattern ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($pattern) { } 49743 43228 92971
if (do { $tag =~ /$pattern/i }) 6286 43457 49743
2777 43228 push (@lst, $tag);
2778 0 } elsif ( $tag =~ m/${pattern}/i ) {
2779 6286 push (@lst, $tag);
2780 }
2781 }
2782  
2783 # Are we searching the parent/main section as well?
2784 1052 ▶ if ( $inherit && $pcfg != $self ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($inherit and $pcfg != $self) 4 1048 1052
Condition100%3/3
$inherit and $pcfg != $self
!ll&&!rl&&r
104534
MC/DC100%2/2
$inherit and $pcfg != $self
$inherit $pcfg != $self
Truth table100%3/3
A and B
A= $inheritB= $pcfg != $self
ABresult
0X0
100
111
2785 4 DBUG_PRINT ("INFO", "Also searching the 'main' section ...");
2786 4 foreach my $tg ( sort keys %{$pcfg->{DATA}} ) {
2787 # Ignore tags repeated from the current section
2788 32 ▶ next if ( exists $self->{DATA}->{$tg} );
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->{"DATA"}{$tg} 11 21 32
2789  
2790 21 ▶ unless ( $pattern ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($pattern) { } 0 21 21
if (do { $tg =~ /$pattern/i }) 0 0 0
2791 21 push (@lst, $tg);
2792 0 } elsif ( $tg =~ m/$pattern/i ) {
2793 0 push (@lst, $tg);
2794 }
2795 }
2796  
2797 4 @lst = sort ( @lst ); # Sort the merged list.
2798 }
2799  
2800 1052 DBUG_RETURN ( @lst );
2801 }
2802  
2803  
2804 #######################################
2805 # No pod on purpose since exposing it would just cause confusion.
2806 # It's a special case variant for find_tags().
2807 # Just called from Advanced::Config::Reader::apply_modifier.
2808  
2809 sub _find_variables
2810 2 ▶{
Subroutine _find_variables: called CC=13 SCAR=27.5
2811 2 DBUG_ENTER_FUNC (@_);
2812 2 my $self = shift;
2813 2 my $pattern = shift;
2814  
2815 2 my %res;
2816  
2817 # Find all tags begining with the pattern ...
2818 2 foreach ( $self->find_tags ("^${pattern}") ) {
2819 2 $res{$_} = 1;
2820 }
2821  
2822 # Find all environment variables starting with the given pattern ...
2823 2 foreach ( keys %ENV ) {
2824 # Never include these 2 special tags in any list ...
2825 74 ▶ next if ( defined $secret_tag && $secret_tag eq $_ );
Branch: 1 branch
BranchTrueFalseTotal
if defined $secret_tag and $secret_tag eq $_ 0 74 74
Condition33%1/3
defined $secret_tag and $secret_tag eq $_
!ll&&!rl&&r
7400
MC/DC0%0/2
defined $secret_tag and $secret_tag eq $_
defined $secret_tag $secret_tag eq $_
Truth table33%1/3
A and B
A= defined $secret_tagB= $secret_tag eq $_
ABresult
0X0
100
111
2826 74 ▶ next if ( defined $fish_tag && $fish_tag eq $_ );
Branch: 1 branch
BranchTrueFalseTotal
if defined $fish_tag and $fish_tag eq $_ 0 74 74
Condition33%1/3
defined $fish_tag and $fish_tag eq $_
!ll&&!rl&&r
7400
MC/DC0%0/2
defined $fish_tag and $fish_tag eq $_
defined $fish_tag $fish_tag eq $_
Truth table33%1/3
A and B
A= defined $fish_tagB= $fish_tag eq $_
ABresult
0X0
100
111
2827  
2828 74 ▶ $res{$_} = 4 if ( $_ =~ m/^${pattern}/ );
Branch: 1 branch
BranchTrueFalseTotal
if $_ =~ /^$pattern/ 2 72 74
2829 }
2830  
2831 # Skip checking the Perl special variables we use (rule 5)
2832 # Since it's now part of (rule 6)
2833  
2834 # Check the pre-defined module variables ... (rule 6)
2835 2 foreach ( keys %begin_special_vars ) {
2836 20 ▶ $res{$_} = 6 if ( $_ =~ m/^${pattern}/ );
Branch: 1 branch
BranchTrueFalseTotal
if $_ =~ /^$pattern/ 0 20 20
2837 }
2838  
2839 # The special date variables ... (rule 7)
2840 2 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
020
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2841 2 foreach ( keys %{$pcfg->{CONTROL}->{DATES}} ) {
2842 32 ▶ $res{$_} = 7 if ( $_ =~ m/^${pattern}/ );
Branch: 1 branch
BranchTrueFalseTotal
if $_ =~ /^$pattern/ 2 30 32
2843 }
2844  
2845 2 DBUG_RETURN ( sort keys %res );
2846 }
2847  
2848  
2849 #######################################
2850  
2851 =item @list = $cfg->find_values ( $pattern[, $override_inherit] );
2852  
2853 It returns a list of all tags whose values contains the passed pattern.
2854  
2855 If the pattern is B<undef> or the empty string, it will return all tags in
2856 the current section. Otherwise it does a case insensitive comparison of the
2857 pattern against each tag's value to see if it should be returned or not.
2858  
2859 If I<override_inherit> is provided it overrides the current I<inherit> option's
2860 setting. If B<undef> it uses the current I<inherit> setting. If I<inherit>
2861 evaluates to true, it looks in the current section I<and> the main section for
2862 a match. Otherwise it just looks in the current section.
2863  
2864 The returned list of tags will be sorted in alphabetical order.
2865  
2866 =cut
2867  
2868 sub find_values
2869 0 ▶{
Subroutine find_values: not called CC=12 SCAR=50.5
Pod documented
2870 0 DBUG_ENTER_FUNC (@_);
2871 0 my $self = shift;
2872 0 my $pattern = shift;
2873 0 my $inherit = shift;
2874  
2875 0 my @lst; # The list of tags found ...
2876  
2877 0 ▶ my $pcfg = $self->{PARENT} || $self;
Condition0%0/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table0%0/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2878  
2879 0 ▶ $inherit = $pcfg->{CONTROL}->{get_opts}->{inherit} unless (defined $inherit);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $inherit 0 0 0
2880  
2881 0 foreach my $tag ( sort keys %{$self->{DATA}} ) {
2882 0 ▶ unless ( $pattern ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pattern) { } 0 0 0
2883 0 push (@lst, $tag);
2884 } else {
2885 0 my $value = $self->{DATA}->{$tag}->{VALUE};
2886 0 ▶ if ( $value =~ m/$pattern/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /$pattern/i) 0 0 0
2887 0 push (@lst, $tag);
2888 }
2889 }
2890 }
2891  
2892 # Are we searching the parent/main section as well?
2893 0 ▶ if ( $inherit && $pcfg != $self ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($inherit and $pcfg != $self) 0 0 0
Condition0%0/3
$inherit and $pcfg != $self
!ll&&!rl&&r
000
MC/DC0%0/2
$inherit and $pcfg != $self
$inherit $pcfg != $self
Truth table0%0/3
A and B
A= $inheritB= $pcfg != $self
ABresult
0X0
100
111
2894 0 DBUG_PRINT ("INFO", "Also searching the main section ...");
2895 0 foreach my $tg ( sort keys %{$pcfg->{DATA}} ) {
2896 # Ignore tags repeated from the current section
2897 0 ▶ next if ( exists $self->{DATA}->{$tg} );
Branch: 1 branch
BranchTrueFalseTotal
if exists $self->{"DATA"}{$tg} 0 0 0
2898  
2899 0 ▶ unless ( $pattern ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pattern) { } 0 0 0
2900 0 push (@lst, $tg);
2901 } else {
2902 0 my $value = $pcfg->{DATA}->{$tg}->{VALUE};
2903 0 ▶ if ( $value =~ m/$pattern/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($value =~ /$pattern/i) 0 0 0
2904 0 push (@lst, $tg);
2905 }
2906 }
2907 }
2908  
2909 0 @lst = sort (@lst); # Sort the merged list.
2910 }
2911  
2912 0 DBUG_RETURN (@lst);
2913 }
2914  
2915 #######################################
2916  
2917 =item @list = $cfg->find_sections ( $pattern );
2918  
2919 It returns a list of all section names which match this pattern.
2920  
2921 If the pattern is B<undef> or the empty string, it will return all the section
2922 names. Otherwise it does a case insensitive comparison of the pattern against
2923 each section name to see if it should be returned or not.
2924  
2925 The returned list of section names will be sorted in alphabetical order.
2926  
2927 =cut
2928  
2929 sub find_sections
2930 189 ▶{
Subroutine find_sections: called CC=5 SCAR=16.3
Pod documented
2931 189 DBUG_ENTER_FUNC (@_);
2932 189 my $self = shift;
2933 189 my $pattern = shift;
2934  
2935 189 ▶ $self = $self->{PARENT} || $self; # Force to parent section ...
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
01890
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2936  
2937 189 my @lst;
2938 189 foreach my $name ( sort keys %{$self->{SECTIONS}} ) {
2939 1076 ▶ unless ( $pattern ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($pattern) { } 144 932 1076
if (do { $name =~ /$pattern/i }) 99 45 144
2940 932 push (@lst, $name);
2941 0 } elsif ( $name =~ m/$pattern/i ) {
2942 99 push (@lst, $name);
2943 }
2944 }
2945  
2946 189 DBUG_RETURN (@lst);
2947 }
2948  
2949  
2950 #######################################
2951  
2952 =back
2953  
2954 =head2 Miscellaneous methods against Advanced::Config object.
2955  
2956 These methods while useful don't really fall into a category of their own. So
2957 they are collected here in the miscellaneous section.
2958  
2959 =over
2960  
2961 =item $file = $cfg->filename ( );
2962  
2963 Returns the fully qualified file name used to load the config file into memory.
2964  
2965 =cut
2966  
2967 sub filename
2968 20 ▶{
Subroutine filename: called CC=2 SCAR=7.4
Pod documented
2969 20 DBUG_ENTER_FUNC ( @_ );
2970 20 my $self = shift;
2971  
2972 # The request only applies to the parent instance ...
2973 20 ▶ $self = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
0200
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2974  
2975 20 DBUG_RETURN( $self->{CONTROL}->{filename} );
2976 }
2977  
2978  
2979 #######################################
2980  
2981 =item ($ropts, $gopts, $dopts) = $cfg->get_cfg_settings ( );
2982  
2983 This method returns references to copies of the current options used to
2984 manipulate the config file. It returns copies of these hashes so feel free to
2985 modify them without fear of affecting the behavior of this module.
2986  
2987 =cut
2988  
2989 sub get_cfg_settings
2990 34837 ▶{
Subroutine get_cfg_settings: called CC=8 SCAR=23.4
Pod documented
2991 34837 DBUG_ENTER_FUNC (@_);
2992 34837 my $self = shift;
2993  
2994 # Get the main/parent section to work against!
2995 34837 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
2956552720
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
2996  
2997 34837 my $ctrl = $pcfg->{CONTROL};
2998  
2999 34837 my (%r_opts, %g_opts, %d_opts);
3000 34837 ▶ %r_opts = %{$ctrl->{read_opts}} if ( $ctrl && $ctrl->{read_opts} );
Branch: 1 branch
BranchTrueFalseTotal
if $ctrl and $ctrl->{"read_opts"} 34837 0 34837
Condition33%1/3
$ctrl and $ctrl->{"read_opts"}
!ll&&!rl&&r
0034837
MC/DC0%0/2
$ctrl and $ctrl->{"read_opts"}
$ctrl $ctrl->{"read_opts"}
Truth table33%1/3
A and B
A= $ctrlB= $ctrl->{"read_opts"}
ABresult
0X0
100
111
3001 34837 ▶ %g_opts = %{$ctrl->{get_opts}} if ( $ctrl && $ctrl->{get_opts} );
Branch: 1 branch
BranchTrueFalseTotal
if $ctrl and $ctrl->{"get_opts"} 34837 0 34837
Condition33%1/3
$ctrl and $ctrl->{"get_opts"}
!ll&&!rl&&r
0034837
MC/DC0%0/2
$ctrl and $ctrl->{"get_opts"}
$ctrl $ctrl->{"get_opts"}
Truth table33%1/3
A and B
A= $ctrlB= $ctrl->{"get_opts"}
ABresult
0X0
100
111
3002 34837 ▶ %d_opts = %{$ctrl->{date_opts}} if ( $ctrl && $ctrl->{date_opts} );
Branch: 1 branch
BranchTrueFalseTotal
if $ctrl and $ctrl->{"date_opts"} 34837 0 34837
Condition33%1/3
$ctrl and $ctrl->{"date_opts"}
!ll&&!rl&&r
0034837
MC/DC0%0/2
$ctrl and $ctrl->{"date_opts"}
$ctrl $ctrl->{"date_opts"}
Truth table33%1/3
A and B
A= $ctrlB= $ctrl->{"date_opts"}
ABresult
0X0
100
111
3003  
3004 34837 DBUG_RETURN ( \%r_opts, \%g_opts, \%d_opts );
3005 }
3006  
3007  
3008 #######################################
3009  
3010 =item $cfg->export_tag_value_to_ENV ( $tag, $value );
3011  
3012 Used to export the requested tag/value pair to the %ENV hash. If it's also
3013 marked as an %ENV tag the config file depends on, it updates internal
3014 bookkeeping so that it won't trigger false refreshes.
3015  
3016 Once it's been promoted to the %ENV hash the change can't be backed out again.
3017  
3018 =cut
3019  
3020 sub export_tag_value_to_ENV
3021 4 ▶{
Subroutine export_tag_value_to_ENV: called CC=5 SCAR=17.6
Pod documented
3022 4 my $self = shift;
3023 4 my $tag = shift;
3024 4 my $value = shift;
3025 4 ▶ my $hide = $_[0] || 0; # Not taken from stack on purpose ...
Condition50%1/2
$_[0] || 0
l!l
40
MC/DC0%0/1
$_[0] || 0
$_[0]
Truth table50%1/2
A
A= $_[0]
Aresult
11
00
3026 4 ▶ DBUG_ENTER_FUNC ( $self, $tag, ($hide ? "*"x8 : $value), @_ );
Branch: 1 branch
BranchTrueFalseTotal
$hide ? : 4 0 4
3027  
3028 4 $ENV{$tag} = $value;
3029  
3030 # Check if the change afects the refresh logic ...
3031 4 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
040
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3032 4 ▶ if ( exists $pcfg->{CONTROL}->{ENV}->{$tag} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $pcfg->{"CONTROL"}{"ENV"}{$tag}) 0 4 4
3033 0 $pcfg->{CONTROL}->{ENV}->{$tag} = $value; # It did ...
3034 }
3035  
3036 4 DBUG_VOID_RETURN ();
3037 }
3038  
3039 #######################################
3040  
3041 =item $sensitive = $cfg->chk_if_sensitive ( $tag[, $override_inherit] );
3042  
3043 This function looks up the requested tag in the current section of the config
3044 file and returns if this module thinks the existing value is sensitive (B<1>)
3045 or not (B<0>).
3046  
3047 If the tag doesn't exist, it will always return that it isn't sensitive. (B<0>)
3048  
3049 An existing tag references sensitive data if one of the following is true.
3050 1) Advanced::Config::Options::should_we_hide_sensitive_data() says it is
3051 or it says the section the tag was found in was sensitive.
3052 2) The config file marked the tag in its comment to HIDE it.
3053 3) The config file marked it as being encrypted.
3054 4) It referenced a variable that was marked as sensitive.
3055  
3056 If I<override_inherit> is provided it overrides the current I<inherit> option's
3057 setting. If B<undef> it uses the current I<inherit> setting. If I<inherit>
3058 evaluates to true, it looks in the current section I<and> the main section for
3059 a match. Otherwise it just looks in the current section for the tag.
3060  
3061 =cut
3062  
3063 sub chk_if_sensitive
3064 188 ▶{
Subroutine chk_if_sensitive: called CC=3 SCAR=11.0
Pod documented
3065 188 DBUG_ENTER_FUNC ( @_ );
3066 188 my $self = shift; # Reference to the current section.
3067 188 my $tag = shift; # The tag to look up ...
3068 188 my $inherit = shift; # undef, 0, or 1.
3069  
3070 188 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
821060
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3071  
3072 188 ▶ $inherit = $pcfg->{CONTROL}->{get_opts}->{inherit} unless (defined $inherit);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $inherit 151 37 188
3073 188 local $pcfg->{CONTROL}->{get_opts}->{inherit} = $inherit;
3074  
3075 188 my $sensitive = ($self->_base_get2 ( $tag ))[1];
3076  
3077 188 DBUG_RETURN ( $sensitive );
3078 }
3079  
3080  
3081 #######################################
3082  
3083 =item $encrypted = $cfg->chk_if_still_encrypted ( $tag[, $override_inherit] );
3084  
3085 This function looks up the requested tag in the current section of the config
3086 file and returns if this module thinks the existing value is still encrypted
3087 (B<1>) or not (B<0>).
3088  
3089 If the tag doesn't exist, it will always return B<0>!
3090  
3091 This module always automatically decrypts everything unless the "Read" option
3092 B<disable_decryption> was used. In that case this method was added to detect
3093 which tags still needed their values decrypted before they were used.
3094  
3095 If I<override_inherit> is provided it overrides the current I<inherit> option's
3096 setting. If B<undef> it uses the current I<inherit> setting. If I<inherit>
3097 evaluates to true, it looks in the current section I<and> the main section for
3098 a match. Otherwise it just looks in the current section for the tag.
3099  
3100 =cut
3101  
3102 sub chk_if_still_encrypted
3103 217 ▶{
Subroutine chk_if_still_encrypted: called CC=3 SCAR=11.1
Pod documented
3104 217 DBUG_ENTER_FUNC ( @_ );
3105 217 my $self = shift; # Reference to the current section.
3106 217 my $tag = shift; # The tag to look up ...
3107 217 my $inherit = shift; # undef, 0, or 1.
3108  
3109 217 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
132850
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3110  
3111 217 ▶ $inherit = $pcfg->{CONTROL}->{get_opts}->{inherit} unless (defined $inherit);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $inherit 217 0 217
3112 217 local $pcfg->{CONTROL}->{get_opts}->{inherit} = $inherit;
3113  
3114 217 my $encrypted = ($self->_base_get2 ( $tag ))[3];
3115  
3116 217 DBUG_RETURN ( $encrypted );
3117 }
3118  
3119  
3120 #######################################
3121  
3122 =item $bool = $cfg->chk_if_still_uses_variables ( $tag[, $override_inherit] );
3123  
3124 This function looks up the requested tag in the current section of the config
3125 file and returns if the tag's value contained variables that failed to expand
3126 when the config file was parsed. (B<1> - has variable, B<0> - none.)
3127  
3128 If the tag doesn't exist, or you called C<set_value> to create it, this function
3129 will always return B<0> for that tag!
3130  
3131 There are only two cases where it can ever return true (B<1>). The first case
3132 is when you used the B<disable_variables> option. The second case is if you
3133 used the B<disable_decryption> option and you had a variable that referenced
3134 a tag that is still encrypted. But use of those two options should be rare.
3135  
3136 If I<override_inherit> is provided it overrides the current I<inherit> option's
3137 setting. If B<undef> it uses the current I<inherit> setting. If I<inherit>
3138 evaluates to true, it looks in the current section I<and> the main section for
3139 a match. Otherwise it just looks in the current section for the tag.
3140  
3141 =cut
3142  
3143 sub chk_if_still_uses_variables
3144 415 ▶{
Subroutine chk_if_still_uses_variables: called CC=3 SCAR=11.1
Pod documented
3145 415 DBUG_ENTER_FUNC ( @_ );
3146 415 my $self = shift; # Reference to the current section.
3147 415 my $tag = shift; # The tag to look up ...
3148 415 my $inherit = shift; # undef, 0, or 1.
3149  
3150 415 ▶ my $pcfg = $self->{PARENT} || $self;
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
2641510
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3151  
3152 415 ▶ $inherit = $pcfg->{CONTROL}->{get_opts}->{inherit} unless (defined $inherit);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $inherit 415 0 415
3153 415 local $pcfg->{CONTROL}->{get_opts}->{inherit} = $inherit;
3154  
3155 415 my $bool = ($self->_base_get2 ( $tag ))[4];
3156  
3157 415 DBUG_RETURN ( $bool );
3158 }
3159  
3160  
3161 #######################################
3162  
3163 =item $string = $cfg->toString ( [$addEncryptFlags[, \%override_read_opts] );
3164  
3165 This function converts the current object into a string that is the equivalent
3166 of the config file loaded into memory without any comments.
3167  
3168 If I<$addEncryptFlags> is set to a non-zero value, it will add the needed
3169 comment to the end of each line saying it's waiting to be encrypted. So that
3170 you may later call B<encrypt_string> to encrypt it.
3171  
3172 If you provide I<%override_read_opts> it will use the information in that hash
3173 to format the string. Otherwise it will use the defaults from B<new()>.
3174  
3175 =cut
3176  
3177 sub toString
3178 3 ▶{
Subroutine toString: called CC=8 SCAR=20.9
Pod documented
3179 3 DBUG_ENTER_FUNC ( @_ );
3180 3 my $self = shift;
3181 3 my $encrypt_flag = shift;
3182 3 my $read_opts = $self->_get_opt_args ( @_ ); # The override options ...
3183  
3184 3 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
030
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3185 3 my $rOpts = get_read_opts ($read_opts, $pcfg->{CONTROL}->{read_opts});
3186  
3187 3 my $cmt = "";
3188 3 ▶ if ( $encrypt_flag ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($encrypt_flag) 2 1 3
3189 2 $cmt = " " . format_encrypt_cmt ( $rOpts );
3190 }
3191  
3192 3 my $line;
3193 3 my $string = "";
3194 3 my $cnt = 0;
3195 3 foreach my $name ( $self->find_sections () ) {
3196 6 my $cfg = $self->get_section ($name);
3197 6 $line = format_section_line ($name, $rOpts);
3198 6 $string .= "\n${line}\n";
3199  
3200 6 ▶ ++$cnt if ( should_we_hide_sensitive_data ( $name, 1 ) );
Branch: 1 branch
BranchTrueFalseTotal
if should_we_hide_sensitive_data($name, 1) 0 6 6
3201  
3202 6 foreach my $tag ( $cfg->find_tags (undef, 0) ) {
3203 24 ▶ ++$cnt if ( $cfg->chk_if_sensitive ($tag, 0) );
Branch: 1 branch
BranchTrueFalseTotal
if $cfg->chk_if_sensitive($tag, 0) 9 15 24
3204  
3205 24 $line = format_tag_value_line ($cfg, $tag, $rOpts);
3206 24 $string .= " " . ${line} . ${cmt} . "\n";
3207 }
3208 }
3209  
3210 # Mask the return value if anything seems sensitive.
3211 3 ▶ DBUG_MASK (0) if ( $cnt > 0 );
Branch: 1 branch
BranchTrueFalseTotal
if $cnt > 0 3 0 3
3212  
3213 3 DBUG_RETURN ( $string );
3214 }
3215  
3216  
3217 #######################################
3218  
3219 =item $hashRef = $cfg->toHash ( [$dropIfSensitive] );
3220  
3221 This function converts the current object into a hash reference that is the
3222 equivalent of the config file loaded into memory. Modifying the returned
3223 hash reference will not modify this object's content.
3224  
3225 If a section has no members, it will not appear in the hash.
3226  
3227 If I<$dropIfSensitive> is set to a non-zero value, it will not export any data
3228 to the returned hash reference that this module thinks is sensitive.
3229  
3230 The returned hash reference has the following keys.
3231 S<$hash_ref-E<gt>{B<section>}-E<gt>{B<tag>}>.
3232  
3233 =cut
3234  
3235 sub toHash
3236 7 ▶{
Subroutine toHash: called CC=8 SCAR=20.8
Pod documented
3237 7 DBUG_ENTER_FUNC ( @_ );
3238 7 my $self = shift;
3239 7 my $sensitive = shift;
3240  
3241 7 my %data;
3242  
3243 7 foreach my $sect ( $self->find_sections () ) {
3244 # Was the section name itself sensitive ...
3245 17 ▶ next if ( $sensitive && should_we_hide_sensitive_data ( $sect, 1 ) );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive and should_we_hide_sensitive_data($sect, 1) 0 17 17
Condition66%2/3
$sensitive and should_we_hide_sensitive_data($sect, 1)
!ll&&!rl&&r
980
MC/DC0%0/2
$sensitive and should_we_hide_sensitive_data($sect, 1)
$sensitive should_we_hide_sensitive_data($sect, 1)
Truth table66%2/3
A and B
A= $sensitiveB= should_we_hide_sensitive_data($sect, 1)
ABresult
0X0
100
111
3246  
3247 17 my %section_data;
3248 17 my $cfg = $self->get_section ($sect, 1);
3249  
3250 17 my $cnt = 0;
3251 17 foreach my $tag ( $cfg->find_tags (undef, 0) ) {
3252 28 my ($val, $hide) = $cfg->_base_get2 ($tag);
3253 28 ▶ next if ( $sensitive && $hide );
Branch: 1 branch
BranchTrueFalseTotal
if $sensitive and $hide 5 23 28
Condition100%3/3
$sensitive and $hide
!ll&&!rl&&r
1585
MC/DC100%2/2
$sensitive and $hide
$sensitive $hide
Truth table100%3/3
A and B
A= $sensitiveB= $hide
ABresult
0X0
100
111
3254 23 $section_data{$tag} = $val;
3255 23 ++$cnt;
3256 }
3257  
3258 # Only add a section that has tags in it!
3259 17 ▶ $data{$sect} = \%section_data if ( $cnt );
Branch: 1 branch
BranchTrueFalseTotal
if $cnt 10 7 17
3260 }
3261  
3262 7 DBUG_RETURN ( \%data );
3263 }
3264  
3265  
3266 #######################################
3267  
3268 =back
3269  
3270 =head2 Encryption/Decryption of your config files.
3271  
3272 The methods here deal with the encryption/decryption of your config file before
3273 you use this module to load it into memory. They allow you to make the contents
3274 of your config files more secure.
3275  
3276 =over
3277  
3278 =item $status = $cfg->encrypt_config_file ( [$file[, $encryptFile[, \%rOpts]]] );
3279  
3280 This function encrypts all tag values inside the specified config file that are
3281 marked as ready for encryption and generates a new config file with everything
3282 encrypted. If a tag/value pair isn't marked as ready for encryption it is left
3283 alone. By default this label is B<ENCRYPT>.
3284  
3285 After a tag's value has been encrypted, the label in the comment is updated
3286 from B<ENCRYPT> to B<DECRYPT> in the config file.
3287  
3288 If you are adding new B<ENCRYPT> tags to an existing config file that already
3289 has B<DECRYPT> tags in it, you must use the same encryption related options in
3290 I<%rOpts> as the last time. Otherwise you won't be able to decrypt all
3291 encrypted values.
3292  
3293 Finally if you provide argument I<$encryptFile>, it will write the encrypted
3294 file to that new file instead of overwriting the current file. But if you do
3295 this, you will require the use of the I<alias> option to be able to decrypt
3296 it again using the new name. This file only gets created if the return status
3297 is B<1>.
3298  
3299 If you leave off the I<$file> and I<\%rOpts>, it will instead use the values
3300 inherited from the call to B<new>.
3301  
3302 This method ignores any request to source in other config files. You must
3303 encrypt each file individually.
3304  
3305 It is an error if basename(I<$file>) is a symbolic link and you didn't provide
3306 I<$encryptFile>.
3307  
3308 Returns: B<1> if something was encrypted. B<-1> if nothing was encrypted.
3309 Otherwise B<0> on error.
3310  
3311 =cut
3312  
3313 sub encrypt_config_file
3314 5 ▶{
Subroutine encrypt_config_file: called CC=15 SCAR=30.8
Pod documented
3315 5 DBUG_ENTER_FUNC ( @_ );
3316 5 my $self = shift;
3317 5 my $file = shift;
3318 5 my $newFile = shift;
3319 5 my $rOpts = shift;
3320  
3321 5 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
050
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3322  
3323 5 my $msg;
3324 5 ▶ if ( $file ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($file) { } 3 2 5
elsif ($pcfg->{'CONTROL'}{'filename'}) { } 2 0 2
3325 3 $file = $self->_fix_path ( $file );
3326 } elsif ( $pcfg->{CONTROL}->{filename} ) {
3327 2 $file = $pcfg->{CONTROL}->{filename};
3328 } else {
3329 0 $msg = "You must provide a file name to encrypt!";
3330 }
3331  
3332 5 ▶ unless ( $msg || -f $file ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($msg or -f $file) 0 5 5
Condition33%1/3
$msg or -f $file
l!l&&r!l&&!r
050
MC/DC0%0/2
$msg or -f $file
$msg -f $file
Truth table33%1/3
A or B
A= $msgB= -f $file
ABresult
1X1
011
000
3333 0 $msg = "No such file to encrypt or it's unreadable! -- $file";
3334 }
3335  
3336 5 ▶ if ( -l $file && ! $newFile ) {
Branch: 1 branch
BranchTrueFalseTotal
if (-l $file and not $newFile) 0 5 5
Condition33%1/3
-l $file and not $newFile
!ll&&!rl&&r
500
MC/DC0%0/2
-l $file and not $newFile
-l $file not $newFile
Truth table33%1/3
A and not(B)
A= -l $fileB= not $newFile
ABresult
0X0
100
111
3337 0 $msg = "You can't encrypt a file via it's symbolic link -- $file";
3338 }
3339  
3340 5 my $scratch;
3341 5 ▶ if ( $newFile ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($newFile) { } 3 2 5
3342 3 $scratch = $self->_fix_path ($newFile);
3343 3 ▶ if ( $scratch eq $file ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($scratch eq $file) 0 3 3
3344 0 $msg = "Args: file & encryptFile must be different!";
3345 }
3346 } else {
3347 2 $scratch = $file . ".$$.encrypted";
3348 }
3349  
3350 5 ▶ if ( $rOpts ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rOpts) { } 3 2 5
3351 3 $rOpts = get_read_opts ($rOpts, $pcfg->{CONTROL}->{read_opts});
3352 } else {
3353 2 $rOpts = $pcfg->{CONTROL}->{read_opts};
3354 }
3355  
3356 5 ▶ if ( $msg ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($msg) 0 5 5
3357 0 return DBUG_RETURN ( croak_helper ( $rOpts, $msg, 0 ) );
3358 }
3359  
3360 5 my $status = encrypt_config_file_details ($file, $scratch, $rOpts);
3361  
3362 # Some type of error ... or nothing was encrypted ...
3363 5 ▶ if ( $status == 0 || $status == -1 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($status == 0 or $status == -1) { } 0 5 5
elsif (not $newFile) { } 2 3 5
Condition33%1/3
$status == 0 or $status == -1
l!l&&r!l&&!r
005
MC/DC0%0/2
$status == 0 or $status == -1
$status == 0 $status == -1
Truth table33%1/3
A or B
A= $status == 0B= $status == -1
ABresult
1X1
011
000
3364 0 unlink ( $scratch );
3365  
3366 # Replacing the original file ...
3367 } elsif ( ! $newFile ) {
3368 2 unlink ( $file );
3369 2 move ( $scratch, $file );
3370 }
3371  
3372 5 DBUG_RETURN ( $status );
3373 }
3374  
3375  
3376 #######################################
3377  
3378 =item $status = $cfg->decrypt_config_file ( [$file[, $decryptFile[, \%rOpts]]] );
3379  
3380 This function decrypts all tag values inside the specified config file that are
3381 marked as ready for decryption and generates a new config file with everything
3382 decrypted. If a tag/value pair isn't marked as ready for decryption it is left
3383 alone. By default this label is B<DECRYPT>.
3384  
3385 After a tag's value has been decrypted, the label in the comment is updated
3386 from B<DECRYPT> to B<ENCRYPT> in the config file.
3387  
3388 For this to work, the encryption related options in I<\%rOpts> must match what
3389 was used in the call to I<encrypt_config_file> or the decryption will fail.
3390  
3391 Finally if you provide argument I<$decryptFile>, it will write the decrypted
3392 file to that new file instead of overwriting the current file. This file only
3393 gets created if the return status is B<1>.
3394  
3395 If you leave off the I<$file> and I<\%rOpts>, it will instead use the values
3396 inherited from the call to B<new>.
3397  
3398 This method ignores any request to source in other config files. You must
3399 decrypt each file individually.
3400  
3401 It is an error if basename(I<$file>) is a symbolic link and you didn't provide
3402 I<$decryptFile>.
3403  
3404 Returns: B<1> if something was decrypted. B<-1> if nothing was decrypted.
3405 Otherwise B<0> on error.
3406  
3407 =cut
3408  
3409 sub decrypt_config_file
3410 8 ▶{
Subroutine decrypt_config_file: called CC=15 SCAR=30.8
Pod documented
3411 8 DBUG_ENTER_FUNC ( @_ );
3412 8 my $self = shift;
3413 8 my $file = shift;
3414 8 my $newFile = shift;
3415 8 my $rOpts = shift;
3416  
3417 8 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
080
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3418  
3419 8 my $msg;
3420 8 ▶ if ( $file ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($file) { } 6 2 8
elsif ($pcfg->{'CONTROL'}{'filename'}) { } 2 0 2
3421 6 $file = $self->_fix_path ( $file );
3422 } elsif ( $pcfg->{CONTROL}->{filename} ) {
3423 2 $file = $pcfg->{CONTROL}->{filename};
3424 } else {
3425 0 $msg = "You must provide a file name to encrypt!";
3426 }
3427  
3428 8 ▶ unless ( $msg || -f $file ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($msg or -f $file) 0 8 8
Condition33%1/3
$msg or -f $file
l!l&&r!l&&!r
080
MC/DC0%0/2
$msg or -f $file
$msg -f $file
Truth table33%1/3
A or B
A= $msgB= -f $file
ABresult
1X1
011
000
3429 0 $msg = "No such file to decrypt or it's unreadable! -- $file";
3430 }
3431  
3432 8 ▶ if ( -l $file && ! $newFile ) {
Branch: 1 branch
BranchTrueFalseTotal
if (-l $file and not $newFile) 0 8 8
Condition33%1/3
-l $file and not $newFile
!ll&&!rl&&r
800
MC/DC0%0/2
-l $file and not $newFile
-l $file not $newFile
Truth table33%1/3
A and not(B)
A= -l $fileB= not $newFile
ABresult
0X0
100
111
3433 0 $msg = "You can't decrypt a file via it's symbolic link -- $file";
3434 }
3435  
3436 8 my $scratch;
3437 8 ▶ if ( $newFile ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($newFile) { } 6 2 8
3438 6 $scratch = $self->_fix_path ( $newFile );
3439 6 ▶ if ( $scratch eq $file ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($scratch eq $file) 0 6 6
3440 0 $msg = "Args: file & decryptFile must be different!";
3441 }
3442 } else {
3443 2 $scratch = $file . ".$$.decrypted";
3444 }
3445  
3446 8 ▶ if ( $rOpts ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rOpts) { } 6 2 8
3447 6 $rOpts = get_read_opts ($rOpts, $pcfg->{CONTROL}->{read_opts});
3448 } else {
3449 2 $rOpts = $pcfg->{CONTROL}->{read_opts};
3450 }
3451  
3452 8 ▶ if ( $msg ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($msg) 0 8 8
3453 0 return DBUG_RETURN ( croak_helper ( $rOpts, $msg, undef ) );
3454 }
3455  
3456 8 my $status = decrypt_config_file_details ($file, $scratch, $rOpts);
3457  
3458 # Some type of error ... or nothing was decrypted ...
3459 8 ▶ if ( $status == 0 || $status == -1 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($status == 0 or $status == -1) { } 0 8 8
elsif (not $newFile) { } 2 6 8
Condition33%1/3
$status == 0 or $status == -1
l!l&&r!l&&!r
008
MC/DC0%0/2
$status == 0 or $status == -1
$status == 0 $status == -1
Truth table33%1/3
A or B
A= $status == 0B= $status == -1
ABresult
1X1
011
000
3460 0 unlink ( $scratch );
3461  
3462 # Replacing the original file ...
3463 } elsif ( ! $newFile ) {
3464 2 unlink ( $file );
3465 2 move ( $scratch, $file );
3466 }
3467  
3468 8 DBUG_RETURN ( $status );
3469 }
3470  
3471  
3472 #######################################
3473  
3474 =item $out_str = $cfg->encrypt_string ( $string, $alias[, \%rOpts] );
3475  
3476 This method takes the passed I<$string> and treats its value as the contents of
3477 a config file, comments and all. Modifying the I<$string> afterwards will not
3478 affect things.
3479  
3480 Since there is no filename to work with, it requires the I<$alias> to assist
3481 with the encryption. And since it's required its passed as a separate argument
3482 instead of being buried in the optional I<%rOpts> hash.
3483  
3484 It takes the I<$string> and encrypts all tag/value pairs per the rules defined
3485 by C<encrypt_config_file>. Once the contents of I$<string> has been encrypted,
3486 the encrypted string is returned as I<$out_str>. It will return B<undef> on
3487 failure.
3488  
3489 You can tell if something was encrypted by comparing I<$string> to I<$out_str>.
3490  
3491 =cut
3492  
3493 sub encrypt_string
3494 2 ▶{
Subroutine encrypt_string: called CC=5 SCAR=17.4
Pod documented
3495 2 DBUG_MASK_NEXT_FUNC_CALL ( 2 ); # mask the alias.
3496 2 DBUG_ENTER_FUNC ( @_ );
3497  
3498 2 my $self = shift;
3499 2 my $string = shift; # The string to treat as a config file's contents.
3500 2 my $alias = shift; # The alias to use during encryption ...
3501 2 my $read_opts = $self->_get_opt_args ( @_ ); # The override options ...
3502  
3503 2 ▶ unless ( $string ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($string) 0 2 2
3504 0 my $msg = "You must provide a string to use this method!";
3505 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
3506 }
3507  
3508 2 ▶ unless ( $alias ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($alias) 0 2 2
3509 0 my $msg = "You must provide an alias to use this method!";
3510 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
3511 }
3512  
3513 # The filename is a reference to the string passed to this method!
3514 2 my $scratch;
3515 2 my $src_file = \$string;
3516 2 my $dst_file = \$scratch;
3517  
3518 # Put the alias into the read option hash ...
3519 2 local $read_opts->{alias} = basename ($alias);
3520  
3521 2 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
020
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3522 2 my $rOpts = get_read_opts ($read_opts, $pcfg->{CONTROL}->{read_opts});
3523  
3524 2 my $status = encrypt_config_file_details ($src_file, $dst_file, $rOpts);
3525  
3526 2 ▶ $scratch = undef if ( $status == 0 );
Branch: 1 branch
BranchTrueFalseTotal
if $status == 0 0 2 2
3527  
3528 2 DBUG_RETURN ( $scratch );
3529 }
3530  
3531  
3532 #######################################
3533  
3534 =item $out_str = $cfg->decrypt_string ( $string, $alias[, \%rOpts] );
3535  
3536 This method takes the passed I<$string> and treats its value as the contents of
3537 an encrypted config file, comments and all. Modifying the I<$string> afterwards
3538 will not affect things.
3539  
3540 Since there is no filename to work with, it requires the I<$alias> to assist
3541 with the decryption. And since it's required its passed as a separate argument
3542 instead of being buried in the optional I<%rOpts> hash.
3543  
3544 It takes the I<$string> and decrypts all tag/value pairs per the rules defined
3545 by C<decrypt_config_file>. Once the contents of I$<string> has been decrypted,
3546 the decrypted string is returned as I<$out_str>. It will return B<undef> on
3547 failure.
3548  
3549 You can tell if something was decrypted by comparing I<$string> to I<$out_str>.
3550  
3551 =cut
3552  
3553 sub decrypt_string
3554 1 ▶{
Subroutine decrypt_string: called CC=5 SCAR=17.4
Pod documented
3555 1 DBUG_MASK_NEXT_FUNC_CALL ( 2 ); # mask the alias.
3556 1 DBUG_ENTER_FUNC ( @_ );
3557  
3558 1 my $self = shift;
3559 1 my $string = shift; # The string to treat as a config file's contents.
3560 1 my $alias = shift; # The alias to use during encryption ...
3561 1 my $read_opts = $self->_get_opt_args ( @_ ); # The override options ...
3562  
3563 1 ▶ unless ( $string ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($string) 0 1 1
3564 0 my $msg = "You must provide a string to use this method!";
3565 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
3566 }
3567  
3568 1 ▶ unless ( $alias ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($alias) 0 1 1
3569 0 my $msg = "You must provide an alias to use this method!";
3570 0 return DBUG_RETURN ( croak_helper ($read_opts, $msg, undef) );
3571 }
3572  
3573 # The filename is a reference to the string passed to this method!
3574 1 my $scratch;
3575 1 my $src_file = \$string;
3576 1 my $dst_file = \$scratch;
3577  
3578 # Put the alias into the read option hash ...
3579 1 local $read_opts->{alias} = basename ($alias);
3580  
3581 1 ▶ my $pcfg = $self->{PARENT} || $self;
Condition33%1/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
010
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table33%1/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3582 1 my $rOpts = get_read_opts ($read_opts, $pcfg->{CONTROL}->{read_opts});
3583  
3584 1 my $status = decrypt_config_file_details ($src_file, $dst_file, $rOpts);
3585  
3586 1 ▶ $scratch = undef if ( $status == 0 );
Branch: 1 branch
BranchTrueFalseTotal
if $status == 0 0 1 1
3587  
3588 1 DBUG_RETURN ( $scratch );
3589 }
3590  
3591  
3592 #######################################
3593  
3594 =back
3595  
3596 =head2 Handling Variables in your config file.
3597  
3598 These methods are used to resolve variables defined in your config file when
3599 it gets loaded into memory by this module. It is not intended for general use
3600 except as an explanation on how variables work.
3601  
3602 =over
3603  
3604 =item ($value, $status) = $cfg->lookup_one_variable ( $variable_name );
3605  
3606 This method takes the given I<$variable_name> and returns its value.
3607  
3608 It returns I<undef> if the given variable doesn't exist. And the optional 2nd
3609 return value tells us about the B<status> of the 1st return value.
3610  
3611 If the B<status> is B<-1>, the returned value is still encrypted. If set to
3612 B<1>, the value is considered sensitive. In all other cases this B<status> flag
3613 is set to B<0>.
3614  
3615 This method is frequently called internally if you define any variables inside
3616 your config files when they are loaded into memory.
3617  
3618 Variables in the config file are surrounded by anchors such as B<${>nameB<}>.
3619 But it's passed as B<name> without any anchors when this method is called.
3620  
3621 The precedence for looking up a variable's value to return is as follows:
3622  
3623 0. Is it the special "shft3" variable or one of its variants?
3624 1. Look for a tag of that same name previously defined in the current section.
3625 2. If not defined there, look for the tag in the "main" section.
3626 3. Special Case, see note below about periods in the variable name.
3627 4. If not defined there, look for a value in the %ENV hash.
3628 5. If not defined there, does it represent a special Perl variable?
3629 6. If not defined there, is it a predefined Advanced::Config variable?
3630 7. If not defined there, is it some predefined special date variable?
3631 8. If not defined there, the result is undef.
3632  
3633 If a variable was defined in the config file, it uses the tag's value when the
3634 line gets parsed. But when you call this method in your code after the config
3635 file has been loaded into memory, it uses the final value for that tag.
3636  
3637 The special B<${>shft3B<}> variable is a way to insert comment chars into a
3638 tag's value in the config file when you can't surround it with quotes. This
3639 variable is always case insensitive and if you repeat the B<3> in the name, you
3640 repeat the comment chars in the substitution.
3641  
3642 * a = ${shft3} - Returns "#" for a.
3643 * b = ${SHFT33} - Returns "##" for b.
3644 * c = ${ShFt333} - Returns "###" for c.
3645 * etc ...
3646  
3647 And since this variable has special meaning, if you try to define one of the
3648 B<SHFT3> variants as a tag in your config file, or call C<set_value> with it,
3649 it will be ignored and a warning will be printed to your screen!
3650  
3651 If the variable had a period (B<.>) in it's name, and it doesn't match anything
3652 (rules 0 to 2), it follows rule B<3> and it treats it as a reference to a tag in
3653 another section. So see F<rule_3_section_lookup> for details on how this works.
3654  
3655 This module provides you special predefined variables (rules 5, 6 & 7) to help
3656 make your config files more dynamic without the need of a ton of code on your
3657 end. If you want to override the special meaning for these variables, all you
3658 have to do is define a tag in the config file of the same name to override it.
3659 Or just don't use these variables in the 1st place.
3660  
3661 For rule B<5>, the special Perl variables you are allowed to reference are:
3662 B<$$>, B<$0>, and B<$^O>. (Each must appear in the config file as: B<${$}>,
3663 B<${0}> or B<${^O}>.)
3664  
3665 For rule B<6>, the predefined module variables are: ${PID}, ${PPID}, ${user},
3666 ${hostname}, ${program}, ${flavor} and ${sep} (The ${flavor} is defined by
3667 F<Perl::OSType> and ${sep} is the path separator defined by F<File::Spec>
3668 for your OS.) The final variable ${section} tells which section this variable
3669 was used in.
3670  
3671 Finally for rule B<7> it provides some special date variables. See
3672 B<F<Advanced::Config::Options::set_special_date_vars>> for a complete list of
3673 what date related variables are defined. The most useful being ${today} and
3674 ${yesterday} so that you can dynamically name your log files
3675 F</my_path/my_log.${today}.txt> and you won't need any special date roll logic
3676 to start a new log file.
3677  
3678 =cut
3679  
3680 sub lookup_one_variable
3681 8047 ▶{
Subroutine lookup_one_variable: called CC=26 SCAR=32.7
Pod documented
3682 8047 DBUG_ENTER_FUNC ( @_ );
3683 8047 my $self = shift; # Reference to the current section.
3684 8047 my $var = shift; # The name of the variable, minus the ${...}.
3685  
3686 8047 ▶ my $pcfg = $self->{PARENT} || $self; # Get the main section ...
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
636416830
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3687  
3688 # Silently disable calling "die" or "warn" on all get/set calls ...
3689 8047 local $pcfg->{CONTROL}->{get_opts}->{required} = -9876;
3690  
3691 8047 my $opts = $pcfg->{CONTROL}->{read_opts};
3692  
3693 # Did we earlier request case insensitive tag lookups?
3694 8047 ▶ $var = lc ($var) if ( $opts->{tag_case} );
Branch: 1 branch
BranchTrueFalseTotal
if $opts->{"tag_case"} 2 8045 8047
3695  
3696 # The default return values ...
3697 8047 my ( $val, $mask_flag, $file, $encrypt_flag ) = ( undef, 0, "", 0 );
3698  
3699 8047 ▶ if ( $var =~ m/^shft(3+)$/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($var =~ /^shft(3+)$/i) { } 291 7756 8047
3700 # 0. The special comment variable ... (Can't override)
3701 291 $val = $1;
3702 291 my $c = $opts->{comment}; # Usually a "#".
3703 291 $val =~ s/3/${c}/g;
3704  
3705 } else {
3706 # 1. Look in the current section ...
3707 7756 ( $val, $mask_flag, $file, $encrypt_flag ) = $self->_base_get2 ( $var );
3708  
3709 # 2. Look in the parent section ... (if not already there)
3710 7756 ▶ if ( ! defined $val && $self != $pcfg ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $val and $self != $pcfg) 4568 3188 7756
Condition100%3/3
not defined $val and $self != $pcfg
!ll&&!rl&&r
23768124568
MC/DC100%2/2
not defined $val and $self != $pcfg
not defined $val $self != $pcfg
Truth table100%3/3
not(A) and B
A= not defined $valB= $self != $pcfg
ABresult
0X0
100
111
3711 4568 ( $val, $mask_flag, $file, $encrypt_flag ) = $pcfg->_base_get2 ( $var );
3712 }
3713  
3714 # 3. Look in the requested section(s) ...
3715 7756 ▶ if ( ! defined $val && $var =~ m/[.]/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $val and $var =~ /[.]/) 1655 6101 7756
Condition100%3/3
not defined $val and $var =~ /[.]/
!ll&&!rl&&r
333827631655
MC/DC100%2/2
not defined $val and $var =~ /[.]/
not defined $val $var =~ /[.]/
Truth table100%3/3
not(A) and B
A= not defined $valB= $var =~ /[.]/
ABresult
0X0
100
111
3716 1655 ($val, $mask_flag, $encrypt_flag) = $self->rule_3_section_lookup ( $var );
3717 }
3718  
3719 # 4. Look in the %ENV hash ...
3720 7756 ▶ if ( ! defined $val && defined $ENV{$var} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $val and defined $ENV{$var}) 1 7755 7756
Condition100%3/3
not defined $val and defined $ENV{$var}
!ll&&!rl&&r
498627691
MC/DC100%2/2
not defined $val and defined $ENV{$var}
not defined $val defined $ENV{$var}
Truth table100%3/3
not(A) and B
A= not defined $valB= defined $ENV{$var}
ABresult
0X0
100
111
3721 1 $val = $ENV{$var};
3722 1 $mask_flag = should_we_hide_sensitive_data ($var);
3723  
3724 # Record so refresh logic will work when %ENV vars change.
3725 1 $pcfg->{CONTROL}->{ENV}->{$var} = $val;
3726 }
3727  
3728 # 5. Look at the special Perl variables ... (now done as part of 6.)
3729 # 6. Is it one of the predefined module variables ...
3730 # Variables should either be all upper case or all lower case!
3731 # But allowing for mixed case.
3732 7756 ▶ if ( ! defined $val ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $val) 2769 4987 7756
3733 2769 ▶ if ( exists $begin_special_vars{$var} ) {
Branch: 4 branches
BranchTrueFalseTotal
if (exists $begin_special_vars{$var}) { } 1663 1106 2769
elsif (exists $begin_special_vars{lc $var}) { } 0 1106 1106
elsif (exists $begin_special_vars{uc $var}) { } 0 1106 1106
elsif ($var eq 'section') { } 8 1098 1106
3734 1663 $val = $begin_special_vars{$var};
3735 } elsif ( exists $begin_special_vars{lc ($var)} ) {
3736 0 $val = $begin_special_vars{lc ($var)};
3737 } elsif ( exists $begin_special_vars{uc ($var)} ) {
3738 0 $val = $begin_special_vars{uc ($var)};
3739 } elsif ( $var eq "section" ) {
3740 8 $val = $self->section_name ();
3741 }
3742 }
3743  
3744 # 7. Is it one of the special date variables ...
3745 # All these date vars only use lower case!
3746 7756 ▶ if ( ! defined $val ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $val) 1098 6658 7756
3747 1098 my $lc_var = lc ($var);
3748 1098 ▶ if ( defined $pcfg->{CONTROL}->{DATES}->{$lc_var} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $pcfg->{"CONTROL"}{"DATES"}{$lc_var}) 420 678 1098
3749 420 $val = $pcfg->{CONTROL}->{DATES}->{$lc_var};
3750  
3751 # Record so refresh logic will work when the date changes.
3752 # Values:
3753 # 0 - unknown date variable. (so refresh will ignore it.)
3754 # 1 - MM/DD/YYYY referenced. (refresh on date change.)
3755 # 2 - MM or MM/YYYY referenced. (refresh if the month changes.)
3756 # 3 - YYYY referenced. (refresh if the year changes.)
3757 420 my $rule = 0;
3758 420 ▶ if ( $lc_var =~ m/^((yesterday)|(today)|(tomorrow)|(dow)|(doy)||(dom))$/ ) {
Branch: 4 branches
BranchTrueFalseTotal
if ($lc_var =~ /^((yesterday)|(today)|(tomorrow)|(dow)|(doy)||(dom))$/) { } 330 90 420
elsif ($lc_var =~ /^((last)|(this)|(next))_month$/) { } 27 63 90
elsif ($lc_var =~ /^((last)|(this)|(next))_period$/) { } 27 36 63
elsif ($lc_var =~ /^((last)|(this)|(next))_year$/) { } 27 9 36
3759 330 $rule = 1;
3760  
3761 } elsif ( $lc_var =~ m/^((last)|(this)|(next))_month$/ ) {
3762 27 $rule = 2;
3763  
3764 } elsif ( $lc_var =~ m/^((last)|(this)|(next))_period$/ ) {
3765 27 $rule = 2;
3766  
3767 } elsif ( $lc_var =~ m/^((last)|(this)|(next))_year$/ ) {
3768 27 $rule = 3;
3769 }
3770 # Don't record if {timestamp} used. (rule == 0)
3771  
3772 # Save the smallest rule referenced ...
3773 420 ▶ if ( $rule != 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rule != 0) 411 9 420
3774 411 ▶ if ( $pcfg->{CONTROL}->{DATE_USED} == 0 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($pcfg->{'CONTROL'}{'DATE_USED'} == 0) { } 42 369 411
elsif ($pcfg->{'CONTROL'}{'DATE_USED'} > $rule) { } 0 369 369
3775 42 $pcfg->{CONTROL}->{DATE_USED} = $rule;
3776 } elsif ( $pcfg->{CONTROL}->{DATE_USED} > $rule ) {
3777 0 $pcfg->{CONTROL}->{DATE_USED} = $rule;
3778 }
3779 }
3780 }
3781 }
3782  
3783 # 8. Then it must be undefined ... (IE: an unknown variable)
3784 }
3785  
3786 # Mask the return value in fish ???
3787 8047 ▶ DBUG_MASK ( 0 ) if ( $mask_flag);
Branch: 1 branch
BranchTrueFalseTotal
if $mask_flag 391 7656 8047
3788  
3789 # Is the return value still encryped ???
3790 8047 ▶ $mask_flag = -1 if ( $encrypt_flag );
Branch: 1 branch
BranchTrueFalseTotal
if $encrypt_flag 43 8004 8047
3791  
3792 8047 DBUG_RETURN ( $val, $mask_flag )
3793 }
3794  
3795 # ==============================================================
3796  
3797 =item ($value, $sens, $encrypt) = $cfg->rule_3_section_lookup ( $variable_name );
3798  
3799 When a variable has a period (B<.>) in its name, it could mean that this
3800 variable is referencing a tag from another section of the config file. So this
3801 helper method to F<lookup_one_variable> exists to perform this complex check.
3802  
3803 For example, a variable called B<${>xxx.extraB<}> would look in Section "xxx"
3804 for tag "extra".
3805  
3806 Here's another example with multiple B<.>'s in its name this time. It would
3807 look up variable B<${>one.two.threeB<}> in Section "one.two" for tag "three".
3808 And if it didn't find it, it would next try Section "one" for tag "two.three".
3809  
3810 If it found such a variable, it returns it's value. If it didn't find anything
3811 it returns B<undef>. The optional 2nd and 3rd values tells you more about the
3812 returned value.
3813  
3814 I<$sens> is a flag that tells if the data value should be considered sensitive
3815 or not.
3816  
3817 I<$encrypt> is a flag that tells if the value still needs to be decrypted or
3818 not.
3819  
3820 =cut
3821  
3822 sub rule_3_section_lookup
3823 1685 ▶{
Subroutine rule_3_section_lookup: called CC=7 SCAR=19.6
Pod documented
3824 1685 DBUG_ENTER_FUNC ( @_ );
3825 1685 my $self = shift;
3826 1685 my $var_name = shift; # EX: abc.efg.xyz ...
3827  
3828 1685 my ( $val, $fish_mask, $f, $encrypted ) = ( undef, 0, "", 0 );
3829  
3830 # If the variable name isn't named correctly ...
3831 1685 ▶ if ( $var_name !~ m/\./ ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($var_name =~ /\./) 0 1685 1685
3832 0 return DBUG_RETURN ($val, $fish_mask, $encrypted);
3833 }
3834  
3835 # Silently disable calling "die" or "warn" on all get/set calls ...
3836 1685 ▶ my $pcfg = $self->{PARENT} || $self; # Get the main section ...
Condition66%2/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
1644410
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table66%2/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3837 1685 local $pcfg->{CONTROL}->{get_opts}->{required} = -9876;
3838  
3839 # So trailing ... in varname won't cause issues ...
3840 1685 my @parts = split (/\s*[.]\s*/, $var_name . ".!");
3841 1685 pop (@parts); # Remove that pesky trailing "!" I just added!
3842  
3843 # Now look for the requested tag in the proper section ...
3844 1685 ▶ for ( my $i = $#parts - 1; $i >= 0; --$i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i >= 0) 1693 7 1700
3845 1693 my $section = join (".", (@parts)[0..$i]);
3846 1693 my $sect = $self->get_section ( $section );
3847 1693 ▶ next unless ( defined $sect );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $sect 15 1678 1693
3848  
3849 1678 my $tag = join (".", (@parts)[$i+1..$#parts]);
3850 1678 ( $val, $fish_mask, $f, $encrypted ) = $sect->_base_get2 ( $tag );
3851  
3852 # Stop looking if we found anything ...
3853 1678 ▶ if ( defined $val ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $val) 1678 0 1678
3854 1678 DBUG_PRINT ("RULE-3", "Found Section/Tag: %s/%s", $section, $tag);
3855 1678 last;
3856 }
3857 }
3858  
3859 # Controls if the return value needs to be masked in fish ...
3860 1685 ▶ DBUG_MASK ( 0 ) if ( $fish_mask );
Branch: 1 branch
BranchTrueFalseTotal
if $fish_mask 24 1661 1685
3861  
3862 1685 DBUG_RETURN ( $val, $fish_mask, $encrypted );
3863 }
3864  
3865 # ======================================================================
3866  
3867 =item $cfg->print_special_vars ( [\%date_opts] );
3868  
3869 This function is for those individuals who don't like to read the POD too
3870 closely, but still need a quick and dirty way to list all the special config
3871 file variables supported by this module.
3872  
3873 It prints to STDERR the list of these special variables and their current
3874 values. These values can change based on the options used in the call to new()
3875 or what OS you are running under. Or even what today's date is.
3876  
3877 Please remember it is possible to override most of these variables if you first
3878 define them in your own config file or with an environment variable of the
3879 same name. But this function doesn't honor any overrides. It just provides
3880 this list on an FYI basis.
3881  
3882 The optional I<date_opts> hash allows you to play with the various date formats
3883 available for the special date vars. See B<The Special Date Variable Formatting
3884 Options> section of the Options module for what these options are. Used to
3885 override what was set in the call to new().
3886  
3887 =cut
3888  
3889 sub print_special_vars
3890 0 ▶{
Subroutine print_special_vars: not called CC=16 SCAR=56.1
Pod documented
3891 0 DBUG_ENTER_FUNC ( @_ );
3892 0 my $self = $_[0]; # Will shift later if it's an object as expected!
3893  
3894 # Detect if called as part of the object or not.
3895 0 ▶ my $is_obj = ( defined $self && ref($self) eq __PACKAGE__ );
Condition0%0/3
defined $self && ref $self eq __PACKAGE__
!ll&&!rl&&r
000
MC/DC0%0/2
defined $self && ref $self eq __PACKAGE__
defined $self ref $self eq __PACKAGE__
Truth table0%0/3
A && B
A= defined $selfB= ref $self eq __PACKAGE__
ABresult
0X0
100
111
3896 0 ▶ if ( $is_obj ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($is_obj) { } 0 0 0
elsif (defined $self and $self eq __PACKAGE__) { } 0 0 0
3897 0 shift; # $cfg->print_special_vars();
3898 ▶ } elsif ( defined $self && $self eq __PACKAGE__ ) {
Condition0%0/3
defined $self and $self eq __PACKAGE__
!ll&&!rl&&r
000
MC/DC0%0/2
defined $self and $self eq __PACKAGE__
defined $self $self eq __PACKAGE__
Truth table0%0/3
A and B
A= defined $selfB= $self eq __PACKAGE__
ABresult
0X0
100
111
3899 0 shift; # Advanced::Config->print_special_vars();
3900 } else {
3901 # No shift, called via: Advanced::Config::print_special_vars();
3902 }
3903  
3904 0 my $date_opts = $_[0]; # The optional argument ...
3905  
3906 # If it wasn't a hash reference, assume passed by value ...
3907 0 ▶ if ( defined $date_opts && ref ($date_opts) eq "" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $date_opts and ref $date_opts eq "") 0 0 0
Condition0%0/3
defined $date_opts and ref $date_opts eq ""
!ll&&!rl&&r
000
MC/DC0%0/2
defined $date_opts and ref $date_opts eq ""
defined $date_opts ref $date_opts eq ""
Truth table0%0/3
A and B
A= defined $date_optsB= ref $date_opts eq ""
ABresult
0X0
100
111
3908 0 my %data = @_;
3909 0 $date_opts = \%data;
3910 }
3911  
3912 # -------------------------------------------------------------
3913 # Start of real work ...
3914 # -------------------------------------------------------------
3915  
3916 0 my ($pcfg, $cmt, $la, $ra, $asgn) = (undef, '#', '${', '}', '=');
3917 0 ▶ if ( $is_obj ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_obj) 0 0 0
3918 # Get the main/parent section to work against!
3919 0 ▶ $pcfg = $self->{PARENT} || $self;
Condition0%0/3
$self->{'PARENT'} || $self
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{'PARENT'} || $self
$self->{'PARENT'} $self
Truth table0%0/3
A || B
A= $self->{'PARENT'}B= $self
ABresult
1X1
011
000
3920  
3921 # Look in the Read Options hash for current settings ...
3922 0 $cmt = $pcfg->{CONTROL}->{read_opts}->{comment};
3923 0 $la = $pcfg->{CONTROL}->{read_opts}->{variable_left};
3924 0 $ra = $pcfg->{CONTROL}->{read_opts}->{variable_right};
3925 0 $asgn = $pcfg->{CONTROL}->{read_opts}->{assign};
3926 }
3927  
3928 0 print STDERR "\n";
3929 0 print STDERR "${cmt} Examples of the Special Predefined Comment Variable ... (controlled via new)\n";
3930 0 print STDERR "${cmt} You can't override these variables.\n";
3931  
3932 0 ▶ unless ( $is_obj ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_obj) { } 0 0 0
3933 0 print STDERR " \${shft3} = #\n";
3934 0 print STDERR " \${shft33} = ##\n";
3935 0 print STDERR " \${shft333} = ###\n";
3936 } else {
3937 # Works since Rule # 0 and can't be overridden.
3938 0 foreach ( "shft3", "shft33", "shft333" ) {
3939 0 my $v = $self->lookup_one_variable ($_);
3940 0 print STDERR " ${la}$_${ra} ${asgn} ${v}\n";
3941 }
3942 }
3943 0 print STDERR " ...\n\n";
3944  
3945 0 print STDERR "${cmt} Any of the variables below can be overridden by putting them\n";
3946 0 print STDERR "${cmt} into %ENV or predefining them inside your config files!\n\n";
3947  
3948 0 print STDERR "${cmt} The Special Predefined Variables ... (OS/Environment dependant)\n";
3949 0 foreach my $k ( sort keys %begin_special_vars ) {
3950 0 print STDERR " ${la}$k${ra} ${asgn} $begin_special_vars{$k}\n";
3951 }
3952  
3953 0 print STDERR "\n";
3954 0 print STDERR "${cmt} The value of this variable changes based on which section of the config file\n";
3955 0 print STDERR "${cmt} it's used in! It's value will always match the name of the current section!\n";
3956 0 ▶ my $section = $is_obj ? $self->section_name () : DEFAULT_SECTION;
Branch: 1 branch
BranchTrueFalseTotal
$is_obj ? : 0 0 0
3957 0 print STDERR " ${la}section${ra} ${asgn} $section\n";
3958  
3959 0 print STDERR "\n";
3960  
3961 0 my ($opts, %dt);
3962 0 ▶ unless ( $is_obj ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_obj) { } 0 0 0
3963 0 $opts = get_date_opts ( $date_opts );
3964 } else {
3965 0 $opts = get_date_opts ( $date_opts, $pcfg->{CONTROL}->{date_opts} );
3966 }
3967 0 my $language = $opts->{month_language};
3968 0 ▶ my $type = ( $opts->{use_gmt} ) ? "gmtime" : "localtime";
Branch: 1 branch
BranchTrueFalseTotal
$opts->{'use_gmt'} ? : 0 0 0
3969  
3970 0 print STDERR "${cmt} The Special Predefined Date Variables ... (in ${language})\n";
3971 0 print STDERR "${cmt} The format and language used can vary based on the date options selected.\n";
3972 0 print STDERR "${cmt} Uses ${type} to convert the current timestamp into the other values.\n";
3973  
3974 0 set_special_date_vars ( $opts, \%dt );
3975 0 foreach my $k ( sort keys %dt ) {
3976 0 print STDERR " ${la}$k${ra} ${asgn} $dt{$k}\n";
3977 }
3978  
3979 0 print STDERR "\n";
3980  
3981 0 DBUG_VOID_RETURN ();
3982 }
3983  
3984 # ======================================================================
3985  
3986 =back
3987  
3988 =head1 ENVIRONMENT
3989  
3990 Expects PERL5LIB to point to the root of the custom Module directory if not
3991 installed in Perl's default location.
3992  
3993 =head1 COPYRIGHT
3994  
3995 Copyright (c) 2007 - 2026 Curtis Leach. All rights reserved.
3996  
3997 This program is free software. You can redistribute it and/or modify it under
3998 the same terms as Perl itself.
3999  
4000 =head1 SEE ALSO
4001  
4002 L<Advanced::Config::Options> - Handles the configuration of the config object.
4003  
4004 L<Advanced::Config::Date> - Handles date parsing for get_date().
4005  
4006 L<Advanced::Config::Reader> - Handles the parsing of the config file.
4007  
4008 L<Advanced::Config::Examples> - Provides some sample config files and commentary.
4009  
4010 =cut
4011  
4012 ###################################################
4013 #required if module is included w/ require command;
4014 27 1;
« Config/Reader.pm ↑ Summary Config/Examples.pm »