lib/Automake/Location.pm

   1 # Copyright (C) 2002, 2003, 2008, 2009  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 to 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 =head2 Methods
  88
  89 =over
  90
  91 =item C<$where = new Automake::Location ([$position])>
  92
  93 Create and return a new Location object.
  94
  95 =cut
  96
  97 sub new ($;$)
  98 {
  99   my ($class, $position) = @_;
 100   my $self = {
 101     position => $position,
 102     contexts => [],
 103   };
 104   bless $self, $class;
 105   return $self;
 106 }
 107
 108 =item C<$location-E<gt>set ($position)>
 109
 110 Change the location to be C<$position>.
 111
 112 =cut
 113
 114 sub set ($$)
 115 {
 116   my ($self, $position) = @_;
 117   $self->{'position'} = $position;
 118 }
 119
 120 =item C<$location-E<gt>get>
 121
 122 Get the location (without context).
 123
 124 =cut
 125
 126 sub get ($)
 127 {
 128   my ($self) = @_;
 129   return $self->{'position'};
 130 }
 131
 132 =item C<$location-E<gt>push_context ($context)>
 133
 134 Push a context to the location.
 135
 136 =cut
 137
 138 sub push_context ($$)
 139 {
 140   my ($self, $context) = @_;
 141   push @{$self->{'contexts'}}, [$self->get, $context];
 142   $self->set (undef);
 143 }
 144
 145 =item C<$where = $location-E<gt>pop_context ($context)>
 146
 147 Pop a context, and reset the location to the previous context.
 148
 149 =cut
 150
 151 sub pop_context ($)
 152 {
 153   my ($self) = @_;
 154   my $pair = pop @{$self->{'contexts'}};
 155   $self->set ($pair->[0]);
 156   return @{$pair};
 157 }
 158
 159 =item C<@contexts = $location-E<gt>get_contexts>
 160
 161 Return the array of contexts.
 162
 163 =cut
 164
 165 sub get_contexts ($)
 166 {
 167   my ($self) = @_;
 168   return @{$self->{'contexts'}};
 169 }
 170
 171 =item C<$location = $location-E<gt>clone>
 172
 173 Clone a Location.  Use this when storing the state of a location
 174 that would otherwise be modified.
 175
 176 =cut
 177
 178 sub clone ($)
 179 {
 180   my ($self) = @_;
 181   my $other = new Automake::Location ($self->get);
 182   my @contexts = $self->get_contexts;
 183   for my $pair (@contexts)
 184     {
 185       push @{$other->{'contexts'}}, [@{$pair}];
 186     }
 187   return $other;
 188 }
 189
 190 =item C<$res = $location-E<gt>dump>
 191
 192 Print the location and the stack of context (for debugging).
 193
 194 =cut
 195
 196 sub dump ($)
 197 {
 198   my ($self) = @_;
 199   my $res = ($self->get || 'INTERNAL') . ":\n";
 200   for my $pair (reverse $self->get_contexts)
 201     {
 202       $res .= $pair->[0] || 'INTERNAL';
 203       $res .= ": $pair->[1]\n";
 204     }
 205   return $res;
 206 }
 207
 208 =item C<@array = $location-E<gt>serialize>
 209
 210 Serialize a Location object (for passing through a thread queue,
 211 for example).
 212
 213 =cut
 214
 215 sub serialize ($)
 216 {
 217   my ($self) = @_;
 218   my @serial = ();
 219   push @serial, $self->get;
 220   my @contexts = $self->get_contexts;
 221   for my $pair (@contexts)
 222     {
 223       push @serial, @{$pair};
 224     }
 225   push @serial, undef;
 226   return @serial;
 227 }
 228
 229 =item C<new Automake::Location::deserialize ($queue)>
 230
 231 De-serialize: recreate a Location object from a queue.
 232
 233 =cut
 234
 235 sub deserialize ($)
 236 {
 237   my ($queue) = @_;
 238   my $position = $queue->dequeue ();
 239   my $self = new Automake::Location $position;
 240   while (my $position = $queue->dequeue ())
 241     {
 242       my $context = $queue->dequeue ();
 243       push @{$self->{'contexts'}}, [$position, $context];
 244     }
 245   return $self;
 246 }
 247
 248 =back
 249
 250 =head1 SEE ALSO
 251
 252 L<Automake::Channels>
 253
 254 =head1 HISTORY
 255
 256 Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.
 257
 258 =cut
 259
 260 1;
 261
 262 ### Setup "GNU" style for perl-mode and cperl-mode.
 263 ## Local Variables:
 264 ## perl-indent-level: 2
 265 ## perl-continued-statement-offset: 2
 266 ## perl-continued-brace-offset: 0
 267 ## perl-brace-offset: 0
 268 ## perl-brace-imaginary-offset: 0
 269 ## perl-label-offset: -2
 270 ## cperl-indent-level: 2
 271 ## cperl-brace-offset: 0
 272 ## cperl-continued-brace-offset: 0
 273 ## cperl-label-offset: -2
 274 ## cperl-extra-newline-before-brace: t
 275 ## cperl-merge-trailing-else: nil
 276 ## cperl-continued-statement-offset: 2
 277 ## End: