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