This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
b8c9c1bf376ed3ed811001523c960e46d0efe3cc
[perl5.git] / ext / VMS-DCLsym / DCLsym.pm
1 package VMS::DCLsym;
2
3 use Carp;
4 use DynaLoader;
5 use vars qw( @ISA $VERSION );
6 use strict;
7
8 # Package globals
9 @ISA = ( 'DynaLoader' );
10 $VERSION = '1.06';
11 my(%Locsyms) = ( ':ID' => 'LOCAL' );
12 my(%Gblsyms) = ( ':ID' => 'GLOBAL');
13 my $DoCache = 1;
14 my $Cache_set = 0;
15
16
17 #====> OO methods
18
19 sub new {
20   my($pkg,$type) = @_;
21   $type ||= 'LOCAL';
22   $type = 'LOCAL' unless $type eq 'GLOBAL';
23   bless { TYPE => $type }, $pkg;
24 }
25
26 sub DESTROY { }
27
28 sub getsym {
29   my($self,$name) = @_;
30   my($val,$table);
31
32   if (($val,$table) = _getsym($name)) {
33     if ($table eq 'GLOBAL') { $Gblsyms{$name} = $val; }
34     else                    { $Locsyms{$name} = $val; }
35   }
36   wantarray ? ($val,$table) : $val;
37 }
38
39 sub setsym {
40   my($self,$name,$val,$table) = @_;
41
42   $table = $self->{TYPE} unless $table;
43   if (_setsym($name,$val,$table)) {
44     if ($table eq 'GLOBAL') { $Gblsyms{$name} = $val; }
45     else                    { $Locsyms{$name} = $val; }
46     1;
47   }
48   else { 0; }
49 }
50   
51 sub delsym {
52   my($self,$name,$table) = @_;
53
54   $table = $self->{TYPE} unless $table;
55   if (_delsym($name,$table)) {
56     if ($table eq 'GLOBAL') { delete $Gblsyms{$name}; }
57     else                    { delete $Locsyms{$name}; }
58     1;
59   }
60   else { 0; }
61 }
62
63 sub clearcache {
64   my($self,$perm) = @_;
65   my($old);
66
67   $Cache_set = 0;
68   %Locsyms = ( ':ID' => 'LOCAL');
69   %Gblsyms = ( ':ID' => 'GLOBAL');
70   $old = $DoCache;
71   $DoCache = $perm if defined($perm);
72   $old;
73 }
74
75 #====> TIEHASH methods
76
77 sub TIEHASH {
78   shift->new(@_);
79 }
80
81 sub FETCH {
82   my($self,$name) = @_;
83   if    ($name eq ':GLOBAL') { $self->{TYPE} eq 'GLOBAL'; }
84   elsif ($name eq ':LOCAL' ) { $self->{TYPE} eq 'LOCAL';  }
85   else                       { scalar($self->getsym($name)); }
86 }
87
88 sub STORE {
89   my($self,$name,$val) = @_;
90   if    ($name eq ':GLOBAL') { $self->{TYPE} = 'GLOBAL'; }
91   elsif ($name eq ':LOCAL' ) { $self->{TYPE} = 'LOCAL';  }
92   else                       { $self->setsym($name,$val); }
93 }
94
95 sub DELETE {
96   my($self,$name) = @_;
97
98   $self->delsym($name);
99 }
100
101 sub FIRSTKEY {
102   my($self) = @_;
103   my($name,$eqs,$val);
104
105   if (!$DoCache || !$Cache_set) {
106     # We should eventually replace this with a C routine which walks the
107     # CLI symbol table directly.  If I ever get 'hold of an I&DS manual . . .
108     open(P,'Show Symbol * |');
109     while (<P>) {
110       ($name,$eqs,$val) = /^\s+(\S+) (=+) (.+)/
111         or carp "VMS::DCLsym: unparseable line $_";
112       $name =~ s#\*##;
113       $val =~ s/"(.*)"$/$1/ or $val =~ s/^(\S+).*/$1/;
114       if ($eqs eq '==') { $Gblsyms{$name} = $val; }
115       else              { $Locsyms{$name} = $val; }
116     }
117     close P;
118     $Cache_set = 1;
119   }
120   $self ->{IDX} = 0;
121   $self->{CACHE} = $self->{TYPE} eq 'GLOBAL' ? \%Gblsyms : \%Locsyms;
122   while (($name,$val) = each(%{$self->{CACHE}}) and !defined($name)) {
123     if ($self->{CACHE}{':ID'} eq 'GLOBAL') { return undef; }
124     $self->{CACHE} = \%Gblsyms;
125   }
126   $name;
127 }
128
129 sub NEXTKEY {
130   my($self) = @_;
131   my($name,$val);
132
133   while (($name,$val) = each(%{$self->{CACHE}}) and !defined($name)) {
134     if ($self->{CACHE}{':ID'} eq 'GLOBAL') { return undef; }
135     $self->{CACHE} = \%Gblsyms;
136   }
137   $name;
138 }
139
140
141 sub EXISTS { defined($_[0]->FETCH(@_)) ? 1 : 0 }
142
143 sub CLEAR { }
144
145
146 bootstrap VMS::DCLsym;
147
148 1;
149
150 __END__
151
152 =head1 NAME
153
154 VMS::DCLsym - Perl extension to manipulate DCL symbols
155
156 =head1 SYNOPSIS
157
158   tie %allsyms, VMS::DCLsym;
159   tie %cgisyms, VMS::DCLsym, 'GLOBAL';
160
161
162   $handle = new VMS::DCLsym;
163   $value = $handle->getsym($name);
164   $handle->setsym($name, $value, 'GLOBAL')
165       or die "Can't create symbol: $!\n";
166   $handle->delsym($name, 'LOCAL') or die "Can't delete symbol: $!\n";
167   $handle->clearcache();
168
169 =head1 DESCRIPTION
170
171 The VMS::DCLsym extension provides access to DCL symbols using a
172 tied hash interface.  This allows Perl scripts to manipulate symbols in
173 a manner similar to the way in which logical names are manipulated via
174 the built-in C<%ENV> hash.  Alternatively, one can call methods in this
175 package directly to read, create, and delete symbols.
176
177 =head2 Tied hash interface
178
179 This interface lets you treat the DCL symbol table as a Perl associative array,
180 in which the key of each element is the symbol name, and the value of the
181 element is that symbol's value.  Case is not significant in the key string, as
182 DCL converts symbol names to uppercase, but it is significant in the value
183 string.  All of the usual operations on associative arrays are supported. 
184 Reading an element retrieves the current value of the symbol, assigning to it
185 defines a new symbol (or overwrites the old value of an existing symbol), and
186 deleting an element deletes the corresponding symbol.  Setting an element to
187 C<undef>, or C<undef>ing it directly, sets the corresponding symbol to the null
188 string. You may also read the special keys ':GLOBAL' and ':LOCAL' to find out
189 whether a default symbol table has been specified for this hash (see C<table>
190 below), or set either or these keys to specify a default symbol table.
191
192 When you call the C<tie> function to bind an associative array to this package,
193 you may specify as an optional argument the symbol table in which you wish to
194 create and delete symbols.  If the argument is the string 'GLOBAL', then the
195 global symbol table is used; any other string causes the local symbol table to
196 be used.  Note that this argument does not affect attempts to read symbols; if
197 a symbol with the specified name exists in the local symbol table, it is always
198 returned in preference to a symbol by the same name in the global symbol table.
199
200 =head2 Object interface
201
202 Although it's less convenient in some ways than the tied hash interface, you
203 can also call methods directly to manipulate individual symbols.  In some
204 cases, this allows you finer control than using a tied hash aggregate.  The
205 following methods are supported:
206
207 =over 4
208
209 =item new
210
211 This creates a C<VMS::DCLsym> object which can be used as a handle for later
212 method calls.  The single optional argument specifies the symbol table used
213 by default in future method calls, in the same way as the optional argument to
214 C<tie> described above.
215
216 =item getsym
217
218 If called in a scalar context, C<getsym> returns the value of the symbol whose
219 name is given as the argument to the call, or C<undef> if no such symbol
220 exists.  Symbols in the local symbol table are always used in preference to
221 symbols in the global symbol table.  If called in a list context, C<getsym>
222 returns a two-element list, whose first element is the value of the symbol, and
223 whose second element is the string 'GLOBAL' or 'LOCAL', indicating the table
224 from which the symbol's value was read.
225
226 =item setsym
227
228 The first two arguments taken by this method are the name of the symbol and the
229 value which should be assigned to it.  The optional third argument is a string
230 specifying the symbol table to be used; 'GLOBAL' specifies the global symbol
231 table, and any other string specifies the local symbol table.  If this argument
232 is omitted, the default symbol table for the object is used.  C<setsym> returns
233 TRUE if successful, and FALSE otherwise.
234
235 =item delsym
236
237 This method deletes the symbol whose name is given as the first argument.  The
238 optional second argument specifies the symbol table, as described above under
239 C<setsym>.  It returns TRUE if the symbol was successfully deleted, and FALSE
240 if it was not.
241
242 =item clearcache
243
244 Because of the overhead associated with obtaining the list of defined symbols
245 for the tied hash iterator, it is only done once, and the list is reused for
246 subsequent iterations.  Changes to symbols made through this package are
247 recorded, but in the rare event that someone changes the process' symbol table
248 from outside (as is possible using some software from the net), the iterator
249 will be out of sync with the symbol table.  If you expect this to happen, you
250 can reset the cache by calling this method.  In addition, if you pass a FALSE
251 value as the first argument, caching will be disabled.  It can be re-enabled
252 later by calling C<clearcache> again with a TRUE value as the first argument.
253 It returns TRUE or FALSE to indicate whether caching was previously enabled or
254 disabled, respectively.
255
256 This method is a stopgap until we can incorporate code into this extension to
257 traverse the process' symbol table directly, so it may disappear in a future
258 version of this package.
259
260 =back
261
262 =head1 AUTHOR
263
264 Charles Bailey  bailey@newman.upenn.edu
265
266 =head1 VERSION
267
268 1.05  12-Feb-2011
269
270 =head1 BUGS
271
272 The list of symbols for the iterator is assembled by spawning off a
273 subprocess, which can be slow.  Ideally, we should just traverse the
274 process' symbol table directly from C.
275