File Coverage

=head1 NAME

Automake::Location - a class for location tracking, with a stack of contexts

=head1 SYNOPSIS

  use Automake::Location;

  # Create a new Location object
  my $where = new Automake::Location "foo.c:13";

  # Change the location
  $where->set ("foo.c:14");

  # Get the location (without context).
  # Here this should print "foo.c:14"
  print $where->get, "\n";

  # Push a context, and change the location
  $where->push_context ("included from here");
  $where->set ("bar.h:1");

  # Print the location and the stack of context (for debugging)
  print $where->dump;
  # This should display
  #   bar.h:1:
  #   foo.c:14:   included from here

  # Get the contexts (list of [$location_string, $description])
  for my $pair (reverse $where->contexts)
    {
      my ($loc, $descr) = @{$pair};
      ...
    }

  # Pop a context, and reset the location to the previous context.
  $where->pop_context;

  # Clone a Location.  Use this when storing the state of a location
  # that would otherwise be modified.
  my $where_copy = $where->clone;

  # Serialize a Location object (for passing through a thread queue,
  # for example)
  my @array = $where->serialize ();

  # De-serialize: recreate a Location object from a queue.
  my $where = new Automake::Location::deserialize ($queue);

=head1 DESCRIPTION

C<Location> objects are used to keep track of locations in Automake,
and used to produce diagnostics.

A C<Location> object is made of two parts: a location string, and
a stack of contexts.

For instance if C<VAR> is defined at line 1 in F<bar.h> which was
included at line 14 in F<foo.c>, then the location string should be
C<"bar.h:10"> and the context should be the pair (C<"foo.c:14">,
C<"included from here">).

Section I<SYNOPSIS> shows how to setup such a C<Location>, and access
the location string or the stack of contexts.

You can pass a C<Location> to C<Automake::Channels::msg>.

=cut

=head2 Methods

=over

=item C<$where = new Automake::Location ([$position])>

Create and return a new Location object.

=cut

=item C<$location-E<gt>set ($position)>

Change the location to be C<$position>.

=cut

=item C<$location-E<gt>get>

Get the location (without context).

=cut

=item C<$location-E<gt>push_context ($context)>

Push a context to the location.

=cut

=item C<$where = $location-E<gt>pop_context ($context)>

Pop a context, and reset the location to the previous context.

=cut

=item C<@contexts = $location-E<gt>get_contexts>

Return the array of contexts.

=cut

=item C<$location = $location-E<gt>clone>

Clone a Location.  Use this when storing the state of a location
that would otherwise be modified.

=cut

=item C<$res = $location-E<gt>dump>

Print the location and the stack of context (for debugging).

=cut

=item C<@array = $location-E<gt>serialize>

Serialize a Location object (for passing through a thread queue,
for example).

=cut

=item C<new Automake::Location::deserialize ($queue)>

De-serialize: recreate a Location object from a queue.

=cut

=head1 SEE ALSO

L<Automake::Channels>

=head1 HISTORY

Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.

=cut