lib/Log/Munger/RulesTemplateOrder.pm

filter: Statementstmt 92.1% 82 / 89 Branchbran 78.9% 30 / 38 Conditioncond 86.6% 13 / 15 MC/DCmcdc 70.0% 7 / 10 Subroutinesub 100% 10 / 10 Podpod 100% 4 / 4 totaltotal 87.9% 146 / 166 CC 30 SCAR 24.1
CC
30
Cov
88%
order_for_rules_hash
15.0
depends_for_rules_hash
14.3
_load_no_templating
4.6
CRAP 11.2
« lib/Log/Munger/Degrok.pm ↑ Summary lib/Log/Munger/RuleFileParser.pm »
1 package Log::Munger::RulesTemplateOrder;
2  
3 32 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 32 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 32 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 32 ▶use Algorithm::Dependency::Ordered;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 32 ▶use Algorithm::Dependency::Source::HoA;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 # Log::Munger::RuleFileParser is loaded at runtime (via require, inside
10 # _load_no_templating below) rather than with a compile-time use:
11 # RuleFileParser already uses this module, so a use here would form a circular
12 # dependency.
13  
14 =head1 NAME
15  
16 Log::Munger::RulesTemplateOrder - Works out the order a rule file's templated vars must be resolved in.
17  
18 =head1 VERSION
19  
20 Version 0.0.1
21  
22 =cut
23  
24 32 our $VERSION = '0.0.1';
25  
26 =head1 SYNOPSIS
27  
28 use Log::Munger::RulesTemplateOrder;
29  
30 my $order = Log::Munger::RulesTemplateOrder->order_for_rules_file( 'file' => 'base' );
31 foreach my $var ( @{$order} ) {
32 print $var . "\n";
33 }
34  
35 A rule file's C<vars_templated> entries reference each other. C<TIMESTAMP_ISO8601>
36 is built out of C<YEAR>, C<MONTHNUM>, C<TIME> and friends, and C<TIME> is in turn
37 built out of C<HOUR>, C<MINUTE> and C<SECOND>. Resolving them in hash order would
38 leave a C<[% TIME %]> sitting unsubstituted in the middle of a timestamp pattern,
39 so L<Log::Munger::RuleFileParser> asks this module for a working order first.
40  
41 The dependencies are read straight off the C<[% VAR %]> references in each
42 templated var and handed to L<Algorithm::Dependency::Ordered>, which returns a
43 schedule where nothing comes before something it needs.
44  
45 C<log_munger rule_file_template_order -f E<lt>fileE<gt>> prints that schedule, and
46 adding C<-d> prints the dependency map it was derived from.
47  
48 =head1 METHODS
49  
50 =head2 order_for_rules_hash
51  
52 Returns the order the templated vars of an already loaded rules hash have to be
53 resolved in.
54  
55 The hash wants to be one from L<Log::Munger::RuleFileParser/load_no_templating>.
56 Once C<load> has run, the templating is already done and the C<[% VAR %]>
57 references this reads have been substituted away.
58  
59 Plain C<vars> are treated as already resolved: a templated var may reference any
60 of them, but they do not appear in the returned schedule. A name defined under
61 both C<vars> and C<vars_templated> resolves as the plain var, which is what lets
62 a file shadow an include's templated var with a plain one.
63  
64 - rules :: The rules hash ref to process.
65 Default :: undef
66  
67 Returns an array ref of the C<vars_templated> names, in the order they should be
68 resolved. A file with neither C<vars> nor C<vars_templated> gets an empty array
69 ref. Dies on anything L</depends_for_rules_hash> dies on, if a templated var
70 references a name that is not defined anywhere, or if the references are
71 circular.
72  
73 my $order = Log::Munger::RulesTemplateOrder->order_for_rules_hash( 'rules' => $rules_hash );
74  
75 =cut
76  
77 326 ▶sub order_for_rules_hash {
Subroutine order_for_rules_hash: called CC=15 SCAR=27.1
Pod documented
78 326 my ( $blank, %opts ) = @_;
79  
80 326 ▶ if ( !defined( $opts{'rules'} ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $opts{'rules'}) { } 1 325 326
elsif (ref $opts{'rules'} ne 'HASH') { } 1 324 325
81 1 die('$opts{rules} is undef');
82 } elsif ( ref( $opts{'rules'} ) ne 'HASH' ) {
83 1 die( '$opts{rules} has a ref of "' . ref( $opts{'rules'} ) . '" and not HASH' );
84 }
85 324 my $rules = $opts{'rules'};
86  
87 324 my $depends_info = Log::Munger::RulesTemplateOrder->depends_for_rules_hash( 'rules' => $rules );
88 324 my @templated_vars = sort( keys( %{$depends_info} ) );
89  
90 324 my @vars;
91 324 ▶ if ( defined( $rules->{'vars'} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rules->{"vars"}) 321 3 324
92 321 @vars = keys( %{ $rules->{'vars'} } );
93 }
94  
95 # nothing to order (a rules-only file with no vars/vars_templated); return
96 # an empty schedule rather than letting Algorithm::Dependency die on it
97 324 ▶ if ( !@vars && !@templated_vars ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@vars or @templated_vars) 2 322 324
Condition100%3/3
@vars or @templated_vars
l!l&&r!l&&!r
32112
MC/DC100%2/2
@vars or @templated_vars
@vars @templated_vars
Truth table100%3/3
A or B
A= @varsB= @templated_vars
ABresult
1X1
011
000
98 2 return [];
99 }
100  
101 # every plain var becomes a dependency-less, already-selected entry so a
102 # templated var may reference it. A name defined under both vars and
103 # vars_templated is taken as the plain var, which is what lets a file
104 # shadow an include's templated var with a plain one
105 322 foreach my $var (@vars) {
106 15254 $depends_info->{$var} = [];
107 }
108  
109 # a reference to a name defined nowhere would otherwise be dropped from the
110 # schedule silently, along with everything that references it
111 322 foreach my $var (@templated_vars) {
112 11317 foreach my $reference ( @{ $depends_info->{$var} } ) {
113 32667 ▶ if ( !exists( $depends_info->{$reference} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $depends_info->{$reference}) 1 32666 32667
114 1 die( '.vars_templated.'
115 . $var
116 . ' references "'
117 . $reference
118 . '", which is not defined under .vars or .vars_templated' );
119 }
120 }
121 } ## end foreach my $var (@templated_vars)
122  
123 321 my $deps_source = Algorithm::Dependency::Source::HoA->new($depends_info);
124 321 ▶ my $dep = Algorithm::Dependency::Ordered->new(
Branch: 1 branch
BranchTrueFalseTotal
my $dep = "Algorithm::Dependency::Ordered"->new("source", $deps_source, "selected", \@vars) or die "Failed to set up dependency algorithm" 321 0 321
125 source => $deps_source,
126 selected => \@vars,
127 ) or die 'Failed to set up dependency algorithm';
128  
129 321 my $schedule = $dep->schedule_all();
130  
131 # a circular reference is unschedulable and Algorithm::Dependency omits it
132 # quietly rather than erroring, so catch it here by name
133 321 my %shadowed = map { $_ => 1 } @vars;
134 321 ▶ my %scheduled = defined($schedule) ? ( map { $_ => 1 } @{$schedule} ) : ();
Branch: 1 branch
BranchTrueFalseTotal
defined $schedule ? : 320 1 321
135 321 ▶ my @unschedulable = grep { !$scheduled{$_} && !$shadowed{$_} } @templated_vars;
Condition100%3/3
$scheduled{$_} || $shadowed{$_}
l!l&&r!l&&!r
1131312
MC/DC100%2/2
$scheduled{$_} || $shadowed{$_}
$scheduled{$_} $shadowed{$_}
Truth table100%3/3
A || B
A= $scheduled{$_}B= $shadowed{$_}
ABresult
1X1
011
000
136 321 ▶ if ( !defined($schedule) || @unschedulable ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $schedule or @unschedulable) 1 320 321
Condition66%2/3
not defined $schedule or @unschedulable
l!l&&r!l&&!r
10320
MC/DC50%1/2
not defined $schedule or @unschedulable
not defined $schedule @unschedulable
Truth table66%2/3
not(A) or B
A= not defined $scheduleB= @unschedulable
ABresult
1X1
011
000
137 1 die( 'Could not work out a resolution order for .vars_templated... circular [% %] references between: '
138 . join( ', ', @unschedulable ) );
139 }
140  
141 320 return $schedule;
142 } ## end sub order_for_rules_hash
143  
144 =head2 depends_for_rules_hash
145  
146 Returns the raw dependency map behind L</order_for_rules_hash>, for when you want
147 to see what references what rather than just the resulting order.
148  
149 Each templated var is scanned for C<[% VAR %]> references and gets an entry
150 listing the names it mentions. A var that references nothing gets an empty list.
151 Nothing is checked for existence here, so a reference to a var that was never
152 defined shows up in the map the same as any other; L</order_for_rules_hash> is
153 what dies on it.
154  
155 - rules :: The rules hash ref to process.
156 Default :: undef
157  
158 Returns a hash ref of C<< { var_name => [ names it references ] } >>, or an empty
159 hash ref if the file has no C<vars_templated>. Dies if C<rules> is undef, is not a
160 hash ref, holds a C<vars> / C<vars_templated> that is not a hash ref, or holds a
161 C<vars_templated> entry whose value is not a plain string.
162  
163 my $depends = Log::Munger::RulesTemplateOrder->depends_for_rules_hash( 'rules' => $rules_hash );
164 # $depends->{TIME} = [ 'HOUR', 'MINUTE', 'SECOND' ]
165  
166 =cut
167  
168 329 ▶sub depends_for_rules_hash {
Subroutine depends_for_rules_hash: called CC=13 SCAR=26.6
Pod documented
169 329 my ( $blank, %opts ) = @_;
170  
171 329 ▶ if ( !defined( $opts{'rules'} ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $opts{'rules'}) { } 0 329 329
elsif (ref $opts{'rules'} ne 'HASH') { } 0 329 329
172 0 die('$opts{rules} is undef');
173 } elsif ( ref( $opts{'rules'} ) ne 'HASH' ) {
174 0 die( '$opts{rules} has a ref of "' . ref( $opts{'rules'} ) . '" and not HASH' );
175 }
176 329 my $rules = $opts{'rules'};
177  
178 329 ▶ if ( defined( $rules->{'vars'} ) && ( ref( $rules->{'vars'} ) ne 'HASH' ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $rules->{'vars'} and ref $rules->{'vars'} ne 'HASH') { } 0 329 329
elsif (defined $rules->{'vars_templated'} and ref $rules->{'vars_templated'} ne 'HASH') { } 1 331 332
Condition66%2/3
defined $rules->{"vars"} and ref $rules->{"vars"} ne "HASH"
!ll&&!rl&&r
53240
MC/DC0%0/2
defined $rules->{"vars"} and ref $rules->{"vars"} ne "HASH"
defined $rules->{"vars"} ref $rules->{"vars"} ne "HASH"
Truth table66%2/3
A and B
A= defined $rules->{"vars"}B= ref $rules->{"vars"} ne "HASH"
ABresult
0X0
100
111
179 0 die( '$opts{rules}{vars} has a ref of "' . ref( $rules->{'vars'} ) . '" and not HASH' );
180 ▶ } elsif ( defined( $rules->{'vars_templated'} ) && ( ref( $rules->{'vars_templated'} ) ne 'HASH' ) ) {
Condition100%3/3
defined $rules->{"vars_templated"} and ref $rules->{"vars_templated"} ne "HASH"
!ll&&!rl&&r
33251
MC/DC100%2/2
defined $rules->{"vars_templated"} and ref $rules->{"vars_templated"} ne "HASH"
defined $rules->{"vars_templated"} ref $rules->{"vars_templated"} ne "HASH"
Truth table100%3/3
A and B
A= defined $rules->{"vars_templated"}B= ref $rules->{"vars_templated"} ne "HASH"
ABresult
0X0
100
111
181 1 die( '$opts{rules}{vars_templated} has a ref of "' . ref( $rules->{'vars_templated'} ) . '" and not HASH' );
182 }
183  
184 328 my @templated_vars;
185 328 ▶ if ( !defined( $rules->{'vars_templated'} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $rules->{'vars_templated'}) { } 3 325 328
186 3 return {};
187 } else {
188 # check this here so we die earlier instead of later after doing more processing
189 325 @templated_vars = keys( %{ $rules->{'vars_templated'} } );
190 325 foreach my $var (@templated_vars) {
191 11367 ▶ if ( ref( $rules->{'vars_templated'}{$var} ) ne '' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $rules->{"vars_templated"}{$var} ne "") 0 11367 11367
192 die( '$opts{rules}{vars_templated}{'
193 . $var
194 . '} has a ref of "'
195 0 . ref( $rules->{'vars_templated'}{$var} )
196 . '" and not ""' );
197 }
198 }
199 } ## end else [ if ( !defined( $rules->{'vars_templated'} ...))]
200  
201 325 my $template_depends = {};
202 325 foreach my $var (@templated_vars) {
203 # each reference is recorded once, in first-appearance order, which
204 # both dedupes the list and keeps the -d dump of this map stable
205 11367 my @has_vars;
206 my %seen;
207 11367 my $string = $rules->{'vars_templated'}{$var};
208 11367 ▶ while ( $string =~ /\[\% +([A-Za-z0-9_]+) +\%\]/g ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($string =~ /\[\% +([A-Za-z0-9_]+) +\%\]/g) 34223 11367 45590
209 34223 ▶ push( @has_vars, $1 ) if ( !$seen{$1}++ );
Branch: 1 branch
BranchTrueFalseTotal
unless $seen{$1}++ 32823 1400 34223
210 }
211 11367 $template_depends->{$var} = \@has_vars;
212 } ## end foreach my $var (@templated_vars)
213  
214 325 return $template_depends;
215 } ## end sub depends_for_rules_hash
216  
217 =head2 order_for_rules_file
218  
219 L</order_for_rules_hash> for a rule file on disk. The file is loaded with
220 L<Log::Munger::RuleFileParser/load_no_templating>, which is the state the ordering
221 has to be worked out in, and the resulting hash is handed straight over.
222  
223 - file :: The file to load. Either a bare name resolved through the search
224 path, such as "base", or a path. Required.
225 Default :: undef
226  
227 Returns an array ref of var names in the order they should be resolved. Dies if
228 the file cannot be found or loaded.
229  
230 my $order = Log::Munger::RulesTemplateOrder->order_for_rules_file( 'file' => 'base' );
231  
232 =cut
233  
234 2 ▶sub order_for_rules_file {
Subroutine order_for_rules_file: called CC=1 SCAR=0.0
Pod documented
235 2 my ( $blank, %opts ) = @_;
236  
237 2 return Log::Munger::RulesTemplateOrder->order_for_rules_hash( 'rules' => _load_no_templating( $opts{'file'} ) );
238 }
239  
240 =head2 depends_for_rules_file
241  
242 L</depends_for_rules_hash> for a rule file on disk, loaded the same way
243 L</order_for_rules_file> loads it.
244  
245 - file :: The file to load. Either a bare name resolved through the search
246 path, such as "base", or a path. Required.
247 Default :: undef
248  
249 Returns a hash ref of C<< { var_name => [ names it references ] } >>. Dies if the
250 file cannot be found or loaded.
251  
252 my $depends = Log::Munger::RulesTemplateOrder->depends_for_rules_file( 'file' => 'base' );
253  
254 =cut
255  
256 2 ▶sub depends_for_rules_file {
Subroutine depends_for_rules_file: called CC=1 SCAR=0.0
Pod documented
257 2 my ( $blank, %opts ) = @_;
258  
259 2 return Log::Munger::RulesTemplateOrder->depends_for_rules_hash( 'rules' => _load_no_templating( $opts{'file'} ) );
260 }
261  
262 # Loads a rule file via Log::Munger::RuleFileParser->load_no_templating, which
263 # is the state the ordering has to be worked out in: once load has run, the
264 # [% VAR %] references this module reads have been substituted away.
265 #
266 # RuleFileParser is required at runtime rather than used at compile time since
267 # it uses this module itself; see the note at the top of the file.
268 #
269 # Args:
270 #
271 # - $file :: The file to load. Either a bare name resolved through the
272 # search path, such as "base", or a path.
273 #
274 # Returns the rules hash ref, with vars_templated left untouched. Dies when
275 # $file is undef or not a plain string, or when the file cannot be found or
276 # loaded.
277 #
278 # my $rules = _load_no_templating( $opts{'file'} );
279 4 ▶sub _load_no_templating {
Subroutine _load_no_templating: called CC=4 SCAR=15.2
280 4 my ($file) = @_;
281  
282 4 ▶ if ( !defined($file) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $file) { } 0 4 4
elsif (ref $file ne '') { } 0 4 4
283 0 die('$opts{file} is undef');
284 } elsif ( ref($file) ne '' ) {
285 0 die( '$opts{file} ref is "' . ref($file) . '" and not ""' );
286 }
287  
288 4 my $rules;
289 4 eval {
290 4 require Log::Munger::RuleFileParser;
291 4 my $parser = Log::Munger::RuleFileParser->new;
292 4 $rules = $parser->load_no_templating( 'file' => $file );
293 };
294 4 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 4 4
295 0 die( 'Failed to call load_no_templating for "' . $file . '"... ' . $@ );
296 }
297  
298 4 return $rules;
299 } ## end sub _load_no_templating
« lib/Log/Munger/Degrok.pm ↑ Summary lib/Log/Munger/RuleFileParser.pm »