xref: /freebsd/crypto/openssl/util/perl/OpenSSL/Template.pm (revision e0c4386e7e71d93b0edc0c8fa156263fc4a8b0b6) 
1#! /usr/bin/env perl
2# Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
3#
4# Licensed under the Apache License 2.0 (the "License").  You may not use
5# this file except in compliance with the License.  You can obtain a copy
6# in the file LICENSE in the source distribution or at
7# https://www.openssl.org/source/license.html
8
9# Implements the functionality to read one or more template files and run
10# them through Text::Template
11
12package OpenSSL::Template;
13
14=head1 NAME
15
16OpenSSL::Template - a private extension of Text::Template
17
18=head1 DESCRIPTION
19
20This provides exactly the functionality from Text::Template, with the
21following additions:
22
23=over 4
24
25=item *
26
27The template perl code delimiters (given with the C<DELIMITER> option)
28are set to C<{-> and C<-}> by default.
29
30=item *
31
32A few extra functions are offered to be used by the template perl code, see
33L</Functions>.
34
35=back
36
37=cut
38
39use File::Basename;
40use File::Spec::Functions;
41use Text::Template 1.46;
42
43our @ISA = qw(Text::Template);  # parent
44
45sub new {
46    my $class = shift;
47
48    # Call the constructor of the parent class.
49    my $self = $class->SUPER::new(DELIMITERS => [ '{-', '-}'],
50                                  @_ );
51
52    # Add few more attributes
53    $self->{_output_off}   = 0; # Default to output hunks
54
55    return bless $self, $class;
56}
57
58sub fill_in {
59    my $self = shift;
60    my %opts = @_;
61    my %hash = ( %{$opts{HASH}} );
62    delete $opts{HASH};
63
64    $self->SUPER::fill_in(HASH => { quotify1 => \&quotify1,
65                                    quotify_l => \&quotify_l,
66                                    output_on => sub { $self->output_on() },
67                                    output_off => sub { $self->output_off() },
68                                    %hash },
69                          %opts);
70}
71
72=head2 Functions
73
74=cut
75
76# Override Text::Template's append_text_to_result, as recommended here:
77#
78# http://search.cpan.org/~mjd/Text-Template-1.46/lib/Text/Template.pm#Automatic_postprocessing_of_template_hunks
79sub append_text_to_output {
80    my $self = shift;
81
82    if ($self->{_output_off} == 0) {
83        $self->SUPER::append_text_to_output(@_);
84    }
85
86    return;
87}
88
89=begin comment
90
91We lie about the OO nature of output_on() and output_off(), 'cause that's
92not how we pass them, see the HASH option used in fill_in() above
93
94=end comment
95
96=over 4
97
98=item output_on()
99
100=item output_off()
101
102Switch on or off template output.  Here's an example usage:
103
104=over 4
105
106 {- output_off() if CONDITION -}
107 whatever
108 {- output_on() if CONDITION -}
109
110=back
111
112In this example, C<whatever> will only become part of the template output
113if C<CONDITION> is true.
114
115=back
116
117=cut
118
119sub output_on {
120    my $self = shift;
121    if (--$self->{_output_off} < 0) {
122        $self->{_output_off} = 0;
123    }
124}
125
126sub output_off {
127    my $self = shift;
128    $self->{_output_off}++;
129}
130
131# Helper functions for the templates #################################
132
133=head1 SEE ALSO
134
135L<Text::Template>
136
137=head1 AUTHORS
138
139Richard Levitte E<lt>levitte@openssl.orgE<gt>
140
141=head1 COPYRIGHT
142
143Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved.
144
145Licensed under the Apache License 2.0 (the "License").  You may not use
146this file except in compliance with the License.  You can obtain a copy
147in the file LICENSE in the source distribution or at
148L<https://www.openssl.org/source/license.html>.
149
150=cut
151