lib/Automake/Location.pm

   1 # Copyright (C) 2002, 2003  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 3, 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 =head1 DESCRIPTION
  61
  62 C<Location> objects are used to keep track of locations in Automake,
  63 and used to produce diagnostics.
  64
  65 A C<Location> object is made of two parts: a location string, and
  66 a stack of contexts.
  67
  68 For instance if C<VAR> is defined at line 1 in F<bar.h> which was
  69 included at line 14 in F<foo.c>, then the location string should be
  70 C<"bar.h:10"> and the context should be the pair (C<"foo.c:14">,
  71 C<"included from here">).
  72
  73 Section I<SYNOPSIS> shows how to setup such a C<Location>, and access
  74 the location string or the stack of contexts.
  75
  76 You can pass a C<Location> to C<Automake::Channels::msg>.
  77
  78 =cut
  79
  80 sub new ($;$)
  81 {
  82   my ($class, $position) = @_;
  83   my $self = {
  84     position => $position,
  85     contexts => [],
  86   };
  87   bless $self, $class;
  88   return $self;
  89 }
  90
  91 sub set ($$)
  92 {
  93   my ($self, $position) = @_;
  94   $self->{'position'} = $position;
  95 }
  96
  97 sub get ($)
  98 {
  99   my ($self) = @_;
 100   return $self->{'position'};
 101 }
 102
 103 sub push_context ($$)
 104 {
 105   my ($self, $context) = @_;
 106   push @{$self->{'contexts'}}, [$self->get, $context];
 107   $self->set (undef);
 108 }
 109
 110 sub pop_context ($)
 111 {
 112   my ($self) = @_;
 113   my $pair = pop @{$self->{'contexts'}};
 114   $self->set ($pair->[0]);
 115   return @{$pair};
 116 }
 117
 118 sub get_contexts ($)
 119 {
 120   my ($self) = @_;
 121   return @{$self->{'contexts'}};
 122 }
 123
 124 sub clone ($)
 125 {
 126   my ($self) = @_;
 127   my $other = new Automake::Location ($self->get);
 128   my @contexts = $self->get_contexts;
 129   for my $pair (@contexts)
 130     {
 131       push @{$other->{'contexts'}}, [@{$pair}];
 132     }
 133   return $other;
 134 }
 135
 136 sub dump ($)
 137 {
 138   my ($self) = @_;
 139   my $res = ($self->get || 'INTERNAL') . ":\n";
 140   for my $pair (reverse $self->get_contexts)
 141     {
 142       $res .= $pair->[0] || 'INTERNAL';
 143       $res .= ": $pair->[1]\n";
 144     }
 145   return $res;
 146 }
 147
 148 =head1 SEE ALSO
 149
 150 L<Automake::Channels>
 151
 152 =head1 HISTORY
 153
 154 Written by Alexandre Duret-Lutz E<lt>F<adl@gnu.org>E<gt>.
 155
 156 =cut
 157
 158 1;
 159
 160 ### Setup "GNU" style for perl-mode and cperl-mode.
 161 ## Local Variables:
 162 ## perl-indent-level: 2
 163 ## perl-continued-statement-offset: 2
 164 ## perl-continued-brace-offset: 0
 165 ## perl-brace-offset: 0
 166 ## perl-brace-imaginary-offset: 0
 167 ## perl-label-offset: -2
 168 ## cperl-indent-level: 2
 169 ## cperl-brace-offset: 0
 170 ## cperl-continued-brace-offset: 0
 171 ## cperl-label-offset: -2
 172 ## cperl-extra-newline-before-brace: t
 173 ## cperl-merge-trailing-else: nil
 174 ## cperl-continued-statement-offset: 2
 175 ## End: