"Fossies" - the Fresh Open Source Software Archive

Member "automake-1.16.3/lib/Automake/Location.pm" (19 Nov 2020, 5542 Bytes) of package /linux/misc/automake-1.16.3.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Location.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.16.2_vs_1.16.3.

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