File Coverage

=head1 NAME

Automake::VarDef - a class for variable definitions

=head1 SYNOPSIS

  use Automake::VarDef;
  use Automake::Location;

  # Create a VarDef for a definition such as
  # | # any comment
  # | foo = bar # more comment
  # in Makefile.am
  my $loc = new Automake::Location 'Makefile.am:2';
  my $def = new Automake::VarDef ('foo', 'bar # more comment',
                                  '# any comment',
                                  $loc, '', VAR_MAKEFILE, VAR_ASIS);

  # Appending to a definition.
  $def->append ('value to append', 'comment to append');

  # Accessors.
  my $value    = $def->value;  # with trailing `#' comments and
                               # continuation ("\\\n") omitted.
  my $value    = $def->raw_value; # the real value, as passed to new().
  my $comment  = $def->comment;
  my $location = $def->location;
  my $type     = $def->type;
  my $owner    = $def->owner;
  my $pretty   = $def->pretty;

  # Changing owner.
  $def->set_owner (VAR_CONFIGURE,
                   new Automake::Location 'configure.ac:15');

  # Marking examined definitions.
  $def->set_seen;
  my $seen_p = $def->seen;

  # Printing a variable for debugging.
  print STDERR $def->dump;

=head1 DESCRIPTION

This class gathers data related to one Makefile-variable definition.

=head2 Constants

=over 4

=item C<VAR_AUTOMAKE>, C<VAR_CONFIGURE>, C<VAR_MAKEFILE>

Possible owners for variables.  A variable can be defined
by Automake, in F<configure.ac> (using C<AC_SUBST>), or in
the user's F<Makefile.am>.

=cut

=item C<VAR_ASIS>, C<VAR_PRETTY>, C<VAR_SILENT>, C<VAR_SORTED>

Possible print styles.  C<VAR_ASIS> variables should be output as-is.
C<VAR_PRETTY> variables are wrapped on multiple lines if they cannot
fit on one.  C<VAR_SILENT> variables are not output at all.  Finally,
C<VAR_SORTED> variables should be sorted and then handled as
C<VAR_PRETTY> variables.

C<VAR_SILENT> variables can also be overridden silently (unlike the
other kinds of variables whose overriding may sometimes produce
warnings).

=cut

=head2 Methods

C<VarDef> defines the following methods in addition to those inherited
from L<Automake::ItemDef>.

=over 4

=item C<my $def = new Automake::VarDef ($varname, $value, $comment, $location, $type, $owner, $pretty)>

Create a new Makefile-variable definition.  C<$varname> is the name of
the variable being defined and C<$value> its value.

C<$comment> is any comment preceding the definition.  (Because
Automake reorders variable definitions in the output, it also tries to
carry comments around.)

C<$location> is the place where the definition occurred, it should be
an instance of L<Automake::Location>.

C<$type> should be C<''> for definitions made with C<=>, and C<':'>
for those made with C<:=>.

C<$owner> specifies who owns the variables, it can be one of
C<VAR_AUTOMAKE>, C<VAR_CONFIGURE>, or C<VAR_MAKEFILE> (see these
definitions).

Finally, C<$pretty> tells how the variable should be output, and can
be one of C<VAR_ASIS>, C<VAR_PRETTY>, or C<VAR_SILENT>, or
C<VAR_SORTED> (see these definitions).

=cut

=item C<$def-E<gt>append ($value, $comment)>

Append C<$value> and <$comment> to the existing value and comment of
C<$def>.  This is normally called on C<+=> definitions.

=cut

=item C<$def-E<gt>value>

=item C<$def-E<gt>raw_value>

=item C<$def-E<gt>type>

=item C<$def-E<gt>pretty>

Accessors to the various constituents of a C<VarDef>.  See the
documentation of C<new>'s arguments for a description of these.

=cut

=item C<$def-E<gt>set_owner ($owner, $location)>

Change the owner of a definition.  This usually happens because
the user used C<+=> on an Automake variable, so (s)he now owns
the content.  C<$location> should be an instance of L<Automake::Location>
indicating where the change took place.

=cut

=item C<$def-E<gt>set_seen>

=item C<$bool = $def-E<gt>seen>

These function allows Automake to mark (C<set_seen>) variable that
it has examined in some way, and latter check (using C<seen>) for
unused variables.  Unused variables usually indicate typos.

=cut

=item C<$str = $def-E<gt>dump>

Format the contents of C<$def> as a human-readable string,
for debugging.

=cut

=head1 SEE ALSO

L<Automake::Variable>, L<Automake::ItemDef>.

=cut