xref: /illumos-gate/usr/src/lib/libtecla/libtecla.h (revision 1da57d55)
1 #ifndef libtecla_h
2 #define libtecla_h
3 
4 /*
5  * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
6  *
7  * All rights reserved.
8  *
9  * Permission is hereby granted, free of charge, to any person obtaining a
10  * copy of this software and associated documentation files (the
11  * "Software"), to deal in the Software without restriction, including
12  * without limitation the rights to use, copy, modify, merge, publish,
13  * distribute, and/or sell copies of the Software, and to permit persons
14  * to whom the Software is furnished to do so, provided that the above
15  * copyright notice(s) and this permission notice appear in all copies of
16  * the Software and that both the above copyright notice(s) and this
17  * permission notice appear in supporting documentation.
18  *
19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
22  * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
23  * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
24  * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
25  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
26  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
27  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
28  *
29  * Except as contained in this notice, the name of a copyright holder
30  * shall not be used in advertising or otherwise to promote the sale, use
31  * or other dealings in this Software without prior written authorization
32  * of the copyright holder.
33  */
34 
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38 
39 #include <stdio.h>   /* FILE * */
40 #include <stdlib.h>  /* size_t */
41 #include <time.h>    /* time_t */
42 #include <signal.h>  /* struct sigaction */
43 
44 /*
45  * The following are the three components of the libtecla version number.
46  * Note that it is better to use the libtecla_version() function than these
47  * macros since the macros only tell you which version of the library your
48  * code was compiled against, whereas the libtecla_version() function
49  * tells you which version of the shared tecla library your program is
50  * actually linked to.
51  */
52 #define TECLA_MAJOR_VER 1
53 #define TECLA_MINOR_VER 6
54 #define TECLA_MICRO_VER 0
55 
56 /*.......................................................................
57  * Query the version number of the tecla library.
58  *
59  * Input:
60  *  major    int *   The major version number of the library
61  *                   will be assigned to *major. This number is
62  *                   only incremented when a change to the library is
63  *                   made that breaks binary (shared library) and/or
64  *                   compilation backwards compatibility.
65  *  minor    int *   The minor version number of the library
66  *                   will be assigned to *minor. This number is
67  *                   incremented whenever new functions are added to
68  *                   the public API.
69  *  micro    int *   The micro version number of the library will be
70  *                   assigned to *micro. This number is incremented
71  *                   whenever internal changes are made that don't
72  *                   change the public API, such as bug fixes and
73  *                   performance enhancements.
74  */
75 void libtecla_version(int *major, int *minor, int *micro);
76 
77 /*-----------------------------------------------------------------------
78  * The getline module provides interactive command-line input, recall
79  * and editing by users at terminals. See the gl_getline(3) man page for
80  * more details.
81  *-----------------------------------------------------------------------*/
82 
83 /*
84  * Provide an opaque handle for the resource object that is defined in
85  * getline.h.
86  */
87 typedef struct GetLine GetLine;
88 
89 /*
90  * The following two functions are used to create and delete the
91  * resource objects that are used by the gl_getline() function.
92  */
93 GetLine *new_GetLine(size_t linelen, size_t histlen);
94 GetLine *del_GetLine(GetLine *gl);
95 
96 /*
97  * Read a line into an internal buffer of gl.
98  */
99 char *gl_get_line(GetLine *gl, const char *prompt, const char *start_line,
100 		  int start_pos);
101 
102 /*.......................................................................
103  * Prompt the user for a single-character reply.
104  *
105  * Input:
106  *  gl       GetLine *  A resource object returned by new_GetLine().
107  *  prompt      char *  The prompt to prefix the query with, or NULL
108  *                      to reuse the previous prompt.
109  *  defchar     char    The character to substitute if the
110  *                      user simply hits return, or '\n' if you don't
111  *                      need to substitute anything.
112  * Output:
113  *  return       int    The character that was read, or EOF if the read
114  *                      had to be aborted (in which case you can call
115  *                      gl_return_status() to find out why).
116  */
117 int gl_query_char(GetLine *gl, const char *prompt, char defchar);
118 
119 /*.......................................................................
120  * Read a single uninterpretted character from the user, without
121  * displaying anything.
122  *
123  * Input:
124  *  gl     GetLine *  A resource object previously returned by
125  *                    new_GetLine().
126  * Output:
127  *  return     int    The character that was read, or EOF if the read
128  *                    had to be aborted (in which case you can call
129  *                    gl_return_status() to find out why).
130  */
131 int gl_read_char(GetLine *gl);
132 
133 /*
134  * Configure the application specific and/or user-specific behavior of
135  * gl_get_line().
136  */
137 int gl_configure_getline(GetLine *gl, const char *app_string,
138 			 const char *app_file, const char *user_file);
139 
140 /*
141  * The following enumerators specify the origin of a key binding, and
142  * are listed in order of decreasing priority, such that user-specified
143  * key-bindings take precedence over application default bindings.
144  */
145 typedef enum {
146   GL_USER_KEY,  /* A key-binding specified by the user */
147   GL_APP_KEY    /* A key-binding specified by the application */
148 } GlKeyOrigin;
149 
150 /*
151  * Bind a key sequence to a given action. If action==NULL, unbind the
152  * key-sequence.
153  */
154 int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin, const char *keyseq,
155 		   const char *action);
156 
157 /*-----------------------------------------------------------------------
158  * The file-expansion module provides facilities for expanding ~user/ and
159  * $envvar expressions, and for expanding glob-style wildcards.
160  * See the ef_expand_file(3) man page for more details.
161  *-----------------------------------------------------------------------*/
162 
163 /*
164  * ExpandFile objects contain the resources needed to expand pathnames.
165  */
166 typedef struct ExpandFile ExpandFile;
167 
168 /*
169  * The following functions are used to create and delete the resource
170  * objects that are used by the ef_expand_file() function.
171  */
172 ExpandFile *new_ExpandFile(void);
173 ExpandFile *del_ExpandFile(ExpandFile *ef);
174 
175 /*
176  * A container of the following type is returned by ef_expand_file().
177  */
178 typedef struct {
179   int exists;       /* True if the files in files[] currently exist. */
180                     /*  This only time that this may not be true is if */
181                     /*  the input filename didn't contain any wildcards */
182                     /*  and thus wasn't matched against existing files. */
183                     /*  In this case the single entry in 'nfile' may not */
184                     /*  refer to an existing file. */
185   int nfile;        /* The number of files in files[] */
186   char **files;     /* An array of 'nfile' filenames. */
187 } FileExpansion;
188 
189 /*
190  * The ef_expand_file() function expands a specified pathname, converting
191  * ~user/ and ~/ patterns at the start of the pathname to the
192  * corresponding home directories, replacing $envvar with the value of
193  * the corresponding environment variable, and then, if there are any
194  * wildcards, matching these against existing filenames.
195  *
196  * If no errors occur, a container is returned containing the array of
197  * files that resulted from the expansion. If there were no wildcards
198  * in the input pathname, this will contain just the original pathname
199  * after expansion of ~ and $ expressions. If there were any wildcards,
200  * then the array will contain the files that matched them. Note that
201  * if there were any wildcards but no existing files match them, this
202  * is counted as an error and NULL is returned.
203  *
204  * The supported wildcards and their meanings are:
205  *  *        -  Match any sequence of zero or more characters.
206  *  ?        -  Match any single character.
207  *  [chars]  -  Match any single character that appears in 'chars'.
208  *              If 'chars' contains an expression of the form a-b,
209  *              then any character between a and b, including a and b,
210  *              matches. The '-' character looses its special meaning
211  *              as a range specifier when it appears at the start
212  *              of the sequence of characters.
213  *  [^chars] -  The same as [chars] except that it matches any single
214  *              character that doesn't appear in 'chars'.
215  *
216  * Wildcard expressions are applied to individual filename components.
217  * They don't match across directory separators. A '.' character at
218  * the beginning of a filename component must also be matched
219  * explicitly by a '.' character in the input pathname, since these
220  * are UNIX's hidden files.
221  *
222  * Input:
223  *  fe         ExpandFile *  The pathname expansion resource object.
224  *  path       const char *  The path name to be expanded.
225  *  pathlen           int    The length of the suffix of path[] that
226  *                           constitutes the filename to be expanded,
227  *                           or -1 to specify that the whole of the
228  *                           path string should be used.
229  * Output:
230  *  return  FileExpansion *  A pointer to a results container within the
231  *                           given ExpandFile object. This contains an
232  *                           array of the pathnames that resulted from
233  *                           expanding ~ and $ expressions and from
234  *                           matching any wildcards, sorted into lexical
235  *                           order.
236  *
237  *                           This container and its contents will be
238  *                           recycled on subsequent calls, so if you need
239  *                           to keep the results of two successive runs,
240  *                           you will either have to allocate a private
241  *                           copy of the array, or use two ExpandFile
242  *                           objects.
243  *
244  *                           On error, NULL is returned. A description
245  *                           of the error can be acquired by calling the
246  *                           ef_last_error() function.
247  */
248 FileExpansion *ef_expand_file(ExpandFile *ef, const char *path, int pathlen);
249 
250 /*.......................................................................
251  * Print out an array of matching files.
252  *
253  * Input:
254  *  result  FileExpansion *   The container of the sorted array of
255  *                            expansions.
256  *  fp               FILE *   The output stream to write to.
257  *  term_width        int     The width of the terminal.
258  * Output:
259  *  return            int     0 - OK.
260  *                            1 - Error.
261  */
262 int ef_list_expansions(FileExpansion *result, FILE *fp, int term_width);
263 
264 /*
265  * The ef_last_error() function returns a description of the last error
266  * that occurred in a call ef_expand_file(). Note that this message is
267  * contained in an array which is allocated as part of *ef, and its
268  * contents thus potentially change on every call to ef_expand_file().
269  */
270 const char *ef_last_error(ExpandFile *ef);
271 
272 /*-----------------------------------------------------------------------
273  * The WordCompletion module is used for completing incomplete words, such
274  * as filenames. Programs can use functions within this module to register
275  * their own customized completion functions.
276  *-----------------------------------------------------------------------*/
277 
278 /*
279  * Ambiguous completion matches are recorded in objects of the
280  * following type.
281  */
282 typedef struct WordCompletion WordCompletion;
283 
284 /*
285  * Create a new completion object.
286  */
287 WordCompletion *new_WordCompletion(void);
288 
289 /*
290  * Delete a redundant completion object.
291  */
292 WordCompletion *del_WordCompletion(WordCompletion *cpl);
293 
294 /*.......................................................................
295  * Callback functions declared and prototyped using the following macro
296  * are called upon to return an array of possible completion suffixes
297  * for the token that precedes a specified location in the given
298  * input line. It is up to this function to figure out where the token
299  * starts, and to call cpl_add_completion() to register each possible
300  * completion before returning.
301  *
302  * Input:
303  *  cpl  WordCompletion *  An opaque pointer to the object that will
304  *                         contain the matches. This should be filled
305  *                         via zero or more calls to cpl_add_completion().
306  *  data           void *  The anonymous 'data' argument that was
307  *                         passed to cpl_complete_word() or
308  *                         gl_customize_completion()).
309  *  line     const char *  The current input line.
310  *  word_end        int    The index of the character in line[] which
311  *                         follows the end of the token that is being
312  *                         completed.
313  * Output
314  *  return          int    0 - OK.
315  *                         1 - Error.
316  */
317 #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, void *data, \
318                                   const char *line, int word_end)
319 typedef CPL_MATCH_FN(CplMatchFn);
320 
321 /*.......................................................................
322  * Optional callback functions declared and prototyped using the
323  * following macro are called upon to return non-zero if a given
324  * file, specified by its pathname, is to be included in a list of
325  * completions.
326  *
327  * Input:
328  *  data            void *  The application specified pointer which
329  *                          was specified when this callback function
330  *                          was registered. This can be used to have
331  *                          anything you like passed to your callback.
332  *  pathname  const char *  The pathname of the file to be checked to
333  *                          see if it should be included in the list
334  *                          of completions.
335  * Output
336  *  return           int    0 - Ignore this file.
337  *                          1 - Do include this file in the list
338  *                              of completions.
339  */
340 #define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
341 typedef CPL_CHECK_FN(CplCheckFn);
342 
343 /*
344  * You can use the following CplCheckFn callback function to only
345  * have executables included in a list of completions.
346  */
347 CPL_CHECK_FN(cpl_check_exe);
348 
349 /*
350  * cpl_file_completions() is the builtin filename completion callback
351  * function. This can also be called by your own custom CPL_MATCH_FN()
352  * callback functions. To do this pass on all of the arguments of your
353  * custom callback function to cpl_file_completions(), with the exception
354  * of the (void *data) argument. The data argument should either be passed
355  * NULL to request the default behaviour of the file-completion function,
356  * or be passed a pointer to a CplFileConf structure (see below). In the
357  * latter case the contents of the structure modify the behavior of the
358  * file-completer.
359  */
360 CPL_MATCH_FN(cpl_file_completions);
361 
362 /*
363  * Objects of the following type can be used to change the default
364  * behavior of the cpl_file_completions() callback function.
365  */
366 typedef struct CplFileConf CplFileConf;
367 
368 /*
369  * If you want to change the behavior of the cpl_file_completions()
370  * callback function, call the following function to allocate a
371  * configuration object, then call one or more of the subsequent
372  * functions to change any of the default configuration parameters
373  * that you don't want. This function returns NULL when there is
374  * insufficient memory.
375  */
376 CplFileConf *new_CplFileConf(void);
377 
378 /*
379  * If backslashes in the prefix being passed to cpl_file_completions()
380  * should be treated as literal characters, call the following function
381  * with literal=1. Otherwise the default is to treat them as escape
382  * characters which remove the special meanings of spaces etc..
383  */
384 void cfc_literal_escapes(CplFileConf *cfc, int literal);
385 
386 /*
387  * Before calling cpl_file_completions(), call this function if you
388  * know the index at which the filename prefix starts in the input line.
389  * Otherwise by default, or if you specify start_index to be -1, the
390  * filename is taken to start after the first unescaped space preceding
391  * the cursor, or the start of the line, which ever comes first.
392  */
393 void cfc_file_start(CplFileConf *cfc, int start_index);
394 
395 /*
396  * If you only want certain types of files to be included in the
397  * list of completions, use the following function to specify a
398  * callback function which will be called to ask whether a given file
399  * should be included. The chk_data argument is will be passed to the
400  * callback function whenever it is called and can be anything you want.
401  */
402 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, void *chk_data);
403 
404 /*
405  * The following function deletes a CplFileConf objects previously
406  * returned by new_CplFileConf(). It always returns NULL.
407  */
408 CplFileConf *del_CplFileConf(CplFileConf *cfc);
409 
410 /*
411  * The following configuration structure is deprecated. Do not change
412  * its contents, since this will break any programs that still use it,
413  * and don't use it in new programs. Instead use opaque CplFileConf
414  * objects as described above. cpl_file_completions() figures out
415  * what type of structure you pass it, by virtue of a magic int code
416  * placed at the start of CplFileConf object by new_CplFileConf().
417  */
418 typedef struct {
419   int escaped;     /* Opposite to the argument of cfc_literal_escapes() */
420   int file_start;  /* Equivalent to the argument of cfc_file_start() */
421 } CplFileArgs;
422 /*
423  * This initializes the deprecated CplFileArgs structures.
424  */
425 void cpl_init_FileArgs(CplFileArgs *cfa);
426 
427 /*.......................................................................
428  * When an error occurs while performing a completion, custom completion
429  * callback functions should register a terse description of the error
430  * by calling cpl_record_error(). This message will then be returned on
431  * the next call to cpl_last_error() and used by getline to display an
432  * error message to the user.
433  *
434  * Input:
435  *  cpl  WordCompletion *  The string-completion resource object that was
436  *                         originally passed to the callback.
437  *  errmsg   const char *  The description of the error.
438  */
439 void cpl_record_error(WordCompletion *cpl, const char *errmsg);
440 
441 /*.......................................................................
442  * This function can be used to replace the builtin filename-completion
443  * function with one of the user's choice. The user's completion function
444  * has the option of calling the builtin filename-completion function
445  * if it believes that the token that it has been presented with is a
446  * filename (see cpl_file_completions() above).
447  *
448  * Input:
449  *  gl            GetLine *  The resource object of the command-line input
450  *                           module.
451  *  data             void *  This is passed to match_fn() whenever it is
452  *                           called. It could, for example, point to a
453  *                           symbol table that match_fn() would look up
454  *                           matches in.
455  *  match_fn   CplMatchFn *  The function that will identify the prefix
456  *                           to be completed from the input line, and
457  *                           report matching symbols.
458  * Output:
459  *  return            int    0 - OK.
460  *                           1 - Error.
461  */
462 int gl_customize_completion(GetLine *gl, void *data, CplMatchFn *match_fn);
463 
464 /*.......................................................................
465  * This function allows you to install alternate completion action
466  * functions or completion listing functions, or to change the
467  * completion function of an existing action of the same type. This
468  * should preferably be called before the first call to gl_get_line()
469  * so that the name of the action becomes defined before the user's
470  * configuration file is read.
471  *
472  * Input:
473  *  gl            GetLine *  The resource object of the command-line input
474  *                           module.
475  *  data             void *  This is passed to match_fn() whenever it is
476  *                           called. It could, for example, point to a
477  *                           symbol table that match_fn() would look up
478  *                           matches in.
479  *  match_fn   CplMatchFn *  The function that will identify the prefix
480  *                           to be completed from the input line, and
481  *                           report matching symbols.
482  *  list_only         int    If non-zero, install an action that only lists
483  *                           possible completions, rather than attempting
484  *                           to perform the completion.
485  *  name       const char *  The name with which users can refer to the
486  *                           binding in tecla configuration files.
487  *  keyseq     const char *  The key sequence with which to invoke
488  *                           the binding. This should be specified in the
489  *                           same manner as key-sequences in tecla
490  *                           configuration files (eg. "M-^I").
491  * Output:
492  *  return            int    0 - OK.
493  *                           1 - Error.
494  */
495 int gl_completion_action(GetLine *gl, void *data, CplMatchFn *match_fn,
496 			 int list_only, const char *name, const char *keyseq);
497 
498 /*.......................................................................
499  * Change the terminal (or stream) that getline interacts with.
500  *
501  * Input:
502  *  gl            GetLine *  The resource object of the command-line input
503  *                           module.
504  *  input_fp         FILE *  The stdio stream to read from.
505  *  output_fp        FILE *  The stdio stream to write to.
506  *  term       const char *  The terminal type. This can be NULL if
507  *                           either or both of input_fp and output_fp don't
508  *                           refer to a terminal. Otherwise it should refer
509  *                           to an entry in the terminal information database.
510  * Output:
511  *  return            int    0 - OK.
512  *                           1 - Error.
513  */
514 int gl_change_terminal(GetLine *gl, FILE *input_fp, FILE *output_fp,
515 		       const char *term);
516 
517 /*.......................................................................
518  * The following functions can be used to save and restore the contents
519  * of the history buffer.
520  *
521  * Input:
522  *  gl            GetLine *  The resource object of the command-line input
523  *                           module.
524  *  filename   const char *  The name of the new file to write to.
525  *  comment    const char *  Extra information such as timestamps will
526  *                           be recorded on a line started with this
527  *                           string, the idea being that the file can
528  *                           double as a command file. Specify "" if
529  *                           you don't care. Be sure to specify the
530  *                           same string to both functions.
531  *  max_lines         int    The maximum number of lines to save, or -1
532  *                           to save all of the lines in the history
533  *                           list.
534  * Output:
535  *  return            int     0 - OK.
536  *                            1 - Error.
537  */
538 int gl_save_history(GetLine *gl, const char *filename, const char *comment,
539 		    int max_lines);
540 int gl_load_history(GetLine *gl, const char *filename, const char *comment);
541 
542 /*
543  * Enumerate file-descriptor events that can be waited for.
544  */
545 typedef enum {
546   GLFD_READ,   /* Watch for data waiting to be read from a file descriptor */
547   GLFD_WRITE,  /* Watch for ability to write to a file descriptor */
548   GLFD_URGENT  /* Watch for urgent out-of-band data on the file descriptor */
549 } GlFdEvent;
550 
551 /*
552  * The following enumeration is used for the return status of file
553  * descriptor event callbacks.
554  */
555 typedef enum {
556   GLFD_ABORT,    /* Cause gl_get_line() to abort with an error */
557   GLFD_REFRESH,  /* Redraw the input line and continue waiting for input */
558   GLFD_CONTINUE  /* Continue to wait for input, without redrawing the line */
559 } GlFdStatus;
560 
561 /*.......................................................................
562  * On systems that have the select() system call, while gl_get_line()
563  * is waiting for terminal input, it can also be asked to listen for
564  * activity on arbitrary file descriptors.  Callback functions of the
565  * following type can be registered to be called when activity is
566  * seen. If your callback needs to write to the terminal or use
567  * signals, please see the gl_get_line(3) man page.
568  *
569  * Input:
570  *  gl       GetLine *  The gl_get_line() resource object. You can use
571  *                      this safely to call gl_watch_fd() or
572  *                      gl_inactivity_timeout(). The effect of calling other
573  *                      functions that take a gl argument is undefined,
574  *                      and must be avoided.
575  *  data        void *  A pointer to arbitrary callback data, as originally
576  *                      registered with gl_watch_fd().
577  *  fd           int    The file descriptor that has activity.
578  *  event  GlFdEvent    The activity seen on the file descriptor. The
579  *                      inclusion of this argument allows the same
580  *                      callback to be registered for multiple events.
581  * Output:
582  *  return GlFdStatus   GLFD_ABORT    - Cause gl_get_line() to abort with
583  *                                      an error (set errno if you need it).
584  *                      GLFD_REFRESH  - Redraw the input line and continue
585  *                                      waiting for input. Use this if you
586  *                                      wrote something to the terminal.
587  *                      GLFD_CONTINUE - Continue to wait for input, without
588  *                                      redrawing the line.
589  */
590 #define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, void *data, int fd, \
591 					   GlFdEvent event)
592 typedef GL_FD_EVENT_FN(GlFdEventFn);
593 
594 /*.......................................................................
595  * Where possible, register a function and associated data to be called
596  * whenever a specified event is seen on a file descriptor.
597  *
598  * Input:
599  *  gl            GetLine *  The resource object of the command-line input
600  *                           module.
601  *  fd                int    The file descriptor to watch.
602  *  event       GlFdEvent    The type of activity to watch for.
603  *  callback  GlFdEventFn *  The function to call when the specified
604  *                           event occurs. Setting this to 0 removes
605  *                           any existing callback.
606  *  data             void *  A pointer to arbitrary data to pass to the
607  *                           callback function.
608  * Output:
609  *  return            int    0 - OK.
610  *                           1 - Either gl==NULL, or this facility isn't
611  *                               available on the the host system
612  *                               (ie. select() isn't available). No
613  *                               error message is generated in the latter
614  *                               case.
615  */
616 int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
617 		GlFdEventFn *callback, void *data);
618 
619 /*
620  * Enumerators from the following list are returned by activity
621  * timeout callbacks registered by gl_inactivity_timeout(). They tell
622  * gl_get_line() whether and how to procede.
623  */
624 typedef enum {
625   GLTO_ABORT,    /* Cause gl_get_line() to abort with an error */
626   GLTO_REFRESH,  /* Redraw the input line and continue waiting for input */
627   GLTO_CONTINUE  /* Continue to wait for input, without redrawing the line */
628 } GlAfterTimeout;
629 
630 /*.......................................................................
631  * On systems that have the select() system call, the application has
632  * the option of providing a callback function of the following type,
633  * which is called whenever no terminal input or other I/O activity is
634  * seen for the timeout duration specified in the last call to
635  * gl_inactivity_timeout().
636  *
637  * Input:
638  *  gl            GetLine *  The gl_get_line() resource object. You can use
639  *                           this safely to call gl_watch_fd() or
640  *                           gl_inactivity_timeout(). The effect of calling other
641  *                           functions that take a gl argument is undefined,
642  *                           and must be avoided.
643  *  data             void *  A pointer to arbitrary callback data, as
644  *                           originally registered with gl_inactivity_timeout().
645  * Output:
646  *  return GlAfterTimeout    GLTO_ABORT    - Cause gl_get_line() to
647  *                                           abort with an error (set
648  *                                           errno if you need it).
649  *                           GLTO_REFRESH  - Redraw the input line and
650  *                                           continue waiting for
651  *                                           input. Use this if you
652  *                                           wrote something to the
653  *                                           terminal.
654  *                           GLTO_CONTINUE - Continue to wait for
655  *                                           input, without redrawing
656  *                                           the line.
657  */
658 #define GL_TIMEOUT_FN(fn) GlAfterTimeout (fn)(GetLine *gl, void *data)
659 typedef GL_TIMEOUT_FN(GlTimeoutFn);
660 
661 /*.......................................................................
662  * On systems with the select() system call, the gl_inactivity_timeout()
663  * function provides the option of setting (or cancelling) an
664  * inactivity timeout. Inactivity, in this case, refers both to
665  * terminal input received from the user, and to I/O on any file
666  * descriptors registered by calls to gl_watch_fd(). If at any time,
667  * no activity is seen for the requested time period, the specified
668  * timeout callback function is called. On returning, this callback
669  * returns a code which tells gl_get_line() what to do next. Note that
670  * each call to gl_inactivity_timeout() replaces any previously installed
671  * timeout callback, and that specifying a callback of 0, turns off
672  * inactivity timing.
673  *
674  * Beware that although the timeout argument includes a nano-second
675  * component, few computer clocks presently have resolutions finer
676  * than a few milliseconds, so asking for less than a few milliseconds
677  * is equivalent to zero on a lot of systems.
678  *
679  * Input:
680  *  gl            GetLine *  The resource object of the command-line input
681  *                           module.
682  *  callback  GlTimeoutFn *  The function to call when the inactivity
683  *                           timeout is exceeded. To turn off
684  *                           inactivity timeouts altogether, send 0.
685  *  data             void *  A pointer to arbitrary data to pass to the
686  *                           callback function.
687  *  sec     unsigned long    The number of whole seconds in the timeout.
688  *  nsec    unsigned long    The fractional number of seconds in the
689  *                           timeout, expressed in nano-seconds (see
690  *                           the caveat above).
691  * Output:
692  *  return            int    0 - OK.
693  *                           1 - Either gl==NULL, or this facility isn't
694  *                               available on the the host system
695  *                               (ie. select() isn't available). No
696  *                               error message is generated in the latter
697  *                               case.
698  */
699 int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *timeout_fn, void *data,
700 		   unsigned long sec, unsigned long nsec);
701 
702 /*.......................................................................
703  * Switch history streams. History streams represent separate history
704  * lists recorded within a single history buffer. Different streams
705  * are distinguished by integer identifiers chosen by the calling
706  * appplicaton. Initially new_GetLine() sets the stream identifier to
707  * 0. Whenever a new line is appended to the history list, the current
708  * stream identifier is recorded with it, and history lookups only
709  * consider lines marked with the current stream identifier.
710  *
711  * Input:
712  *  gl      GetLine *  The resource object of gl_get_line().
713  *  id     unsigned    The new history stream identifier.
714  * Output:
715  *  return      int    0 - OK.
716  *                     1 - Error.
717  */
718 int gl_group_history(GetLine *gl, unsigned id);
719 
720 /*.......................................................................
721  * Display the contents of the history list.
722  *
723  * Input:
724  *  gl      GetLine *  The resource object of gl_get_line().
725  *  fp         FILE *  The stdio output stream to write to.
726  *  fmt  const char *  A format string. This containing characters to be
727  *                     written verbatim, plus any of the following
728  *                     format directives:
729  *                       %D  -  The date, formatted like 2001-11-20
730  *                       %T  -  The time of day, formatted like 23:59:59
731  *                       %N  -  The sequential entry number of the
732  *                              line in the history buffer.
733  *                       %G  -  The number of the history group that
734  *                              the line belongs to.
735  *                       %%  -  A literal % character.
736  *                       %H  -  The history line itself.
737  *                     Note that a '\n' newline character is not
738  *                     appended by default.
739  *  all_groups  int    If true, display history lines from all
740  *                     history groups. Otherwise only display
741  *                     those of the current history group.
742  *  max_lines   int    If max_lines is < 0, all available lines
743  *                     are displayed. Otherwise only the most
744  *                     recent max_lines lines will be displayed.
745  * Output:
746  *  return      int    0 - OK.
747  *                     1 - Error.
748  */
749 int gl_show_history(GetLine *gl, FILE *fp, const char *fmt, int all_groups,
750 		    int max_lines);
751 
752 /*.......................................................................
753  * Resize or delete the history buffer.
754  *
755  * Input:
756  *  gl      GetLine *  The resource object of gl_get_line().
757  *  bufsize  size_t    The number of bytes in the history buffer, or 0
758  *                     to delete the buffer completely.
759  * Output:
760  *  return      int    0 - OK.
761  *                     1 - Insufficient memory (the previous buffer
762  *                         will have been retained). No error message
763  *                         will be displayed.
764  */
765 int gl_resize_history(GetLine *gl, size_t bufsize);
766 
767 /*.......................................................................
768  * Set an upper limit to the number of lines that can be recorded in the
769  * history list, or remove a previously specified limit.
770  *
771  * Input:
772  *  gl      GetLine *  The resource object of gl_get_line().
773  *  max_lines   int    The maximum number of lines to allow, or -1 to
774  *                     cancel a previous limit and allow as many lines
775  *                     as will fit in the current history buffer size.
776  */
777 void gl_limit_history(GetLine *gl, int max_lines);
778 
779 /*.......................................................................
780  * Discard either all historical lines, or just those associated with the
781  * current history group.
782  *
783  * Input:
784  *  gl      GetLine *  The resource object of gl_get_line().
785  *  all_groups  int    If true, clear all of the history. If false,
786  *                     clear only the stored lines associated with the
787  *                     currently selected history group.
788  */
789 void gl_clear_history(GetLine *gl, int all_groups);
790 
791 /*.......................................................................
792  * Temporarily enable or disable the gl_get_line() history mechanism.
793  *
794  * Input:
795  *  gl      GetLine *  The resource object of gl_get_line().
796  *  enable      int    If true, turn on the history mechanism. If
797  *                     false, disable it.
798  */
799 void gl_toggle_history(GetLine *gl, int enable);
800 
801 /*
802  * Objects of the following type are returned by gl_terminal_size().
803  */
804 typedef struct {
805   int nline;        /* The terminal has nline lines */
806   int ncolumn;      /* The terminal has ncolumn columns */
807 } GlTerminalSize;
808 
809 /*.......................................................................
810  * Update if necessary, and return the current size of the terminal.
811  *
812  * Input:
813  *  gl            GetLine *  The resource object of gl_get_line().
814  *  def_ncolumn       int    If the number of columns in the terminal
815  *                           can't be determined, substitute this number.
816  *  def_nline         int    If the number of lines in the terminal can't
817  *                           be determined, substitute this number.
818  * Output:
819  *  return GlTerminalSize    The current terminal size.
820  */
821 GlTerminalSize gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline);
822 
823 /*.......................................................................
824  * Tell gl_get_line() the current terminal size. Note that this is only
825  * necessary on systems where changes in terminal size aren't reported
826  * via SIGWINCH.
827  *
828  * Input:
829  *  gl            GetLine *  The resource object of gl_get_line().
830  *  ncolumn           int    The number of columns in the terminal.
831  *  nline             int    The number of rows in the terminal.
832  * Output:
833  *  return            int    0 - OK.
834  *                           1 - Error.
835  */
836 int gl_set_term_size(GetLine *gl, int ncolumn, int nline);
837 
838 /*
839  * The gl_lookup_history() function returns information in an
840  * argument of the following type.
841  */
842 typedef struct {
843   const char *line;    /* The requested history line */
844   unsigned group;      /* The history group to which the */
845                        /*  line belongs. */
846   time_t timestamp;    /* The date and time at which the */
847                        /*  line was originally entered. */
848 } GlHistoryLine;
849 
850 /*.......................................................................
851  * Lookup a history line by its sequential number of entry in the
852  * history buffer.
853  *
854  * Input:
855  *  gl            GetLine *  The resource object of gl_get_line().
856  *  id      unsigned long    The identification number of the line to
857  *                           be returned, where 0 denotes the first line
858  *                           that was entered in the history list, and
859  *                           each subsequently added line has a number
860  *                           one greater than the previous one. For
861  *                           the range of lines currently in the list,
862  *                           see the gl_range_of_history() function.
863  * Input/Output:
864  *  line    GlHistoryLine *  A pointer to the variable in which to
865  *                           return the details of the line.
866  * Output:
867  *  return            int    0 - The line is no longer in the history
868  *                               list, and *line has not been changed.
869  *                           1 - The requested line can be found in
870  *                               *line. Note that the string in
871  *                               line->line is part of the history
872  *                               buffer and will change, so a private
873  *                               copy should be made if you wish to
874  *                               use it after subsequent calls to any
875  *                               functions that take gl as an argument.
876  */
877 int gl_lookup_history(GetLine *gl, unsigned long id, GlHistoryLine *line);
878 
879 /*
880  * The gl_state_of_history() function returns information in an argument
881  * of the following type.
882  */
883 typedef struct {
884   int enabled;     /* True if history is enabled */
885   unsigned group;  /* The current history group */
886   int max_lines;   /* The current upper limit on the number of lines */
887                    /*  in the history list, or -1 if unlimited. */
888 } GlHistoryState;
889 
890 /*.......................................................................
891  * Query the state of the history list. Note that any of the input/output
892  * pointers can be specified as NULL.
893  *
894  * Input:
895  *  gl            GetLine *  The resource object of gl_get_line().
896  * Input/Output:
897  *  state  GlHistoryState *  A pointer to the variable in which to record
898  *                           the return values.
899  */
900 void gl_state_of_history(GetLine *gl, GlHistoryState *state);
901 
902 /*
903  * The gl_range_of_history() function returns information in an argument
904  * of the following type.
905  */
906 typedef struct {
907   unsigned long oldest;  /* The sequential entry number of the oldest */
908                          /*  line in the history list. */
909   unsigned long newest;  /* The sequential entry number of the newest */
910                          /*  line in the history list. */
911   int nlines;            /* The number of lines in the history list */
912 } GlHistoryRange;
913 
914 /*.......................................................................
915  * Query the number and range of lines in the history buffer.
916  *
917  * Input:
918  *  gl            GetLine *  The resource object of gl_get_line().
919  *  range  GlHistoryRange *  A pointer to the variable in which to record
920  *                           the return values. If range->nline=0, the
921  *                           range of lines will be given as 0-0.
922  */
923 void gl_range_of_history(GetLine *gl, GlHistoryRange *range);
924 
925 /*
926  * The gl_size_of_history() function returns information in an argument
927  * of the following type.
928  */
929 typedef struct {
930   size_t size;      /* The size of the history buffer (bytes) */
931   size_t used;      /* The number of bytes of the history buffer */
932                     /*  that are currently occupied. */
933 } GlHistorySize;
934 
935 /*.......................................................................
936  * Return the size of the history buffer and the amount of the
937  * buffer that is currently in use.
938  *
939  * Input:
940  *  gl         GetLine *  The resource object of gl_get_line().
941  * Input/Output:
942  *  GlHistorySize size *  A pointer to the variable in which to return
943  *                        the results.
944  */
945 void gl_size_of_history(GetLine *gl, GlHistorySize *size);
946 
947 /*.......................................................................
948  * Enable or disable the automatic addition of newly entered lines to the
949  * history list.
950  *
951  * Input:
952  *  gl          GetLine *   The resource object of gl_get_line().
953  *  enable          int     If true, subsequently entered lines will
954  *                          automatically be added to the history list
955  *                          before they are returned to the caller of
956  *                          gl_get_line(). If 0, the choice of how and
957  *                          when to archive lines in the history list,
958  *                          is left up to the calling application, which
959  *                          can do so via calls to gl_append_history().
960  * Output:
961  *  return          int     0 - OK.
962  *                          1 - Error.
963  */
964 int gl_automatic_history(GetLine *gl, int enable);
965 
966 /*.......................................................................
967  * Append a specified line to the history list.
968  *
969  * Input:
970  *  gl          GetLine *   The resource object of gl_get_line().
971  *  line     const char *   The line to be added.
972  * Output:
973  *  return          int     0 - OK.
974  *                          1 - Error.
975  */
976 int gl_append_history(GetLine *gl, const char *line);
977 
978 /*.......................................................................
979  * Specify whether text that users type should be displayed or hidden.
980  * In the latter case, only the prompt is displayed, and the final
981  * input line is not archived in the history list.
982  *
983  * Input:
984  *  gl         GetLine *  The input-line history maintenance object.
985  *  enable         int     0 - Disable echoing.
986  *                         1 - Enable echoing.
987  *                        -1 - Just query the mode without changing it.
988  * Output:
989  *  return         int    The echoing disposition that was in effect
990  *                        before this function was called:
991  *                         0 - Echoing was disabled.
992  *                         1 - Echoing was enabled.
993  */
994 int gl_echo_mode(GetLine *gl, int enable);
995 
996 /*.......................................................................
997  * This function can be called from gl_get_line() callbacks to have
998  * the prompt changed when they return. It has no effect if gl_get_line()
999  * is not currently being invoked.
1000  *
1001  * Input:
1002  *  gl         GetLine *  The resource object of gl_get_line().
1003  *  prompt  const char *  The new prompt.
1004  */
1005 void gl_replace_prompt(GetLine *gl, const char *prompt);
1006 
1007 /*
1008  * Enumerate the available prompt formatting styles.
1009  */
1010 typedef enum {
1011   GL_LITERAL_PROMPT,   /* Display the prompt string literally */
1012   GL_FORMAT_PROMPT     /* The prompt string can contain any of the */
1013                        /* following formatting directives: */
1014                        /*   %B  -  Display subsequent characters */
1015                        /*          with a bold font. */
1016                        /*   %b  -  Stop displaying characters */
1017                        /*          with the bold font. */
1018                        /*   %U  -  Underline subsequent characters. */
1019                        /*   %u  -  Stop underlining characters. */
1020                        /*   %S  -  Highlight subsequent characters */
1021                        /*          (also known as standout mode). */
1022                        /*   %s  -  Stop highlighting characters */
1023                        /*   %%  -  Display a single % character. */
1024 } GlPromptStyle;
1025 
1026 /*.......................................................................
1027  * Specify whether to heed text attribute directives within prompt
1028  * strings.
1029  *
1030  * Input:
1031  *  gl           GetLine *  The resource object of gl_get_line().
1032  *  style  GlPromptStyle    The style of prompt (see the definition of
1033  *                          GlPromptStyle in libtecla.h for details).
1034  */
1035 void gl_prompt_style(GetLine *gl, GlPromptStyle style);
1036 
1037 /*.......................................................................
1038  * Remove a signal from the list of signals that gl_get_line() traps.
1039  *
1040  * Input:
1041  *  gl           GetLine *  The resource object of gl_get_line().
1042  *  signo            int    The number of the signal to be ignored.
1043  * Output:
1044  *  return           int    0 - OK.
1045  *                          1 - Error.
1046  */
1047 int gl_ignore_signal(GetLine *gl, int signo);
1048 
1049 /*
1050  * A bitwise union of the following enumerators is passed to
1051  * gl_trap_signal() to specify the environment in which the
1052  * application's signal handler is to be called.
1053  */
1054 typedef enum {
1055   GLS_RESTORE_SIG=1,  /* Restore the caller's signal environment */
1056                       /* while handling the signal. */
1057   GLS_RESTORE_TTY=2,  /* Restore the caller's terminal settings */
1058                       /* while handling the signal. */
1059   GLS_RESTORE_LINE=4, /* Move the cursor to the start of the next line */
1060   GLS_REDRAW_LINE=8,  /* Redraw the input line when the signal handler */
1061                       /*  returns. */
1062   GLS_UNBLOCK_SIG=16, /* Normally a signal who's delivery is found to */
1063                       /*  be blocked by the calling application is not */
1064                       /*  trapped by gl_get_line(). Including this flag */
1065                       /*  causes it to be temporarily unblocked and */
1066                       /*  trapped while gl_get_line() is executing. */
1067   GLS_DONT_FORWARD=32,/* Don't forward the signal to the signal handler */
1068                       /*  of the calling program. */
1069   GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | GLS_REDRAW_LINE,
1070   GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE
1071 } GlSignalFlags;
1072 
1073 /*
1074  * The following enumerators are passed to gl_trap_signal() to tell
1075  * it what to do after the application's signal handler has been called.
1076  */
1077 typedef enum {
1078   GLS_RETURN,      /* Return the line as though the user had pressed the */
1079                    /*  return key. */
1080   GLS_ABORT,       /* Cause gl_get_line() to return NULL */
1081   GLS_CONTINUE     /* After handling the signal, resume command line editing */
1082 } GlAfterSignal;
1083 
1084 /*.......................................................................
1085  * Tell gl_get_line() how to respond to a given signal. This can be used
1086  * both to override the default responses to signals that gl_get_line()
1087  * normally catches and to add new signals to the list that are to be
1088  * caught.
1089  *
1090  * Input:
1091  *  gl           GetLine *  The resource object of gl_get_line().
1092  *  signo            int    The number of the signal to be caught.
1093  *  flags       unsigned    A bitwise union of GlSignalFlags enumerators.
1094  *  after  GlAfterSignal    What to do after the application's signal
1095  *                          handler has been called.
1096  *  errno_value      int    The value to set errno to.
1097  * Output:
1098  *  return           int    0 - OK.
1099  *                          1 - Insufficient memory to record the
1100  *                              new signal disposition.
1101  */
1102 int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
1103 		   GlAfterSignal after, int errno_value);
1104 
1105 /*.......................................................................
1106  * By default, gl_get_line() doesn't trap signals that are blocked
1107  * when it is called. This default can be changed either on a
1108  * per-signal basis by calling gl_trap_signal(), or on a global basis
1109  * by calling this function. What this function does is add the
1110  * GLS_UNBLOCK_SIG flag to all signals that are currently configured
1111  * to be trapped by gl_get_line(), such that when subsequent calls to
1112  * gl_get_line() wait for I/O, these signals are temporarily
1113  * unblocked. This behavior is useful in non-blocking server-I/O mode,
1114  * where it is used to avoid race conditions related to handling these
1115  * signals externally to gl_get_line(). See the demonstration code in
1116  * demo3.c, or the gl_handle_signal() man page for further
1117  * information.
1118  *
1119  * Input:
1120  *  gl         GetLine *   The resource object of gl_get_line().
1121  */
1122 void gl_catch_blocked(GetLine *gl);
1123 
1124 /*.......................................................................
1125  * In server-I/O mode the terminal is left in raw mode between calls
1126  * to gl_get_line(), so it is necessary for the application to install
1127  * terminal restoring signal handlers for signals that could terminate
1128  * or suspend the process, plus a terminal reconfiguration handler to
1129  * be called when a process resumption signal is received, and finally
1130  * a handler to be called when a terminal-resize signal is received.
1131  *
1132  * Since there are many signals that by default terminate or suspend
1133  * processes, and different systems support different sub-sets of
1134  * these signals, this function provides a convenient wrapper around
1135  * sigaction() for assigning the specified handlers to all appropriate
1136  * signals. It also arranges that when any one of these signals is
1137  * being handled, all other catchable signals are blocked. This is
1138  * necessary so that the specified signal handlers can safely call
1139  * gl_raw_io(), gl_normal_io() and gl_update_size() without reentrancy
1140  * issues.
1141  *
1142  * Input:
1143  *  term_handler  void (*)(int)  The signal handler to invoke when
1144  *                               a process terminating signal is
1145  *                               received.
1146  *  susp_handler  void (*)(int)  The signal handler to invoke when
1147  *                               a process suspending signal is
1148  *                               received.
1149  *  cont_handler  void (*)(int)  The signal handler to invoke when
1150  *                               a process resumption signal is
1151  *                               received (ie. SIGCONT).
1152  *  size_handler  void (*)(int)  The signal handler to invoke when
1153  *                               a terminal-resize signal (ie. SIGWINCH)
1154  *                               is received.
1155  * Output:
1156  *  return                  int  0 - OK.
1157  *                               1 - Error.
1158  */
1159 int gl_tty_signals(void (*term_handler)(int), void (*susp_handler)(int),
1160 		   void (*cont_handler)(int), void (*size_handler)(int));
1161 
1162 /*.......................................................................
1163  * Return the last signal that was caught by the most recent call to
1164  * gl_get_line(), or -1 if no signals were caught. This is useful if
1165  * gl_get_line() returns errno=EINTR and you need to find out what signal
1166  * caused it to abort.
1167  *
1168  * Input:
1169  *  gl           GetLine *  The resource object of gl_get_line().
1170  * Output:
1171  *  return           int    The last signal caught by the most recent
1172  *                          call to gl_get_line(), or -1 if no signals
1173  *                          were caught.
1174  */
1175 int gl_last_signal(GetLine *gl);
1176 
1177 /*.......................................................................
1178  * Return the signal mask used by gl_get_line(). This is the set of
1179  * signals that gl_get_line() is currently configured to trap.
1180  *
1181  * Input:
1182  *  gl         GetLine *  The resource object of gl_get_line().
1183  * Input/Output:
1184  *  set       sigset_t *  The set of signals will be returned in *set,
1185  *                        in the form of a signal process mask, as
1186  *                        used by sigaction(), sigprocmask(),
1187  *                        sigpending(), sigsuspend(), sigsetjmp() and
1188  *                        other standard POSIX signal-aware
1189  *                        functions.
1190  * Output:
1191  *  return         int    0 - OK.
1192  *                        1 - Error (examine errno for reason).
1193  */
1194 int gl_list_signals(GetLine *gl, sigset_t *set);
1195 
1196 /*.......................................................................
1197  * Respond to signals who's default effects have important
1198  * consequences to gl_get_line(). This is intended for use in
1199  * non-blocking server mode, where the external event loop is
1200  * responsible for catching signals. Signals that are handled include
1201  * those that by default terminate or suspend the process, and the
1202  * signal that indicates that the terminal size has changed. Note that
1203  * this function is not signal safe and should thus not be called from
1204  * a signal handler itself. See the gl_io_mode() man page for how it
1205  * should be used.
1206  *
1207  * In the case of signals that by default terminate or suspend
1208  * processes, command-line editing will be suspended, the terminal
1209  * returned to a usable state, then the default disposition of the
1210  * signal restored and the signal resent, in order to suspend or
1211  * terminate the process.  If the process subsequently resumes,
1212  * command-line editing is resumed.
1213  *
1214  * In the case of signals that indicate that the terminal has been
1215  * resized, the new size will be queried, and any input line that is
1216  * being edited will be redrawn to fit the new dimensions of the
1217  * terminal.
1218  *
1219  * Input:
1220  *  signo    int    The number of the signal to respond to.
1221  *  gl   GetLine *  The first element of an array of 'ngl' GetLine
1222  *                  objects.
1223  *  ngl      int    The number of elements in the gl[] array. Normally
1224  *                  this will be one.
1225  */
1226 void gl_handle_signal(int signo, GetLine *gl, int ngl);
1227 
1228 /*.......................................................................
1229  * Return extra information (ie. in addition to that provided by errno)
1230  * about the last error to occur in either gl_get_line() or its
1231  * associated public functions.
1232  *
1233  * Input:
1234  *  gl         GetLine *  The resource object of gl_get_line().
1235  * Input/Output:
1236  *  buff          char *  An optional output buffer. Note that if the
1237  *                        calling application calls any gl_*()
1238  *                        functions from signal handlers, it should
1239  *                        provide a buffer here, so that a copy of
1240  *                        the latest error message can safely be made
1241  *                        while signals are blocked.
1242  *  n           size_t    The allocated size of buff[].
1243  * Output:
1244  *  return  const char *  A pointer to the error message. This will
1245  *                        be the buff argument, unless buff==NULL, in
1246  *                        which case it will be a pointer to an
1247  *                        internal error buffer. In the latter case,
1248  *                        note that the contents of the returned buffer
1249  *                        will change on subsequent calls to any gl_*()
1250  *                        functions.
1251  */
1252 const char *gl_error_message(GetLine *gl, char *buff, size_t n);
1253 
1254 /*.......................................................................
1255  * Clear the terminal and leave the cursor at the home position.  In
1256  * server I/O mode, arrange for the input line to be redrawn from scratch
1257  * when gl_get_line() is next called.
1258  *
1259  * Input:
1260  *  gl          GetLine *   The resource object of gl_get_line().
1261  * Output:
1262  *  return          int     0 - OK.
1263  *                          1 - Error.
1264  */
1265 int gl_erase_terminal(GetLine *gl);
1266 
1267 /*.......................................................................
1268  * Display a left-justified string over multiple terminal lines,
1269  * taking account of the current width of the terminal. Optional
1270  * indentation and an optional prefix string can be specified to be
1271  * displayed at the start of each new terminal line used. Similarly,
1272  * an optional suffix can be specified to be displayed at the end of
1273  * each terminal line.  If needed, a single paragraph can be broken
1274  * across multiple calls.  Note that literal newlines in the input
1275  * string can be used to force a newline at any point and that you
1276  * should use this feature to explicitly end all paragraphs, including
1277  * at the end of the last string that you write. Note that when a new
1278  * line is started between two words that are separated by spaces,
1279  * those spaces are not output, whereas when a new line is started
1280  * because a newline character was found in the string, only the
1281  * spaces before the newline character are discarded.
1282  *
1283  * Input:
1284  *  gl         GetLine *  The resource object of gl_get_line().
1285  *  indentation    int    The number of spaces of indentation to write
1286  *                        at the beginning of each new terminal line.
1287  *  prefix  const char *  An optional prefix string to write after the
1288  *                        indentation margin at the start of each new
1289  *                        terminal line. You can specify NULL if no
1290  *                        prefix is required.
1291  *  suffix  const char *  An optional suffix string to draw at the end
1292  *                        of the terminal line. Spaces will be added
1293  *                        where necessary to ensure that the suffix ends
1294  *                        in the last column of the terminal line. If
1295  *                        no suffix is desired, specify NULL.
1296  *  fill_char      int    The padding character to use when indenting
1297  *                        the line or padding up to the suffix.
1298  *  def_width      int    If the terminal width isn't known, such as when
1299  *                        writing to a pipe or redirecting to a file,
1300  *                        this number specifies what width to assume.
1301  *  start          int    The number of characters already written to
1302  *                        the start of the current terminal line. This
1303  *                        is primarily used to allow individual
1304  *                        paragraphs to be written over multiple calls
1305  *                        to this function, but can also be used to
1306  *                        allow you to start the first line of a
1307  *                        paragraph with a different prefix or
1308  *                        indentation than those specified above.
1309  *  string  const char *  The string to be written.
1310  * Output:
1311  *  return         int    On error -1 is returned. Otherwise the
1312  *                        return value is the terminal column index at
1313  *                        which the cursor was left after writing the
1314  *                        final word in the string. Successful return
1315  *                        values can thus be passed verbatim to the
1316  *                        'start' arguments of subsequent calls to
1317  *                        gl_display_text() to allow the printing of a
1318  *                        paragraph to be broken across multiple calls
1319  *                        to gl_display_text().
1320  */
1321 int gl_display_text(GetLine *gl, int indentation, const char *prefix,
1322 		    const char *suffix, int fill_char, int def_width,
1323 		    int start, const char *string);
1324 
1325 
1326 /*
1327  * Enumerate the I/O modes supported by gl_get_line().
1328  */
1329 typedef enum {
1330   GL_NORMAL_MODE,    /* Normal line-at-a-time mode using gl_get_line()'s */
1331                      /*  internal event loop. */
1332   GL_SERVER_MODE     /* Non-blocking server mode, driven by an external */
1333                      /*  event loop. */
1334 } GlIOMode;
1335 
1336 /*.......................................................................
1337  * Select the I/O mode to be used by gl_get_line().
1338  *
1339  * Input:
1340  *  gl         GetLine *         The resource object of gl_get_line().
1341  *  mode      GlIOMode           The I/O mode to establish. Note that
1342  *                               when server mode, the terminal is placed
1343  *                               in raw mode, as though gl_raw_io() had
1344  *                               been called.
1345  * Output:
1346  *  return                  int  0 - OK.
1347  *                               1 - Error.
1348  */
1349 int gl_io_mode(GetLine *gl, GlIOMode mode);
1350 
1351 /*.......................................................................
1352  * In server mode, this function configures the terminal for non-blocking
1353  * raw terminal I/O. In normal I/O mode it does nothing.
1354  *
1355  * Callers of this function must be careful to trap all signals that
1356  * terminate or suspend the program, and call gl_normal_io()
1357  * from the corresponding signal handlers in order to restore the
1358  * terminal to its original settings before the program is terminated
1359  * or suspended. They should also trap the SIGCONT signal to detect
1360  * when the program resumes, and ensure that its signal handler
1361  * call gl_raw_io() to redisplay the line and resume editing.
1362  *
1363  * Input:
1364  *  gl      GetLine *  The line editor resource object.
1365  * Output:
1366  *  return      int    0 - OK.
1367  *                     1 - Error.
1368  */
1369 int gl_raw_io(GetLine *gl);
1370 
1371 /*.......................................................................
1372  * Restore the terminal to the state that it had when gl_raw_io() was
1373  * last called. After calling gl_raw_io(), this function must be called
1374  * before terminating or suspending the program, and before attempting
1375  * other uses of the terminal from within the program. See gl_raw_io()
1376  * for more details.
1377  *
1378  * Input:
1379  *  gl      GetLine *  The line editor resource object.
1380  * Output:
1381  *  return      int    0 - OK.
1382  *                     1 - Error.
1383  */
1384 int gl_normal_io(GetLine *gl);
1385 
1386 /*.......................................................................
1387  * When in non-blocking server mode, this function can be used to abandon
1388  * the current incompletely entered input line, and prepare to start
1389  * editing a new line on the next call to gl_get_line().
1390  *
1391  * Input:
1392  *  gl      GetLine *  The line editor resource object.
1393  * Output:
1394  *  return      int    0 - OK.
1395  *                     1 - Error.
1396  */
1397 void gl_abandon_line(GetLine *gl);
1398 
1399 /*
1400  * Enumerators of the following type are used to report why
1401  * gl_get_line() returned. This is most useful in non-blocking
1402  * server mode, since in that mode a NULL return value can mean
1403  * either that an error occurred, or that I/O blocked.
1404  */
1405 typedef enum {
1406   GLR_NEWLINE,  /* A new input line was returned */
1407   GLR_BLOCKED,  /* The terminal was in non-blocking mode, and input */
1408                 /* or output would have blocked. */
1409   GLR_SIGNAL,   /* A signal caused gl_get_line() to return. */
1410   GLR_TIMEOUT,  /* An application timeout callback returned GLTO_ABORT */
1411   GLR_FDABORT,  /* An application I/O callack returned GLFD_ABORT */
1412   GLR_EOF,      /* End of file reached */
1413   GLR_ERROR     /* An unexpected error caused gl_get_line() to abort */
1414 } GlReturnStatus;
1415 
1416 /*.......................................................................
1417  * Ask gl_get_line() what caused it to return.
1418  *
1419  * Input:
1420  *  gl             GetLine *  The line editor resource object.
1421  * Output:
1422  *  return  GlReturnStatus    The return status of the last call to
1423  *                            gl_get_line().
1424  */
1425 GlReturnStatus gl_return_status(GetLine *gl);
1426 
1427 /*
1428  * Enumerate the types of I/O that gl_get_line() can be waiting for
1429  * in non-blocking sedrver I/O mode.
1430  */
1431 typedef enum {
1432   GLP_READ,   /* gl_get_line() is waiting to write to the terminal */
1433   GLP_WRITE   /* gl_get_line() is waiting to read from the terminal */
1434 } GlPendingIO;
1435 
1436 /*.......................................................................
1437  * In non-blocking server-I/O mode, this function should be called
1438  * from the application's external event loop to see what type of
1439  * terminal I/O is being waited for by gl_get_line(), and thus what
1440  * direction of I/O to wait for with select() or poll().
1441  *
1442  * Input:
1443  *  gl          GetLine *  The resource object of gl_get_line().
1444  * Output:
1445  *  return  GlPendingIO    The type of pending I/O being waited for.
1446  */
1447 GlPendingIO gl_pending_io(GetLine *gl);
1448 
1449 /*
1450  * The following enumerators are returned by externally defined action
1451  * functions to tell gl_get_line() how to procede after the action
1452  * function returns.
1453  */
1454 typedef enum {
1455   GLA_ABORT,     /* Cause gl_get_line() to return NULL */
1456   GLA_RETURN,    /* Return the line as though the user had pressed the */
1457                  /*  return key. */
1458   GLA_CONTINUE   /* Resume command-line editing */
1459 } GlAfterAction;
1460 
1461 /*.......................................................................
1462  * Functions of the following form implement external
1463  * application-specific action functions, which can then be bound to
1464  * sequences of terminal keys.
1465  *
1466  * Input:
1467  *  gl            GetLine *  The line editor resource object.
1468  *  data             void *  The anonymous 'data' argument that was
1469  *                           passed to gl_external_action() when the
1470  *                           callback function was registered.
1471  *  count             int    A positive repeat count specified by the user,
1472  *                           or 1 if not specified. Action functions should
1473  *                           ignore this if repeating the action multiple
1474  *                           times isn't appropriate. Alternatively they
1475  *                           can interpret it as a general numeric
1476  *                           argument.
1477  *  curpos         size_t    The position of the cursor within the input
1478  *                           line, expressed as the index of the
1479  *                           corresponding character within the line[]
1480  *                           array.
1481  *  line       const char *  A read-only copy of the current input line.
1482  * Output
1483  *  return  GlAfterAction    What should gl_get_line() do when the action
1484  *                           function returns?
1485  *                            GLA_ABORT    - Cause gl_get_line() to
1486  *                                           abort with an error (set
1487  *                                           errno if you need it).
1488  *                            GLA_RETURN   - Return the input line as
1489  *                                           though the user had typed
1490  *                                           the return key.
1491  *                            GLA_CONTINUE - Resume waiting for keyboard
1492  *                                           input.
1493  */
1494 #define GL_ACTION_FN(fn) GlAfterAction (fn)(GetLine *gl, void *data, \
1495 	      int count, size_t curpos, const char *line)
1496 
1497 typedef GL_ACTION_FN(GlActionFn);
1498 
1499 /*.......................................................................
1500  * Register an application-provided function as an action function.
1501  * This should preferably be called before the first call to gl_get_line()
1502  * so that the name of the action becomes defined before the user's
1503  * configuration file is read.
1504  *
1505  * Input:
1506  *  gl            GetLine *  The resource object of the command-line input
1507  *                           module.
1508  *  data             void *  Arbitrary application-specific callback
1509  *                           data to be passed to the callback
1510  *                           function, fn().
1511  *  fn         GlActionFn *  The application-specific function that
1512  *                           implements the action. This will be invoked
1513  *                           whenever the user presses any
1514  *                           key-sequence which is bound to this action.
1515  *  name       const char *  The name with which users can refer to the
1516  *                           binding in tecla configuration files.
1517  *  keyseq     const char *  The key sequence with which to invoke
1518  *                           the binding. This should be specified in the
1519  *                           same manner as key-sequences in tecla
1520  *                           configuration files (eg. "M-^I").
1521  * Output:
1522  *  return            int    0 - OK.
1523  *                           1 - Error.
1524  */
1525 int gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
1526                        const char *name, const char *keyseq);
1527 
1528 /*.......................................................................
1529  * This function is designed to be called by CPL_MATCH_FN() callback
1530  * functions. It adds one possible completion of the token that is being
1531  * completed to an array of completions. If the completion needs any
1532  * special quoting to be valid when displayed in the input line, this
1533  * quoting must be included in the string.
1534  *
1535  * Input:
1536  *  cpl      WordCompletion *  The argument of the same name that was passed
1537  *                             to the calling CPL_MATCH_FN() callback function.
1538  *  line         const char *  The input line, as received by the callback
1539  *                             function.
1540  *  word_start          int    The index within line[] of the start of the
1541  *                             word that is being completed. If an empty
1542  *                             string is being completed, set this to be
1543  *                             the same as word_end.
1544  *  word_end            int    The index within line[] of the character which
1545  *                             follows the incomplete word, as received by the
1546  *                             callback function.
1547  *  suffix       const char *  The appropriately quoted string that could
1548  *                             be appended to the incomplete token to complete
1549  *                             it. A copy of this string will be allocated
1550  *                             internally.
1551  *  type_suffix  const char *  When listing multiple completions, gl_get_line()
1552  *                             appends this string to the completion to indicate
1553  *                             its type to the user. If not pertinent pass "".
1554  *                             Otherwise pass a literal or static string.
1555  *  cont_suffix  const char *  If this turns out to be the only completion,
1556  *                             gl_get_line() will append this string as
1557  *                             a continuation. For example, the builtin
1558  *                             file-completion callback registers a directory
1559  *                             separator here for directory matches, and a
1560  *                             space otherwise. If the match were a function
1561  *                             name you might want to append an open
1562  *                             parenthesis, etc.. If not relevant pass "".
1563  *                             Otherwise pass a literal or static string.
1564  * Output:
1565  *  return              int    0 - OK.
1566  *                             1 - Error.
1567  */
1568 int cpl_add_completion(WordCompletion *cpl, const char *line,
1569 		       int word_start, int word_end, const char *suffix,
1570 		       const char *type_suffix, const char *cont_suffix);
1571 
1572 /*
1573  * Each possible completion string is recorded in an array element of
1574  * the following type.
1575  */
1576 typedef struct {
1577   char *completion;        /* The matching completion string */
1578   char *suffix;            /* The pointer into completion[] at which the */
1579                            /*  string was extended. */
1580   const char *type_suffix; /* A suffix to be added when listing completions */
1581                            /*  to indicate the type of the completion. */
1582 } CplMatch;
1583 
1584 /*
1585  * Completions are returned in a container of the following form.
1586  */
1587 typedef struct {
1588   char *suffix;            /* The common initial part of all of the */
1589                            /*  completion suffixes. */
1590   const char *cont_suffix; /* Optional continuation string to be appended to */
1591                            /*  the sole completion when nmatch==1. */
1592   CplMatch *matches;       /* The array of possible completion strings, */
1593                            /*  sorted into lexical order. */
1594   int nmatch;              /* The number of elements in matches[] */
1595 } CplMatches;
1596 
1597 /*.......................................................................
1598  * Given an input line and the point at which completion is to be
1599  * attempted, return an array of possible completions.
1600  *
1601  * Input:
1602  *  cpl    WordCompletion *  The word-completion resource object.
1603  *  line       const char *  The current input line.
1604  *  word_end          int    The index of the character in line[] which
1605  *                           follows the end of the token that is being
1606  *                           completed.
1607  *  data             void *  Anonymous 'data' to be passed to match_fn().
1608  *  match_fn   CplMatchFn *  The function that will identify the prefix
1609  *                           to be completed from the input line, and
1610  *                           record completion suffixes.
1611  * Output:
1612  *  return     CplMatches *  The container of the array of possible
1613  *                           completions. The returned pointer refers
1614  *                           to a container owned by the parent Completion
1615  *                           object, and its contents thus potentially
1616  *                           change on every call to cpl_complete_word().
1617  */
1618 CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
1619 			      int word_end, void *data,
1620 			      CplMatchFn *match_fn);
1621 
1622 /*.......................................................................
1623  * Recall the return value of the last call to cpl_complete_word().
1624  *
1625  * Input:
1626  *  cpl    WordCompletion *  The completion resource object.
1627  * Output:
1628  *  return     CplMatches *  The container of the array of possible
1629  *                           completions, as returned by the last call to
1630  *                           cpl_complete_word(). The returned pointer refers
1631  *                           to a container owned by the parent WordCompletion
1632  *                           object, and its contents thus potentially
1633  *                           change on every call to cpl_complete_word().
1634  *                           On error, either in the execution of this
1635  *                           function, or in the last call to
1636  *                           cpl_complete_word(), NULL is returned, and a
1637  *                           description of the error can be acquired by
1638  *                           calling cpl_last_error(cpl).
1639  */
1640 CplMatches *cpl_recall_matches(WordCompletion *cpl);
1641 
1642 /*.......................................................................
1643  * Print out an array of matching completions.
1644  *
1645  * Input:
1646  *  result  CplMatches *   The container of the sorted array of
1647  *                         completions.
1648  *  fp            FILE *   The output stream to write to.
1649  *  term_width     int     The width of the terminal.
1650  * Output:
1651  *  return         int     0 - OK.
1652  *                         1 - Error.
1653  */
1654 int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);
1655 
1656 /*.......................................................................
1657  * Return a description of the error that occurred on the last call to
1658  * cpl_complete_word() or cpl_add_completion().
1659  *
1660  * Input:
1661  *  cpl   WordCompletion *  The string-completion resource object.
1662  * Output:
1663  *  return    const char *  The description of the last error.
1664  */
1665 const char *cpl_last_error(WordCompletion *cpl);
1666 
1667 /*
1668  * PathCache objects encapsulate the resources needed to record
1669  * files of interest from comma-separated lists of directories.
1670  */
1671 typedef struct PathCache PathCache;
1672 
1673 /*.......................................................................
1674  * Create an object who's function is to maintain a cache of filenames
1675  * found within a list of directories, and provide quick lookup and
1676  * completion of selected files in this cache.
1677  *
1678  * Output:
1679  *  return     PathCache *  The new, initially empty cache, or NULL
1680  *                          on error.
1681  */
1682 PathCache *new_PathCache(void);
1683 
1684 /*.......................................................................
1685  * Delete a given cache of files, returning the resources that it
1686  * was using to the system.
1687  *
1688  * Input:
1689  *  pc      PathCache *  The cache to be deleted (can be NULL).
1690  * Output:
1691  *  return  PathCache *  The deleted object (ie. allways NULL).
1692  */
1693 PathCache *del_PathCache(PathCache *pc);
1694 
1695 /*.......................................................................
1696  * Return a description of the last path-caching error that occurred.
1697  *
1698  * Input:
1699  *  pc     PathCache *   The filename cache that suffered the error.
1700  * Output:
1701  *  return      char *   The description of the last error.
1702  */
1703 const char *pca_last_error(PathCache *pc);
1704 
1705 /*.......................................................................
1706  * Build the list of files of interest contained in a given
1707  * colon-separated list of directories.
1708  *
1709  * Input:
1710  *  pc         PathCache *  The cache in which to store the names of
1711  *                          the files that are found in the list of
1712  *                          directories.
1713  *  path      const char *  A colon-separated list of directory
1714  *                          paths. Under UNIX, when searching for
1715  *                          executables, this should be the return
1716  *                          value of getenv("PATH").
1717  * Output:
1718  *  return           int    0 - OK.
1719  *                          1 - An error occurred.
1720  */
1721 int pca_scan_path(PathCache *pc, const char *path);
1722 
1723 /*.......................................................................
1724  * If you want subsequent calls to pca_lookup_file() and
1725  * pca_path_completions() to only return the filenames of certain
1726  * types of files, for example executables, or filenames ending in
1727  * ".ps", call this function to register a file-selection callback
1728  * function. This callback function takes the full pathname of a file,
1729  * plus application-specific data, and returns 1 if the file is of
1730  * interest, and zero otherwise.
1731  *
1732  * Input:
1733  *  pc         PathCache *  The filename cache.
1734  *  check_fn  CplCheckFn *  The function to call to see if the name of
1735  *                          a given file should be included in the
1736  *                          cache. This determines what type of files
1737  *                          will reside in the cache. To revert to
1738  *                          selecting all files, regardless of type,
1739  *                          pass 0 here.
1740  *  data            void *  You can pass a pointer to anything you
1741  *                          like here, including NULL. It will be
1742  *                          passed to your check_fn() callback
1743  *                          function, for its private use.
1744  */
1745 void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, void *data);
1746 
1747 /*.......................................................................
1748  * Given the simple name of a file, search the cached list of files
1749  * in the order in which they where found in the list of directories
1750  * previously presented to pca_scan_path(), and return the pathname
1751  * of the first file which has this name.
1752  *
1753  * Input:
1754  *  pc     PathCache *  The cached list of files.
1755  *  name  const char *  The name of the file to lookup.
1756  *  name_len     int    The length of the filename substring at the
1757  *                      beginning of name[], or -1 to assume that the
1758  *                      filename occupies the whole of the string.
1759  *  literal      int    If this argument is zero, lone backslashes
1760  *                      in name[] are ignored during comparison
1761  *                      with filenames in the cache, under the
1762  *                      assumption that they were in the input line
1763  *                      soley to escape the special significance of
1764  *                      characters like spaces. To have them treated
1765  *                      as normal characters, give this argument a
1766  *                      non-zero value, such as 1.
1767  * Output:
1768  *  return      char *  The pathname of the first matching file,
1769  *                      or NULL if not found. Note that the returned
1770  *                      pointer points to memory owned by *pc, and
1771  *                      will become invalid on the next call.
1772  */
1773 char *pca_lookup_file(PathCache *pc, const char *name, int name_len,
1774 		      int literal);
1775 
1776 /*
1777  * Objects of the following type can be used to change the default
1778  * behavior of the pca_path_completions() callback function.
1779  */
1780 typedef struct PcaPathConf PcaPathConf;
1781 
1782 /*
1783  * pca_path_completions() is a completion callback function for use directly
1784  * with cpl_complete_word() or gl_customize_completions(), or indirectly
1785  * from your own completion callback function. It requires that a PcaPathConf
1786  * object be passed via its 'void *data' argument (see below).
1787  */
1788 CPL_MATCH_FN(pca_path_completions);
1789 
1790 /*.......................................................................
1791  * Allocate and initialize a pca_path_completions() configuration object.
1792  *
1793  * Input:
1794  *  pc         PathCache *  The filename cache in which to look for
1795  *                          file name completions.
1796  * Output:
1797  *  return   PcaPathConf *  The new configuration structure, or NULL
1798  *                          on error.
1799  */
1800 PcaPathConf *new_PcaPathConf(PathCache *pc);
1801 
1802 /*.......................................................................
1803  * Deallocate memory, previously allocated by new_PcaPathConf().
1804  *
1805  * Input:
1806  *  ppc     PcaPathConf *  Any pointer previously returned by
1807  *                         new_PcaPathConf() [NULL is allowed].
1808  * Output:
1809  *  return  PcaPathConf *  The deleted structure (always NULL).
1810  */
1811 PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);
1812 
1813 /*
1814  * If backslashes in the prefix being passed to pca_path_completions()
1815  * should be treated as literal characters, call the following function
1816  * with literal=1. Otherwise the default is to treat them as escape
1817  * characters which remove the special meanings of spaces etc..
1818  */
1819 void ppc_literal_escapes(PcaPathConf *ppc, int literal);
1820 
1821 /*
1822  * Before calling pca_path_completions, call this function if you know
1823  * the index at which the filename prefix starts in the input line.
1824  * Otherwise by default, or if you specify start_index to be -1, the
1825  * filename is taken to start after the first unescaped space preceding
1826  * the cursor, or the start of the line, whichever comes first.
1827  */
1828 void ppc_file_start(PcaPathConf *ppc, int start_index);
1829 
1830 #ifdef __cplusplus
1831 }
1832 #endif
1833 
1834 #endif
1835