-
Notifications
You must be signed in to change notification settings - Fork 1
/
which_routine.pro
266 lines (237 loc) · 9.58 KB
/
which_routine.pro
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
;+
; Support function used in which_routine.
;
; LOOKS FOR A MATCH BETWEEN ROUTINE INFORMATION AND
; AN IDL MODULE NAME...
; CLEVERLY, COMPILATION OF WHICH_ROUTINE GUARANTEES THAT THERE WILL ALWAYS
; BE AT LEAST ONE PROCEDURE (WHICH_ROUTINE) AND FUNCTION
; (WHICH_FIND_ROUTINE)...
;
; @param proname {in}{required}{type=string} The routine to look for.
; @keyword _REF_EXTRA {in}{optional}{type=extra keywords} Passed to
; IDL routine_info.
;
; @hidden
;-
function which_find_routine, proname, _REF_EXTRA=_extra
compile_opt idl2, hidden
return, strmatch(routine_info(_EXTRA=_extra), proname, /FOLD_CASE)
end; which_find_routine
;+
; Search for any file in the IDL !path that contains the
; user-supplied IDL routine (procedure or function) name.
;
; <p> If the returned string has non-zero length, the routine has
; been compiled (resolved in IDL lingo) otherwise, it has not.
; Any unresolved files that contain this routine are also returned
; in the unresolved keyword value. If both the returned string and
; the resolved keyword values have zero length, then the routine could
; not be found in the !path.
;
; <p> This is the code behind <a href="which.html">which</a>. It was
; originally all in which but was split so that other code could make
; use of this functionality (e.g. driving a browser to the appropriate
; reference manual location, finding and summarizing the help
; information for a routine).
;
; <p>
; <b>Restrictions:</b>
; The IDL !path is searched for file names that are simply the
; module (in IDL documentation, "module" and "routine" are used
; interchangeably) name with a ".pro" suffix appended to them.
; A module stored inside a file whose name is different than the
; module name (followed by a ".pro") will not be found UNLESS
; that module happens to be the currently-resolved module!
; E.g., if the module "pro test_proc" lives in a file named
; "dumb_name.pro", then it will not be found:
;
; <pre>
; IDL> a=which_routine('test_proc',unresolved=unresolved)
; IDL> print, strlen(a), strlen(unresolved)
; 0 0
; </pre>
;
; unless it happens to be resolved:
;
; <pre>
; IDL> .run dumb_name
; % Compiled module: TEST_PROC.
; IDL> print,which_routine('test_proc')
; /hvc/robishaw/dumb_name.pro
; </pre>
;
; However, this is terrible programming style and sooner or
; later, if you hide generically-named modules in
; inappropriately-named files, bad things will (deservedly)
; happen to you.
;
; The routine further assumes that a file named "dumb_name.pro"
; actually contains a module named "dumb_name"! If it doesn't,
; then you are a bad programmer and should seek professional
; counseling.
;
; <p>
; <b>Notes:</b>
; First, all currently-compiled procedures and functions are searched.
; Then the remainder of the IDL !path is searched.
;
; <p>
; <b>MODIFICATION HISTORY:</b>
; <ul>
; <li>30 May 2003 Written by Tim Robishaw, Berkeley
; <li>17 Feb 2004 Fixed oddity where user tries to call a function as
; if it were a procedure, thus listing the module in both
; the Compiled Functions and Compiled Procedures
; list.
; <li>14 Jun 2005 Split code into which_routine function for use
; elsewhere in GBTIDL and which. Reformatted
; comments for use with idldoc.
; </ul>
;
; @param name {in}{required}{type=string} The procedure or function
; name to search for.
;
; @keyword unresolved {out}{type=string} The paths to files that
; likely contain this name but are not the currently compiled
; version containing name.
;
; @examples
; You haven't yet resolved (compiled) the routine (module)
; DEFROI. Let's look for it anyway:
;
; <pre>
; IDL> a=which_routine('defroi',unresolved=unresolved)
; IDL> print,strlen(a)
; 0
; IDL> print, unresolved
; /usr/local/rsi/idl/lib/defroi.pro
; </pre>
;
; For some reason you have two modules with the same name.
; (This can occur in libraries of IDL routines such as the
; Goddard IDL Astronomy User's Library; an updated version of a
; routine is stored in a special directory while the old version
; is stored in its original directory.) Let's see which version
; of the module ADSTRING we are currently using:
;
; <pre>
; IDL> a=which_routine('adstring.pro',unresolved=unresolved)
; IDL> print,a
; /hvc/robishaw/idl/goddard/pro/v5.4+/adstring.pro
; IDL> print,unresolved
; /hvc/robishaw/idl/goddard/pro/astro/adstring.pro
; </pre>
;
; @returns String containing the file name from which the resolved
; (compiled) version of name was found. This is a zero-length
; string if name has not been resolved (compiled) yet.
;
; @version $Id: which_routine.pro,v 1.4 2006/05/13 04:34:01 bgarwood Exp $
;-
function which_routine, name, unresolved=unresolved
on_error, 2
resolve_routine, 'strsplit', /IS_FUN, /NO_RECOMPILE
proname = name
; WHAT IS THE PATH SEPARATOR ON THIS OS...
psep = path_sep()
; IF .PRO SUFFIX INCLUDED, DROP IT...
proname = strtrim(proname,2)
if strmatch(proname,'*.pro', /FOLD_CASE) $
then proname = strmid(proname,0,strlen(proname)-4)
; SEARCH THE CURRENTLY-COMPILED PROCEDURES AND FUNCTIONS FIRST...
pindx = where(which_find_routine(proname),presolved)
findx = where(which_find_routine(proname,/FUNCTIONS),fresolved)
; IF PROCEDURE OR FUNCTION WAS FOUND, IS IT UNRESOLVED...
punresolved = total(which_find_routine(proname,/UNRESOLVED))
funresolved = total(which_find_routine(proname,/UNRESOLVED,/FUNCTIONS))
; WE NEED TO HANDLE BIZARRO CASES OF HAVING A FUNCTION THAT THE USER TRIES
; TO CALL AS A PROCEDURE, THUS TRICKING IDL INTO THINKING IT HAS ON ITS
; HANDS A RESOLVED FUNCTION, A RESOLVED PROCEDURE AND AN UNRESOLVED PROCEDURE...
if (presolved AND punresolved AND fresolved) then begin
presolved = 0 & punresolved = 0
endif
; AND WHILE WE'RE AT IT, WE TAKE CARE OF THE CONVERSE... A PROCEDURE
; THAT HAS BEEN CALLED AS A FUNCTION BEFORE COMPILATION...
if (fresolved AND funresolved AND presolved) then begin
fresolved = 0 & funresolved = 0
endif
result = ''
unresolved=''
; THE FULL PATH TO THE RESULTING RESOLVED ROUTINE...
if (presolved and not punresolved) OR $
(fresolved and not funresolved) then begin
; THE PROCEDURE OR FUNCTION WAS FOUND...
result = (presolved AND fresolved) ? $
[(routine_info(/SOURCE))[pindx].PATH, $
(routine_info(/SOURCE,/FUNCTIONS))[findx].PATH] : $
(presolved ? (routine_info(/SOURCE))[pindx].PATH : $
(routine_info(/SOURCE,/FUNCTIONS))[findx].PATH)
; result has two elements if procedure AND function found
endif
; EXTRACT THE !PATH INTO A STRING ARRAY...
path = strsplit(!path, path_sep(/SEARCH_PATH), /EXTRACT)
; GET RID OF "." IF USER INCLUDES THIS IN PATH...
path = path[where(path ne '.')]
; WHAT IS THE CURRENT DIRECTORY
cd, CURRENT=current
; GET TARGET OF ANY SYMBOLIC LINKS IN THE IDL !PATH...
path_syml = path
for i = 0, N_elements(path_syml)-1 do begin
d = path_syml[i]
if not file_test(d,/DIRECTORY) then continue
cd, d & cd, CURRENT=dnew
if not strmatch(d,dnew) then path_syml[i] = dnew
endfor
; REMOVE ANY DUPLICATE PATH ELEMENTS, KEEPING ON THE ONE CLOSEST TO THE
; TOP...
rev_path_syml = reverse(path_syml)
rind = reverse(lindgen(N_elements(path_syml)))
u = uniq(rev_path_syml,sort(rev_path_syml))
path_syml = reverse(path_syml[rind[u[sort(u)]]])
path = reverse(path[rind[u[sort(u)]]])
; IF THE CURRENT DIRECTORY IS ANYWHERE IN THE PATH, THEN MOVE IT TO THE
; FRONT OF THE PATH, SINCE THE CURRENT PATH WILL BE SEARCHED FIRST BY .RUN,
; .COMPILE, .RNEW, ETC...
cpath = where(strmatch(path_syml,current) eq 1,n_cpath,COMPLEMENT=rpath)
path_syml = [current,path_syml[rpath]]
path = [(n_cpath gt 0) ? path[cpath] : current, path[rpath]]
; ADD THE FILENAME TO EACH PATH DIRECTORY...
filenames = path + psep + proname + '.pro'
; DOES ANY SUCH FILE EXIST IN THE CURRENT PATH...
; THIS WAS WRITTEN BACK IN V5.4, BEFORE FILE_SEARCH, LEAVE IT ALONE...
file_exists = where(file_test(filenames), N_exists)
; IF THERE IS NO SUCH FILE THEN SPLIT...
if (N_exists eq 0) then begin
cd, current
return, result
endif
; GET TARGET OF A SYMBOLIC LINK IN THE PATH OF THE RESOLVED ROUTINE...
; ALSO HANDLES INDIRECT MOUNT POINTS ON LINUX SYSTEMS...
resolved_routine = result
for i = 0, N_elements(resolved_routine)-1 do begin
; GET THE PATH TO THE RESOLVED ROUTINE...
p = strsplit(resolved_routine[i],psep,COUNT=np,/EXTRACT)
d = psep+((np gt 1) ? strjoin(p[0:np-2],psep,/SINGLE) : '')
cd, d & cd, CURRENT=dnew
if not strmatch(d,dnew) $
then resolved_routine = [resolved_routine,dnew+psep+p[np-1]]
endfor
cd, current
; PULL OUT ALL THE FILES THAT EXIST...
filenames = filenames[file_exists]
filenames_syml = path_syml[file_exists] + psep + proname + '.pro'
; TAKE RESOLVED ROUTINE OUT OF THE LIST...
if (n_elements(resolved_routine) gt 1 or strlen(resolved_routine[0]) gt 0) then begin
; GET THE INDICES OF THE UNRESOLVED ROUTINES...
find_resolved = strmatch(filenames_syml,resolved_routine[0])
for i = 1, N_elements(resolved_routine)-1 do $
find_resolved = find_resolved OR $
strmatch(filenames_syml,resolved_routine[i])
file_exists = where(find_resolved eq 0, N_exists)
; WAS THE RESOLVED ROUTINE THE ONLY ONE...
if (N_exists eq 0) then return, result
filenames = filenames[file_exists]
endif
unresolved = filenames
return, result
end