blib/lib/Rex/Template.pm

filter: Statementstmt 82.5% 99 / 120 Branchbran 56.6% 17 / 30 Conditioncond 55.5% 15 / 27 MC/DCmcdc 18.7% 3 / 16 Subroutinesub 91.6% 11 / 12 Podpod 50.0% 2 / 4 totaltotal 70.3% 147 / 209 CC 28 SCAR 33.8
CC
28
Cov
74%
parse
42.9
is_defined
6.0
new
2.1
CRAP 29.2
« lib/Rex/Commands/Download.pm ↑ Summary lib/Rex/Helper/Run.pm »
1 #
2 # (c) Jan Gehring <jan.gehring@gmail.com>
3 #
4  
5 =head1 NAME
6  
7 Rex::Template - simple template engine
8  
9 =head1 SYNOPSIS
10  
11 use Rex::Template;
12  
13 my $template = Rex::Template->new;
14  
15 print $template->parse($content, \%template_vars);
16 print $template->parse($content, @template_vars);
17  
18 =head1 DESCRIPTION
19  
20 This is a simple template engine for configuration files. It is included mostly for backwards compatibility, and it is recommended to use L<Rex::Template::NG> instead (for better control of chomping new lines, and better diagnostics if things go wrong).
21  
22 =head2 SYNTAX
23  
24 The following syntax is recognized:
25  
26 =over 4
27  
28 =item * anything between C<E<lt>%> and C<%E<gt>> markers are considered as a template directive, which is treated as Perl code
29  
30 =item * if the opening marker is followed by an equal sign (C<E<lt>%=>) or a plus sign (C<E<lt>%+>), then the directive is replaced with the value it evaluates to
31  
32 =item * if the closing marker is prefixed with a minus sign (C<-%E<gt>>), then any trailing newlines are chomped for that directive
33  
34 =back
35  
36 The built-in template support is intentionally kept basic and simple. For anything more sophisticated, please use your favorite template engine.
37  
38 =head2 EXAMPLES
39  
40 Plain text is unchanged:
41  
42 my $result = $template->parse( 'one two three', {} );
43  
44 # $result is 'one two three'
45  
46 Variable interpolation:
47  
48 my $result = template->parse( 'Hello, this is <%= $::name %>', { name => 'foo' } ); # original format
49 my $result = template->parse( 'Hello, this is <%+ $::name %>', { name => 'foo' } ); # alternative format with + sign
50 my $result = template->parse( 'Hello, this is <%= $name %>', { name => 'foo' } ); # local variables
51 my $result = template->parse( 'Hello, this is <%= $name %>', name => 'foo' ); # array of variables, instead of hashref
52  
53 # $result is 'Hello, this is foo' for all cases above
54  
55 Simple evaluation:
56  
57 my $result = $template->parse( '<%= join("/", @{$elements} ) %>', elements => [qw(one two three)] );
58 # $result is 'one/two/three'
59  
60 Embedded code blocks:
61  
62 my $content = '<% if ($logged_in) { %>
63 Logged in!
64 <% } else { %>
65 Logged out!
66 <% } %>';
67  
68 my $result = $template->parse( $content, logged_in => 1 );
69  
70 # $result is "\nLogged in!\n"
71  
72 =head1 DIAGNOSTICS
73  
74 Not much, mainly due to the internal approach of the module.
75  
76 If there was a problem, it prints an C<INFO> level I<"syntax error at ...">, followed by a C<WARN> about I<"It seems that there was an error processing the template because the result is empty.">, and finally I<"Error processing template at ...">.
77  
78 The beginning of the reported syntax error might give some clue where the error happened in the template, but that's it.
79  
80 Use L<Rex::Template::NG> instead for better diagnostics.
81  
82 =head1 CONFIGURATION AND ENVIRONMENT
83  
84 If C<$Rex::Template::BE_LOCAL> is set to a true value, then local template variables are supported instead of only global ones (C<$foo> vs C<$::foo>). The default value is C<1> since Rex-0.41. It can be disabled with the L<no_local_template_vars|Rex#no_local_template_vars> feature flag.
85  
86 If C<$Rex::Template::DO_CHOMP> is set to a true value, then any trailing new line character resulting from template directives are chomped. Defaults to C<0>.
87  
88 This module does not support any environment variables.
89  
90 =head1 EXPORTED FUNCTIONS
91  
92 =cut
93  
94 package Rex::Template;
95  
96 108 ▶use v5.14.4;
Subroutine BEGIN: called CC=1 SCAR=0.0
97 108 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
98 108 ▶use Symbol;
Subroutine BEGIN: called CC=1 SCAR=0.0
99  
100 108 our $VERSION = '1.16.1'; # VERSION
101  
102 108 ▶use Rex::Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
103 108 ▶use Rex::Logger;
Subroutine BEGIN: called CC=1 SCAR=0.0
104 108 require Rex::Args;
105  
106 108 our $DO_CHOMP = 0;
107 108 our $BE_LOCAL = 1;
108  
109 1 ▶sub function {
Subroutine function: called CC=1 SCAR=0.0
Pod undocumented
110 1 my ( $class, $name, $code ) = @_;
111  
112 1 my $ref_to_name = qualify_to_ref( $name, $class );
113 1 *{$ref_to_name} = $code;
114 }
115  
116 120 ▶sub new {
Subroutine new: called CC=2 SCAR=7.2
Pod undocumented
117 120 my $that = shift;
118 120 ▶ my $proto = ref($that) || $that;
Condition33%1/3
ref $that || $that
l!l&&r!l&&!r
01200
MC/DC0%0/2
ref $that || $that
ref $that $that
Truth table33%1/3
A || B
A= ref $thatB= $that
ABresult
1X1
011
000
119 120 my $self = {@_};
120  
121 120 bless( $self, $proto );
122  
123 120 return $self;
124 }
125  
126 =head2 parse($content, $variables)
127  
128 Parse C<$content> as a template, using C<$variables> hash reference to pass name-value pairs of variables to make them available for the template function.
129  
130 Alternatively, the variables may be passed as an array instead of a hash reference.
131  
132 =cut
133  
134 130 ▶sub parse {
Subroutine parse: called CC=26 SCAR=37.6
Pod documented
135 130 my $self = shift;
136 130 my $data = shift;
137  
138 130 my $vars = {};
139  
140 130 ▶ if ( ref( $_[0] ) eq "HASH" ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[0] eq 'HASH') { } 128 2 130
141 128 $vars = shift;
142 }
143 else {
144 2 $vars = {@_};
145 }
146  
147 130 my $new_data;
148 130 my $___r = "";
149  
150 130 my $do_chomp = 0;
151 $new_data = join(
152 "\n",
153 map {
154 130 my ( $code, $type, $text ) = ( $_ =~ m/(\<%)*([+=])*(.+)%\>/s );
155  
156 407 ▶ if ($code) {
Branch: 1 branch
BranchTrueFalseTotal
if ($code) { } 153 254 407
157 153 my $pcmd = substr( $text, -1 );
158 153 ▶ if ( $pcmd eq "-" ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pcmd eq "-") 0 153 153
159 0 $text = substr( $text, 0, -1 );
160 0 $do_chomp = 1;
161 }
162  
163 153 my ( $var_type, $var_name ) = ( $text =~ m/([\$])::([a-zA-Z0-9_]+)/ );
164  
165 153 ▶ if ( $var_name && !ref( $vars->{$var_name} ) && !$BE_LOCAL ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($var_name and not ref $vars->{$var_name} and not $Rex::Template::BE_LOCAL) { } 0 153 153
elsif ($var_name and not ref $vars->{$var_name} and $Rex::Template::BE_LOCAL) { } 44 109 153
Condition83%5/6
$var_name and not ref $vars->{$var_name} and not $Rex::Template::BE_LOCAL
!ll&&!rl&&r
109440
$var_name and not ref $vars->{$var_name}
!ll&&!rl&&r
105444
MC/DC0%0/3
$var_name and not ref $vars->{$var_name} and not $Rex::Template::BE_LOCAL
$var_name not ref $vars->{$var_name} not $Rex::Template::BE_LOCAL
Truth table75%3/4
A and not(B) and not(C)
A= $var_nameB= not ref $vars->{$var_name}C= not $Rex::Template::BE_LOCAL
ABCresult
0XX0
10X0
1100
1111
166 0 $text =~ s/([\$])::([a-zA-Z0-9_]+)/$1\{\$$2\}/g;
167 }
168 ▶ elsif ( $var_name && !ref( $vars->{$var_name} ) && $BE_LOCAL ) {
Condition83%5/6
$var_name and not ref $vars->{$var_name} and $Rex::Template::BE_LOCAL
!ll&&!rl&&r
109044
$var_name and not ref $vars->{$var_name}
!ll&&!rl&&r
105444
MC/DC66%2/3
$var_name and not ref $vars->{$var_name} and $Rex::Template::BE_LOCAL
$var_name not ref $vars->{$var_name} $Rex::Template::BE_LOCAL
Truth table75%3/4
A and not(B) and C
A= $var_nameB= not ref $vars->{$var_name}C= $Rex::Template::BE_LOCAL
ABCresult
0XX0
10X0
1100
1111
169 44 $text =~ s/([\$])::([a-zA-Z0-9_]+)/$1$2/g;
170 }
171 else {
172 109 $text =~ s/([\$])::([a-zA-Z0-9_]+)/\$$2/g;
173 }
174  
175 153 ▶ if ( $type && $type =~ m/^[+=]$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($type and $type =~ /^[+=]$/u) { } 95 58 153
Condition66%2/3
$type and $type =~ /^[+=]$/u
!ll&&!rl&&r
58095
MC/DC50%1/2
$type and $type =~ /^[+=]$/u
$type $type =~ /^[+=]$/u
Truth table66%2/3
A and B
A= $typeB= $type =~ /^[+=]$/u
ABresult
0X0
100
111
176 95 "\$___r .= $text;";
177 }
178 else {
179 58 $text;
180 }
181  
182 }
183  
184 else {
185 254 my $chomped = $_;
186 254 ▶ if ( $DO_CHOMP || $do_chomp ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Rex::Template::DO_CHOMP or $do_chomp) 0 254 254
Condition33%1/3
$Rex::Template::DO_CHOMP or $do_chomp
l!l&&r!l&&!r
00254
MC/DC0%0/2
$Rex::Template::DO_CHOMP or $do_chomp
$Rex::Template::DO_CHOMP $do_chomp
Truth table33%1/3
A or B
A= $Rex::Template::DO_CHOMPB= $do_chomp
ABresult
1X1
011
000
187 0 chomp $chomped;
188 0 $do_chomp = 0;
189 }
190 254 '$___r .= "' . _quote($chomped) . '";';
191  
192 }
193  
194 } split( /(\<%.*?%\>)/s, $data )
195 );
196  
197 130 eval {
198 108 ▶ no strict 'vars';
Subroutine BEGIN: called CC=1 SCAR=0.0
199  
200 130 for my $var ( keys %{$vars} ) {
201 610 Rex::Logger::debug("Registering: $var");
202  
203 610 my $ref_to_var = qualify_to_ref($var);
204  
205 610 ▶ unless ( ref( $vars->{$var} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $vars->{$var}) { } 212 398 610
206 398 $ref_to_var = \$vars->{$var};
207 }
208 else {
209 212 $ref_to_var = $vars->{$var};
210 }
211 }
212  
213 130 ▶ if ( $BE_LOCAL == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($BE_LOCAL == 1) { } 130 0 130
214 130 my $var_data = '
215
216 return sub {
217 my $___r = "";
218 my (
219
220 ';
221  
222 130 my @code_values;
223 130 for my $var ( keys %{$vars} ) {
224 610 my $new_var = _normalize_var_name($var);
225 610 Rex::Logger::debug("Registering local: $new_var");
226 610 $var_data .= '$' . $new_var . ", \n";
227 610 push( @code_values, $vars->{$var} );
228 }
229  
230 130 $var_data .= '$this_is_really_nothing) = @_;';
231 130 $var_data .= "\n";
232  
233 130 $var_data .= $new_data;
234  
235 130 $var_data .= "\n";
236 130 $var_data .= ' return $___r;';
237 130 $var_data .= "\n};";
238  
239 130 Rex::Logger::debug("BE_LOCAL==1");
240  
241 130 my %args = Rex::Args->getopts;
242 130 ▶ if ( defined $args{'d'} && $args{'d'} > 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $args{"d"} and $args{"d"} > 1) 0 130 130
Condition33%1/3
defined $args{"d"} and $args{"d"} > 1
!ll&&!rl&&r
13000
MC/DC0%0/2
defined $args{"d"} and $args{"d"} > 1
defined $args{"d"} $args{"d"} > 1
Truth table33%1/3
A and B
A= defined $args{"d"}B= $args{"d"} > 1
ABresult
0X0
100
111
243 0 Rex::Logger::debug($var_data);
244 }
245  
246 130 my $tpl_code = eval($var_data);
247  
248 130 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 130 130
249 0 Rex::Logger::info($@);
250 }
251  
252 130 $___r = $tpl_code->(@code_values);
253  
254 }
255 else {
256 0 Rex::Logger::debug("BE_LOCAL==0");
257 0 my %args = Rex::Args->getopts;
258 0 ▶ if ( defined $args{'d'} && $args{'d'} > 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $args{"d"} and $args{"d"} > 1) 0 0 0
Condition0%0/3
defined $args{"d"} and $args{"d"} > 1
!ll&&!rl&&r
000
MC/DC0%0/2
defined $args{"d"} and $args{"d"} > 1
defined $args{"d"} $args{"d"} > 1
Truth table0%0/3
A and B
A= defined $args{"d"}B= $args{"d"} > 1
ABresult
0X0
100
111
259 0 Rex::Logger::debug($new_data);
260 }
261  
262 0 $___r = eval($new_data);
263  
264 0 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
265 0 Rex::Logger::info($@);
266 }
267 }
268  
269 # undef the vars
270 130 for my $var ( keys %{$vars} ) {
271 128 $$var = undef;
272 }
273  
274 };
275  
276 130 ▶ if ( !$___r ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($___r) 0 130 130
277 0 Rex::Logger::info(
278 "It seems that there was an error processing the template", "warn" );
279 0 Rex::Logger::info( "because the result is empty.", "warn" );
280 0 die("Error processing template");
281 }
282  
283 130 return $___r;
284 }
285  
286 254 ▶sub _quote {
Subroutine _quote: called CC=1 SCAR=0.0
287 254 my ($str) = @_;
288  
289 254 $str =~ s/\\/\\\\/g;
290 254 $str =~ s/"/\\"/g;
291 254 $str =~ s/\@/\\@/g;
292 254 $str =~ s/\%/\\%/g;
293 254 $str =~ s/\$/\\\$/g;
294  
295 254 return $str;
296 }
297  
298 620 ▶sub _normalize_var_name {
Subroutine _normalize_var_name: called CC=1 SCAR=0.0
299 620 my ($input) = @_;
300 620 $input =~ s/[^A-Za-z0-9_]/_/g;
301 620 return $input;
302 }
303  
304 =head2 is_defined($variable, $default_value)
305  
306 This function will check if C<$variable> is defined. If yes, it will return the value of C<$variable>, otherwise it will return C<$default_value>.
307  
308 You can use this function inside your templates, for example:
309  
310 ServerTokens <%= is_defined( $::server_tokens, 'Prod' ) %>
311  
312 =cut
313  
314 0 ▶sub is_defined {
Subroutine is_defined: not called CC=2 SCAR=17.9
Pod documented
315 0 my ( $check_var, $default ) = @_;
316 0 ▶ if ( defined $check_var ) { return $check_var; }
Branch: 1 branch
BranchTrueFalseTotal
if (defined $check_var) 0 0 0
317  
318 0 return $default;
319 }
320  
321 108 1;
322  
323 __END__
« lib/Rex/Commands/Download.pm ↑ Summary lib/Rex/Helper/Run.pm »