1 # Copyright (C) 1997-2024 Free Software Foundation, Inc.
3 # This program is free software; you can redistribute it and/or modify
4 # it under the terms of the GNU General Public License as published by
5 # the Free Software Foundation; either version 2, or (at your option)
8 # This program is distributed in the hope that it will be useful,
9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 # GNU General Public License for more details.
13 # You should have received a copy of the GNU General Public License
14 # along with this program. If not, see <https://www.gnu.org/licenses/>.
16 package Automake
::Condition
;
20 use warnings FATAL
=> 'all';
25 our @ISA = qw
(Exporter
);
26 our @EXPORT_OK = qw
(TRUE FALSE reduce_and reduce_or
);
30 Automake::Condition - record a conjunction of conditionals
34 use Automake::Condition;
36 # Create a condition to represent "COND1 and not COND2".
37 my $cond = new Automake::Condition "COND1_TRUE", "COND2_FALSE";
38 # Create a condition to represent "not COND3".
39 my $other = new Automake::Condition "COND3_FALSE";
41 # Create a condition to represent
42 # "COND1 and not COND2 and not COND3".
43 my $both = $cond->merge ($other);
45 # Likewise, but using a list of conditional strings
46 my $both2 = $cond->merge_conds ("COND3_FALSE");
48 # Strip from $both any subconditions which are in $other.
49 # This is the opposite of merge.
50 $cond = $both->strip ($other);
52 # Return the list of conditions ("COND1_TRUE", "COND2_FALSE"):
53 my @conds = $cond->conds;
55 # Is $cond always true? (Not in this example)
56 if ($cond->true) { ... }
58 # Is $cond always false? (Not in this example)
59 if ($cond->false) { ... }
61 # Return the list of conditionals as a string:
62 # "COND1_TRUE COND2_FALSE"
63 my $str = $cond->string;
65 # Return the list of conditionals as a human readable string:
67 my $str = $cond->human;
69 # Return the list of conditionals as a AC_SUBST-style string:
70 # "@COND1_TRUE@@COND2_FALSE@"
71 my $subst = $cond->subst_string;
73 # Is $cond true when $both is true? (Yes in this example)
74 if ($cond->true_when ($both)) { ... }
76 # Is $cond redundant w.r.t. {$other, $both}?
77 # (Yes in this example)
78 if ($cond->redundant_wrt ($other, $both)) { ... }
80 # Does $cond imply any of {$other, $both}?
81 # (Not in this example)
82 if ($cond->implies_any ($other, $both)) { ... }
84 # Remove superfluous conditionals assuming they will eventually
85 # be multiplied together.
86 # (Returns @conds = ($both) in this example, because
87 # $other and $cond are implied by $both.)
88 @conds = Automake::Condition::reduce_and ($other, $both, $cond);
90 # Remove superfluous conditionals assuming they will eventually
92 # (Returns @conds = ($cond, $other) in this example, because
93 # $both is a subset condition of $cond: $cond is true whenever $both
95 @conds = Automake::Condition::reduce_or ($other, $both, $cond);
97 # Invert a Condition. This returns a list of Conditions.
102 A C<Condition> is a conjunction of conditionals (i.e., atomic conditions
103 defined in F<configure.ac> by C<AM_CONDITIONAL>. In Automake they
104 are used to represent the conditions into which F<Makefile> variables and
105 F<Makefile> rules are defined.
107 If the variable C<VAR> is defined as
115 then it will be associated a C<Condition> created with
116 the following statement.
118 new Automake::Condition "COND1_TRUE", "COND2_TRUE";
120 Remember that a C<Condition> is a I<conjunction> of conditionals, so
121 the above C<Condition> means C<VAR> is defined when C<COND1>
122 B<and> C<COND2> are true. There is no way to express disjunctions
123 (i.e., I<or>s) with this class (but see L<DisjConditions>).
125 Another point worth to mention is that each C<Condition> object is
126 unique with respect to its conditionals. Two C<Condition> objects
127 created for the same set of conditionals will have the same address.
128 This makes it easy to compare C<Condition>s: just compare the
131 my $c1 = new Automake::Condition "COND1_TRUE", "COND2_TRUE";
132 my $c2 = new Automake::Condition "COND1_TRUE", "COND2_TRUE";
139 =item C<$cond = new Automake::Condition [@conds]>
141 Return a C<Condition> objects for the conjunctions of conditionals
142 listed in C<@conds> as strings.
144 An item in C<@conds> should be either C<"FALSE">, C<"TRUE">, or have
145 the form C<"NAME_FALSE"> or C<"NAME_TRUE"> where C<NAME> can be
146 anything (in practice C<NAME> should be the name of a conditional
147 declared in F<configure.ac> with C<AM_CONDITIONAL>, but it's not
148 C<Automake::Condition>'s responsibility to ensure this).
150 An empty C<@conds> means C<"TRUE">.
152 As explained previously, the reference (object) returned is unique
153 with respect to C<@conds>. For this purpose, duplicate elements are
154 ignored, and C<@conds> is rewritten as C<("FALSE")> if it contains
155 C<"FALSE"> or two contradictory conditionals (such as C<"NAME_FALSE">
158 Therefore the following two statements create the same object (they
159 both create the C<"FALSE"> condition).
161 my $c3 = new Automake::Condition "COND1_TRUE", "COND1_FALSE";
162 my $c4 = new Automake::Condition "COND2_TRUE", "FALSE";
164 $c3 == FALSE; # True!
168 # Keys in this hash are conditional strings. Values are the
169 # associated object conditions. This is used by 'new' to reuse
170 # Condition objects with identical conditionals.
171 our %_condition_singletons;
172 # Do NOT reset this hash here. It's already empty by default,
173 # and any setting would otherwise occur AFTER the 'TRUE' and 'FALSE'
174 # constants definitions.
175 # %_condition_singletons = ();
179 my ($class, @conds) = @_;
185 for my $cond (@conds)
187 # Catch some common programming errors:
188 # - A Condition passed to new
189 confess
"'$cond' is a reference, expected a string" if ref $cond;
190 # - A Condition passed as a string to new
191 confess
"'$cond' does not look like a condition" if $cond =~ /::/;
194 # Accept strings like "FOO BAR" as shorthand for ("FOO", "BAR").
195 @conds = map { split (' ', $_) } @conds;
197 for my $cond (@conds)
199 next if $cond eq 'TRUE';
201 # Detect cases when @conds can be simplified to FALSE.
202 if (($cond eq 'FALSE' && $#conds > 0)
203 || ($cond =~ /^(.*)_TRUE$/ && exists $self->{'hash'}{"${1}_FALSE"})
204 || ($cond =~ /^(.*)_FALSE$/ && exists $self->{'hash'}{"${1}_TRUE"}))
209 $self->{'hash'}{$cond} = 1;
212 my $key = $self->string;
213 if (exists $_condition_singletons{$key})
215 return $_condition_singletons{$key};
217 $_condition_singletons{$key} = $self;
221 =item C<$newcond = $cond-E<gt>merge (@otherconds)>
223 Return a new condition which is the conjunction of
224 C<$cond> and C<@otherconds>.
230 my ($self, @otherconds) = @_;
231 new Automake
::Condition
(map { $_->conds } ($self, @otherconds));
234 =item C<$newcond = $cond-E<gt>merge_conds (@conds)>
236 Return a new condition which is the conjunction of C<$cond> and
237 C<@conds>, where C<@conds> is a list of conditional strings, as
244 my ($self, @conds) = @_;
245 new Automake
::Condition
$self->conds, @conds;
248 =item C<$newcond = $cond-E<gt>strip ($minuscond)>
250 Return a new condition which has all the conditionals of C<$cond>
251 except those of C<$minuscond>. This is the opposite of C<merge>.
257 my ($self, $minus) = @_;
258 my @res = grep { not $minus->_has ($_) } $self->conds;
259 return new Automake
::Condition
@res;
262 =item C<@list = $cond-E<gt>conds>
264 Return the set of conditionals defining C<$cond>, as strings. Note that
265 this might not be exactly the list passed to C<new> (or a
266 concatenation of such lists if C<merge> was used), because of the
267 cleanup mentioned in C<new>'s description.
269 For instance C<$c3-E<gt>conds> will simply return C<("FALSE")>.
276 my @conds = keys %{$self->{'hash'}};
277 return ("TRUE") unless @conds;
281 # Undocumented, shouldn't be needed outside of this class.
284 my ($self, $cond) = @_;
285 return exists $self->{'hash'}{$cond};
288 =item C<$cond-E<gt>false>
290 Return 1 iff this condition is always false.
297 return $self->_has ('FALSE');
300 =item C<$cond-E<gt>true>
302 Return 1 iff this condition is always true.
309 return 0 == keys %{$self->{'hash'}};
312 =item C<$cond-E<gt>string>
314 Build a string which denotes the condition.
316 For instance using the C<$cond> definition from L<SYNOPSYS>,
317 C<$cond-E<gt>string> will return C<"COND1_TRUE COND2_FALSE">.
325 return $self->{'string'} if defined $self->{'string'};
334 $res = join (' ', $self->conds);
336 $self->{'string'} = $res;
340 =item C<$cond-E<gt>human>
342 Build a human readable string which denotes the condition.
344 For instance using the C<$cond> definition from L<SYNOPSYS>,
345 C<$cond-E<gt>string> will return C<"COND1 and !COND2">.
352 if ($s =~ /^(.*)_(TRUE|FALSE)$/)
354 return (($2 eq 'FALSE') ?
'!' : '') . $1;
366 return $self->{'human'} if defined $self->{'human'};
375 $res = join (' and ', map { _to_human
$_ } $self->conds);
377 $self->{'human'} = $res;
381 =item C<$cond-E<gt>subst_string>
383 Build a C<AC_SUBST>-style string for output in F<Makefile.in>.
385 For instance using the C<$cond> definition from L<SYNOPSYS>,
386 C<$cond-E<gt>subst_string> will return C<"@COND1_TRUE@@COND2_FALSE@">.
390 sub subst_string
($ )
394 return $self->{'subst_string'} if defined $self->{'subst_string'};
401 elsif (! $self->true)
403 $res = '@' . join ('@@', sort $self->conds) . '@';
405 $self->{'subst_string'} = $res;
409 =item C<$cond-E<gt>true_when ($when)>
411 Return 1 iff C<$cond> is true when C<$when> is true.
414 Using the definitions from L<SYNOPSYS>, C<$cond> is true
415 when C<$both> is true, but the converse is wrong.
421 my ($self, $when) = @_;
423 # Nothing is true when FALSE (not even FALSE itself, but it
424 # shouldn't hurt if you decide to change that).
425 return 0 if $self->false || $when->false;
427 # If we are true, we stay true when $when is true :)
428 return 1 if $self->true;
430 # $SELF is true under $WHEN if each conditional component of $SELF
432 foreach my $cond ($self->conds)
434 return 0 unless $when->_has ($cond);
439 =item C<$cond-E<gt>redundant_wrt (@conds)>
441 Return 1 iff C<$cond> is true for any condition in C<@conds>.
442 If @conds is empty, return 1 iff C<$cond> is C<FALSE>.
447 sub redundant_wrt
($@
)
449 my ($self, @conds) = @_;
451 foreach my $cond (@conds)
453 return 1 if $self->true_when ($cond);
458 =item C<$cond-E<gt>implies_any (@conds)>
460 Return 1 iff C<$cond> implies any of the conditions in C<@conds>.
467 my ($self, @conds) = @_;
469 foreach my $cond (@conds)
471 return 1 if $cond->true_when ($self);
476 =item C<$cond-E<gt>not>
478 Return a negation of C<$cond> as a list of C<Condition>s.
479 This list should be used to construct a C<DisjConditions>
480 (we cannot return a C<DisjConditions> from C<Automake::Condition>,
481 because that would make these two packages interdependent).
488 return @
{$self->{'not'}} if defined $self->{'not'};
490 map { new Automake
::Condition
&conditional_negate
($_) } $self->conds;
491 $self->{'not'} = [@res];
495 =item C<$cond-E<gt>multiply (@conds)>
497 Assumption: C<@conds> represent a disjunction of conditions.
499 Return the result of multiplying C<$cond> with that disjunction.
500 The result will be a list of conditions suitable to construct a
507 my ($self, @set) = @_;
511 my $ans = $self->merge ($cond);
515 # FALSE can always be removed from a disjunction.
518 # Now, $self is a common factor of the remaining conditions.
519 # If one of the conditions is $self, we can discard the rest.
521 if exists $res{$self};
523 return (values %res);
528 =head2 Other helper functions
534 The C<"TRUE"> conditional.
538 The C<"FALSE"> conditional.
542 use constant TRUE
=> new Automake
::Condition
"TRUE";
543 use constant FALSE
=> new Automake
::Condition
"FALSE";
545 =item C<reduce_and (@conds)>
547 Return a subset of @conds with the property that the conjunction of
548 the subset is the same as the conjunction of @conds. For example, if
549 both C<COND1_TRUE COND2_TRUE> and C<COND1_TRUE> are in the list,
550 discard the latter. If the input list is empty, return C<(TRUE)>.
561 $cond = shift @conds;
563 # FALSE is absorbent.
567 if (! $cond->redundant_wrt (@ret, @conds))
573 return TRUE
if @ret == 0;
577 =item C<reduce_or (@conds)>
579 Return a subset of @conds with the property that the disjunction of
580 the subset is equivalent to the disjunction of @conds. For example,
581 if both C<COND1_TRUE COND2_TRUE> and C<COND1_TRUE> are in the list,
582 discard the former. If the input list is empty, return C<(FALSE)>.
593 $cond = shift @conds;
601 unless $cond->implies_any (@ret, @conds);
604 return FALSE
if @ret == 0;
608 =item C<conditional_negate ($condstr)>
610 Negate a conditional string.
614 sub conditional_negate
($)
618 $cond =~ s/TRUE$/TRUEO/;
619 $cond =~ s/FALSE$/TRUE/;
620 $cond =~ s/TRUEO$/FALSE/;
629 L<Automake::DisjConditions>.
633 C<AM_CONDITIONAL>s and supporting code were added to Automake 1.1o by
634 Ian Lance Taylor <ian@cygnus.org> in 1997. Since then it has been
635 improved by Tom Tromey <tromey@redhat.com>, Richard Boulton
636 <richard@tartarus.org>, Raja R Harinath <harinath@cs.umn.edu>,
637 Akim Demaille <akim@epita.fr>, and Alexandre Duret-Lutz <adl@gnu.org>.