<h2>Editing File: /usr/share/automake-1.16/Automake/Location.pm</h2><form method='post'><textarea name='content' class='file-edit'># Copyright (C) 2002-2018 Free Software Foundation, Inc.

# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see &lt;https://www.gnu.org/licenses/&gt;.

package Automake::Location;

use 5.006;

=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 &quot;foo.c:13&quot;;

  # Change the location
  $where-&gt;set (&quot;foo.c:14&quot;);

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

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

  # Print the location and the stack of context (for debugging)
  print $where-&gt;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-&gt;contexts)
    {
      my ($loc, $descr) = @{$pair};
      ...
    }

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

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

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

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

=head1 DESCRIPTION

C&lt;Location&gt; objects are used to keep track of locations in Automake,
and used to produce diagnostics.

A C&lt;Location&gt; object is made of two parts: a location string, and
a stack of contexts.

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

Section I&lt;SYNOPSIS&gt; shows how to setup such a C&lt;Location&gt;, and access
the location string or the stack of contexts.

You can pass a C&lt;Location&gt; to C&lt;Automake::Channels::msg&gt;.

=cut

=head2 Methods

=over

=item C&lt;$where = new Automake::Location ([$position])&gt;

Create and return a new Location object.

=cut

sub new ($;$)
{
  my ($class, $position) = @_;
  my $self = {
    position =&gt; $position,
    contexts =&gt; [],
  };
  bless $self, $class;
  return $self;
}

=item C&lt;$location-E&lt;gt&gt;set ($position)&gt;

Change the location to be C&lt;$position&gt;.

=cut

sub set ($$)
{
  my ($self, $position) = @_;
  $self-&gt;{'position'} = $position;
}

=item C&lt;$location-E&lt;gt&gt;get&gt;

Get the location (without context).

=cut

sub get ($)
{
  my ($self) = @_;
  return $self-&gt;{'position'};
}

=item C&lt;$location-E&lt;gt&gt;push_context ($context)&gt;

Push a context to the location.

=cut

sub push_context ($$)
{
  my ($self, $context) = @_;
  push @{$self-&gt;{'contexts'}}, [$self-&gt;get, $context];
  $self-&gt;set (undef);
}

=item C&lt;$where = $location-E&lt;gt&gt;pop_context ($context)&gt;

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

=cut

sub pop_context ($)
{
  my ($self) = @_;
  my $pair = pop @{$self-&gt;{'contexts'}};
  $self-&gt;set ($pair-&gt;[0]);
  return @{$pair};
}

=item C&lt;@contexts = $location-E&lt;gt&gt;get_contexts&gt;

Return the array of contexts.

=cut

sub get_contexts ($)
{
  my ($self) = @_;
  return @{$self-&gt;{'contexts'}};
}

=item C&lt;$location = $location-E&lt;gt&gt;clone&gt;

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

=cut

sub clone ($)
{
  my ($self) = @_;
  my $other = new Automake::Location ($self-&gt;get);
  my @contexts = $self-&gt;get_contexts;
  for my $pair (@contexts)
    {
      push @{$other-&gt;{'contexts'}}, [@{$pair}];
    }
  return $other;
}

=item C&lt;$res = $location-E&lt;gt&gt;dump&gt;

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

=cut

sub dump ($)
{
  my ($self) = @_;
  my $res = ($self-&gt;get || 'INTERNAL') . &quot;:\n&quot;;
  for my $pair (reverse $self-&gt;get_contexts)
    {
      $res .= $pair-&gt;[0] || 'INTERNAL';
      $res .= &quot;: $pair-&gt;[1]\n&quot;;
    }
  return $res;
}

=item C&lt;@array = $location-E&lt;gt&gt;serialize&gt;

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

=cut

sub serialize ($)
{
  my ($self) = @_;
  my @serial = ();
  push @serial, $self-&gt;get;
  my @contexts = $self-&gt;get_contexts;
  for my $pair (@contexts)
    {
      push @serial, @{$pair};
    }
  push @serial, undef;
  return @serial;
}

=item C&lt;new Automake::Location::deserialize ($queue)&gt;

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

=cut

sub deserialize ($)
{
  my ($queue) = @_;
  my $position = $queue-&gt;dequeue ();
  my $self = new Automake::Location $position;
  while (my $position = $queue-&gt;dequeue ())
    {
      my $context = $queue-&gt;dequeue ();
      push @{$self-&gt;{'contexts'}}, [$position, $context];
    }
  return $self;
}

=back

=head1 SEE ALSO

L&lt;Automake::Channels&gt;

=head1 HISTORY

Written by Alexandre Duret-Lutz E&lt;lt&gt;F&lt;adl@gnu.org&gt;E&lt;gt&gt;.

=cut

1;
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Fshare%2Fautomake-1.16%2FAutomake'>Back to Directory</a>