lib/Automake/VarDef.pm

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