Config/Options.pm

filter: Statementstmt 92.4% 406 / 439 Branchbran 75.4% 154 / 204 Conditioncond 69.2% 63 / 91 MC/DCmcdc 37.9% 22 / 58 Subroutinesub 100% 28 / 28 Podpod 100% 14 / 14 totaltotal 82.3% 687 / 834 CC 138 SCAR 35.8
CC
138
Cov
85%
apply_get_rules
64.4
_get_opt_base
54.6
set_special_date_vars
26.2
CRAP 35.7
« Config/Date.pm ↑ Summary Config/Reader.pm »
1 ###
2 ### Copyright (c) 2007 - 2026 Curtis Leach. All rights reserved.
3 ###
4 ### Module: Advanced::Config::Options
5  
6 =head1 NAME
7  
8 Advanced::Config::Options - Options manager for L<Advanced::Config>.
9  
10 =head1 SYNOPSIS
11  
12 use Advanced::Config::Options;
13 or
14 require Advanced::Config::Options;
15  
16 =head1 DESCRIPTION
17  
18 F<Advanced::Config::Options> is a helper module to L<Advanced::Config>. So it
19 should be very rare to directly call any methods defined by this module.
20  
21 It's main job is to help manage the settings of the B<Read>, B<Get> and B<Date>
22 options hashes. It was implemented as a separate module to make it simpler to
23 document the various supported options without cluttering up the POD of the main
24 module. So you are not expected to ever call any of these methods yourself.
25 It's here mainly as an FYI.
26  
27 If you don't specify the options below, this module will assume you wish to use
28 the default behavior for that option. So only override what you need to.
29 Also all options are in lower case. But you may provide them in mixed case if
30 you wish. This module will auto downshift them for you.
31  
32 If an option is misspelled, or you don't provide a valid value, a warning will
33 be written to the screen and that option will be ignored.
34  
35 =head1 ==================================================================
36  
37 =head2 Z<>
38  
39 =head1 The Read Options
40  
41 In most cases the defaults should do nicely for you. But when you share config
42 files between applications, you may not have any control over the config file's
43 format. This may also apply if your organization requires a specific format
44 for its config files.
45  
46 So this section deals with the options you can use to override how it parses and
47 interprets the config file when it is loaded into memory. None of these options
48 below allows leading or trailing spaces in the option's value. And if any are
49 found, they will be automatically trimmed off before their value is used.
50 Internal spaces are OK when non-numeric values are expected. In most cases
51 values with a length of B<0> or B<undef> are not allowed.
52  
53 Just be aware that some combinations of I<Read> options may result in this
54 module being unable to parse the config file. If you encounter such a
55 combination open a CPAN ticket and I'll see what I can do about it. But some
56 combinations may just be too ambiguous to handle.
57  
58 Also note that some I<Read> options have B<left> and B<right> variants. These
59 options are used in pairs and both must anchor the target in order for the rule
60 to be applied to it. These start/end anchors can be set to the same string or
61 different strings. Your choice.
62  
63 =head2 Tag(s) Best Set in Call to the Constructor new().
64  
65 While not required to set these options during the call to B<new>, changing
66 their settings later on can cause unexpected issues if you are not careful.
67  
68 But it's still recommended that most I<Read> Options be set during the call to
69 B<new> to avoid having to keep on resetting them all the time and limit these
70 later changes to handle exceptions to your defaults.
71  
72 =over 4
73  
74 B<tag_case> - Config files are made up of tag/value pairs. This option controls
75 whether the tags are case sensitive (B<0>, the default) or case insensitive
76 (B<1>). IE do tags B<ABC> and B<abc> represent the same tag or not? So if set,
77 all tags are assumed to be in lower case for the get/set methods!
78  
79 =back
80  
81 =head2 Generic Read Options
82  
83 These options are also usually set during the call to B<new>, but setting them
84 later on doesn't produce strange behavior if you change the settings later on.
85  
86 =over 4
87  
88 B<croak> - This controls what happens when a function hits an unexpected error
89 while parsing the config file. Set to B<0> to return an error code (default),
90 B<-1> to return an error code and print a warning to your screen, B<1> to call
91 die and terminate your program.
92  
93 B<export> - Tells if we should export all tag/value pairs to perl's %ENV hash
94 or not. The default is B<0> for I<No>. Set to B<1> if you want this to happen.
95 But if set, it reverses the meaning of the B<export_lbl> option defined later
96 on.
97  
98 B<use_utf8> - Defaults to B<0>. Set to B<1> if the config file was created
99 using utf8 encoding. (IE Unicode or Wide Characters.) Guessing this
100 setting wrong means the file will be unusable as a config file.
101  
102 B<disable_quotes> - Defaults to B<0>. Set to B<1> if you want to disallow
103 the stripping of balanced quotes in your config files.
104  
105 B<disable_variables> - Defaults to B<0>. Set to B<1> if you want to disable
106 variable expansion in your config files when they are loaded into memory.
107  
108 B<disable_variable_modifiers> - Defaults to B<0>. Set to B<1> if you want to
109 disable this feature. See L<http://wiki.bash-hackers.org/syntax/pe> for more
110 details. This feature allows you to put logic into your config files via
111 your variable definitions. Automatically disabled when variables are
112 disabled. Useful when you put a lot of special chars into your variable
113 names.
114  
115 B<disable_decryption> - Defaults to B<0>. Set to B<1> if you want to disable
116 decrypting values that have been marked as encrypted. If a variable references
117 an encrypted value while disable_decription is active, that variable isn't
118 expanded.
119  
120 =cut
121  
122 # B<enable_backquotes> - Defaults to B<0>. Set to B<1> if you want to enable
123 # this feature. It's disabled by default since it can be considered a security
124 # hole if an unauthorized user can modify your config file or your code.
125  
126 =pod
127  
128 B<trap_recursion> - Defaults to B<0>. Set to B<1> if you want to treat
129 recursion as a fatal error when loading a config file. By default it just
130 ignores the recursion request to prevent infinite loops.
131  
132 B<source_cb_opts> - A work area for holding values between calls to the
133 callback function. This is expected to be a hash reference to provide any
134 needed configuration values needed to parse the next config file. This way
135 you can avoid global variables. Defaults to an empty hash reference.
136  
137 B<source_cb> - An optional callback routine called each time your config file
138 sources in another config file. It's main use is when the I<Read Options>
139 and/or I<Date Format Options> required to parse each config file change between
140 files. It's automatically called right before the sourced in file is opened up
141 for parsing.
142  
143 Once the new file is sourced in, it inherits most of the options currently used
144 unless you override them. The only ones not inherited deal with decryption.
145  
146 Here is the callback function's expected definition:
147  
148 my ($rOpts, $dOpts) = source_callback_func ($file[, $cbOpts]);
149  
150 $file --> The file being sourced in.
151  
152 $cbOpts --> A hash reference containing values needed by your callback
153 function to decide what options are required to source in the
154 requested file. You may update the contents of this hash to
155 preserve info between calls. This module will "never" examine
156 the contents of this hash!
157  
158 $rOpts --> A reference to the "Read Options" hash used to parse the file
159 you want to source in. Returns "undef" if the options don't
160 change. The returned options override what's currently in use by
161 "load_config" when loading the current file.
162  
163 $dOpts --> A reference to the "Date Formatting Options" hash used to tell how
164 to format the special date variables. Returns "undef" if the
165 options don't change. The returned options override what's
166 currently in use by "load_config" when loading the current file.
167  
168 NOTE: This callback option is disabled if you use another config file to tell
169 how to parse the current config file.
170  
171 =back
172  
173 =head2 Parse Read Options
174  
175 These options deal with how to parse the config file itself. All values are
176 literal values. No regular expressions are supported. If you don't want to
177 allow a particular option to be supported in your config file, and there is
178 no disable option, feel free to set it to some unlikely long string of
179 characters that will never match anything in your config files. Such as
180 "#"x100. (A string of 100 #'s.)
181  
182 =over 4
183  
184 B<assign> - Defaults to B<=>. You may use this option to override what string
185 of characters make up the assignment operator. It's used to split a line
186 into a tag/value pair. If you want the special case of no separator, IE the
187 first space separates a tag/value pair, try setting it to B<\\s> since the
188 interface doesn't allow whitespace as a value.
189  
190 B<comment> - Defaults to B<#>. This is the comment symbol used when parsing
191 your config file and everything after it is ignored in most cases. The first
192 case is when it appears between balanced quotes as part of a tag's value, it's
193 not considered the start of a comment. The other case is when you put one
194 of the labels in the comments to override default behavior. (See next section)
195  
196 B<source> - Defaults to "B<.>". When followed by a file name, this is an
197 instruction to source in another config file (similar to how it works in a
198 I<Unix> shell script.) Another common setting for this option is "include".
199  
200 B<section_left> & B<section_right> - This pair is used to anchor breaking
201 your config file into multiple independent sections. The defaults are B<[>
202 and B<]>.
203  
204 B<variable_left> & B<variable_right> - This pair is used to anchor a variable
205 definition. Any value between these anchors will be a variable name and it's
206 value will be used instead, unless you've disabled this expansion. The defaults
207 are B<${> and B<}>. If you override these anchors to both have the same value,
208 then the optional variable modifiers are not supported nor are nested variables.
209  
210 B<quote_left> & B<quote_right> - This pair is used to define what balanced
211 quotes look like in your config file. By default, it allows you to use either
212 B<"> or B<'> as a matching pair. But if you override one of them you must
213 override both. And in that case it can only be with literal values. If the
214 quotes surrounding a tag's value are balanced, the quotes will be automatically
215 removed from the value. If they are unbalanced the quotes will not be removed.
216  
217 =cut
218  
219 # B<backquote_left> & B<backquote_right> - This pair is used to surround a command
220 # you wish to run, just like in Perl itself. What the command writes to STDOUT
221 # becomes the tag's value. Assumes the command takes nothing from STDIN. Due to
222 # security concerns you must explicitly set these values yourself before they are
223 # usable. A good value is the backqoute itself (B<`>). But use something else
224 # if you don't want to be so obvious about it.
225  
226 =pod
227  
228 =back
229  
230 =head2 Modifiers in the trailing Comments for tag/value pairs.
231  
232 In some cases we need to handle exceptions to the rule. So we define labels
233 to tell this module that we need to apply special rules to this tag/value pair.
234 These labels may appear anywhere in the comment. So when looking for "EXPORT",
235 it will match "B<# Please EXPORT me.>", but won't match "B<# EXPORTED>". This
236 allows you to put multiple labels in a single comment if needed.
237  
238 As long as the text is surrounded by white space or punctuation a match will
239 be found. It is strongly recommended that you don't use punctuation in your
240 label when you override one with values of your own.
241  
242 Here are the labels you may override.
243  
244 =over 4
245  
246 B<export_lbl> - Defaults to "B<EXPORT>". Tells this module to export this
247 particular tag/value pair to perl's B<%ENV> hash. If the I<export> option
248 was also set, it inverts the meaning of this label to mean don't export it!
249 You can also gain the same functionality by doing one of the following
250 instead:
251  
252 export tag = value # Optional unix type shell script prefix.
253  
254 set tag = value # Optional windows type batch file prefix.
255  
256 These prefixes allow you to easily use shell/batch files as config files if
257 they contain no logic.
258  
259 B<hide_lbl> - Defaults to "B<HIDE>". Tells this module that this tag's value
260 contains sensitive information. So when fish logging is turned on, this module
261 will never write it to these logs. If the parser thinks a tag's name suggests
262 it's a password, it will assume that you put this label in the comment. This
263 is what triggers the sensitive/mask arguments and return values that some
264 methods use.
265  
266 B<encrypt_lbl> - Defaults to "B<ENCRYPT>". Tells this module that you are
267 waiting for this tag's value to be encrypted in the config file. It assumes
268 the value is still in clear text. When present it assumes the value is
269 sensitive as well.
270  
271 B<decrypt_lbl> - Defaults to "B<DECRYPT>". Tells this module that this value
272 has already been encrypted and needs to be decrypted before it is used. When
273 present it assumes that the value is sensitive as well.
274  
275 B<source_file_section_lbl> - Defaults to "B<DEFAULT>". Tells this module to
276 use the current section as the default/unlabeled section in the file being
277 source in. This new value will be inherited should the sourced in file source
278 in any further files.
279  
280 =back
281  
282 =head2 Encryption/Decryption options. (or Encode/Decode options.)
283  
284 The following options deal with the encryption/decryption of the contents of a
285 config file. Only the encryption of a tag's value is supported. And this is
286 triggered by the appropriate label in the comment on the same line after the
287 value.
288  
289 Unless you use the B<encrypt_cb> option, this module isn't using true
290 encryption. It's more a complex obscuring of the tag's value making it very
291 difficult to retrieve a tag's value without using this module to examine the
292 config file's contents. It's main use is to prevent casual browsers of your
293 file system from being able to examine your config files using their favorite
294 editor to capture sensitive data from your config files.
295  
296 By default, the I<basename> of the config file's name and the tag's name are the
297 keys used to encode each value in the config file. This means that each tag's
298 value in the config file uses a different key to obscure it. But by using just
299 the defaults, anyone using this module may automatically decode everything in
300 the config file just by writing a perl program that uses this module.
301  
302 But by using the options below, you gain additional security even without using
303 true encryption. Since if you don't know the options used, you can't easily
304 decode each tag's value even by examining the code. Just be aware that using
305 too many keys with too similar values could cancel each other out and weaken
306 the results.
307  
308 These options are ignored if you've disabled decryption.
309  
310 When you source in another file in your config files, the current values
311 for B<alias>, B<pass_phrase> and B<encrypt_by_user> are not inherited. But the
312 remaining options are. See option B<source_cb> if you need to set them in this
313 case.
314  
315 =over 4
316  
317 B<alias> - Defaults to the empty string. (Meaning no alias provided.) This
318 option is used to override using the file's I<basename> as one of the
319 encryption/decryption keys with the I<basename> of the value you provide here.
320  
321 If you encrypt a file with no I<alias>, and then rename the config file, you
322 must set the I<alias> to the original filename to be able to decrypt anything.
323 If you encrypt a file with an I<alias>, you must use the same I<alias> to
324 decrypt things again.
325  
326 If your config file is a symbolic link to another name, it will auto set this
327 option for you using the file's real name as the alias if you don't override
328 it by setting the alias yourself.
329  
330 B<pass_phrase> - Defaults to the empty string. If you used a pass phrase to
331 encrypt the value, then you need to use the same pass phrase again when
332 decrypting each tag's value.
333  
334 B<inherit_pass_phrase> - Defaults to 0 (no). Set to 1 if you want to use the
335 same B<pass_pharase> when you source in a sub-file in your config files.
336  
337 B<encrypt_by_user> - Defaults to 0 (no). Set to 1 if you want use the user
338 name you are running the program under as part of the encryption key. So only
339 the user who encrypted the file can decrypt it.
340  
341 B<encrypt_cb_opts> - A work area for holding values between calls to the
342 callback function. This is expected to be a hash reference to provide any
343 values needed by your encryption efforts. So you can avoid global variables
344 and having to figure out the correct context of the call. Defaults to an empty
345 hash reference.
346  
347 B<encrypt_cb> - An optional callback function to provide hooks for B<true
348 encryption> or an additional layer of masking. It defaults to no callback
349 function used. This callback function is called in addition to any obscuring
350 work done by this module.
351  
352 Here is the callback function's expected definition:
353  
354 my $new_value = encrypt_callback_func ($mode, $tag, $value, $file[, $cbOpts]);
355  
356 $mode ==> 1 - Encrypt this value, 0 - Decrypt this value.
357  
358 $tag ==> The name of the tag whose value is being encrypted/decrypted.
359  
360 $value ==> The value to encrypt/decrypt.
361  
362 $file ==> The basename of the file the tag/value pair came from. If the
363 "alias" option was used, the basename of that "alias" is
364 passed as "$file" instead.
365  
366 $cbOpts ==> A hash reference containing values needed by your function to
367 do it's custom encrypt/decrypt duties. You may update the
368 contents of this hash to preserve info between calls. This
369 module will "never" examine the contents of this hash!
370  
371 =back
372  
373 =head1 ==================================================================
374  
375 =head2 Z<>
376  
377 =head1 The Get Options
378  
379 This section deals with the options you can use to override how the I<B<get>>
380 methods behave when you try to access the values for individual tags. None
381 of the options below allows leading or trailing spaces in it's value. If any
382 are found, they will be automatically trimmed off before their value is used.
383 Internal spaces are OK.
384  
385 These options can be set as global defaults via the call to the constructor,
386 B<new()>, or for individual B<get_...> calls if you don't like the defaults
387 for individual calls.
388  
389 But it is strongly recommended that the B<inherit> option only be set in the
390 constructor and not changed elsewhere. Changing its value between calls can
391 cause strange behavior if you do so. Since it globally affects how this
392 module locates the requested tag and affects variable lookups when the
393 config file is parsed.
394  
395 After that, where to set the other options is more a personal choice than
396 anything else.
397  
398 =over 4
399  
400 B<inherit> - Defaults to B<0> where each section is independent, the tag either
401 exists or it doesn't in the section. Set to B<1> if each section should be
402 considered an override for what's in the main section. IE if tag "abc" doesn't
403 exist in the current section, it next looks in the main section for it.
404  
405 B<required> - This controls what happens when the requested tag doesn't exist
406 in your I<Advanced::Config> object. Set to B<0> to return B<undef> (default),
407 B<-1> to return B<undef> and write a warning to your screen, B<1> to call
408 die and terminate your program.
409  
410 B<vcase> - Controls what case to force all values to. Defaults to B<0> which
411 says to preserve the case as entered in the config file. Use B<1> to convert
412 everything to upper case. Use B<-1> to convert everything to lower case.
413  
414 B<split_pattern> - Defaults to B<qr /\s+/>. The pattern to use when splitting
415 a tag's value into an array via perl's C<split> function. It can be a string
416 or a regular expression. For example to split on a comma separated string
417 you could do: B<qr /\s*,\s*/>.
418  
419 B<date_language> - Defaults to I<English>. Tells what language I<get_date()>
420 should use when converting the date into a standard format. Can be almost any
421 language supported by I<Date::Language>.
422  
423 B<date_language_warn> - Defaults to B<0> (no). Should I<Advanced::Config::Date>
424 methods print out warnings?
425  
426 B<date_enable_yy> - Defaults to B<0> (no). When parsing dates, should we
427 enable recognizing two digit years as valid?
428  
429 B<date_format> - Numeric dates are inherently ambiguous so hints are required
430 in order to eliminate ambiguities. For example is 01/02/03 I<Jan 2, 2003> (USA)
431 or I<Feb 1, 2003> (European) or even I<Feb 3, 2001> (ISO). To a lesser extent
432 this is also true when you use 4-digit years. So this option was added for
433 you to provide parsing hints on the order to try out.
434  
435 0 - ISO only
436 1 - USA only
437 2 - European only
438 3 - ISO, USA, European (default)
439 4 - ISO, European, USA
440 5 - USA, European, ISO
441 6 - USA, ISO, European
442 7 - European, USA, ISO
443 8 - European, ISO, USA
444 If you provide an invalid choice, it will assume the default format.
445  
446 B<date_dl_conversion> - Defaults to B<0> (no). When parsing dates, should we
447 be using L<Date::Language>, if it's installed, for additional parsing of dates
448 if nothing else works?
449  
450 There are many other I<Get Options> not exposed in the POD. They are only set
451 via the specialized B<get_...> functions. So they are not documented here.
452  
453 =back
454  
455 =head1 ==================================================================
456  
457 =head2 Z<>
458  
459 =head1 The Special Date Variable Formatting Options
460  
461 This module allows for special predefined date related variables for use in your
462 config files. These options deal with how to format these dates when these
463 variables are referenced. These formatting rules apply to all of the special
464 date variables.
465  
466 =over 4
467  
468 B<date_order> - Used to define the ordering of the parts of the dates.
469 0 - YMD (ISO), 1 - MDY (American), 2 - DMY (European). The default is B<0>.
470  
471 B<date_sep> - The separator to use with the date. Defaults to "-".
472  
473 B<month_type> - How to display the month variables. 0 - numeric, 1 -
474 abbreviate names, 2 - full names. The default is B<0>.
475  
476 B<month_language> - What language to use when using month names. Defaults
477 to I<English>.
478  
479 B<use_gmt> - How to calculate the date values. 0 - use localtime, 1 - use
480 gmtime. The default is B<0>.
481  
482 =back
483  
484 =head1 ==================================================================
485  
486 =head2 Z<>
487  
488 =head1 FUNCTIONS
489  
490 As a reminder, there is no need to directly call any of the following functions.
491 They are documented mostly for the benefit of the developer who uses them to
492 implement the internals to L<Advanced::Config>.
493  
494 Most of them are too specialized to be of much use to you.
495  
496 =over 4
497  
498 =cut
499  
500 package Advanced::Config::Options;
501  
502 28 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
503 28 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
504  
505 28 ▶use vars qw( @ISA @EXPORT @EXPORT_OK $VERSION );
Subroutine BEGIN: called CC=1 SCAR=0.0
506 28 ▶use Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
507  
508 28 $VERSION = "1.15";
509 28 @ISA = qw( Exporter );
510  
511 28 @EXPORT = qw( get_read_opts get_get_opts get_date_opts
512 apply_get_rules
513 is_assign_spaces
514 using_default_quotes
515 convert_to_regexp_string
516 convert_to_regexp_modifier
517 should_we_hide_sensitive_data
518 make_it_sensitive
519 sensitive_cnt
520 croak_helper
521 set_special_date_vars
522 change_special_date_vars
523 );
524  
525 28 @EXPORT_OK = qw( );
526  
527 28 ▶use Advanced::Config::Date;
Subroutine BEGIN: called CC=1 SCAR=0.0
528 28 ▶use Fred::Fish::DBUG 2.09 qw / on_if_set ADVANCED_CONFIG_FISH /;
Subroutine BEGIN: called CC=1 SCAR=0.0
529  
530 # The name of the default section ... (even if no sections are defined!)
531 28 ▶use constant DEFAULT_SECTION_NAME => "main"; # Must be in lower case!
Subroutine BEGIN: called CC=1 SCAR=0.0
532  
533 28 my %default_read_opts;
534 my %default_get_opts;
535 28 my %default_date_opts;
536 28 my @hide_from_fish;
537  
538  
539 # ==============================================================
540 # Get who you're currrently logged in as.
541 # Put here to avoid circular references between modules.
542 sub _get_user_id
543 55 ▶{
Subroutine _get_user_id: called CC=4 SCAR=15.9
544 55 DBUG_ENTER_FUNC ( @_ );
545 55 my $user = "??";
546 55 eval {
547 # Mostly used on unix like systms.
548 55 ▶ $user = getpwuid ($<) || "??";
Condition50%1/2
getpwuid $< || '??'
l!l
550
MC/DC0%0/1
getpwuid $< || '??'
getpwuid $<
Truth table50%1/2
A
A= getpwuid $<
Aresult
11
00
549 };
550 55 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 55 55
551 # Can't use on unix due to sudo issue returns wrong user.
552 0 ▶ $user = getlogin () || "??";
Condition0%0/2
getlogin || '??'
l!l
00
MC/DC0%0/1
getlogin || '??'
getlogin
Truth table0%0/2
A
A= getlogin
Aresult
11
00
553 }
554 55 DBUG_RETURN ($user);
555 }
556  
557 # ==============================================================
558 # A stub of the source callback function ...
559 sub _source_callback_stub
560 20 ▶{
Subroutine _source_callback_stub: called CC=1 SCAR=0.0
561 20 DBUG_ENTER_FUNC ( @_ );
562 20 my $file = shift;
563 20 my $opts = shift;
564 20 DBUG_RETURN ( undef, undef );
565 }
566  
567  
568 # ==============================================================
569 # A stub of the encryption/decryption callback function ...
570 sub _encryption_callback_stub
571 18748 ▶{
Subroutine _encryption_callback_stub: called CC=1 SCAR=0.0
572 18748 DBUG_MASK_NEXT_FUNC_CALL (2); # Mask $value!
573 18748 DBUG_ENTER_FUNC ( @_ );
574 18748 my $mode = shift;
575 18748 my $tag = shift;
576 18748 my $value = shift; # Clear text sensitive value ...
577 18748 my $file = shift;
578 18748 my $cbOpts = shift;
579 18748 DBUG_MASK ( 0 );
580 18748 DBUG_RETURN ( $value );
581 }
582  
583  
584 # ==============================================================
585 # Initialize the global hashes with their default values ...
586 BEGIN
587 28 ▶{
Subroutine BEGIN: called CC=1 SCAR=0.0
588 28 DBUG_ENTER_FUNC ();
589  
590 # ---------------------------------------------------------------------
591 # Make sure no hash value is undef !!!
592 # ---------------------------------------------------------------------
593  
594 # You can only add to this list, you can't remove anything from it!
595 # See should_we_hide_sensitive_data () on how this list is used.
596 28 DBUG_PRINT ("INFO", "Initializing the tag patterns to hide from fish ...");
597 28 push ( @hide_from_fish, "password" );
598 28 push ( @hide_from_fish, "pass" );
599 28 push ( @hide_from_fish, "pwd" );
600  
601 # ---------------------------------------------------------------------
602  
603 28 DBUG_PRINT ("INFO", "Initializing the READ options global hash ...");
604 # Should always be set in the constructor ...
605 28 $default_read_opts{tag_case} = 0; # Case sensitive tags.
606  
607 # The generic options ...
608 28 my %src_empty;
609 28 $default_read_opts{croak} = 0; # Don't croak by default.
610 28 $default_read_opts{export} = 0; # Don't export any tag/val pairs.
611 28 $default_read_opts{use_utf8} = 0; # Doesn't support utf8/Unicode/Wide Chars.
612 28 $default_read_opts{disable_quotes} = 0; # Don't disable balanced quotes.
613 28 $default_read_opts{disable_variables} = 0; # Don't disable variables!
614 28 $default_read_opts{disable_variable_modifiers} = 0; # Don't disable variable modifiers!
615 28 $default_read_opts{disable_decryption} = 0; # Don't disable decryption!
616 # $default_read_opts{enable_backquotes} = 0; # Don't allow random command execution.
617 28 $default_read_opts{trap_recursion} = 0; # Recursion is ignored, not fatal
618 28 $default_read_opts{source_cb} = __PACKAGE__->can ("_source_callback_stub");
619 28 $default_read_opts{source_cb_opts} = \%src_empty;
620  
621 # The file parsing options ...
622 28 $default_read_opts{assign} = '='; # The assignment operator
623 28 $default_read_opts{comment} = '#'; # The comment symbol
624 28 $default_read_opts{source} = '.'; # The file source symbol
625 28 $default_read_opts{section_left} = '['; # The start section string
626 28 $default_read_opts{section_right} = ']'; # The end section string
627 28 $default_read_opts{variable_left} = '${'; # The start variable string
628 28 $default_read_opts{variable_right} = '}'; # The end variable string
629  
630 # Unlikely default values due to security concerns.
631 # $default_read_opts{backquote_left} = '`'x101; # The start backquote string
632 # $default_read_opts{backquote_right} = '`'x102; # The end backquote string
633  
634 # The quote chars ... (Special case doesn't work for anything else.)
635 # See using_default_quotes() if this changes ...
636 28 $default_read_opts{quote_left} = $default_read_opts{quote_right} = "['\"]";
637  
638 # The tag/value modifiers. These labels are found inside the comments!
639 28 $default_read_opts{export_lbl} = "EXPORT"; # Label for a single %ENV.
640 28 $default_read_opts{hide_lbl} = "HIDE"; # Mark as sensitive.
641 28 $default_read_opts{encrypt_lbl} = "ENCRYPT"; # Pending encryption.
642 28 $default_read_opts{decrypt_lbl} = "DECRYPT"; # Already encrypted.
643 28 $default_read_opts{source_file_section_lbl} = "DEFAULT"; # Override default.
644  
645 # The Encrypt/Decrypt options ... (Encode/Decode)
646 28 my %empty_encrypt;
647 28 $default_read_opts{alias} = "";
648 28 $default_read_opts{pass_phrase} = "";
649 28 $default_read_opts{inherit_pass_phrase} = 0;
650 28 $default_read_opts{encrypt_by_user} = 0;
651 28 $default_read_opts{encrypt_cb} = __PACKAGE__->can ("_encryption_callback_stub");
652 28 $default_read_opts{encrypt_cb_opts} = \%empty_encrypt;
653  
654 # Special undocumented test prog option for overriding fish in parse_line().
655 28 $default_read_opts{dbug_test_use_case_parse_override} = 0; # Always off.
656  
657 # Special undocumented test prog option for overriding fish in read_config().
658 28 $default_read_opts{dbug_test_use_case_hide_override} = 0; # Always off.
659  
660  
661 # ---------------------------------------------------------------------
662  
663 28 DBUG_PRINT ("INFO", "Initializing the GET options global hash ...");
664 # Should always be set in the constructor ...
665 28 $default_get_opts{inherit} = 0; # Can inherit from the parent section.
666  
667 # The generic options ... Who cares where set!
668 28 $default_get_opts{required} = 0; # Return undef by default.
669 28 $default_get_opts{vcase} = 0; # Case of the value. (0 = as is)
670 28 $default_get_opts{split_pattern} = qr /\s+/; # Space separated lists.
671  
672 # Used in parsing dates for get_date() ...
673 28 $default_get_opts{date_language} = "English"; # The language to use in parsing dates.
674 28 $default_get_opts{date_language_warn} = 0; # Disable warnings in Date.pm.
675 28 $default_get_opts{date_dl_conversion} = 0; # 1-Enable 0-Disable using Date::Language for parsing.
676 28 $default_get_opts{date_enable_yy} = 0; # 1-Enable 0-Disable using 2 digit years in a date!
677 28 $default_get_opts{date_format} = 3; # Hints are 0 to 8.
678  
679 # These special case options not to show up in the POD ...
680 # All associated with special "get_*()" functions that will auto set if needed.
681 28 $default_get_opts{numeric} = 0; # 0-no, 1-integer (truncate), 2-integer (round), 3-real.
682 28 $default_get_opts{auto_true} = 0; # Don't return as boolean.
683 28 $default_get_opts{filename} = 0; # Tag doesn't do a file test.
684 28 $default_get_opts{directory} = 0; # Tag doesn't do a directory test.
685 28 $default_get_opts{split} = 0; # Don't split the value.
686 28 $default_get_opts{sort} = 0; # Don't sort the split value. (1 - sort, -1 - reverse sort)
687 28 $default_get_opts{date_active} = 0; # 0-No, 1-Yes expecing it to be a date.
688  
689  
690 # ---------------------------------------------------------------------
691  
692 28 DBUG_PRINT ("INFO", "Initializing the DATE formatting options global hash ...");
693 28 $default_date_opts{date_order} = 0; # 0 - YMD, 1 - MDY, 2 - DMY
694 28 $default_date_opts{date_sep} = "-"; # Separator to format dates with.
695 28 $default_date_opts{month_type} = 0; # 0 - numeric, 1 - abbreviate, 2 - full.
696 28 $default_date_opts{month_language} = "English"; # See Date::Language.
697 28 $default_date_opts{use_gmt} = 0; # 0 - localtime, 1 - gmtime.
698 # $default_date_opts{timestamp} = ?; # Special case can't set directly.
699  
700 # ---------------------------------------------------------------------
701  
702  
703 28 DBUG_VOID_RETURN ();
704 }
705  
706 # ==============================================================
707 # A private helper method ... (not exported)
708 sub _get_opt_base
709 7316 ▶{
Subroutine _get_opt_base: called CC=26 SCAR=40.0
710 7316 DBUG_ENTER_FUNC ( @_ );
711 7316 my $user_opts = shift;
712 7316 my $defaults = shift; # Which default hash to validate against ...
713  
714 # Make own copy of the defaults hash ...
715 7316 my %result = %{$defaults};
716  
717 # Must warn about invalid key values ...
718 7316 foreach ( sort keys %{$user_opts} ) {
719 78250 my $k = lc ($_);
720 78250 my $val = $user_opts->{$_};
721  
722 78250 ▶ unless ( exists $defaults->{$k} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $defaults->{$k}) 0 78250 78250
723 0 warn "Unknown option '$k'. Option ignored.\n";
724 0 next;
725 }
726  
727 # -------------------------------------
728 # Trim it to make sure it's valid ...
729 # -------------------------------------
730 78250 my $no_spaces_allowed = 1;
731 78250 ▶ if ( defined $val ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $val) { } 78250 0 78250
732 78250 ▶ if ( $k eq "date_sep" ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($k eq 'date_sep') { } 32 78218 78250
733 32 $no_spaces_allowed = 0;
734 } else {
735 78218 $val =~ s/^\s+//;
736 78218 $val =~ s/\s+$//;
737 }
738  
739 } else {
740 0 ▶ if ( defined $defaults->{$k} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $defaults->{$k}) { } 0 0 0
741 0 warn "Option '$k' has no defined value. Override ignored.\n";
742 } else {
743 0 $result{$k} = undef;
744 }
745 0 next;
746 }
747  
748 # Making sure never undef for easier comparisons later on ...
749 78250 ▶ my $expect = ( defined $defaults->{$k} ) ? $defaults->{$k} : "";
Branch: 1 branch
BranchTrueFalseTotal
defined $defaults->{$k} ? : 78250 0 78250
750  
751 # -------------------------------------
752 # Is this a call back reference ...
753 # -------------------------------------
754 78250 ▶ if ( ref ( $expect ) eq "CODE" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $expect eq "CODE") 996 77254 78250
755 996 my $call;
756 996 ▶ if ( ref ($val) eq "CODE" ) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $val eq 'CODE') { } 992 4 996
elsif (ref $val eq '') { } 4 0 4
757 992 $call = $val;
758 } elsif ( ref ($val) eq "") {
759 4 ▶ if ( $val =~ m/^(.*)::([^:]+)$/ ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($val =~ /^(.*)::([^:]+)$/) { } 4 0 4
elsif ($val ne '') { } 0 0 0
760 4 my ($pkg, $func) = ($1, $2);
761 4 $call = $pkg->can ($func);
762 } elsif ( $val ne "" ) {
763 0 $call = "main"->can ($val);
764 }
765 }
766  
767 996 ▶ if ( $call ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($call) { } 994 2 996
768 994 $result{$k} = $call;
769 } else {
770 2 warn "Option '$k' must be a callback function. Can't reference '$val'. Override ignored.\n";
771 }
772 996 next;
773 }
774  
775 # -------------------------------------
776 # Is this a regular expression?
777 # Used in calls to split ...
778 # -------------------------------------
779 77254 ▶ if ( ref ( $expect ) eq "Regexp" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $expect eq "Regexp") 3558 73696 77254
780 3558 ▶ if ( ref ( $val ) eq "Regexp" ) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $val eq 'Regexp') { } 3558 0 3558
elsif (ref $val eq '' and $val) { } 0 0 0
781 3558 $result{$k} = $val;
782 ▶ } elsif ( ref ( $val ) eq "" && $val ) {
Condition0%0/3
ref $val eq "" and $val
!ll&&!rl&&r
000
MC/DC0%0/2
ref $val eq "" and $val
ref $val eq "" $val
Truth table0%0/3
A and B
A= ref $val eq ""B= $val
ABresult
0X0
100
111
783 0 $result{$k} = $val;
784 } else {
785 0 warn "Option '$k' must be a Regexp or a string, not '$val'. Override ignored.\n";
786 }
787 }
788  
789 # -------------------------------------
790 # Setting up a work area hash ...
791 # -------------------------------------
792 77254 ▶ if ( ref ( $expect ) eq "HASH" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $expect eq "HASH") 962 76292 77254
793 962 ▶ if ( ref ( $val ) eq "HASH" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $val eq 'HASH') { } 962 0 962
794 962 $result{$k} = $val;
795 } else {
796 0 warn "Option '$k' must be a hash reference, not '$val'. Override ignored.\n";
797 }
798 962 next;
799 }
800  
801 # -------------------------------------
802 76292 ▶ if ( $val eq "" && $expect ne "" && $no_spaces_allowed ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($val eq "" and $expect ne "" and $no_spaces_allowed) 0 76292 76292
Condition83%5/6
$val eq "" and $expect ne "" and $no_spaces_allowed
!ll&&!rl&&r
7629110
$val eq "" and $expect ne ""
!ll&&!rl&&r
754868051
MC/DC0%0/3
$val eq "" and $expect ne "" and $no_spaces_allowed
$val eq "" $expect ne "" $no_spaces_allowed
Truth table75%3/4
A and B and C
A= $val eq ""B= $expect ne ""C= $no_spaces_allowed
ABCresult
0XX0
10X0
1100
1111
803 0 warn "Option '$k' can't be set to the empty string. Override ignored.\n";
804 0 next;
805 }
806  
807 # -------------------------------------
808 76292 ▶ if ( $expect =~ m/^-?\d+$/ && $val !~ m/^-?\d+$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($expect =~ /^-?\d+$/ and not $val =~ /^-?\d+$/) 0 76292 76292
Condition66%2/3
$expect =~ /^-?\d+$/ and not $val =~ /^-?\d+$/
!ll&&!rl&&r
17357589350
MC/DC0%0/2
$expect =~ /^-?\d+$/ and not $val =~ /^-?\d+$/
$expect =~ /^-?\d+$/ not $val =~ /^-?\d+$/
Truth table66%2/3
A and not(B)
A= $expect =~ /^-?\d+$/B= not $val =~ /^-?\d+$/
ABresult
0X0
100
111
809 0 warn "Option '$k' must be numeric ($val). Override ignored.\n";
810 0 next;
811 }
812  
813 # -------------------------------------
814 76292 ▶ if ( $expect !~ m/^-?\d+$/ && $val =~ m/^-?\d+$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $expect =~ /^-?\d+$/ and $val =~ /^-?\d+$/) 0 76292 76292
Condition66%2/3
not $expect =~ /^-?\d+$/ and $val =~ /^-?\d+$/
!ll&&!rl&&r
58935173570
MC/DC0%0/2
not $expect =~ /^-?\d+$/ and $val =~ /^-?\d+$/
not $expect =~ /^-?\d+$/ $val =~ /^-?\d+$/
Truth table66%2/3
not(A) and B
A= not $expect =~ /^-?\d+$/B= $val =~ /^-?\d+$/
ABresult
0X0
100
111
815 0 warn "Option '$k' may not be numeric ($val). Override ignored.\n";
816 0 next;
817 }
818  
819 76292 $result{$k} = $val;
820 }
821  
822 7316 DBUG_RETURN ( \%result );
823 }
824  
825 # ==============================================================
826  
827 =item $ropts = get_read_opts ( [\%user_opts[, \%current_opts]] )
828  
829 This method takes the I<user's> options that override the behavior for reading
830 in your config file by this module and merges it into the I<current> options.
831 If no I<current> options hash reference is given, it will use the module's
832 defaults instead.
833  
834 It returns a hash reference of all applicable "Read" options.
835  
836 =cut
837  
838 # ==============================================================
839 sub get_read_opts
840 528 ▶{
Subroutine get_read_opts: called CC=4 SCAR=14.6
Pod documented
841 528 DBUG_ENTER_FUNC ( @_ );
842 528 my $user_opts = shift;
843 528 my $current = shift;
844  
845 # Get the default values ...
846 528 my %def = %default_read_opts;
847 528 my $ref = \%def;
848  
849 528 ▶ $ref = _get_opt_base ( $current, $ref ) if ( defined $current );
Branch: 1 branch
BranchTrueFalseTotal
if defined $current 219 309 528
850 528 ▶ $ref = _get_opt_base ( $user_opts, $ref ) if ( defined $user_opts );
Branch: 1 branch
BranchTrueFalseTotal
if defined $user_opts 410 118 528
851  
852 # Some additional validation ...
853 528 ▶ if ( $ref->{encrypt_lbl} eq $ref->{decrypt_lbl} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ref->{"encrypt_lbl"} eq $ref->{"decrypt_lbl"}) 0 528 528
854 0 my $val = $ref->{encrypt_lbl};
855 0 $ref->{encrypt_lbl} = $default_read_opts{encrypt_lbl};
856 0 $ref->{decrypt_lbl} = $default_read_opts{decrypt_lbl};
857 0 warn ("Options 'encrypt_lbl' and 'decrypt_lbl' may not be set to the same value ($val).\n",
858 "Resetting both to their default settings!\n");
859 }
860  
861 528 DBUG_RETURN ( $ref );
862 }
863  
864 # ==============================================================
865  
866 =item $gopts = get_get_opts ( [\%user_opts[, \%current_opts]] )
867  
868 This method takes the I<user's> options that override the behavior of I<get>
869 methods for this module and merges it into the I<current> options. If no
870 I<current> options hash reference is given, it will use the module's defaults
871 instead.
872  
873 It returns a hash reference of all applicable "Get" options.
874  
875 =cut
876  
877 # ==============================================================
878 sub get_get_opts
879 3386 ▶{
Subroutine get_get_opts: called CC=5 SCAR=17.2
Pod documented
880 3386 DBUG_ENTER_FUNC ( @_ );
881 3386 my $user_opts = shift;
882 3386 my $current = shift;
883  
884 # Get the default values ...
885 3386 my %def = %default_get_opts;
886 3386 my $ref = \%def;
887  
888 3386 ▶ $ref = _get_opt_base ( $current, $ref ) if ( defined $current );
Branch: 1 branch
BranchTrueFalseTotal
if defined $current 3280 106 3386
889 3386 ▶ $ref = _get_opt_base ( $user_opts, $ref ) if ( defined $user_opts );
Branch: 1 branch
BranchTrueFalseTotal
if defined $user_opts 3343 43 3386
890  
891 # Some additional validation ...
892 3386 ▶ unless ( 0 <= $ref->{date_format} && $ref->{date_format} <= 8 ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (0 <= $ref->{"date_format"} and $ref->{"date_format"} <= 8) 0 3386 3386
Condition33%1/3
0 <= $ref->{"date_format"} and $ref->{"date_format"} <= 8
!ll&&!rl&&r
003386
MC/DC0%0/2
0 <= $ref->{"date_format"} and $ref->{"date_format"} <= 8
0 <= $ref->{"date_format"} $ref->{"date_format"} <= 8
Truth table33%1/3
A and B
A= 0 <= $ref->{"date_format"}B= $ref->{"date_format"} <= 8
ABresult
0X0
100
111
893 0 my $val = $ref->{date_format};
894 0 $ref->{date_format} = $default_read_opts{date_format};
895 0 warn ("Option 'date_format' is invalid ($val). Resetting to it's default!\n");
896 }
897  
898 3386 DBUG_RETURN ( $ref );
899 }
900  
901 # ==============================================================
902  
903 =item $dopts = get_date_opts ( [\%user_opts[, \%current_opts]] )
904  
905 This method takes the I<user's> options that override the behavior of I<date>
906 formatting for this module and merges it into the I<current> options. If no
907 I<current> options hash reference is given, it will use the module's defaults
908 instead.
909  
910 It returns a hash reference of all applicable "Date" formatting options.
911  
912 =cut
913  
914 # ==============================================================
915 sub get_date_opts
916 116 ▶{
Subroutine get_date_opts: called CC=3 SCAR=11.0
Pod documented
917 116 DBUG_ENTER_FUNC ( @_ );
918 116 my $user_opts = shift;
919 116 my $current = shift;
920  
921 # Get the default values ...
922 116 my %def = %default_date_opts;
923 116 my $ref = \%def;
924  
925 116 ▶ $ref = _get_opt_base ( $current, $ref ) if ( defined $current );
Branch: 1 branch
BranchTrueFalseTotal
if defined $current 9 107 116
926 116 ▶ $ref = _get_opt_base ( $user_opts, $ref ) if ( defined $user_opts );
Branch: 1 branch
BranchTrueFalseTotal
if defined $user_opts 55 61 116
927  
928 116 DBUG_RETURN ( $ref );
929 }
930  
931 # ==============================================================
932  
933 =item $ref = apply_get_rules ( $tag, $section, $val1, $val2, $wide, $getOpts )
934  
935 Returns an updated hash reference containing the requested data value after all
936 the I<$getOpts> rules have been applied. If the I<$tag> doesn't exist then it
937 will return B<undef> instead or B<die> if it's I<required>.
938  
939 I<$val1> is the DATA hash value from the specified section.
940  
941 I<$val2> is the DATA hash value from the parent section. This value is ignored
942 unless the I<inherit> option was specified via I<$getOpts>.
943  
944 I<$wide> tells if UTF-8 dates are allowed.
945  
946 =cut
947  
948 # ==============================================================
949 sub apply_get_rules
950 68564 ▶{
Subroutine apply_get_rules: called CC=57 SCAR=41.7
Pod documented
951 68564 DBUG_ENTER_FUNC (@_);
952 68564 my $tag = shift; # The tag we are processing ...
953 68564 my $section = shift; # The name of the current section ...
954 68564 my $value1 = shift; # The value hash from the current section ...
955 68564 my $value2 = shift; # The value hash from the "main" section ...
956 68564 my $wide_flg = shift; # Tells if langages like Greek are allowed ...
957 68564 my $get_opts = shift; # The current "Get" options hash ...
958  
959 # Did we find a value to process?
960 68564 my $data = $value1;
961 68564 ▶ if ( $get_opts->{inherit} && (! defined $data) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"inherit"} and not defined $data) 562 68002 68564
Condition100%3/3
$get_opts->{"inherit"} and not defined $data
!ll&&!rl&&r
67897105562
MC/DC100%2/2
$get_opts->{"inherit"} and not defined $data
$get_opts->{"inherit"} not defined $data
Truth table100%3/3
A and not(B)
A= $get_opts->{"inherit"}B= not defined $data
ABresult
0X0
100
111
962 562 $data = $value2;
963 }
964 68564 ▶ unless ( defined $data ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $data) 9028 59536 68564
965 9028 return DBUG_RETURN ( croak_helper ( $get_opts,
966 "No such tag ($tag) in section ($section).",
967 undef ) );
968 }
969  
970 # Make a local copy to work with, we don't want to modify the source.
971 # We're only interested in two entries from the hash: VALUE & MASK_IN_FISH.
972 # All others are ignored by this method.
973 59536 my %result = %{$data};
974  
975 # Do we split up the value? ( Took 2 options to implement the split. )
976 59536 my @vals;
977 59536 ▶ unless ( $get_opts->{split} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{'split'}) { } 266 59270 59536
978 59270 push (@vals, $result{VALUE}); # Nope!
979  
980 } else {
981 266 @vals = split ( $get_opts->{split_pattern}, $result{VALUE} );
982 266 $result{VALUE} = \@vals;
983 }
984  
985 # Only if sorting, assume everything in the list is numeric ...
986 59536 ▶ my $is_all_numbers = $get_opts->{sort} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$get_opts->{'sort'} ? : 125 59411 59536
987  
988 # Do any validation that needs to be done against the individual parts ...
989 59536 foreach my $v ( @vals ) {
990 60452 my $old = $v; # Save in case someone modifies $v!
991  
992 # -------------------------------------------------------------------
993 # Do we need to convert to upper or lower case?
994 60452 ▶ if ( $get_opts->{vcase} > 0 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($get_opts->{'vcase'} > 0) { } 0 60452 60452
elsif ($get_opts->{'vcase'} < 0) { } 0 60452 60452
995 0 $v = uc ( $v );
996 } elsif ( $get_opts->{vcase} < 0 ) {
997 0 $v = lc ( $v );
998 }
999  
1000 # -------------------------------------------------------------------
1001 # Convert into a boolean value ??? (you never see the original value)
1002 60452 ▶ if ( $get_opts->{auto_true} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"auto_true"}) 89 60363 60452
1003 89 $result{MASK_IN_FISH} = 0; # Boolean values are never sensitive!
1004  
1005 89 my $numeric = 0;
1006 89 ▶ if ( $old =~ m/^[-+]?\d+([.]\d*)?$/ ||
Branch: 1 branch
BranchTrueFalseTotal
if ($old =~ /^[-+]?\d+([.]\d*)?$/ or $old =~ /^[-+]?[.]\d+$/) 48 41 89
Condition100%3/3
$old =~ /^[-+]?\d+([.]\d*)?$/ or $old =~ /^[-+]?[.]\d+$/
l!l&&r!l&&!r
42641
MC/DC100%2/2
$old =~ /^[-+]?\d+([.]\d*)?$/ or $old =~ /^[-+]?[.]\d+$/
$old =~ /^[-+]?\d+([.]\d*)?$/ $old =~ /^[-+]?[.]\d+$/
Truth table100%3/3
A or B
A= $old =~ /^[-+]?\d+([.]\d*)?$/B= $old =~ /^[-+]?[.]\d+$/
ABresult
1X1
011
000
1007 $old =~ m/^[-+]?[.]\d+$/ ) {
1008 48 $numeric = 1;
1009 48 $old += 0; # Convert string to a number ...
1010 }
1011  
1012 89 $v = 0; # Assume FALSE ...
1013 89 ▶ unless ( $old ) {
Branch: 3 branches
BranchTrueFalseTotal
if ($old) { } 64 25 89
if (do { $numeric }) { } 24 40 64
elsif ($old =~ /(^true[.!;]?$)|(^yes[.!;]?$)|(^good[.!;]?$)|(^[TYG]$)|(^on[.!;]?$)/i) { } 18 22 40
1014 ;
1015 } elsif ( $numeric ) {
1016 24 $v = 1; # It's TRUE for a non-zero numeric value ...
1017 } elsif ( $old =~ m/(^true[.!;]?$)|(^yes[.!;]?$)|(^good[.!;]?$)|(^[TYG]$)|(^on[.!;]?$)/i ) {
1018 18 $v = 1; # It's TRUE for certain text strings ...
1019 }
1020 }
1021  
1022 # -------------------------------------------------------------------
1023 # Are we requiring it to be a numeric value?
1024 # Also run if we want to test if something is numeric for the later sort!
1025 # 0 - Skip test.
1026 # 1 - integer (round).
1027 # 2 - integer (truncate).
1028 # 3 - real.
1029 60452 ▶ if ( $get_opts->{numeric} || $is_all_numbers ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"numeric"} or $is_all_numbers) 496 59956 60452
Condition100%3/3
$get_opts->{"numeric"} or $is_all_numbers
l!l&&r!l&&!r
32816859956
MC/DC100%2/2
$get_opts->{"numeric"} or $is_all_numbers
$get_opts->{"numeric"} $is_all_numbers
Truth table100%3/3
A or B
A= $get_opts->{"numeric"}B= $is_all_numbers
ABresult
1X1
011
000
1030 496 my $fp = 0;
1031 496 my $err;
1032 496 my $run_flg = ($get_opts->{numeric} != 0);
1033  
1034 496 ▶ if ( $v =~ m/^[+-]?\d+([.]\d*)?[Ee][+-]?\d+$/ ||
Branch: 3 branches
BranchTrueFalseTotal
if ($v =~ /^[+-]?\d+([.]\d*)?[Ee][+-]?\d+$/ or $v =~ /^[+-]?[.]\d+[Ee][+-]?\d$/) { } 0 496 496
elsif ($v =~ /^[+-]?\d+$/) { } 281 215 496
elsif ($v =~ /^[+-]?\d+[.]\d*$/ or $v =~ /^[+-]?[.]\d+$/) { } 168 47 215
Condition33%1/3
$v =~ /^[+-]?\d+([.]\d*)?[Ee][+-]?\d+$/ or $v =~ /^[+-]?[.]\d+[Ee][+-]?\d$/
l!l&&r!l&&!r
00496
MC/DC0%0/2
$v =~ /^[+-]?\d+([.]\d*)?[Ee][+-]?\d+$/ or $v =~ /^[+-]?[.]\d+[Ee][+-]?\d$/
$v =~ /^[+-]?\d+([.]\d*)?[Ee][+-]?\d+$/ $v =~ /^[+-]?[.]\d+[Ee][+-]?\d$/
Truth table33%1/3
A or B
A= $v =~ /^[+-]?\d+([.]\d*)?[Ee][+-]?\d+$/B= $v =~ /^[+-]?[.]\d+[Ee][+-]?\d$/
ABresult
1X1
011
000
1035 $v =~ m/^[+-]?[.]\d+[Ee][+-]?\d$/ ) {
1036 0 $fp = 1; # In Scientific Notiation ...
1037 0 ▶ if ( $run_flg ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($run_flg) 0 0 0
1038 0 $v += 0; # Converts out of Scientific Notiation if possible!
1039 }
1040 } elsif ( $v =~ m/^[+-]?\d+$/ ) {
1041 281 $fp = 0; # It was an integer ...
1042 ▶ } elsif ( $v =~ m/^[+-]?\d+[.]\d*$/ ||
Condition100%3/3
$v =~ /^[+-]?\d+[.]\d*$/ or $v =~ /^[+-]?[.]\d+$/
l!l&&r!l&&!r
165347
MC/DC100%2/2
$v =~ /^[+-]?\d+[.]\d*$/ or $v =~ /^[+-]?[.]\d+$/
$v =~ /^[+-]?\d+[.]\d*$/ $v =~ /^[+-]?[.]\d+$/
Truth table100%3/3
A or B
A= $v =~ /^[+-]?\d+[.]\d*$/B= $v =~ /^[+-]?[.]\d+$/
ABresult
1X1
011
000
1043 $v =~ m/^[+-]?[.]\d+$/ ) {
1044 168 $fp = 1; # A floating point numeric value ...
1045 168 ▶ $v += 0 if ( $run_flg );
Branch: 1 branch
BranchTrueFalseTotal
if $run_flg 120 48 168
1046 } else {
1047 47 $err = 1; # Not a valid number!
1048 47 $is_all_numbers = 0;
1049 }
1050  
1051 # If really a floating point number & asking for an integer ...
1052 496 ▶ if ( $run_flg && $fp && $get_opts->{numeric} != 3 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($run_flg and $fp and $get_opts->{"numeric"} != 3) 80 416 496
Condition100%6/6
$run_flg and $fp and $get_opts->{"numeric"} != 3
!ll&&!rl&&r
3764080
$run_flg and $fp
!ll&&!rl&&r
168208120
MC/DC100%3/3
$run_flg and $fp and $get_opts->{"numeric"} != 3
$run_flg $fp $get_opts->{"numeric"} != 3
Truth table100%4/4
A and B and C
A= $run_flgB= $fpC= $get_opts->{"numeric"} != 3
ABCresult
0XX0
10X0
1100
1111
1053 80 ▶ if ( $get_opts->{numeric} == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{'numeric'} == 1) { } 40 40 80
1054 40 $v = sprintf ("%.0f", $v); # Round it up ...
1055 } else {
1056 40 $v = sprintf ("%d", $v); # Truncate it ...
1057 }
1058 }
1059  
1060 496 ▶ if ( $err && $run_flg ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err and $run_flg) 15 481 496
Condition100%3/3
$err and $run_flg
!ll&&!rl&&r
4493215
MC/DC100%2/2
$err and $run_flg
$err $run_flg
Truth table100%3/3
A and B
A= $errB= $run_flg
ABresult
0X0
100
111
1061 15 return DBUG_RETURN ( croak_helper ( $get_opts,
1062 "Value is not numeric ($v) for tag ($tag) in section ($section).",
1063 undef ) );
1064 }
1065 }
1066  
1067 # -------------------------------------------------------------------
1068 # Are we expecting to find a date someplace inside this string?
1069 60437 ▶ if ( $get_opts->{date_active} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"date_active"}) 2687 57750 60437
1070 2687 my @order = ( "1", "2", "3", "1,2,3", "1,3,2", "2,3,1", "2,1,3", "3,2,1", "3,1,2" );
1071 my $l = swap_language ( $get_opts->{date_language},
1072 $get_opts->{date_language_warn},
1073 2687 $wide_flg );
1074 my $date = parse_date ( $v, $order[$get_opts->{date_format}],
1075 $get_opts->{date_dl_conversion},
1076 2687 $get_opts->{date_enable_yy} );
1077 2687 ▶ if ( $date ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($date) { } 2673 14 2687
1078 2673 $v = $date;
1079 } else {
1080 14 ▶ my $l2 = $get_opts->{date_language} || $l;
Condition33%1/3
$get_opts->{'date_language'} || $l
l!l&&r!l&&!r
1400
MC/DC0%0/2
$get_opts->{'date_language'} || $l
$get_opts->{'date_language'} $l
Truth table33%1/3
A || B
A= $get_opts->{'date_language'}B= $l
ABresult
1X1
011
000
1081 14 return DBUG_RETURN ( croak_helper ( $get_opts,
1082 "Value is not a date ($v) for tag ($tag) in section ($section) for language ($l2).",
1083 undef ) );
1084 }
1085 }
1086  
1087 # -------------------------------------------------------------------
1088 # Are we referencing a file?
1089 60423 ▶ if ( $get_opts->{filename} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"filename"}) 18 60405 60423
1090 18 my $valid = 1; # Assume it's a filename ...
1091 18 ▶ $valid = 0 unless ( -f $v );
Branch: 1 branch
BranchTrueFalseTotal
unless -f $v 10 8 18
1092 18 ▶ $valid = 0 if ( ($get_opts->{filename} & 2) && ! -r _ );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"filename"} & 2 and not -r _ 0 18 18
Condition33%1/3
$get_opts->{"filename"} & 2 and not -r _
!ll&&!rl&&r
1800
MC/DC0%0/2
$get_opts->{"filename"} & 2 and not -r _
$get_opts->{"filename"} & 2 not -r _
Truth table33%1/3
A and not(B)
A= $get_opts->{"filename"} & 2B= not -r _
ABresult
0X0
100
111
1093 18 ▶ $valid = 0 if ( ($get_opts->{filename} & 4) && ! -w _ );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"filename"} & 4 and not -w _ 0 18 18
Condition33%1/3
$get_opts->{"filename"} & 4 and not -w _
!ll&&!rl&&r
1800
MC/DC0%0/2
$get_opts->{"filename"} & 4 and not -w _
$get_opts->{"filename"} & 4 not -w _
Truth table33%1/3
A and not(B)
A= $get_opts->{"filename"} & 4B= not -w _
ABresult
0X0
100
111
1094 18 ▶ $valid = 0 if ( ($get_opts->{filename} & 8) && ! -x _ );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"filename"} & 8 and not -x _ 0 18 18
Condition33%1/3
$get_opts->{"filename"} & 8 and not -x _
!ll&&!rl&&r
1800
MC/DC0%0/2
$get_opts->{"filename"} & 8 and not -x _
$get_opts->{"filename"} & 8 not -x _
Truth table33%1/3
A and not(B)
A= $get_opts->{"filename"} & 8B= not -x _
ABresult
0X0
100
111
1095 18 ▶ unless ( $valid ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($valid) 10 8 18
1096 10 return DBUG_RETURN ( croak_helper ( $get_opts,
1097 "Tag ${tag} doesn't reference a valid filename or it doesn't have the requested permissions! ($v)",
1098 undef ) );
1099 }
1100 }
1101  
1102 # -------------------------------------------------------------------
1103 # Are we referencing a directory?
1104 60413 ▶ if ( $get_opts->{directory} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"directory"}) 19 60394 60413
1105 19 my $valid = 1; # Assume it's a directory ...
1106 19 ▶ $valid = 0 unless ( -d $v );
Branch: 1 branch
BranchTrueFalseTotal
unless -d $v 10 9 19
1107 19 ▶ $valid = 0 if ( ($get_opts->{directory} & 2) && ! -r _ );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"directory"} & 2 and not -r _ 0 19 19
Condition66%2/3
$get_opts->{"directory"} & 2 and not -r _
!ll&&!rl&&r
1360
MC/DC0%0/2
$get_opts->{"directory"} & 2 and not -r _
$get_opts->{"directory"} & 2 not -r _
Truth table66%2/3
A and not(B)
A= $get_opts->{"directory"} & 2B= not -r _
ABresult
0X0
100
111
1108 19 ▶ $valid = 0 if ( ($get_opts->{directory} & 4) && ! -w _ );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"directory"} & 4 and not -w _ 0 19 19
Condition66%2/3
$get_opts->{"directory"} & 4 and not -w _
!ll&&!rl&&r
1810
MC/DC0%0/2
$get_opts->{"directory"} & 4 and not -w _
$get_opts->{"directory"} & 4 not -w _
Truth table66%2/3
A and not(B)
A= $get_opts->{"directory"} & 4B= not -w _
ABresult
0X0
100
111
1109 19 ▶ $valid = 0 if ( ($get_opts->{directory} & 8) && ! -x _ );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"directory"} & 8 and not -x _ 0 19 19
Condition66%2/3
$get_opts->{"directory"} & 8 and not -x _
!ll&&!rl&&r
1360
MC/DC0%0/2
$get_opts->{"directory"} & 8 and not -x _
$get_opts->{"directory"} & 8 not -x _
Truth table66%2/3
A and not(B)
A= $get_opts->{"directory"} & 8B= not -x _
ABresult
0X0
100
111
1110 19 ▶ unless ( $valid ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($valid) 10 9 19
1111 10 return DBUG_RETURN ( croak_helper ( $get_opts,
1112 "Tag ${tag} doesn't reference a valid directory or it doesn't have the requested permissions! ($v)",
1113 undef ) );
1114 }
1115 }
1116  
1117 # -------------------------------------------------------------------
1118 # If not splitting after all, save any changes ... (keep last in loop)
1119 60403 ▶ if ( (! $get_opts->{split}) && $old ne $v ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $get_opts->{"split"} and $old ne $v) 2663 57740 60403
Condition100%3/3
not $get_opts->{"split"} and $old ne $v
!ll&&!rl&&r
1179565612663
MC/DC100%2/2
not $get_opts->{"split"} and $old ne $v
not $get_opts->{"split"} $old ne $v
Truth table100%3/3
not(A) and B
A= not $get_opts->{"split"}B= $old ne $v
ABresult
0X0
100
111
1120 2663 $result{VALUE} = $v;
1121 }
1122 } # End foreach @vals loop ...
1123  
1124  
1125 # Do we need to sort the results ???
1126 59487 ▶ if ( $get_opts->{split} && $get_opts->{sort} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($get_opts->{"split"} and $get_opts->{"sort"}) 125 59362 59487
Condition100%3/3
$get_opts->{"split"} and $get_opts->{"sort"}
!ll&&!rl&&r
59224138125
MC/DC100%2/2
$get_opts->{"split"} and $get_opts->{"sort"}
$get_opts->{"split"} $get_opts->{"sort"}
Truth table100%3/3
A and B
A= $get_opts->{"split"}B= $get_opts->{"sort"}
ABresult
0X0
100
111
1127 125 ▶ if ( $is_all_numbers ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_all_numbers) { } 93 32 125
1128 93 @{$result{VALUE}} = sort { $a <=> $b } @{$result{VALUE}};
1129 } else {
1130 32 @{$result{VALUE}} = sort ( @{$result{VALUE}} );
1131 }
1132 125 ▶ @{$result{VALUE}} = reverse ( @{$result{VALUE}} ) if ( $get_opts->{sort} < 0 );
Branch: 1 branch
BranchTrueFalseTotal
if $get_opts->{"sort"} < 0 60 65 125
1133 }
1134  
1135 59487 DBUG_RETURN ( \%result );
1136 }
1137  
1138 # ==============================================================
1139  
1140 =item $boolean = is_assign_spaces ( $ropts )
1141  
1142 Tells if the assignment operator selected is the special case of using spaces
1143 to separate the tag/value pair. Only returns true if it's B<\\s>.
1144  
1145 =cut
1146  
1147 # No fish since it's called so frequently, over & over again ...
1148 sub is_assign_spaces
1149 131186 ▶{
Subroutine is_assign_spaces: called CC=2 SCAR=6.9
Pod documented
1150 # Checking the ${rOpts} settings ...
1151 131186 ▶ return ( exists $_[0]->{assign} && $_[0]->{assign} eq "\\s" );
Condition100%3/3
exists $_[0]{'assign'} && $_[0]{'assign'} eq '\\s'
!ll&&!rl&&r
8130778400
MC/DC100%2/2
exists $_[0]{'assign'} && $_[0]{'assign'} eq '\\s'
exists $_[0]{'assign'} $_[0]{'assign'} eq '\\s'
Truth table100%3/3
A && B
A= exists $_[0]{'assign'}B= $_[0]{'assign'} eq '\\s'
ABresult
0X0
100
111
1152 }
1153  
1154 # ==============================================================
1155  
1156 =item $boolean = using_default_quotes ( $ropts )
1157  
1158 This function tells if you are currently using the default quotes. This is the
1159 only case where there can be multiple values for the quote string anchors. All
1160 other cases allow only for a single value for each of the quote string anchors.
1161  
1162 =cut
1163  
1164 sub using_default_quotes
1165 76786 ▶{
Subroutine using_default_quotes: called CC=5 SCAR=16.1
Pod documented
1166 76786 DBUG_ENTER_FUNC ( @_ );
1167 76786 my $ropts = shift;
1168  
1169 76786 my $def = 0; # Assume not using the default quotes ...
1170  
1171 76786 ▶ unless ( $ropts->{disable_quotes} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ropts->{"disable_quotes"}) 76776 10 76786
1172 76776 ▶ if ( $ropts->{quote_left} eq $ropts->{quote_right} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ropts->{"quote_left"} eq $ropts->{"quote_right"}) 76459 317 76776
1173 76459 ▶ if ( $ropts->{quote_left} eq "['\"]" ||
Branch: 1 branch
BranchTrueFalseTotal
if ($ropts->{"quote_left"} eq "['\"]" or $ropts->{"quote_left"} eq "[\"']") 69068 7391 76459
Condition66%2/3
$ropts->{"quote_left"} eq "['\"]" or $ropts->{"quote_left"} eq "[\"']"
l!l&&r!l&&!r
6906807391
MC/DC50%1/2
$ropts->{"quote_left"} eq "['\"]" or $ropts->{"quote_left"} eq "[\"']"
$ropts->{"quote_left"} eq "['\"]" $ropts->{"quote_left"} eq "[\"']"
Truth table66%2/3
A or B
A= $ropts->{"quote_left"} eq "['\"]"B= $ropts->{"quote_left"} eq "[\"']"
ABresult
1X1
011
000
1174 $ropts->{quote_left} eq "[\"']" ) {
1175 69068 $def = 1;
1176 }
1177 }
1178 }
1179  
1180 76786 DBUG_RETURN ( $def );
1181 }
1182  
1183  
1184 # ==============================================================
1185  
1186 =item $str = convert_to_regexp_string ( $string[, $no_logs] )
1187  
1188 Converts the passed string that may contain special chars for a Perl RegExp
1189 into something that is a literal constant value to Perl's RegExp engine by
1190 turning these problem chars into escape sequences.
1191  
1192 It then returns the new string.
1193  
1194 If I<$no_logs> is set to a non-zero value, it won't write anything to the logs.
1195  
1196 =cut
1197  
1198 sub convert_to_regexp_string
1199 461369 ▶{
Subroutine convert_to_regexp_string: called CC=3 SCAR=11.0
Pod documented
1200 461369 my $no_fish = $_[1];
1201 461369 ▶ DBUG_ENTER_FUNC ( @_ ) unless ( $no_fish );;
Branch: 1 branch
BranchTrueFalseTotal
unless $no_fish 52995 408374 461369
1202 461369 my $str = shift;
1203  
1204 # The 8 problem chars with special meaning in a RegExp ...
1205 # Chars: . + ^ | $ \ * ?
1206 461369 $str =~ s/([.+^|\$\\*?])/\\$1/g;
1207  
1208 # As do these 3 types of brackets: (), {}, []
1209 461369 $str =~ s/([(){}[\]])/\\$1/g;
1210  
1211 461369 ▶ return DBUG_RETURN ( $str ) unless ( $no_fish );
Branch: 1 branch
BranchTrueFalseTotal
unless $no_fish 52995 408374 461369
1212 408374 return ( $str );
1213 }
1214  
1215 # ==============================================================
1216  
1217 =item $str = convert_to_regexp_modifier ( $string )
1218  
1219 Similar to C<convert_to_regexp_string> except that it doesn't convert
1220 all the wild card chars.
1221  
1222 Leaves the following RegExp wild card's unescaped!
1223 S<(B<*>, B<?>, B<[>, and B<]>)>
1224  
1225 Used when processing variable modifier rules.
1226  
1227 =cut
1228  
1229 sub convert_to_regexp_modifier
1230 11 ▶{
Subroutine convert_to_regexp_modifier: called CC=1 SCAR=0.0
Pod documented
1231 11 DBUG_ENTER_FUNC ( @_ );
1232 11 my $str = shift;
1233  
1234 # The 6 problem chars with special meaning in a RegExp ...
1235 # Chars: . + ^ | $ \ (Skips * ?)
1236 11 $str =~ s/([.+^|\$\\])/\\$1/g;
1237  
1238 # As do these 2 of 3 types of brackets: () & {}, not []
1239 11 $str =~ s/([(){}])/\\$1/g;
1240  
1241 11 DBUG_RETURN ( $str );
1242 }
1243  
1244 # ==============================================================
1245  
1246 =item $sensitive = should_we_hide_sensitive_data ( $tag )
1247  
1248 Checks the tag against an internal list of patterns to see if there is a match.
1249 This check is done in a case insensitive way.
1250  
1251 If there is a match it will return true and the caller should take care about
1252 writing anything about this tag to any log files.
1253  
1254 If there is no match it will return false, and you can write what you please to
1255 your logs.
1256  
1257 See I<make_it_sensitive> to add additional patterns to the list.
1258  
1259 =cut
1260  
1261 sub should_we_hide_sensitive_data
1262 55350 ▶{
Subroutine should_we_hide_sensitive_data: called CC=4 SCAR=13.9
Pod documented
1263 55350 my $tag = shift;
1264 55350 my $skip_fish = shift; # Undocumented ...
1265  
1266 55350 my $sensitive = 0; # Assume it's not to be hidden!
1267  
1268 55350 foreach my $hide ( @hide_from_fish ) {
1269 168394 ▶ if ( $tag =~ m/${hide}/i ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag =~ /$hide/i) 259 168135 168394
1270 259 $sensitive = 1; # We found a match! It's sensitive!
1271 }
1272 }
1273  
1274 55350 ▶ unless ( $skip_fish ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($skip_fish) 675 54675 55350
1275 675 DBUG_ENTER_FUNC ( $tag, $skip_fish, @_ );
1276 675 return DBUG_RETURN ( $sensitive );
1277 }
1278  
1279 54675 return ( $sensitive );
1280 }
1281  
1282 # ==============================================================
1283  
1284 =item make_it_sensitive ( @patterns )
1285  
1286 Add these pattern(s) to the internal list of patterns that this module considers
1287 sensitive. Should any tag contain this pattern, that tag's value will be
1288 masked when written to this module's internal logs. Leading/trailing spaces
1289 will be ignored in the pattern. Wild cards are not honored.
1290  
1291 The 3 default patterns are password, pass, and pwd.
1292  
1293 This pattern affects all L<Advanced::Config> objects loaded into memory. Not
1294 just the current one.
1295  
1296 =cut
1297  
1298 sub make_it_sensitive
1299 4 ▶{
Subroutine make_it_sensitive: called CC=4 SCAR=14.0
Pod documented
1300 4 DBUG_ENTER_FUNC ( @_ );
1301 4 my @tags = @_;
1302  
1303 4 foreach my $tag ( @tags ) {
1304 8 ▶ if ( $tag ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag) 8 0 8
1305 8 $tag =~ s/^\s+//;
1306 8 $tag =~ s/\s+$//;
1307 8 ▶ if ( $tag ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag) 8 0 8
1308 8 $tag = convert_to_regexp_string ( $tag, 1 );
1309 8 push ( @hide_from_fish, $tag );
1310 }
1311 }
1312 }
1313  
1314 4 DBUG_VOID_RETURN ();
1315 }
1316  
1317 # ==============================================================
1318  
1319 =item $cnt = sensitive_cnt ( )
1320  
1321 Returns a count of how many sensitive patterns are being used.
1322  
1323 =cut
1324  
1325 sub sensitive_cnt
1326 243 ▶{
Subroutine sensitive_cnt: called CC=1 SCAR=0.0
Pod documented
1327 243 DBUG_ENTER_FUNC ( @_ );
1328 243 DBUG_RETURN ( scalar (@hide_from_fish) );
1329 }
1330  
1331 # ==============================================================
1332  
1333 =item @ret = croak_helper ($opts, $croak_message, @croak_return_vals)
1334  
1335 This helper method helps standardizes what to do on fatal errors when reading
1336 the config file or what to do if you can't find the tag on lookups.
1337  
1338 It knows I<\%opts> is a "Read" option hash if B<croak> is a member and it's
1339 a "Get" option hash if B<required> is a member. Both options use the same
1340 logic when called.
1341  
1342 See B<croak> and B<required> on what these options do.
1343  
1344 Returns whatever I<@croak_return_vals> references. It may be a single value or
1345 an array of values.
1346  
1347 It calls B<warn> or B<die> with the message passed.
1348  
1349 =cut
1350  
1351 # ==============================================================
1352 # No ENTER/RETURN fish calls on purpose here ...
1353  
1354 sub croak_helper
1355 9084 ▶{
Subroutine croak_helper: called CC=7 SCAR=19.6
Pod documented
1356 9084 my $opts = shift;
1357 9084 my $msg = shift;
1358 9084 my @ret = @_; # Use whatever was passed to me ...
1359  
1360 # Look up the needed value in the hash we'd like to test out.
1361 9084 my $croak = 0;
1362 9084 ▶ if ( exists $opts->{croak} ) {
Branch: 2 branches
BranchTrueFalseTotal
if (exists $opts->{'croak'}) { } 5 9079 9084
elsif (exists $opts->{'required'}) { } 9079 0 9079
1363 5 $croak = $opts->{croak}; # From the Read Opt Hash ...
1364 } elsif ( exists $opts->{required} ) {
1365 9079 $croak = $opts->{required}; # From the Get Opt Hash ...
1366 }
1367  
1368 9084 ▶ if ( $croak > 0 ) {
Branch: 3 branches
BranchTrueFalseTotal
if ($croak > 0) { } 2 9082 9084
elsif ($croak == -9876) { } 8986 96 9082
elsif ($croak < 0) { } 0 96 96
1369 2 die ($msg, "\n");
1370  
1371 # The -9876 value is undocumented where we don't even want the msg in fish!
1372 } elsif ( $croak == -9876 ) {
1373 ;
1374  
1375 } elsif ( $croak < 0 ) {
1376 0 warn ($msg, "\n");
1377  
1378 } else {
1379 96 DBUG_PRINT ("WARN", $msg);
1380 }
1381  
1382 9082 ▶ return ( wantarray ? @ret : $ret[0] );
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 9080 2 9082
1383 }
1384  
1385 # ==============================================================
1386  
1387 =item $lvl = set_special_date_vars ( $date_opts_ref, $date_hash_ref[, $old_hash_ref] )
1388  
1389 The I<$date_opts_ref> contains the special date variable formatting options
1390 used to control the formattiong of the data returned via I<$date_hash_ref>.
1391 The relevant tags are: I<date_order>, I<date_sep>, I<month_type>, I<use_gmt>
1392 and I<month_language>. Any missing hash key and it's default is used.
1393  
1394 This function populates the following date keys in I<$date_hash_ref> for use
1395 by the config object using the current date/time. These keys are also defined
1396 as the date variables available for use by your config files.
1397  
1398 The keys set are: (Shown using the default formats)
1399  
1400 today, yesterday, tomorrow -- A formatted date in YYYY-MM-DD format.
1401 this_month, last_month, next_month -- The Month.
1402 this_year, last_year, next_year -- A 4 digit year.
1403 this_period, last_period, next_period -- The YYYY-MM part of a date.
1404 dow -- The day of the week (Sunday to Saturday or 1..7).
1405 doy -- The day of the year (1..365 most years, 1..366 in leap years).
1406 dom -- The day of the month. (1..31)
1407 timestamp -- The time used to generate the above variables with. [time()]
1408  
1409 The I<$old_hash_ref> contains the values from the previous call to this
1410 function. If missing, assumes 1st time called. If provided and the date
1411 options for this call doesn't match what was used to create this hash
1412 the return value is unreliable.
1413  
1414 Returns the level of what changed in ${date_hash_ref}:
1415  
1416 0 -- Nothing changed from previous call or it's the 1st time called.
1417 1 -- Just the day of month changed.
1418 2 -- The month also changed.
1419 3 -- The year also changed.
1420  
1421 =cut
1422  
1423 # ==============================================================
1424  
1425 sub set_special_date_vars
1426 149 ▶{
Subroutine set_special_date_vars: called CC=22 SCAR=32.7
Pod documented
1427 149 DBUG_ENTER_FUNC (@_);
1428 149 my $opts = shift; # The date formatting options ...
1429 149 my $dates = shift; # A hash reference of dates to return ...
1430 149 my $prev = shift; # The previous hash reference to see what changed ...
1431  
1432 149 my %empty;
1433 149 ▶ %{$dates} = %empty if (defined $dates);
Branch: 1 branch
BranchTrueFalseTotal
if defined $dates 149 0 149
1434 149 ▶ $prev = \%empty unless (defined $prev);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $prev 109 40 149
1435  
1436 149 my ($t1, $t2, $t3) = ("month_language", "month_type", "");
1437 149 ▶ my $lang = (exists $opts->{$t1}) ? $opts->{$t1} : $default_date_opts{$t1};
Branch: 1 branch
BranchTrueFalseTotal
exists $opts->{$t1} ? : 149 0 149
1438 149 ▶ my $mtyp = (exists $opts->{$t2}) ? $opts->{$t2} : $default_date_opts{$t2};
Branch: 1 branch
BranchTrueFalseTotal
exists $opts->{$t2} ? : 149 0 149
1439 149 my ($month_ref, $week_day_ref) = init_special_date_arrays ($lang, $mtyp, 0, 0);
1440  
1441 # The formatting info ...
1442 149 ($t1, $t2, $t3) = ("date_order", "date_sep", "use_gmt");
1443 149 ▶ my $order = (exists $opts->{$t1}) ? $opts->{$t1} : $default_date_opts{$t1};
Branch: 1 branch
BranchTrueFalseTotal
exists $opts->{$t1} ? : 149 0 149
1444 149 ▶ my $sep = (exists $opts->{$t2}) ? $opts->{$t2} : $default_date_opts{$t2};
Branch: 1 branch
BranchTrueFalseTotal
exists $opts->{$t2} ? : 149 0 149
1445 149 ▶ my $gmt = (exists $opts->{$t3}) ? $opts->{$t3} : $default_date_opts{$t3};
Branch: 1 branch
BranchTrueFalseTotal
exists $opts->{$t3} ? : 149 0 149
1446  
1447 149 my $what_changed = 0; # Nothing ...
1448  
1449 # -------------------------------------------------------------------------
1450 # Initialize the date to use properly
1451 # -------------------------------------------------------------------------
1452 149 my $now;
1453 149 ▶ if ( $opts->{timestamp} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opts->{'timestamp'}) { } 9 140 149
1454 # Only set by change_special_date_vars() ... (So undocumented)
1455 9 $now = $opts->{timestamp}; # Re-use a previous timestamp.
1456 } else {
1457 140 $now = time (); # Start a new timestamp.
1458 }
1459  
1460 149 $dates->{timestamp} = $now;
1461  
1462 # -------------------------------------------------------------------------
1463 # Get the desired dates ...
1464  
1465 # Get today ...
1466 149 ▶ my ($yr, $mon, $day, $hr, $dow, $doy) = $gmt
Branch: 1 branch
BranchTrueFalseTotal
$gmt ? : 0 149 149
1467 ? (gmtime ($now))[5,4,3,2,6,7]
1468 : (localtime ($now))[5,4,3,2,6,7];
1469 149 $yr += 1900;
1470 149 my $month = $month_ref->[$mon];
1471 149 $dates->{today} = _fmt_date ($sep, $order, $yr, $month, $day);
1472  
1473 # Get yesterday's date ...
1474 149 my $sec = ($hr + 2) * 3600 + 2; # Convert hours to seconds ...
1475 149 ▶ my ($yr2, $mon2, $day2) = $gmt ? (gmtime ($now - $sec))[5,4,3]
Branch: 1 branch
BranchTrueFalseTotal
$gmt ? : 0 149 149
1476 : (localtime ($now - $sec))[5,4,3];
1477 149 $yr2 += 1900;
1478 149 my $month2 = $month_ref->[$mon2];
1479 149 $dates->{yesterday} = _fmt_date ($sep, $order, $yr2, $month2, $day2);
1480  
1481 # Get tomorrow's date ...
1482 149 $sec = (24 - $hr + 1) * 3600 + 2; # Convert hours to seconds ...
1483 149 ▶ my ($yr3, $mon3, $day3) = $gmt ? (gmtime ($now + $sec))[5,4,3]
Branch: 1 branch
BranchTrueFalseTotal
$gmt ? : 0 149 149
1484 : (localtime ($now + $sec))[5,4,3];
1485 149 $yr3 += 1900;
1486 149 my $month3 = $month_ref->[$mon3];
1487 149 $dates->{tomorrow} = _fmt_date ($sep, $order, $yr3, $month3, $day3);
1488  
1489 DBUG_PRINT (" DATES ($day)", "LAST: %s, NOW: %s, NEXT: %s",
1490 149 $dates->{yesterday}, $dates->{today}, $dates->{tomorrow});
1491  
1492 149 ▶ if ( $prev->{today} && $prev->{today} ne $dates->{today} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($prev->{"today"} and $prev->{"today"} ne $dates->{"today"}) 0 149 149
Condition66%2/3
$prev->{"today"} and $prev->{"today"} ne $dates->{"today"}
!ll&&!rl&&r
109400
MC/DC0%0/2
$prev->{"today"} and $prev->{"today"} ne $dates->{"today"}
$prev->{"today"} $prev->{"today"} ne $dates->{"today"}
Truth table66%2/3
A and B
A= $prev->{"today"}B= $prev->{"today"} ne $dates->{"today"}
ABresult
0X0
100
111
1493 0 $what_changed = 1; # The date changed ...
1494 }
1495  
1496 # -------------------------------------------------------------------------
1497 # Get the desired months ... ($mon == 0..11)
1498 149 $dates->{this_month} = $month_ref->[$mon];
1499 149 ▶ $dates->{last_month} = ( $mon == 0 ) ? $month_ref->[11] : $month_ref->[$mon - 1];
Branch: 1 branch
BranchTrueFalseTotal
$mon == 0 ? : 0 149 149
1500 149 ▶ $dates->{next_month} = ( $mon == 11 ) ? $month_ref->[0] : $month_ref->[$mon + 1];
Branch: 1 branch
BranchTrueFalseTotal
$mon == 11 ? : 0 149 149
1501  
1502 DBUG_PRINT (" MONTHS ($mon)", "LAST: %s, NOW: %s, NEXT: %s",
1503 149 $dates->{last_month}, $dates->{this_month}, $dates->{next_month});
1504  
1505 # -------------------------------------------------------------------------
1506 # Get the desired periods Year-Month ... ($mon == 0..11)
1507 149 ▶ my $lyr = ( $mon == 0 ) ? ($yr - 1) : $yr;
Branch: 1 branch
BranchTrueFalseTotal
$mon == 0 ? : 0 149 149
1508 149 ▶ my $nyr = ( $mon == 11 ) ? ($yr + 1) : $yr;
Branch: 1 branch
BranchTrueFalseTotal
$mon == 11 ? : 0 149 149
1509 149 $dates->{this_period} = _fmt_period ($sep, $order, $yr, $dates->{this_month});
1510 149 $dates->{last_period} = _fmt_period ($sep, $order, $lyr, $dates->{last_month});
1511 149 $dates->{next_period} = _fmt_period ($sep, $order, $nyr, $dates->{next_month});
1512  
1513 DBUG_PRINT ("PERIODS ($mon)", "LAST: %s, NOW: %s, NEXT: %s",
1514 149 $dates->{last_period}, $dates->{this_period}, $dates->{next_period});
1515  
1516 # -------------------------------------------------------------------------
1517  
1518 149 ▶ if ( $prev->{this_month} && $prev->{this_month} ne $dates->{this_month} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($prev->{"this_month"} and $prev->{"this_month"} ne $dates->{"this_month"}) 0 149 149
Condition66%2/3
$prev->{"this_month"} and $prev->{"this_month"} ne $dates->{"this_month"}
!ll&&!rl&&r
109400
MC/DC0%0/2
$prev->{"this_month"} and $prev->{"this_month"} ne $dates->{"this_month"}
$prev->{"this_month"} $prev->{"this_month"} ne $dates->{"this_month"}
Truth table66%2/3
A and B
A= $prev->{"this_month"}B= $prev->{"this_month"} ne $dates->{"this_month"}
ABresult
0X0
100
111
1519 0 $what_changed = 2; # The month & periods changed ...
1520 }
1521  
1522 # -------------------------------------------------------------------------
1523 # Get the desired years ...
1524 149 $dates->{this_year} = sprintf ("%04d", $yr);
1525 149 $dates->{last_year} = sprintf ("%04d", $yr - 1);
1526 149 $dates->{next_year} = sprintf ("%04d", $yr + 1);
1527  
1528 DBUG_PRINT (" YEARS", "LAST: %s, NOW: %s, NEXT: %s",
1529 149 $dates->{last_year}, $dates->{this_year}, $dates->{next_year});
1530  
1531 149 ▶ if ( $prev->{this_year} && $prev->{this_year} ne $dates->{this_year} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($prev->{"this_year"} and $prev->{"this_year"} ne $dates->{"this_year"}) 0 149 149
Condition66%2/3
$prev->{"this_year"} and $prev->{"this_year"} ne $dates->{"this_year"}
!ll&&!rl&&r
109400
MC/DC0%0/2
$prev->{"this_year"} and $prev->{"this_year"} ne $dates->{"this_year"}
$prev->{"this_year"} $prev->{"this_year"} ne $dates->{"this_year"}
Truth table66%2/3
A and B
A= $prev->{"this_year"}B= $prev->{"this_year"} ne $dates->{"this_year"}
ABresult
0X0
100
111
1532 0 $what_changed = 3; # The year changed ...
1533 }
1534  
1535 # -------------------------------------------------------------------------
1536 # Get the miscellanious vars ...
1537 149 $dates->{dow} = $week_day_ref->[$dow]; # 1..7 or spelled out.
1538 149 $dates->{doy} = $doy + 1; # 1..365 normal, 1..366 in leap years.
1539 149 $dates->{dom} = $day; # 1..31, range based on month.
1540  
1541 DBUG_PRINT (" MISC", " DOW: %s, DOY: %d, DOM: %d",
1542 149 $dates->{dow}, $dates->{doy}, $dates->{dom});
1543  
1544 149 DBUG_RETURN ($what_changed);
1545 }
1546  
1547 # ==============================================================
1548  
1549 =item change_special_date_vars ( $timestamp, $date_opts_ref, $date_hash_ref )
1550  
1551 Same as L<set_special_date_vars> except it uses the specified date/time to
1552 convert.
1553  
1554 =cut
1555  
1556 sub change_special_date_vars
1557 9 ▶{
Subroutine change_special_date_vars: called CC=1 SCAR=0.0
Pod documented
1558 9 DBUG_ENTER_FUNC (@_);
1559 9 my $timestamp = shift;
1560 9 my $date_opts = shift;
1561 9 my $dates = shift;
1562  
1563 # Special flag for special handling ... (undocumented)
1564 9 local $date_opts->{timestamp} = $timestamp;
1565  
1566 # Forces all dates to use the specified date/time
1567 9 set_special_date_vars ($date_opts, $dates);
1568  
1569 9 DBUG_VOID_RETURN ();
1570 }
1571  
1572 # ==============================================================
1573 # For formatting the full dates ...
1574  
1575 sub _fmt_date
1576 447 ▶{
Subroutine _fmt_date: called CC=3 SCAR=11.0
1577 447 my $sep = shift;
1578 447 my $order = shift;
1579 447 my $year = shift;
1580 447 my $month = shift; # 1..12 or the name.
1581 447 my $day = shift; # 1..31
1582  
1583 447 my $dt;
1584 447 ▶ if ( $order == 1 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($order == 1) { } 12 435 447
elsif ($order == 2) { } 12 423 435
1585 # MM-DD-YYYY format
1586 12 $dt = sprintf ("%s%s%02d%s%04d", $month, $sep, $day, $sep, $year);
1587 } elsif ( $order == 2 ) {
1588 # DD-MM-YYYY format
1589 12 $dt = sprintf ("%02d%s%s%s%04d", $day, $sep, $month, $sep, $year);
1590 } else {
1591 # YYYY-MM-DD order ...
1592 423 $dt = sprintf ("%04d%s%s%s%02d", $year, $sep, $month, $sep, $day);
1593 }
1594  
1595 447 return ($dt);
1596 }
1597  
1598 # ==============================================================
1599 # Formatting to be "year-month" or "month-year".
1600  
1601 sub _fmt_period
1602 447 ▶{
Subroutine _fmt_period: called CC=3 SCAR=11.0
1603 447 my $sep = shift;
1604 447 my $order = shift;
1605 447 my $year = shift;
1606 447 my $month = shift; # 1..12 or the name.
1607  
1608 447 my $dt;
1609 447 ▶ if ( $order == 1 || $order == 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($order == 1 or $order == 2) { } 24 423 447
Condition100%3/3
$order == 1 or $order == 2
l!l&&r!l&&!r
1212423
MC/DC100%2/2
$order == 1 or $order == 2
$order == 1 $order == 2
Truth table100%3/3
A or B
A= $order == 1B= $order == 2
ABresult
1X1
011
000
1610 # MM-YYYY format
1611 24 $dt = sprintf ("%s%s%04d", $month, $sep, $year);
1612 } else {
1613 # YYYY-MM format
1614 423 $dt = sprintf ("%04d%s%s", $year, $sep, $month);
1615 }
1616  
1617 447 return ($dt);
1618 }
1619  
1620 # ==============================================================
1621  
1622 =back
1623  
1624 =head1 COPYRIGHT
1625  
1626 Copyright (c) 2007 - 2026 Curtis Leach. All rights reserved.
1627  
1628 This program is free software. You can redistribute it and/or modify it under
1629 the same terms as Perl itself.
1630  
1631 =head1 SEE ALSO
1632  
1633 L<Advanced::Config> - The main user of this module. It defines the Config object.
1634  
1635 L<Advanced::Config::Date> - Handles date parsing for get_date().
1636  
1637 L<Advanced::Config::Reader> - Handles the parsing of the config file.
1638  
1639 L<Advanced::Config::Examples> - Provides some sample config files and commentary.
1640  
1641 =cut
1642  
1643 # ==============================================================
1644 #required if module is included w/ require command;
1645 28 1;
1646  
« Config/Date.pm ↑ Summary Config/Reader.pm »