lib/Automake/Location.pm

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