"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;