lib/Automake/VarDef.pm

   1 # Copyright (C) 2003, 2004, 2006, 2009  Free Software Foundation, Inc.
   2
   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)
   6 # any later version.
   7
   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.
  12
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 package Automake::VarDef;
  17 use strict;
  18 use Carp;
  19 use Automake::ChannelDefs;
  20 use Automake::ItemDef;
  21
  22 require Exporter;
  23 use vars '@ISA', '@EXPORT';
  24 @ISA = qw/Automake::ItemDef Exporter/;
  25 @EXPORT = qw (&VAR_AUTOMAKE &VAR_CONFIGURE &VAR_MAKEFILE
  26               &VAR_ASIS &VAR_PRETTY &VAR_SILENT &VAR_SORTED);
  27
  28 =head1 NAME
  29
  30 Automake::VarDef - a class for variable definitions
  31
  32 =head1 SYNOPSIS
  33
  34   use Automake::VarDef;
  35   use Automake::Location;
  36
  37   # Create a VarDef for a definition such as
  38   # | # any comment
  39   # | foo = bar # more comment
  40   # in Makefile.am
  41   my $loc = new Automake::Location 'Makefile.am:2';
  42   my $def = new Automake::VarDef ('foo', 'bar # more comment',
  43                                   '# any comment',
  44                                   $loc, '', VAR_MAKEFILE, VAR_ASIS);
  45
  46   # Appending to a definition.
  47   $def->append ('value to append', 'comment to append');
  48
  49   # Accessors.
  50   my $value    = $def->value;  # with trailing `#' comments and
  51                                # continuation ("\\\n") omitted.
  52   my $value    = $def->raw_value; # the real value, as passed to new().
  53   my $comment  = $def->comment;
  54   my $location = $def->location;
  55   my $type     = $def->type;
  56   my $owner    = $def->owner;
  57   my $pretty   = $def->pretty;
  58
  59   # Changing owner.
  60   $def->set_owner (VAR_CONFIGURE,
  61                    new Automake::Location 'configure.ac:15');
  62
  63   # Marking examined definitions.
  64   $def->set_seen;
  65   my $seen_p = $def->seen;
  66
  67   # Printing a variable for debugging.
  68   print STDERR $def->dump;
  69
  70 =head1 DESCRIPTION
  71
  72 This class gathers data related to one Makefile-variable definition.
  73
  74 =head2 Constants
  75
  76 =over 4
  77
  78 =item C<VAR_AUTOMAKE>, C<VAR_CONFIGURE>, C<VAR_MAKEFILE>
  79
  80 Possible owners for variables.  A variable can be defined
  81 by Automake, in F<configure.ac> (using C<AC_SUBST>), or in
  82 the user's F<Makefile.am>.
  83
  84 =cut
  85
  86 # Defined so that the owner of a variable can only be increased (e.g
  87 # Automake should not override a configure or Makefile variable).
  88 use constant VAR_AUTOMAKE => 0; # Variable defined by Automake.
  89 use constant VAR_CONFIGURE => 1;# Variable defined in configure.ac.
  90 use constant VAR_MAKEFILE => 2; # Variable defined in Makefile.am.
  91
  92 =item C<VAR_ASIS>, C<VAR_PRETTY>, C<VAR_SILENT>, C<VAR_SORTED>
  93
  94 Possible print styles.  C<VAR_ASIS> variables should be output as-is.
  95 C<VAR_PRETTY> variables are wrapped on multiple lines if they cannot
  96 fit on one.  C<VAR_SILENT> variables are not output at all.  Finally,
  97 C<VAR_SORTED> variables should be sorted and then handled as
  98 C<VAR_PRETTY> variables.
  99
 100 C<VAR_SILENT> variables can also be overridden silently (unlike the
 101 other kinds of variables whose overriding may sometimes produce
 102 warnings).
 103
 104 =cut
 105
 106 # Possible values for pretty.
 107 use constant VAR_ASIS => 0;     # Output as-is.
 108 use constant VAR_PRETTY => 1;   # Pretty printed on output.
 109 use constant VAR_SILENT => 2;   # Not output.  (Can also be
 110                                 # overridden silently.)
 111 use constant VAR_SORTED => 3;   # Sorted and pretty-printed.
 112
 113 =back
 114
 115 =head2 Methods
 116
 117 C<VarDef> defines the following methods in addition to those inherited
 118 from L<Automake::ItemDef>.
 119
 120 =over 4
 121
 122 =item C<my $def = new Automake::VarDef ($varname, $value, $comment, $location, $type, $owner, $pretty)>
 123
 124 Create a new Makefile-variable definition.  C<$varname> is the name of
 125 the variable being defined and C<$value> its value.
 126
 127 C<$comment> is any comment preceding the definition.  (Because
 128 Automake reorders variable definitions in the output, it also tries to
 129 carry comments around.)
 130
 131 C<$location> is the place where the definition occurred, it should be
 132 an instance of L<Automake::Location>.
 133
 134 C<$type> should be C<''> for definitions made with C<=>, and C<':'>
 135 for those made with C<:=>.
 136
 137 C<$owner> specifies who owns the variables, it can be one of
 138 C<VAR_AUTOMAKE>, C<VAR_CONFIGURE>, or C<VAR_MAKEFILE> (see these
 139 definitions).
 140
 141 Finally, C<$pretty> tells how the variable should be output, and can
 142 be one of C<VAR_ASIS>, C<VAR_PRETTY>, or C<VAR_SILENT>, or
 143 C<VAR_SORTED> (see these definitions).
 144
 145 =cut
 146
 147 sub new ($$$$$$$$)
 148 {
 149   my ($class, $var, $value, $comment, $location, $type, $owner, $pretty) = @_;
 150
 151   # A user variable must be set by either `=' or `:=', and later
 152   # promoted to `+='.
 153   if ($owner != VAR_AUTOMAKE && $type eq '+')
 154     {
 155       error $location, "$var must be set with `=' before using `+='";
 156     }
 157
 158   my $self = Automake::ItemDef::new ($class, $comment, $location, $owner);
 159   $self->{'value'} = $value;
 160   $self->{'type'} = $type;
 161   $self->{'pretty'} = $pretty;
 162   $self->{'seen'} = 0;
 163   return $self;
 164 }
 165
 166 =item C<$def-E<gt>append ($value, $comment)>
 167
 168 Append C<$value> and <$comment> to the existing value and comment of
 169 C<$def>.  This is normally called on C<+=> definitions.
 170
 171 =cut
 172
 173 sub append ($$$)
 174 {
 175   my ($self, $value, $comment) = @_;
 176   $self->{'comment'} .= $comment;
 177
 178   my $val = $self->{'value'};
 179
 180   # Strip comments from augmented variables.  This is so that
 181   #   VAR = foo # com
 182   #   VAR += bar
 183   # does not become
 184   #   VAR = foo # com bar
 185   # Furthermore keeping `#' would not be portable if the variable is
 186   # output on multiple lines.
 187   $val =~ s/ ?#.*//;
 188
 189   if (chomp $val)
 190     {
 191       # Insert a backslash before a trailing newline.
 192       $val .= "\\\n";
 193     }
 194   elsif ($val)
 195     {
 196       # Insert a separator.
 197       $val .= ' ';
 198     }
 199   $self->{'value'} = $val . $value;
 200   # Turn ASIS appended variables into PRETTY variables.  This is to
 201   # cope with `make' implementation that cannot read very long lines.
 202   $self->{'pretty'} = VAR_PRETTY if $self->{'pretty'} == VAR_ASIS;
 203 }
 204
 205 =item C<$def-E<gt>value>
 206
 207 =item C<$def-E<gt>raw_value>
 208
 209 =item C<$def-E<gt>type>
 210
 211 =item C<$def-E<gt>pretty>
 212
 213 Accessors to the various constituents of a C<VarDef>.  See the
 214 documentation of C<new>'s arguments for a description of these.
 215
 216 =cut
 217
 218 sub value ($)
 219 {
 220   my ($self) = @_;
 221   my $val = $self->raw_value;
 222   # Strip anything past `#'.  `#' characters cannot be escaped
 223   # in Makefiles, so we don't have to be smart.
 224   $val =~ s/#.*$//s;
 225   # Strip backslashes.
 226   $val =~ s/\\$/ /mg;
 227   return $val;
 228 }
 229
 230 sub raw_value ($)
 231 {
 232   my ($self) = @_;
 233   return $self->{'value'};
 234 }
 235
 236 sub type ($)
 237 {
 238   my ($self) = @_;
 239   return $self->{'type'};
 240 }
 241
 242 sub pretty ($)
 243 {
 244   my ($self) = @_;
 245   return $self->{'pretty'};
 246 }
 247
 248 =item C<$def-E<gt>set_owner ($owner, $location)>
 249
 250 Change the owner of a definition.  This usually happens because
 251 the user used C<+=> on an Automake variable, so (s)he now owns
 252 the content.  C<$location> should be an instance of L<Automake::Location>
 253 indicating where the change took place.
 254
 255 =cut
 256
 257 sub set_owner ($$$)
 258 {
 259   my ($self, $owner, $location) = @_;
 260   # We always adjust the location when the owner changes (even for
 261   # `+=' statements).  The risk otherwise is to warn about
 262   # a VAR_MAKEFILE variable and locate it in configure.ac...
 263   $self->{'owner'} = $owner;
 264   $self->{'location'} = $location;
 265 }
 266
 267 =item C<$def-E<gt>set_seen>
 268
 269 =item C<$bool = $def-E<gt>seen>
 270
 271 These function allows Automake to mark (C<set_seen>) variable that
 272 it has examined in some way, and latter check (using C<seen>) for
 273 unused variables.  Unused variables usually indicate typos.
 274
 275 =cut
 276
 277 sub set_seen ($)
 278 {
 279   my ($self) = @_;
 280   $self->{'seen'} = 1;
 281 }
 282
 283 sub seen ($)
 284 {
 285   my ($self) = @_;
 286   return $self->{'seen'};
 287 }
 288
 289 =item C<$str = $def-E<gt>dump>
 290
 291 Format the contents of C<$def> as a human-readable string,
 292 for debugging.
 293
 294 =cut
 295
 296 sub dump ($)
 297 {
 298   my ($self) = @_;
 299   my $owner = $self->owner;
 300
 301   if ($owner == VAR_AUTOMAKE)
 302     {
 303       $owner = 'Automake';
 304     }
 305   elsif ($owner == VAR_CONFIGURE)
 306     {
 307       $owner = 'Configure';
 308     }
 309   elsif ($owner == VAR_MAKEFILE)
 310     {
 311       $owner = 'Makefile';
 312     }
 313   else
 314     {
 315       prog_error ("unexpected owner");
 316     }
 317
 318   my $where = $self->location->dump;
 319   my $comment = $self->comment;
 320   my $value = $self->raw_value;
 321   my $type = $self->type;
 322
 323   return "{
 324       type: $type=
 325       where: $where      comment: $comment
 326       value: $value
 327       owner: $owner
 328     }\n";
 329 }
 330
 331 =back
 332
 333 =head1 SEE ALSO
 334
 335 L<Automake::Variable>, L<Automake::ItemDef>.
 336
 337 =cut
 338
 339 1;
 340
 341 ### Setup "GNU" style for perl-mode and cperl-mode.
 342 ## Local Variables:
 343 ## perl-indent-level: 2
 344 ## perl-continued-statement-offset: 2
 345 ## perl-continued-brace-offset: 0
 346 ## perl-brace-offset: 0
 347 ## perl-brace-imaginary-offset: 0
 348 ## perl-label-offset: -2
 349 ## cperl-indent-level: 2
 350 ## cperl-brace-offset: 0
 351 ## cperl-continued-brace-offset: 0
 352 ## cperl-label-offset: -2
 353 ## cperl-extra-newline-before-brace: t
 354 ## cperl-merge-trailing-else: nil
 355 ## cperl-continued-statement-offset: 2
 356 ## End: