"Fossies" - the Fresh Open Source Software Archive

Member "automake-1.16.3/lib/Automake/VarDef.pm" (19 Nov 2020, 8566 Bytes) of package /linux/misc/automake-1.16.3.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "VarDef.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.16.2_vs_1.16.3.

    1 # Copyright (C) 2003-2020 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/ ?#.*//;
  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;