lib/Automake/Location.pm

   1 # Copyright (C) 2002, 2003, 2008  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 <http://www.gnu.org/licenses/>.
  15
  16 package Automake::Location;
  17
  18 =head1 NAME
  19
  20 Automake::Location - a class for location tracking, with a stack of contexts
  21
  22 =head1 SYNOPSIS
  23
  24   use Automake::Location;
  25
  26   # Create a new Location object
  27   my $where = new Automake::Location "foo.c:13";
  28
  29   # Change the location
  30   $where->set ("foo.c:14");
  31
  32   # Get the location (without context).
  33   # Here this should print "foo.c:14"
  34   print $where->get, "\n";
  35
  36   # Push a context, and change the location
  37   $where->push_context ("included from here");
  38   $where->set ("bar.h:1");
  39
  40   # Print the location and the stack of context (for debugging)
  41   print $where->dump;
  42   # This should display
  43   #   bar.h:1:
  44   #   foo.c:14:   included from here
  45
  46   # Get the contexts (list of [$location_string, $description])
  47   for my $pair (reverse $where->contexts)
  48     {
  49       my ($loc, $descr) = @{$pair};
  50       ...
  51     }
  52
  53   # Pop a context, and reset the location from the previous context.
  54   $where->pop_context;
  55
  56   # Clone a Location.  Use this when storing the state of a location
  57   # that would otherwise be modified.
  58   my $where_copy = $where->clone;
  59
  60   # Serialize a Location object (for passing through a thread queue,
  61   # for example)
  62   my @array = $where->serialize ();
  63
  64   # De-serialize: recreate a Location object from a queue.
  65   my $where = new Automake::Location::deserialize ($queue);
  66
  67 =head1 DESCRIPTION
  68
  69 C<Location> objects are used to keep track of locations in Automake,
  70 and used to produce diagnostics.
  71
  72 A C<Location> object is made of two parts: a location string, and
  73 a stack of contexts.
  74
  75 For instance if C<VAR> is defined at line 1 in F<bar.h> which was
  76 included at line 14 in F<foo.c>, then the location string should be
  77 C<"bar.h:10"> and the context should be the pair (C<"foo.c:14">,
  78 C<"included from here">).
  79
  80 Section I<SYNOPSIS> shows how to setup such a C<Location>, and access
  81 the location string or the stack of contexts.
  82
  83 You can pass a C<Location> to C<Automake::Channels::msg>.
  84
  85 =cut
  86
  87 sub new ($;$)
  88 {
  89   my ($class, $position) = @_;
  90   my $self = {
  91     position => $position,
  92     contexts => [],
  93   };
  94   bless $self, $class;
  95   return $self;
  96 }
  97
  98 sub set ($$)
  99 {
 100   my ($self, $position) = @_;
 101   $self->{'position'} = $position;
 102 }
 103
 104 sub get ($)
 105 {
 106   my ($self) = @_;
 107   return $self->{'position'};
 108 }
 109
 110 sub push_context ($$)
 111 {
 112   my ($self, $context) = @_;
 113   push @{$self->{'contexts'}}, [$self->get, $context];
 114   $self->set (undef);
 115 }
 116
 117 sub pop_context ($)
 118 {
 119   my ($self) = @_;
 120   my $pair = pop @{$self->{'contexts'}};
 121   $self->set ($pair->[0]);
 122   return @{$pair};
 123 }
 124
 125 sub get_contexts ($)
 126 {
 127   my ($self) = @_;
 128   return @{$self->{'contexts'}};
 129 }
 130
 131 sub clone ($)
 132 {
 133   my ($self) = @_;
 134   my $other = new Automake::Location ($self->get);
 135   my @contexts = $self->get_contexts;
 136   for my $pair (@contexts)
 137     {
 138       push @{$other->{'contexts'}}, [@{$pair}];
 139     }
 140   return $other;
 141 }
 142
 143 sub dump ($)
 144 {
 145   my ($self) = @_;
 146   my $res = ($self->get || 'INTERNAL') . ":\n";
 147   for my $pair (reverse $self->get_contexts)
 148     {
 149       $res .= $pair->[0] || 'INTERNAL';
 150       $res .= ": $pair->[1]\n";
 151     }
 152   return $res;
 153 }
 154
 155 sub serialize ($)
 156 {
 157   my ($self) = @_;
 158   my @serial = ();
 159   push @serial, $self->get;
 160   my @contexts = $self->get_contexts;
 161   for my $pair (@contexts)
 162     {
 163       push @serial, @{$pair};
 164     }
 165   push @serial, undef;
 166   return @serial;
 167 }
 168
 169 sub deserialize ($)
 170 {
 171   my ($queue) = @_;
 172   my $position = $queue->dequeue ();
 173   my $self = new Automake::Location $position;
 174   while (my $position = $queue->dequeue ())
 175     {
 176       my $context = $queue->dequeue ();
 177       push @{$self->{'contexts'}}, [$position, $context];
 178     }
 179   return $self;
 180 }
 181
 182 =head1 SEE ALSO
 183
 184 L<Automake::Channels>
 185
 186 =head1 HISTORY
 187
 188 Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.
 189
 190 =cut
 191
 192 1;
 193
 194 ### Setup "GNU" style for perl-mode and cperl-mode.
 195 ## Local Variables:
 196 ## perl-indent-level: 2
 197 ## perl-continued-statement-offset: 2
 198 ## perl-continued-brace-offset: 0
 199 ## perl-brace-offset: 0
 200 ## perl-brace-imaginary-offset: 0
 201 ## perl-label-offset: -2
 202 ## cperl-indent-level: 2
 203 ## cperl-brace-offset: 0
 204 ## cperl-continued-brace-offset: 0
 205 ## cperl-label-offset: -2
 206 ## cperl-extra-newline-before-brace: t
 207 ## cperl-merge-trailing-else: nil
 208 ## cperl-continued-statement-offset: 2
 209 ## End: