lib/Automake/Condition.pm

   1 # Copyright (C) 1997, 2001, 2002, 2003, 2006, 2008  Free Software
   2 # Foundation, Inc.
   3
   4 # This program is free software; you can redistribute it and/or modify
   5 # it under the terms of the GNU General Public License as published by
   6 # the Free Software Foundation; either version 2, or (at your option)
   7 # any later version.
   8
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU General Public License for more details.
  13
  14 # You should have received a copy of the GNU General Public License
  15 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 package Automake::Condition;
  18 use strict;
  19 use Carp;
  20
  21 require Exporter;
  22 use vars '@ISA', '@EXPORT_OK';
  23 @ISA = qw/Exporter/;
  24 @EXPORT_OK = qw/TRUE FALSE reduce_and reduce_or/;
  25
  26 =head1 NAME
  27
  28 Automake::Condition - record a conjunction of conditionals
  29
  30 =head1 SYNOPSIS
  31
  32   use Automake::Condition;
  33
  34   # Create a condition to represent "COND1 and not COND2".
  35   my $cond = new Automake::Condition "COND1_TRUE", "COND2_FALSE";
  36   # Create a condition to represent "not COND3".
  37   my $other = new Automake::Condition "COND3_FALSE";
  38
  39   # Create a condition to represent
  40   #   "COND1 and not COND2 and not COND3".
  41   my $both = $cond->merge ($other);
  42
  43   # Likewise, but using a list of conditional strings
  44   my $both2 = $cond->merge_conds ("COND3_FALSE");
  45
  46   # Strip from $both any subconditions which are in $other.
  47   # This is the opposite of merge.
  48   $cond = $both->strip ($other);
  49
  50   # Return the list of conditions ("COND1_TRUE", "COND2_FALSE"):
  51   my @conds = $cond->conds;
  52
  53   # Is $cond always true?  (Not in this example)
  54   if ($cond->true) { ... }
  55
  56   # Is $cond always false? (Not in this example)
  57   if ($cond->false) { ... }
  58
  59   # Return the list of conditionals as a string:
  60   #  "COND1_TRUE COND2_FALSE"
  61   my $str = $cond->string;
  62
  63   # Return the list of conditionals as a human readable string:
  64   #  "COND1 and !COND2"
  65   my $str = $cond->human;
  66
  67   # Return the list of conditionals as a AC_SUBST-style string:
  68   #  "@COND1_TRUE@@COND2_FALSE@"
  69   my $subst = $cond->subst_string;
  70
  71   # Is $cond true when $both is true?  (Yes in this example)
  72   if ($cond->true_when ($both)) { ... }
  73
  74   # Is $cond redundant w.r.t. {$other, $both}?
  75   # (Yes in this example)
  76   if ($cond->redundant_wrt ($other, $both)) { ... }
  77
  78   # Does $cond imply any of {$other, $both}?
  79   # (Not in this example)
  80   if ($cond->implies_any ($other, $both)) { ... }
  81
  82   # Remove superfluous conditionals assuming they will eventually
  83   # be multiplied together.
  84   # (Returns @conds = ($both) in this example, because
  85   # $other and $cond are implied by $both.)
  86   @conds = Automake::Condition::reduce_and ($other, $both, $cond);
  87
  88   # Remove superfluous conditionals assuming they will eventually
  89   # be summed together.
  90   # (Returns @conds = ($cond, $other) in this example, because
  91   # $both is a subset condition of $cond: $cond is true whenever $both
  92   # is true.)
  93   @conds = Automake::Condition::reduce_or ($other, $both, $cond);
  94
  95   # Invert a Condition.  This returns a list of Conditions.
  96   @conds = $both->not;
  97
  98 =head1 DESCRIPTION
  99
 100 A C<Condition> is a conjunction of conditionals (i.e., atomic conditions
 101 defined in F<configure.ac> by C<AM_CONDITIONAL>.  In Automake they
 102 are used to represent the conditions into which F<Makefile> variables and
 103 F<Makefile> rules are defined.
 104
 105 If the variable C<VAR> is defined as
 106
 107   if COND1
 108     if COND2
 109       VAR = value
 110     endif
 111   endif
 112
 113 then it will be associated a C<Condition> created with
 114 the following statement.
 115
 116   new Automake::Condition "COND1_TRUE", "COND2_TRUE";
 117
 118 Remember that a C<Condition> is a I<conjunction> of conditionals, so
 119 the above C<Condition> means C<VAR> is defined when C<COND1>
 120 B<and> C<COND2> are true. There is no way to express disjunctions
 121 (i.e., I<or>s) with this class (but see L<DisjConditions>).
 122
 123 Another point worth to mention is that each C<Condition> object is
 124 unique with respect to its conditionals.  Two C<Condition> objects
 125 created for the same set of conditionals will have the same address.
 126 This makes it easy to compare C<Condition>s: just compare the
 127 references.
 128
 129   my $c1 = new Automake::Condition "COND1_TRUE", "COND2_TRUE";
 130   my $c2 = new Automake::Condition "COND1_TRUE", "COND2_TRUE";
 131   $c1 == $c2;  # True!
 132
 133 =head2 Methods
 134
 135 =over 4
 136
 137 =item C<$cond = new Automake::Condition [@conds]>
 138
 139 Return a C<Condition> objects for the conjunctions of conditionals
 140 listed in C<@conds> as strings.
 141
 142 An item in C<@conds> should be either C<"FALSE">, C<"TRUE">, or have
 143 the form C<"NAME_FALSE"> or C<"NAME_TRUE"> where C<NAME> can be
 144 anything (in practice C<NAME> should be the name of a conditional
 145 declared in F<configure.ac> with C<AM_CONDITIONAL>, but it's not
 146 C<Automake::Condition>'s responsibility to ensure this).
 147
 148 An empty C<@conds> means C<"TRUE">.
 149
 150 As explained previously, the reference (object) returned is unique
 151 with respect to C<@conds>.  For this purpose, duplicate elements are
 152 ignored, and C<@conds> is rewritten as C<("FALSE")> if it contains
 153 C<"FALSE"> or two contradictory conditionals (such as C<"NAME_FALSE">
 154 and C<"NAME_TRUE">.)
 155
 156 Therefore the following two statements create the same object (they
 157 both create the C<"FALSE"> condition).
 158
 159   my $c3 = new Automake::Condition "COND1_TRUE", "COND1_FALSE";
 160   my $c4 = new Automake::Condition "COND2_TRUE", "FALSE";
 161   $c3 == $c4;   # True!
 162   $c3 == FALSE; # True!
 163
 164 =cut
 165
 166 # Keys in this hash are conditional strings. Values are the
 167 # associated object conditions.  This is used by `new' to reuse
 168 # Condition objects with identical conditionals.
 169 use vars '%_condition_singletons';
 170 # Do NOT reset this hash here.  It's already empty by default,
 171 # and any setting would otherwise occur AFTER the `TRUE' and `FALSE'
 172 # constants definitions.
 173 #   %_condition_singletons = ();
 174
 175 sub new ($;@)
 176 {
 177   my ($class, @conds) = @_;
 178   my $self = {
 179     hash => {},
 180   };
 181   bless $self, $class;
 182
 183   # Accept strings like "FOO BAR" as shorthand for ("FOO", "BAR").
 184   @conds = map { split (' ', $_) } @conds;
 185
 186   for my $cond (@conds)
 187     {
 188       next if $cond eq 'TRUE';
 189
 190       # Catch some common programming errors:
 191       # - A Condition passed to new
 192       confess "`$cond' is a reference, expected a string" if ref $cond;
 193       # - A Condition passed as a string to new
 194       confess "`$cond' does not look like a condition" if $cond =~ /::/;
 195
 196       # Detect cases when @conds can be simplified to FALSE.
 197       if (($cond eq 'FALSE' && $#conds > 0)
 198           || ($cond =~ /^(.*)_TRUE$/ && exists $self->{'hash'}{"${1}_FALSE"})
 199           || ($cond =~ /^(.*)_FALSE$/ && exists $self->{'hash'}{"${1}_TRUE"}))
 200         {
 201           return &FALSE;
 202         }
 203
 204       $self->{'hash'}{$cond} = 1;
 205     }
 206
 207   my $key = $self->string;
 208   if (exists $_condition_singletons{$key})
 209     {
 210       return $_condition_singletons{$key};
 211     }
 212   $_condition_singletons{$key} = $self;
 213   return $self;
 214 }
 215
 216 =item C<$newcond = $cond-E<gt>merge (@otherconds)>
 217
 218 Return a new condition which is the conjunction of
 219 C<$cond> and C<@otherconds>.
 220
 221 =cut
 222
 223 sub merge ($@)
 224 {
 225   my ($self, @otherconds) = @_;
 226   new Automake::Condition (map { $_->conds } ($self, @otherconds));
 227 }
 228
 229 =item C<$newcond = $cond-E<gt>merge_conds (@conds)>
 230
 231 Return a new condition which is the conjunction of C<$cond> and
 232 C<@conds>, where C<@conds> is a list of conditional strings, as
 233 passed to C<new>.
 234
 235 =cut
 236
 237 sub merge_conds ($@)
 238 {
 239   my ($self, @conds) = @_;
 240   new Automake::Condition $self->conds, @conds;
 241 }
 242
 243 =item C<$newcond = $cond-E<gt>strip ($minuscond)>
 244
 245 Return a new condition which has all the conditionals of C<$cond>
 246 except those of C<$minuscond>.  This is the opposite of C<merge>.
 247
 248 =cut
 249
 250 sub strip ($$)
 251 {
 252   my ($self, $minus) = @_;
 253   my @res = grep { not $minus->has ($_) } $self->conds;
 254   return new Automake::Condition @res;
 255 }
 256
 257 =item C<@list = $cond-E<gt>conds>
 258
 259 Return the set of conditionals defining C<$cond>, as strings.  Note that
 260 this might not be exactly the list passed to C<new> (or a
 261 concatenation of such lists if C<merge> was used), because of the
 262 cleanup mentioned in C<new>'s description.
 263
 264 For instance C<$c3-E<gt>conds> will simply return C<("FALSE")>.
 265
 266 =cut
 267
 268 sub conds ($ )
 269 {
 270   my ($self) = @_;
 271   my @conds = keys %{$self->{'hash'}};
 272   return ("TRUE") unless @conds;
 273   return sort @conds;
 274 }
 275
 276 # Undocumented, shouldn't be needed outside of this class.
 277 sub has ($$)
 278 {
 279   my ($self, $cond) = @_;
 280   return exists $self->{'hash'}{$cond};
 281 }
 282
 283 =item C<$cond-E<gt>false>
 284
 285 Return 1 iff this condition is always false.
 286
 287 =cut
 288
 289 sub false ($ )
 290 {
 291   my ($self) = @_;
 292   return $self->has ('FALSE');
 293 }
 294
 295 =item C<$cond-E<gt>true>
 296
 297 Return 1 iff this condition is always true.
 298
 299 =cut
 300
 301 sub true ($ )
 302 {
 303   my ($self) = @_;
 304   return 0 == keys %{$self->{'hash'}};
 305 }
 306
 307 =item C<$cond-E<gt>string>
 308
 309 Build a string which denotes the condition.
 310
 311 For instance using the C<$cond> definition from L<SYNOPSYS>,
 312 C<$cond-E<gt>string> will return C<"COND1_TRUE COND2_FALSE">.
 313
 314 =cut
 315
 316 sub string ($ )
 317 {
 318   my ($self) = @_;
 319
 320   return $self->{'string'} if defined $self->{'string'};
 321
 322   my $res = '';
 323   if ($self->false)
 324     {
 325       $res = 'FALSE';
 326     }
 327   else
 328     {
 329       $res = join (' ', $self->conds);
 330     }
 331   $self->{'string'} = $res;
 332   return $res;
 333 }
 334
 335 =item C<$cond-E<gt>human>
 336
 337 Build a human readable string which denotes the condition.
 338
 339 For instance using the C<$cond> definition from L<SYNOPSYS>,
 340 C<$cond-E<gt>string> will return C<"COND1 and !COND2">.
 341
 342 =cut
 343
 344 sub _to_human ($ )
 345 {
 346   my ($s) = @_;
 347   if ($s =~ /^(.*)_(TRUE|FALSE)$/)
 348     {
 349       return (($2 eq 'FALSE') ? '!' : '') . $1;
 350     }
 351   else
 352     {
 353       return $s;
 354     }
 355 }
 356
 357 sub human ($ )
 358 {
 359   my ($self) = @_;
 360
 361   return $self->{'human'} if defined $self->{'human'};
 362
 363   my $res = '';
 364   if ($self->false)
 365     {
 366       $res = 'FALSE';
 367     }
 368   else
 369     {
 370       $res = join (' and ', map { _to_human $_ } $self->conds);
 371     }
 372   $self->{'human'} = $res;
 373   return $res;
 374 }
 375
 376 =item C<$cond-E<gt>subst_string>
 377
 378 Build a C<AC_SUBST>-style string for output in F<Makefile.in>.
 379
 380 For instance using the C<$cond> definition from L<SYNOPSYS>,
 381 C<$cond-E<gt>subst_string> will return C<"@COND1_TRUE@@COND2_FALSE@">.
 382
 383 =cut
 384
 385 sub subst_string ($ )
 386 {
 387   my ($self) = @_;
 388
 389   return $self->{'subst_string'} if defined $self->{'subst_string'};
 390
 391   my $res = '';
 392   if ($self->false)
 393     {
 394       $res = '#';
 395     }
 396   elsif (! $self->true)
 397     {
 398       $res = '@' . join ('@@', sort $self->conds) . '@';
 399     }
 400   $self->{'subst_string'} = $res;
 401   return $res;
 402 }
 403
 404 =item C<$cond-E<gt>true_when ($when)>
 405
 406 Return 1 iff C<$cond> is true when C<$when> is true.
 407 Return 0 otherwise.
 408
 409 Using the definitions from L<SYNOPSYS>, C<$cond> is true
 410 when C<$both> is true, but the converse is wrong.
 411
 412 =cut
 413
 414 sub true_when ($$)
 415 {
 416   my ($self, $when) = @_;
 417
 418   # Nothing is true when FALSE (not even FALSE itself, but it
 419   # shouldn't hurt if you decide to change that).
 420   return 0 if $self->false || $when->false;
 421
 422   # If we are true, we stay true when $when is true :)
 423   return 1 if $self->true;
 424
 425   # $SELF is true under $WHEN if each conditional component of $SELF
 426   # exists in $WHEN.
 427   foreach my $cond ($self->conds)
 428     {
 429       return 0 unless $when->has ($cond);
 430     }
 431   return 1;
 432 }
 433
 434 =item C<$cond-E<gt>redundant_wrt (@conds)>
 435
 436 Return 1 iff C<$cond> is true for any condition in C<@conds>.
 437 If @conds is empty, return 1 iff C<$cond> is C<FALSE>.
 438 Return 0 otherwise.
 439
 440 =cut
 441
 442 sub redundant_wrt ($@)
 443 {
 444   my ($self, @conds) = @_;
 445
 446   foreach my $cond (@conds)
 447     {
 448       return 1 if $self->true_when ($cond);
 449     }
 450   return $self->false;
 451 }
 452
 453 =item C<$cond-E<gt>implies_any (@conds)>
 454
 455 Return 1 iff C<$cond> implies any of the conditions in C<@conds>.
 456 Return 0 otherwise.
 457
 458 =cut
 459
 460 sub implies_any ($@)
 461 {
 462   my ($self, @conds) = @_;
 463
 464   foreach my $cond (@conds)
 465     {
 466       return 1 if $cond->true_when ($self);
 467     }
 468   return 0;
 469 }
 470
 471 =item C<$cond-E<gt>not>
 472
 473 Return a negation of C<$cond> as a list of C<Condition>s.
 474 This list should be used to construct a C<DisjConditions>
 475 (we cannot return a C<DisjConditions> from C<Automake::Condition>,
 476 because that would make these two packages interdependent).
 477
 478 =cut
 479
 480 sub not ($ )
 481 {
 482   my ($self) = @_;
 483   return @{$self->{'not'}} if defined $self->{'not'};
 484   my @res =
 485     map { new Automake::Condition &conditional_negate ($_) } $self->conds;
 486   $self->{'not'} = [@res];
 487   return @res;
 488 }
 489
 490 =item C<$cond-E<gt>multiply (@conds)>
 491
 492 Assumption: C<@conds> represent a disjunction of conditions.
 493
 494 Return the result of multiplying C<$cond> with that disjunction.
 495 The result will be a list of conditions suitable to construct a
 496 C<DisjConditions>.
 497
 498 =cut
 499
 500 sub multiply ($@)
 501 {
 502   my ($self, @set) = @_;
 503   my %res = ();
 504   for my $cond (@set)
 505     {
 506       my $ans = $self->merge ($cond);
 507       $res{$ans} = $ans;
 508     }
 509
 510   # FALSE can always be removed from a disjunction.
 511   delete $res{FALSE};
 512
 513   # Now, $self is a common factor of the remaining conditions.
 514   # If one of the conditions is $self, we can discard the rest.
 515   return ($self, ())
 516     if exists $res{$self};
 517
 518   return (values %res);
 519 }
 520
 521 =head2 Other helper functions
 522
 523 =over 4
 524
 525 =item C<TRUE>
 526
 527 The C<"TRUE"> conditional.
 528
 529 =item C<FALSE>
 530
 531 The C<"FALSE"> conditional.
 532
 533 =cut
 534
 535 use constant TRUE => new Automake::Condition "TRUE";
 536 use constant FALSE => new Automake::Condition "FALSE";
 537
 538 =item C<reduce_and (@conds)>
 539
 540 Return a subset of @conds with the property that the conjunction of
 541 the subset is the same as the conjunction of @conds.  For example, if
 542 both C<COND1_TRUE COND2_TRUE> and C<COND1_TRUE> are in the list,
 543 discard the latter.  If the input list is empty, return C<(TRUE)>.
 544
 545 =cut
 546
 547 sub reduce_and (@)
 548 {
 549   my (@conds) = @_;
 550   my @ret = ();
 551   my $cond;
 552   while (@conds > 0)
 553     {
 554       $cond = shift @conds;
 555
 556       # FALSE is absorbent.
 557       return FALSE
 558         if $cond == FALSE;
 559
 560       if (! $cond->redundant_wrt (@ret, @conds))
 561         {
 562           push (@ret, $cond);
 563         }
 564     }
 565
 566   return TRUE if @ret == 0;
 567   return @ret;
 568 }
 569
 570 =item C<reduce_or (@conds)>
 571
 572 Return a subset of @conds with the property that the disjunction of
 573 the subset is equivalent to the disjunction of @conds.  For example,
 574 if both C<COND1_TRUE COND2_TRUE> and C<COND1_TRUE> are in the list,
 575 discard the former.  If the input list is empty, return C<(FALSE)>.
 576
 577 =cut
 578
 579 sub reduce_or (@)
 580 {
 581   my (@conds) = @_;
 582   my @ret = ();
 583   my $cond;
 584   while (@conds > 0)
 585     {
 586       $cond = shift @conds;
 587
 588       next
 589        if $cond == FALSE;
 590       return TRUE
 591        if $cond == TRUE;
 592
 593       push (@ret, $cond)
 594        unless $cond->implies_any (@ret, @conds);
 595     }
 596
 597   return FALSE if @ret == 0;
 598   return @ret;
 599 }
 600
 601 =item C<conditional_negate ($condstr)>
 602
 603 Negate a conditional string.
 604
 605 =cut
 606
 607 sub conditional_negate ($)
 608 {
 609   my ($cond) = @_;
 610
 611   $cond =~ s/TRUE$/TRUEO/;
 612   $cond =~ s/FALSE$/TRUE/;
 613   $cond =~ s/TRUEO$/FALSE/;
 614
 615   return $cond;
 616 }
 617
 618 =head1 SEE ALSO
 619
 620 L<Automake::DisjConditions>.
 621
 622 =head1 HISTORY
 623
 624 C<AM_CONDITIONAL>s and supporting code were added to Automake 1.1o by
 625 Ian Lance Taylor <ian@cygnus.org> in 1997.  Since then it has been
 626 improved by Tom Tromey <tromey@redhat.com>, Richard Boulton
 627 <richard@tartarus.org>, Raja R Harinath <harinath@cs.umn.edu>,
 628 Akim Demaille <akim@epita.fr>, and  Alexandre Duret-Lutz <adl@gnu.org>.
 629
 630 =cut
 631
 632 1;
 633
 634 ### Setup "GNU" style for perl-mode and cperl-mode.
 635 ## Local Variables:
 636 ## perl-indent-level: 2
 637 ## perl-continued-statement-offset: 2
 638 ## perl-continued-brace-offset: 0
 639 ## perl-brace-offset: 0
 640 ## perl-brace-imaginary-offset: 0
 641 ## perl-label-offset: -2
 642 ## cperl-indent-level: 2
 643 ## cperl-brace-offset: 0
 644 ## cperl-continued-brace-offset: 0
 645 ## cperl-label-offset: -2
 646 ## cperl-extra-newline-before-brace: t
 647 ## cperl-merge-trailing-else: nil
 648 ## cperl-continued-statement-offset: 2
 649 ## End: