43
44 void ppc_file_start(PcaPathConf *ppc, int start_index);
45
46
47 void ppc_literal_escapes(PcaPathConf *ppc, int literal);
48
49
50 DESCRIPTION
51 The PathCache object is part of the libtecla(3LIB) library. PathCache
52 objects allow an application to search for files in any colon separated
53 list of directories, such as the UNIX execution PATH environment
54 variable. Files in absolute directories are cached in a PathCache
55 object, whereas relative directories are scanned as needed. Using a
56 PathCache object, you can look up the full pathname of a simple
57 filename, or you can obtain a list of the possible completions of a
58 given filename prefix. By default all files in the list of directories
59 are targets for lookup and completion, but a versatile mechanism is
60 provided for only selecting specific types of files. The obvious
61 application of this facility is to provide Tab-completion and lookup of
62 executable commands in the UNIX PATH, so an optional callback which
63 rejects all but executable files, is provided.
64
65 An Example
66 Under UNIX, the following example program looks up and displays the
67 full pathnames of each of the command names on the command line.
68
69 #include <stdio.h>
70 #include <stdlib.h>
71 #include <libtecla.h>
72
73 int main(int argc, char *argv[])
74 {
75 int i;
76 /*
77 * Create a cache for executable files.
78 */
79 PathCache *pc = new_PathCache();
80 if(!pc)
81 exit(1);
82 /*
83 * Scan the user's PATH for executables.
191 characters, call ppc_literal_escapes() with a non-zero value in its
192 literal argument.
193
194
195 When you have finished with a PcaPathConf variable, you can pass it to
196 the del_PcaPathConf() destructor function to reclaim its memory.
197
198 Being Selective
199 If you are only interested in certain types or files, such as, for
200 example, executable files, or files whose names end in a particular
201 suffix, you can arrange for the file completion and lookup functions to
202 be selective in the filenames that they return. This is done by
203 registering a callback function with your PathCache object. Thereafter,
204 whenever a filename is found which either matches a filename being
205 looked up or matches a prefix which is being completed, your callback
206 function will be called with the full pathname of the file, plus any
207 application-specific data that you provide. If the callback returns 1
208 the filename will be reported as a match. If it returns 0, it will be
209 ignored. Suitable callback functions and their prototypes should be
210 declared with the following macro. The CplCheckFn typedef is also
211 provided in case you wish to declare pointers to such functions
212
213 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
214 typedef CPL_CHECK_FN(CplCheckFn);
215
216
217
218 Registering one of these functions involves calling the
219 pca_set_check_fn() function. In addition to the callback function
220 passed with the check_fn argument, you can pass a pointer to anything
221 with the data argument. This pointer will be passed on to your callback
222 function by its own data argument whenever it is called, providing a
223 way to pass application-specific data to your callback. Note that these
224 callbacks are passed the full pathname of each matching file, so the
225 decision about whether a file is of interest can be based on any
226 property of the file, not just its filename. As an example, the
227 provided cpl_check_exe() callback function looks at the executable
228 permissions of the file and the permissions of its parent directories,
229 and only returns 1 if the user has execute permission to the file. This
230 callback function can thus be used to lookup or complete command names
231 found in the directories listed in the user's PATH environment
232 variable. The example program above provides a demonstration of this.
233
234
235 Beware that if somebody tries to complete an empty string, your
236 callback will get called once for every file in the cache, which could
237 number in the thousands. If your callback does anything time consuming,
238 this could result in an unacceptable delay for the user, so callbacks
239 should be kept short.
240
241
242 To improve performance, whenever one of these callbacks is called, the
243 choice that it makes is cached, and the next time the corresponding
244 file is looked up, instead of calling the callback again, the cached
245 record of whether it was accepted or rejected is used. Thus if somebody
246 tries to complete an empty string, and hits tab a second time when
247 nothing appears to happen, there will only be one long delay, since the
248 second pass will operate entirely from the cached dispositions of the
249 files. These cached dipositions are discarded whenever pca_scan_path()
250 is called, and whenever pca_set_check_fn() is called with changed
251 callback function or data arguments.
252
253 Error Handling
254 If pca_scan_path() reports that an error occurred by returning 1, you
255 can obtain a terse description of the error by calling
256 pca_last_error(pc). This returns an internal string containing an error
257 message.
258
259 Cleaning Up
260 Once you have finished using a PathCache object, you can reclaim its
261 resources by passing it to the del_PathCache() destructor function.
262 This takes a pointer to one of these objects, and always returns NULL.
263
264 Thread Safety
265 It is safe to use the facilities of this module in multiple threads,
266 provided that each thread uses a separately allocated PathCache object.
267 In other words, if two threads want to do path searching, they should
268 each call new_PathCache() to allocate their own caches.
269
270 ATTRIBUTES
271 See attributes(5) for descriptions of the following attributes:
272
273
274
275
276 +--------------------+-----------------+
277 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
278 +--------------------+-----------------+
279 |Interface Stability | Evolving |
280 +--------------------+-----------------+
281 |MT-Level | MT-Safe |
282 +--------------------+-----------------+
283
284 SEE ALSO
285 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
286 libtecla(3LIB), attributes(5)
287
288
289
290 August 13, 2007 PCA_LOOKUP_FILE(3TECLA)
|
43
44 void ppc_file_start(PcaPathConf *ppc, int start_index);
45
46
47 void ppc_literal_escapes(PcaPathConf *ppc, int literal);
48
49
50 DESCRIPTION
51 The PathCache object is part of the libtecla(3LIB) library. PathCache
52 objects allow an application to search for files in any colon separated
53 list of directories, such as the UNIX execution PATH environment
54 variable. Files in absolute directories are cached in a PathCache
55 object, whereas relative directories are scanned as needed. Using a
56 PathCache object, you can look up the full pathname of a simple
57 filename, or you can obtain a list of the possible completions of a
58 given filename prefix. By default all files in the list of directories
59 are targets for lookup and completion, but a versatile mechanism is
60 provided for only selecting specific types of files. The obvious
61 application of this facility is to provide Tab-completion and lookup of
62 executable commands in the UNIX PATH, so an optional callback which
63 rejects all but executable files is provided.
64
65 An Example
66 Under UNIX, the following example program looks up and displays the
67 full pathnames of each of the command names on the command line.
68
69 #include <stdio.h>
70 #include <stdlib.h>
71 #include <libtecla.h>
72
73 int main(int argc, char *argv[])
74 {
75 int i;
76 /*
77 * Create a cache for executable files.
78 */
79 PathCache *pc = new_PathCache();
80 if(!pc)
81 exit(1);
82 /*
83 * Scan the user's PATH for executables.
191 characters, call ppc_literal_escapes() with a non-zero value in its
192 literal argument.
193
194
195 When you have finished with a PcaPathConf variable, you can pass it to
196 the del_PcaPathConf() destructor function to reclaim its memory.
197
198 Being Selective
199 If you are only interested in certain types or files, such as, for
200 example, executable files, or files whose names end in a particular
201 suffix, you can arrange for the file completion and lookup functions to
202 be selective in the filenames that they return. This is done by
203 registering a callback function with your PathCache object. Thereafter,
204 whenever a filename is found which either matches a filename being
205 looked up or matches a prefix which is being completed, your callback
206 function will be called with the full pathname of the file, plus any
207 application-specific data that you provide. If the callback returns 1
208 the filename will be reported as a match. If it returns 0, it will be
209 ignored. Suitable callback functions and their prototypes should be
210 declared with the following macro. The CplCheckFn typedef is also
211 provided in case you wish to declare pointers to such functions.
212
213 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
214 typedef CPL_CHECK_FN(CplCheckFn);
215
216
217
218 Registering one of these functions involves calling the
219 pca_set_check_fn() function. In addition to the callback function
220 passed with the check_fn argument, you can pass a pointer to anything
221 with the data argument. This pointer will be passed on to your callback
222 function by its own data argument whenever it is called, providing a
223 way to pass application-specific data to your callback. Note that these
224 callbacks are passed the full pathname of each matching file, so the
225 decision about whether a file is of interest can be based on any
226 property of the file, not just its filename. As an example, the
227 provided cpl_check_exe() callback function looks at the executable
228 permissions of the file and the permissions of its parent directories,
229 and only returns 1 if the user has execute permission to the file. This
230 callback function can thus be used to lookup or complete command names
231 found in the directories listed in the user's PATH environment
232 variable. The example program above provides a demonstration of this.
233
234
235 Beware that if somebody tries to complete an empty string, your
236 callback will get called once for every file in the cache, which could
237 number in the thousands. If your callback does anything time consuming,
238 this could result in an unacceptable delay for the user, so callbacks
239 should be kept short.
240
241
242 To improve performance, whenever one of these callbacks is called, the
243 choice that it makes is cached, and the next time the corresponding
244 file is looked up, instead of calling the callback again, the cached
245 record of whether it was accepted or rejected is used. Thus if somebody
246 tries to complete an empty string, and hits tab a second time when
247 nothing appears to happen, there will only be one long delay, since the
248 second pass will operate entirely from the cached dispositions of the
249 files. These cached dispositions are discarded whenever pca_scan_path()
250 is called, and whenever pca_set_check_fn() is called with changed
251 callback function or data arguments.
252
253 Error Handling
254 If pca_scan_path() reports that an error occurred by returning 1, you
255 can obtain a terse description of the error by calling
256 pca_last_error(pc). This returns an internal string containing an error
257 message.
258
259 Cleaning Up
260 Once you have finished using a PathCache object, you can reclaim its
261 resources by passing it to the del_PathCache() destructor function.
262 This takes a pointer to one of these objects, and always returns NULL.
263
264 Thread Safety
265 It is safe to use the facilities of this module in multiple threads,
266 provided that each thread uses a separately allocated PathCache object.
267 In other words, if two threads want to do path searching, they should
268 each call new_PathCache() to allocate their own caches.
269
270 ATTRIBUTES
271 See attributes(5) for descriptions of the following attributes:
272
273
274
275
276 +--------------------+-----------------+
277 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
278 +--------------------+-----------------+
279 |Interface Stability | Evolving |
280 +--------------------+-----------------+
281 |MT-Level | MT-Safe |
282 +--------------------+-----------------+
283
284 SEE ALSO
285 cpl_complete_word(3TECLA), ef_expand_file(3TECLA), gl_get_line(3TECLA),
286 libtecla(3LIB), attributes(5)
287
288
289
290 January 18, 2020 PCA_LOOKUP_FILE(3TECLA)
|