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