OpenSolaris_b135/lib/libtecla/libtecla.h
#ifndef libtecla_h
#define libtecla_h
/*
* Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
*
* All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the
* "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish,
* distribute, and/or sell copies of the Software, and to permit persons
* to whom the Software is furnished to do so, provided that the above
* copyright notice(s) and this permission notice appear in all copies of
* the Software and that both the above copyright notice(s) and this
* permission notice appear in supporting documentation.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
* OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
* HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
* INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
* FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
* NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
* WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*
* Except as contained in this notice, the name of a copyright holder
* shall not be used in advertising or otherwise to promote the sale, use
* or other dealings in this Software without prior written authorization
* of the copyright holder.
*/
#pragma ident "%Z%%M% %I% %E% SMI"
#ifdef __cplusplus
extern "C" {
#endif
#include <stdio.h> /* FILE * */
#include <stdlib.h> /* size_t */
#include <time.h> /* time_t */
#include <signal.h> /* struct sigaction */
/*
* The following are the three components of the libtecla version number.
* Note that it is better to use the libtecla_version() function than these
* macros since the macros only tell you which version of the library your
* code was compiled against, whereas the libtecla_version() function
* tells you which version of the shared tecla library your program is
* actually linked to.
*/
#define TECLA_MAJOR_VER 1
#define TECLA_MINOR_VER 6
#define TECLA_MICRO_VER 0
/*.......................................................................
* Query the version number of the tecla library.
*
* Input:
* major int * The major version number of the library
* will be assigned to *major. This number is
* only incremented when a change to the library is
* made that breaks binary (shared library) and/or
* compilation backwards compatibility.
* minor int * The minor version number of the library
* will be assigned to *minor. This number is
* incremented whenever new functions are added to
* the public API.
* micro int * The micro version number of the library will be
* assigned to *micro. This number is incremented
* whenever internal changes are made that don't
* change the public API, such as bug fixes and
* performance enhancements.
*/
void libtecla_version(int *major, int *minor, int *micro);
/*-----------------------------------------------------------------------
* The getline module provides interactive command-line input, recall
* and editing by users at terminals. See the gl_getline(3) man page for
* more details.
*-----------------------------------------------------------------------*/
/*
* Provide an opaque handle for the resource object that is defined in
* getline.h.
*/
typedef struct GetLine GetLine;
/*
* The following two functions are used to create and delete the
* resource objects that are used by the gl_getline() function.
*/
GetLine *new_GetLine(size_t linelen, size_t histlen);
GetLine *del_GetLine(GetLine *gl);
/*
* Read a line into an internal buffer of gl.
*/
char *gl_get_line(GetLine *gl, const char *prompt, const char *start_line,
int start_pos);
/*.......................................................................
* Prompt the user for a single-character reply.
*
* Input:
* gl GetLine * A resource object returned by new_GetLine().
* prompt char * The prompt to prefix the query with, or NULL
* to reuse the previous prompt.
* defchar char The character to substitute if the
* user simply hits return, or '\n' if you don't
* need to substitute anything.
* Output:
* return int The character that was read, or EOF if the read
* had to be aborted (in which case you can call
* gl_return_status() to find out why).
*/
int gl_query_char(GetLine *gl, const char *prompt, char defchar);
/*.......................................................................
* Read a single uninterpretted character from the user, without
* displaying anything.
*
* Input:
* gl GetLine * A resource object previously returned by
* new_GetLine().
* Output:
* return int The character that was read, or EOF if the read
* had to be aborted (in which case you can call
* gl_return_status() to find out why).
*/
int gl_read_char(GetLine *gl);
/*
* Configure the application specific and/or user-specific behavior of
* gl_get_line().
*/
int gl_configure_getline(GetLine *gl, const char *app_string,
const char *app_file, const char *user_file);
/*
* The following enumerators specify the origin of a key binding, and
* are listed in order of decreasing priority, such that user-specified
* key-bindings take precedence over application default bindings.
*/
typedef enum {
GL_USER_KEY, /* A key-binding specified by the user */
GL_APP_KEY /* A key-binding specified by the application */
} GlKeyOrigin;
/*
* Bind a key sequence to a given action. If action==NULL, unbind the
* key-sequence.
*/
int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin, const char *keyseq,
const char *action);
/*-----------------------------------------------------------------------
* The file-expansion module provides facilities for expanding ~user/ and
* $envvar expressions, and for expanding glob-style wildcards.
* See the ef_expand_file(3) man page for more details.
*-----------------------------------------------------------------------*/
/*
* ExpandFile objects contain the resources needed to expand pathnames.
*/
typedef struct ExpandFile ExpandFile;
/*
* The following functions are used to create and delete the resource
* objects that are used by the ef_expand_file() function.
*/
ExpandFile *new_ExpandFile(void);
ExpandFile *del_ExpandFile(ExpandFile *ef);
/*
* A container of the following type is returned by ef_expand_file().
*/
typedef struct {
int exists; /* True if the files in files[] currently exist. */
/* This only time that this may not be true is if */
/* the input filename didn't contain any wildcards */
/* and thus wasn't matched against existing files. */
/* In this case the single entry in 'nfile' may not */
/* refer to an existing file. */
int nfile; /* The number of files in files[] */
char **files; /* An array of 'nfile' filenames. */
} FileExpansion;
/*
* The ef_expand_file() function expands a specified pathname, converting
* ~user/ and ~/ patterns at the start of the pathname to the
* corresponding home directories, replacing $envvar with the value of
* the corresponding environment variable, and then, if there are any
* wildcards, matching these against existing filenames.
*
* If no errors occur, a container is returned containing the array of
* files that resulted from the expansion. If there were no wildcards
* in the input pathname, this will contain just the original pathname
* after expansion of ~ and $ expressions. If there were any wildcards,
* then the array will contain the files that matched them. Note that
* if there were any wildcards but no existing files match them, this
* is counted as an error and NULL is returned.
*
* The supported wildcards and their meanings are:
* * - Match any sequence of zero or more characters.
* ? - Match any single character.
* [chars] - Match any single character that appears in 'chars'.
* If 'chars' contains an expression of the form a-b,
* then any character between a and b, including a and b,
* matches. The '-' character looses its special meaning
* as a range specifier when it appears at the start
* of the sequence of characters.
* [^chars] - The same as [chars] except that it matches any single
* character that doesn't appear in 'chars'.
*
* Wildcard expressions are applied to individual filename components.
* They don't match across directory separators. A '.' character at
* the beginning of a filename component must also be matched
* explicitly by a '.' character in the input pathname, since these
* are UNIX's hidden files.
*
* Input:
* fe ExpandFile * The pathname expansion resource object.
* path const char * The path name to be expanded.
* pathlen int The length of the suffix of path[] that
* constitutes the filename to be expanded,
* or -1 to specify that the whole of the
* path string should be used.
* Output:
* return FileExpansion * A pointer to a results container within the
* given ExpandFile object. This contains an
* array of the pathnames that resulted from
* expanding ~ and $ expressions and from
* matching any wildcards, sorted into lexical
* order.
*
* This container and its contents will be
* recycled on subsequent calls, so if you need
* to keep the results of two successive runs,
* you will either have to allocate a private
* copy of the array, or use two ExpandFile
* objects.
*
* On error, NULL is returned. A description
* of the error can be acquired by calling the
* ef_last_error() function.
*/
FileExpansion *ef_expand_file(ExpandFile *ef, const char *path, int pathlen);
/*.......................................................................
* Print out an array of matching files.
*
* Input:
* result FileExpansion * The container of the sorted array of
* expansions.
* fp FILE * The output stream to write to.
* term_width int The width of the terminal.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int ef_list_expansions(FileExpansion *result, FILE *fp, int term_width);
/*
* The ef_last_error() function returns a description of the last error
* that occurred in a call ef_expand_file(). Note that this message is
* contained in an array which is allocated as part of *ef, and its
* contents thus potentially change on every call to ef_expand_file().
*/
const char *ef_last_error(ExpandFile *ef);
/*-----------------------------------------------------------------------
* The WordCompletion module is used for completing incomplete words, such
* as filenames. Programs can use functions within this module to register
* their own customized completion functions.
*-----------------------------------------------------------------------*/
/*
* Ambiguous completion matches are recorded in objects of the
* following type.
*/
typedef struct WordCompletion WordCompletion;
/*
* Create a new completion object.
*/
WordCompletion *new_WordCompletion(void);
/*
* Delete a redundant completion object.
*/
WordCompletion *del_WordCompletion(WordCompletion *cpl);
/*.......................................................................
* Callback functions declared and prototyped using the following macro
* are called upon to return an array of possible completion suffixes
* for the token that precedes a specified location in the given
* input line. It is up to this function to figure out where the token
* starts, and to call cpl_add_completion() to register each possible
* completion before returning.
*
* Input:
* cpl WordCompletion * An opaque pointer to the object that will
* contain the matches. This should be filled
* via zero or more calls to cpl_add_completion().
* data void * The anonymous 'data' argument that was
* passed to cpl_complete_word() or
* gl_customize_completion()).
* line const char * The current input line.
* word_end int The index of the character in line[] which
* follows the end of the token that is being
* completed.
* Output
* return int 0 - OK.
* 1 - Error.
*/
#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, void *data, \
const char *line, int word_end)
typedef CPL_MATCH_FN(CplMatchFn);
/*.......................................................................
* Optional callback functions declared and prototyped using the
* following macro are called upon to return non-zero if a given
* file, specified by its pathname, is to be included in a list of
* completions.
*
* Input:
* data void * The application specified pointer which
* was specified when this callback function
* was registered. This can be used to have
* anything you like passed to your callback.
* pathname const char * The pathname of the file to be checked to
* see if it should be included in the list
* of completions.
* Output
* return int 0 - Ignore this file.
* 1 - Do include this file in the list
* of completions.
*/
#define CPL_CHECK_FN(fn) int (fn)(void *data, const char *pathname)
typedef CPL_CHECK_FN(CplCheckFn);
/*
* You can use the following CplCheckFn callback function to only
* have executables included in a list of completions.
*/
CPL_CHECK_FN(cpl_check_exe);
/*
* cpl_file_completions() is the builtin filename completion callback
* function. This can also be called by your own custom CPL_MATCH_FN()
* callback functions. To do this pass on all of the arguments of your
* custom callback function to cpl_file_completions(), with the exception
* of the (void *data) argument. The data argument should either be passed
* NULL to request the default behaviour of the file-completion function,
* or be passed a pointer to a CplFileConf structure (see below). In the
* latter case the contents of the structure modify the behavior of the
* file-completer.
*/
CPL_MATCH_FN(cpl_file_completions);
/*
* Objects of the following type can be used to change the default
* behavior of the cpl_file_completions() callback function.
*/
typedef struct CplFileConf CplFileConf;
/*
* If you want to change the behavior of the cpl_file_completions()
* callback function, call the following function to allocate a
* configuration object, then call one or more of the subsequent
* functions to change any of the default configuration parameters
* that you don't want. This function returns NULL when there is
* insufficient memory.
*/
CplFileConf *new_CplFileConf(void);
/*
* If backslashes in the prefix being passed to cpl_file_completions()
* should be treated as literal characters, call the following function
* with literal=1. Otherwise the default is to treat them as escape
* characters which remove the special meanings of spaces etc..
*/
void cfc_literal_escapes(CplFileConf *cfc, int literal);
/*
* Before calling cpl_file_completions(), call this function if you
* know the index at which the filename prefix starts in the input line.
* Otherwise by default, or if you specify start_index to be -1, the
* filename is taken to start after the first unescaped space preceding
* the cursor, or the start of the line, which ever comes first.
*/
void cfc_file_start(CplFileConf *cfc, int start_index);
/*
* If you only want certain types of files to be included in the
* list of completions, use the following function to specify a
* callback function which will be called to ask whether a given file
* should be included. The chk_data argument is will be passed to the
* callback function whenever it is called and can be anything you want.
*/
void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, void *chk_data);
/*
* The following function deletes a CplFileConf objects previously
* returned by new_CplFileConf(). It always returns NULL.
*/
CplFileConf *del_CplFileConf(CplFileConf *cfc);
/*
* The following configuration structure is deprecated. Do not change
* its contents, since this will break any programs that still use it,
* and don't use it in new programs. Instead use opaque CplFileConf
* objects as described above. cpl_file_completions() figures out
* what type of structure you pass it, by virtue of a magic int code
* placed at the start of CplFileConf object by new_CplFileConf().
*/
typedef struct {
int escaped; /* Opposite to the argument of cfc_literal_escapes() */
int file_start; /* Equivalent to the argument of cfc_file_start() */
} CplFileArgs;
/*
* This initializes the deprecated CplFileArgs structures.
*/
void cpl_init_FileArgs(CplFileArgs *cfa);
/*.......................................................................
* When an error occurs while performing a completion, custom completion
* callback functions should register a terse description of the error
* by calling cpl_record_error(). This message will then be returned on
* the next call to cpl_last_error() and used by getline to display an
* error message to the user.
*
* Input:
* cpl WordCompletion * The string-completion resource object that was
* originally passed to the callback.
* errmsg const char * The description of the error.
*/
void cpl_record_error(WordCompletion *cpl, const char *errmsg);
/*.......................................................................
* This function can be used to replace the builtin filename-completion
* function with one of the user's choice. The user's completion function
* has the option of calling the builtin filename-completion function
* if it believes that the token that it has been presented with is a
* filename (see cpl_file_completions() above).
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* data void * This is passed to match_fn() whenever it is
* called. It could, for example, point to a
* symbol table that match_fn() would look up
* matches in.
* match_fn CplMatchFn * The function that will identify the prefix
* to be completed from the input line, and
* report matching symbols.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_customize_completion(GetLine *gl, void *data, CplMatchFn *match_fn);
/*.......................................................................
* This function allows you to install alternate completion action
* functions or completion listing functions, or to change the
* completion function of an existing action of the same type. This
* should preferably be called before the first call to gl_get_line()
* so that the name of the action becomes defined before the user's
* configuration file is read.
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* data void * This is passed to match_fn() whenever it is
* called. It could, for example, point to a
* symbol table that match_fn() would look up
* matches in.
* match_fn CplMatchFn * The function that will identify the prefix
* to be completed from the input line, and
* report matching symbols.
* list_only int If non-zero, install an action that only lists
* possible completions, rather than attempting
* to perform the completion.
* name const char * The name with which users can refer to the
* binding in tecla configuration files.
* keyseq const char * The key sequence with which to invoke
* the binding. This should be specified in the
* same manner as key-sequences in tecla
* configuration files (eg. "M-^I").
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_completion_action(GetLine *gl, void *data, CplMatchFn *match_fn,
int list_only, const char *name, const char *keyseq);
/*.......................................................................
* Change the terminal (or stream) that getline interacts with.
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* input_fp FILE * The stdio stream to read from.
* output_fp FILE * The stdio stream to write to.
* term const char * The terminal type. This can be NULL if
* either or both of input_fp and output_fp don't
* refer to a terminal. Otherwise it should refer
* to an entry in the terminal information database.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_change_terminal(GetLine *gl, FILE *input_fp, FILE *output_fp,
const char *term);
/*.......................................................................
* The following functions can be used to save and restore the contents
* of the history buffer.
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* filename const char * The name of the new file to write to.
* comment const char * Extra information such as timestamps will
* be recorded on a line started with this
* string, the idea being that the file can
* double as a command file. Specify "" if
* you don't care. Be sure to specify the
* same string to both functions.
* max_lines int The maximum number of lines to save, or -1
* to save all of the lines in the history
* list.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_save_history(GetLine *gl, const char *filename, const char *comment,
int max_lines);
int gl_load_history(GetLine *gl, const char *filename, const char *comment);
/*
* Enumerate file-descriptor events that can be waited for.
*/
typedef enum {
GLFD_READ, /* Watch for data waiting to be read from a file descriptor */
GLFD_WRITE, /* Watch for ability to write to a file descriptor */
GLFD_URGENT /* Watch for urgent out-of-band data on the file descriptor */
} GlFdEvent;
/*
* The following enumeration is used for the return status of file
* descriptor event callbacks.
*/
typedef enum {
GLFD_ABORT, /* Cause gl_get_line() to abort with an error */
GLFD_REFRESH, /* Redraw the input line and continue waiting for input */
GLFD_CONTINUE /* Continue to wait for input, without redrawing the line */
} GlFdStatus;
/*.......................................................................
* On systems that have the select() system call, while gl_get_line()
* is waiting for terminal input, it can also be asked to listen for
* activity on arbitrary file descriptors. Callback functions of the
* following type can be registered to be called when activity is
* seen. If your callback needs to write to the terminal or use
* signals, please see the gl_get_line(3) man page.
*
* Input:
* gl GetLine * The gl_get_line() resource object. You can use
* this safely to call gl_watch_fd() or
* gl_inactivity_timeout(). The effect of calling other
* functions that take a gl argument is undefined,
* and must be avoided.
* data void * A pointer to arbitrary callback data, as originally
* registered with gl_watch_fd().
* fd int The file descriptor that has activity.
* event GlFdEvent The activity seen on the file descriptor. The
* inclusion of this argument allows the same
* callback to be registered for multiple events.
* Output:
* return GlFdStatus GLFD_ABORT - Cause gl_get_line() to abort with
* an error (set errno if you need it).
* GLFD_REFRESH - Redraw the input line and continue
* waiting for input. Use this if you
* wrote something to the terminal.
* GLFD_CONTINUE - Continue to wait for input, without
* redrawing the line.
*/
#define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, void *data, int fd, \
GlFdEvent event)
typedef GL_FD_EVENT_FN(GlFdEventFn);
/*.......................................................................
* Where possible, register a function and associated data to be called
* whenever a specified event is seen on a file descriptor.
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* fd int The file descriptor to watch.
* event GlFdEvent The type of activity to watch for.
* callback GlFdEventFn * The function to call when the specified
* event occurs. Setting this to 0 removes
* any existing callback.
* data void * A pointer to arbitrary data to pass to the
* callback function.
* Output:
* return int 0 - OK.
* 1 - Either gl==NULL, or this facility isn't
* available on the the host system
* (ie. select() isn't available). No
* error message is generated in the latter
* case.
*/
int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event,
GlFdEventFn *callback, void *data);
/*
* Enumerators from the following list are returned by activity
* timeout callbacks registered by gl_inactivity_timeout(). They tell
* gl_get_line() whether and how to procede.
*/
typedef enum {
GLTO_ABORT, /* Cause gl_get_line() to abort with an error */
GLTO_REFRESH, /* Redraw the input line and continue waiting for input */
GLTO_CONTINUE /* Continue to wait for input, without redrawing the line */
} GlAfterTimeout;
/*.......................................................................
* On systems that have the select() system call, the application has
* the option of providing a callback function of the following type,
* which is called whenever no terminal input or other I/O activity is
* seen for the timeout duration specified in the last call to
* gl_inactivity_timeout().
*
* Input:
* gl GetLine * The gl_get_line() resource object. You can use
* this safely to call gl_watch_fd() or
* gl_inactivity_timeout(). The effect of calling other
* functions that take a gl argument is undefined,
* and must be avoided.
* data void * A pointer to arbitrary callback data, as
* originally registered with gl_inactivity_timeout().
* Output:
* return GlAfterTimeout GLTO_ABORT - Cause gl_get_line() to
* abort with an error (set
* errno if you need it).
* GLTO_REFRESH - Redraw the input line and
* continue waiting for
* input. Use this if you
* wrote something to the
* terminal.
* GLTO_CONTINUE - Continue to wait for
* input, without redrawing
* the line.
*/
#define GL_TIMEOUT_FN(fn) GlAfterTimeout (fn)(GetLine *gl, void *data)
typedef GL_TIMEOUT_FN(GlTimeoutFn);
/*.......................................................................
* On systems with the select() system call, the gl_inactivity_timeout()
* function provides the option of setting (or cancelling) an
* inactivity timeout. Inactivity, in this case, refers both to
* terminal input received from the user, and to I/O on any file
* descriptors registered by calls to gl_watch_fd(). If at any time,
* no activity is seen for the requested time period, the specified
* timeout callback function is called. On returning, this callback
* returns a code which tells gl_get_line() what to do next. Note that
* each call to gl_inactivity_timeout() replaces any previously installed
* timeout callback, and that specifying a callback of 0, turns off
* inactivity timing.
*
* Beware that although the timeout argument includes a nano-second
* component, few computer clocks presently have resolutions finer
* than a few milliseconds, so asking for less than a few milliseconds
* is equivalent to zero on a lot of systems.
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* callback GlTimeoutFn * The function to call when the inactivity
* timeout is exceeded. To turn off
* inactivity timeouts altogether, send 0.
* data void * A pointer to arbitrary data to pass to the
* callback function.
* sec unsigned long The number of whole seconds in the timeout.
* nsec unsigned long The fractional number of seconds in the
* timeout, expressed in nano-seconds (see
* the caveat above).
* Output:
* return int 0 - OK.
* 1 - Either gl==NULL, or this facility isn't
* available on the the host system
* (ie. select() isn't available). No
* error message is generated in the latter
* case.
*/
int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *timeout_fn, void *data,
unsigned long sec, unsigned long nsec);
/*.......................................................................
* Switch history streams. History streams represent separate history
* lists recorded within a single history buffer. Different streams
* are distinguished by integer identifiers chosen by the calling
* appplicaton. Initially new_GetLine() sets the stream identifier to
* 0. Whenever a new line is appended to the history list, the current
* stream identifier is recorded with it, and history lookups only
* consider lines marked with the current stream identifier.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* id unsigned The new history stream identifier.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_group_history(GetLine *gl, unsigned id);
/*.......................................................................
* Display the contents of the history list.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* fp FILE * The stdio output stream to write to.
* fmt const char * A format string. This containing characters to be
* written verbatim, plus any of the following
* format directives:
* %D - The date, formatted like 2001-11-20
* %T - The time of day, formatted like 23:59:59
* %N - The sequential entry number of the
* line in the history buffer.
* %G - The number of the history group that
* the line belongs to.
* %% - A literal % character.
* %H - The history line itself.
* Note that a '\n' newline character is not
* appended by default.
* all_groups int If true, display history lines from all
* history groups. Otherwise only display
* those of the current history group.
* max_lines int If max_lines is < 0, all available lines
* are displayed. Otherwise only the most
* recent max_lines lines will be displayed.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_show_history(GetLine *gl, FILE *fp, const char *fmt, int all_groups,
int max_lines);
/*.......................................................................
* Resize or delete the history buffer.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* bufsize size_t The number of bytes in the history buffer, or 0
* to delete the buffer completely.
* Output:
* return int 0 - OK.
* 1 - Insufficient memory (the previous buffer
* will have been retained). No error message
* will be displayed.
*/
int gl_resize_history(GetLine *gl, size_t bufsize);
/*.......................................................................
* Set an upper limit to the number of lines that can be recorded in the
* history list, or remove a previously specified limit.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* max_lines int The maximum number of lines to allow, or -1 to
* cancel a previous limit and allow as many lines
* as will fit in the current history buffer size.
*/
void gl_limit_history(GetLine *gl, int max_lines);
/*.......................................................................
* Discard either all historical lines, or just those associated with the
* current history group.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* all_groups int If true, clear all of the history. If false,
* clear only the stored lines associated with the
* currently selected history group.
*/
void gl_clear_history(GetLine *gl, int all_groups);
/*.......................................................................
* Temporarily enable or disable the gl_get_line() history mechanism.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* enable int If true, turn on the history mechanism. If
* false, disable it.
*/
void gl_toggle_history(GetLine *gl, int enable);
/*
* Objects of the following type are returned by gl_terminal_size().
*/
typedef struct {
int nline; /* The terminal has nline lines */
int ncolumn; /* The terminal has ncolumn columns */
} GlTerminalSize;
/*.......................................................................
* Update if necessary, and return the current size of the terminal.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* def_ncolumn int If the number of columns in the terminal
* can't be determined, substitute this number.
* def_nline int If the number of lines in the terminal can't
* be determined, substitute this number.
* Output:
* return GlTerminalSize The current terminal size.
*/
GlTerminalSize gl_terminal_size(GetLine *gl, int def_ncolumn, int def_nline);
/*.......................................................................
* Tell gl_get_line() the current terminal size. Note that this is only
* necessary on systems where changes in terminal size aren't reported
* via SIGWINCH.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* ncolumn int The number of columns in the terminal.
* nline int The number of rows in the terminal.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_set_term_size(GetLine *gl, int ncolumn, int nline);
/*
* The gl_lookup_history() function returns information in an
* argument of the following type.
*/
typedef struct {
const char *line; /* The requested history line */
unsigned group; /* The history group to which the */
/* line belongs. */
time_t timestamp; /* The date and time at which the */
/* line was originally entered. */
} GlHistoryLine;
/*.......................................................................
* Lookup a history line by its sequential number of entry in the
* history buffer.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* id unsigned long The identification number of the line to
* be returned, where 0 denotes the first line
* that was entered in the history list, and
* each subsequently added line has a number
* one greater than the previous one. For
* the range of lines currently in the list,
* see the gl_range_of_history() function.
* Input/Output:
* line GlHistoryLine * A pointer to the variable in which to
* return the details of the line.
* Output:
* return int 0 - The line is no longer in the history
* list, and *line has not been changed.
* 1 - The requested line can be found in
* *line. Note that the string in
* line->line is part of the history
* buffer and will change, so a private
* copy should be made if you wish to
* use it after subsequent calls to any
* functions that take gl as an argument.
*/
int gl_lookup_history(GetLine *gl, unsigned long id, GlHistoryLine *line);
/*
* The gl_state_of_history() function returns information in an argument
* of the following type.
*/
typedef struct {
int enabled; /* True if history is enabled */
unsigned group; /* The current history group */
int max_lines; /* The current upper limit on the number of lines */
/* in the history list, or -1 if unlimited. */
} GlHistoryState;
/*.......................................................................
* Query the state of the history list. Note that any of the input/output
* pointers can be specified as NULL.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Input/Output:
* state GlHistoryState * A pointer to the variable in which to record
* the return values.
*/
void gl_state_of_history(GetLine *gl, GlHistoryState *state);
/*
* The gl_range_of_history() function returns information in an argument
* of the following type.
*/
typedef struct {
unsigned long oldest; /* The sequential entry number of the oldest */
/* line in the history list. */
unsigned long newest; /* The sequential entry number of the newest */
/* line in the history list. */
int nlines; /* The number of lines in the history list */
} GlHistoryRange;
/*.......................................................................
* Query the number and range of lines in the history buffer.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* range GlHistoryRange * A pointer to the variable in which to record
* the return values. If range->nline=0, the
* range of lines will be given as 0-0.
*/
void gl_range_of_history(GetLine *gl, GlHistoryRange *range);
/*
* The gl_size_of_history() function returns information in an argument
* of the following type.
*/
typedef struct {
size_t size; /* The size of the history buffer (bytes) */
size_t used; /* The number of bytes of the history buffer */
/* that are currently occupied. */
} GlHistorySize;
/*.......................................................................
* Return the size of the history buffer and the amount of the
* buffer that is currently in use.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Input/Output:
* GlHistorySize size * A pointer to the variable in which to return
* the results.
*/
void gl_size_of_history(GetLine *gl, GlHistorySize *size);
/*.......................................................................
* Enable or disable the automatic addition of newly entered lines to the
* history list.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* enable int If true, subsequently entered lines will
* automatically be added to the history list
* before they are returned to the caller of
* gl_get_line(). If 0, the choice of how and
* when to archive lines in the history list,
* is left up to the calling application, which
* can do so via calls to gl_append_history().
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_automatic_history(GetLine *gl, int enable);
/*.......................................................................
* Append a specified line to the history list.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* line const char * The line to be added.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_append_history(GetLine *gl, const char *line);
/*.......................................................................
* Specify whether text that users type should be displayed or hidden.
* In the latter case, only the prompt is displayed, and the final
* input line is not archived in the history list.
*
* Input:
* gl GetLine * The input-line history maintenance object.
* enable int 0 - Disable echoing.
* 1 - Enable echoing.
* -1 - Just query the mode without changing it.
* Output:
* return int The echoing disposition that was in effect
* before this function was called:
* 0 - Echoing was disabled.
* 1 - Echoing was enabled.
*/
int gl_echo_mode(GetLine *gl, int enable);
/*.......................................................................
* This function can be called from gl_get_line() callbacks to have
* the prompt changed when they return. It has no effect if gl_get_line()
* is not currently being invoked.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* prompt const char * The new prompt.
*/
void gl_replace_prompt(GetLine *gl, const char *prompt);
/*
* Enumerate the available prompt formatting styles.
*/
typedef enum {
GL_LITERAL_PROMPT, /* Display the prompt string literally */
GL_FORMAT_PROMPT /* The prompt string can contain any of the */
/* following formatting directives: */
/* %B - Display subsequent characters */
/* with a bold font. */
/* %b - Stop displaying characters */
/* with the bold font. */
/* %U - Underline subsequent characters. */
/* %u - Stop underlining characters. */
/* %S - Highlight subsequent characters */
/* (also known as standout mode). */
/* %s - Stop highlighting characters */
/* %% - Display a single % character. */
} GlPromptStyle;
/*.......................................................................
* Specify whether to heed text attribute directives within prompt
* strings.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* style GlPromptStyle The style of prompt (see the definition of
* GlPromptStyle in libtecla.h for details).
*/
void gl_prompt_style(GetLine *gl, GlPromptStyle style);
/*.......................................................................
* Remove a signal from the list of signals that gl_get_line() traps.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* signo int The number of the signal to be ignored.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_ignore_signal(GetLine *gl, int signo);
/*
* A bitwise union of the following enumerators is passed to
* gl_trap_signal() to specify the environment in which the
* application's signal handler is to be called.
*/
typedef enum {
GLS_RESTORE_SIG=1, /* Restore the caller's signal environment */
/* while handling the signal. */
GLS_RESTORE_TTY=2, /* Restore the caller's terminal settings */
/* while handling the signal. */
GLS_RESTORE_LINE=4, /* Move the cursor to the start of the next line */
GLS_REDRAW_LINE=8, /* Redraw the input line when the signal handler */
/* returns. */
GLS_UNBLOCK_SIG=16, /* Normally a signal who's delivery is found to */
/* be blocked by the calling application is not */
/* trapped by gl_get_line(). Including this flag */
/* causes it to be temporarily unblocked and */
/* trapped while gl_get_line() is executing. */
GLS_DONT_FORWARD=32,/* Don't forward the signal to the signal handler */
/* of the calling program. */
GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | GLS_REDRAW_LINE,
GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE
} GlSignalFlags;
/*
* The following enumerators are passed to gl_trap_signal() to tell
* it what to do after the application's signal handler has been called.
*/
typedef enum {
GLS_RETURN, /* Return the line as though the user had pressed the */
/* return key. */
GLS_ABORT, /* Cause gl_get_line() to return NULL */
GLS_CONTINUE /* After handling the signal, resume command line editing */
} GlAfterSignal;
/*.......................................................................
* Tell gl_get_line() how to respond to a given signal. This can be used
* both to override the default responses to signals that gl_get_line()
* normally catches and to add new signals to the list that are to be
* caught.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* signo int The number of the signal to be caught.
* flags unsigned A bitwise union of GlSignalFlags enumerators.
* after GlAfterSignal What to do after the application's signal
* handler has been called.
* errno_value int The value to set errno to.
* Output:
* return int 0 - OK.
* 1 - Insufficient memory to record the
* new signal disposition.
*/
int gl_trap_signal(GetLine *gl, int signo, unsigned flags,
GlAfterSignal after, int errno_value);
/*.......................................................................
* By default, gl_get_line() doesn't trap signals that are blocked
* when it is called. This default can be changed either on a
* per-signal basis by calling gl_trap_signal(), or on a global basis
* by calling this function. What this function does is add the
* GLS_UNBLOCK_SIG flag to all signals that are currently configured
* to be trapped by gl_get_line(), such that when subsequent calls to
* gl_get_line() wait for I/O, these signals are temporarily
* unblocked. This behavior is useful in non-blocking server-I/O mode,
* where it is used to avoid race conditions related to handling these
* signals externally to gl_get_line(). See the demonstration code in
* demo3.c, or the gl_handle_signal() man page for further
* information.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
*/
void gl_catch_blocked(GetLine *gl);
/*.......................................................................
* In server-I/O mode the terminal is left in raw mode between calls
* to gl_get_line(), so it is necessary for the application to install
* terminal restoring signal handlers for signals that could terminate
* or suspend the process, plus a terminal reconfiguration handler to
* be called when a process resumption signal is received, and finally
* a handler to be called when a terminal-resize signal is received.
*
* Since there are many signals that by default terminate or suspend
* processes, and different systems support different sub-sets of
* these signals, this function provides a convenient wrapper around
* sigaction() for assigning the specified handlers to all appropriate
* signals. It also arranges that when any one of these signals is
* being handled, all other catchable signals are blocked. This is
* necessary so that the specified signal handlers can safely call
* gl_raw_io(), gl_normal_io() and gl_update_size() without reentrancy
* issues.
*
* Input:
* term_handler void (*)(int) The signal handler to invoke when
* a process terminating signal is
* received.
* susp_handler void (*)(int) The signal handler to invoke when
* a process suspending signal is
* received.
* cont_handler void (*)(int) The signal handler to invoke when
* a process resumption signal is
* received (ie. SIGCONT).
* size_handler void (*)(int) The signal handler to invoke when
* a terminal-resize signal (ie. SIGWINCH)
* is received.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_tty_signals(void (*term_handler)(int), void (*susp_handler)(int),
void (*cont_handler)(int), void (*size_handler)(int));
/*.......................................................................
* Return the last signal that was caught by the most recent call to
* gl_get_line(), or -1 if no signals were caught. This is useful if
* gl_get_line() returns errno=EINTR and you need to find out what signal
* caused it to abort.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Output:
* return int The last signal caught by the most recent
* call to gl_get_line(), or -1 if no signals
* were caught.
*/
int gl_last_signal(GetLine *gl);
/*.......................................................................
* Return the signal mask used by gl_get_line(). This is the set of
* signals that gl_get_line() is currently configured to trap.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Input/Output:
* set sigset_t * The set of signals will be returned in *set,
* in the form of a signal process mask, as
* used by sigaction(), sigprocmask(),
* sigpending(), sigsuspend(), sigsetjmp() and
* other standard POSIX signal-aware
* functions.
* Output:
* return int 0 - OK.
* 1 - Error (examine errno for reason).
*/
int gl_list_signals(GetLine *gl, sigset_t *set);
/*.......................................................................
* Respond to signals who's default effects have important
* consequences to gl_get_line(). This is intended for use in
* non-blocking server mode, where the external event loop is
* responsible for catching signals. Signals that are handled include
* those that by default terminate or suspend the process, and the
* signal that indicates that the terminal size has changed. Note that
* this function is not signal safe and should thus not be called from
* a signal handler itself. See the gl_io_mode() man page for how it
* should be used.
*
* In the case of signals that by default terminate or suspend
* processes, command-line editing will be suspended, the terminal
* returned to a usable state, then the default disposition of the
* signal restored and the signal resent, in order to suspend or
* terminate the process. If the process subsequently resumes,
* command-line editing is resumed.
*
* In the case of signals that indicate that the terminal has been
* resized, the new size will be queried, and any input line that is
* being edited will be redrawn to fit the new dimensions of the
* terminal.
*
* Input:
* signo int The number of the signal to respond to.
* gl GetLine * The first element of an array of 'ngl' GetLine
* objects.
* ngl int The number of elements in the gl[] array. Normally
* this will be one.
*/
void gl_handle_signal(int signo, GetLine *gl, int ngl);
/*.......................................................................
* Return extra information (ie. in addition to that provided by errno)
* about the last error to occur in either gl_get_line() or its
* associated public functions.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Input/Output:
* buff char * An optional output buffer. Note that if the
* calling application calls any gl_*()
* functions from signal handlers, it should
* provide a buffer here, so that a copy of
* the latest error message can safely be made
* while signals are blocked.
* n size_t The allocated size of buff[].
* Output:
* return const char * A pointer to the error message. This will
* be the buff argument, unless buff==NULL, in
* which case it will be a pointer to an
* internal error buffer. In the latter case,
* note that the contents of the returned buffer
* will change on subsequent calls to any gl_*()
* functions.
*/
const char *gl_error_message(GetLine *gl, char *buff, size_t n);
/*.......................................................................
* Clear the terminal and leave the cursor at the home position. In
* server I/O mode, arrange for the input line to be redrawn from scratch
* when gl_get_line() is next called.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_erase_terminal(GetLine *gl);
/*.......................................................................
* Display a left-justified string over multiple terminal lines,
* taking account of the current width of the terminal. Optional
* indentation and an optional prefix string can be specified to be
* displayed at the start of each new terminal line used. Similarly,
* an optional suffix can be specified to be displayed at the end of
* each terminal line. If needed, a single paragraph can be broken
* across multiple calls. Note that literal newlines in the input
* string can be used to force a newline at any point and that you
* should use this feature to explicitly end all paragraphs, including
* at the end of the last string that you write. Note that when a new
* line is started between two words that are separated by spaces,
* those spaces are not output, whereas when a new line is started
* because a newline character was found in the string, only the
* spaces before the newline character are discarded.
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* indentation int The number of spaces of indentation to write
* at the beginning of each new terminal line.
* prefix const char * An optional prefix string to write after the
* indentation margin at the start of each new
* terminal line. You can specify NULL if no
* prefix is required.
* suffix const char * An optional suffix string to draw at the end
* of the terminal line. Spaces will be added
* where necessary to ensure that the suffix ends
* in the last column of the terminal line. If
* no suffix is desired, specify NULL.
* fill_char int The padding character to use when indenting
* the line or padding up to the suffix.
* def_width int If the terminal width isn't known, such as when
* writing to a pipe or redirecting to a file,
* this number specifies what width to assume.
* start int The number of characters already written to
* the start of the current terminal line. This
* is primarily used to allow individual
* paragraphs to be written over multiple calls
* to this function, but can also be used to
* allow you to start the first line of a
* paragraph with a different prefix or
* indentation than those specified above.
* string const char * The string to be written.
* Output:
* return int On error -1 is returned. Otherwise the
* return value is the terminal column index at
* which the cursor was left after writing the
* final word in the string. Successful return
* values can thus be passed verbatim to the
* 'start' arguments of subsequent calls to
* gl_display_text() to allow the printing of a
* paragraph to be broken across multiple calls
* to gl_display_text().
*/
int gl_display_text(GetLine *gl, int indentation, const char *prefix,
const char *suffix, int fill_char, int def_width,
int start, const char *string);
/*
* Enumerate the I/O modes supported by gl_get_line().
*/
typedef enum {
GL_NORMAL_MODE, /* Normal line-at-a-time mode using gl_get_line()'s */
/* internal event loop. */
GL_SERVER_MODE /* Non-blocking server mode, driven by an external */
/* event loop. */
} GlIOMode;
/*.......................................................................
* Select the I/O mode to be used by gl_get_line().
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* mode GlIOMode The I/O mode to establish. Note that
* when server mode, the terminal is placed
* in raw mode, as though gl_raw_io() had
* been called.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_io_mode(GetLine *gl, GlIOMode mode);
/*.......................................................................
* In server mode, this function configures the terminal for non-blocking
* raw terminal I/O. In normal I/O mode it does nothing.
*
* Callers of this function must be careful to trap all signals that
* terminate or suspend the program, and call gl_normal_io()
* from the corresponding signal handlers in order to restore the
* terminal to its original settings before the program is terminated
* or suspended. They should also trap the SIGCONT signal to detect
* when the program resumes, and ensure that its signal handler
* call gl_raw_io() to redisplay the line and resume editing.
*
* Input:
* gl GetLine * The line editor resource object.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_raw_io(GetLine *gl);
/*.......................................................................
* Restore the terminal to the state that it had when gl_raw_io() was
* last called. After calling gl_raw_io(), this function must be called
* before terminating or suspending the program, and before attempting
* other uses of the terminal from within the program. See gl_raw_io()
* for more details.
*
* Input:
* gl GetLine * The line editor resource object.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_normal_io(GetLine *gl);
/*.......................................................................
* When in non-blocking server mode, this function can be used to abandon
* the current incompletely entered input line, and prepare to start
* editing a new line on the next call to gl_get_line().
*
* Input:
* gl GetLine * The line editor resource object.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
void gl_abandon_line(GetLine *gl);
/*
* Enumerators of the following type are used to report why
* gl_get_line() returned. This is most useful in non-blocking
* server mode, since in that mode a NULL return value can mean
* either that an error occurred, or that I/O blocked.
*/
typedef enum {
GLR_NEWLINE, /* A new input line was returned */
GLR_BLOCKED, /* The terminal was in non-blocking mode, and input */
/* or output would have blocked. */
GLR_SIGNAL, /* A signal caused gl_get_line() to return. */
GLR_TIMEOUT, /* An application timeout callback returned GLTO_ABORT */
GLR_FDABORT, /* An application I/O callack returned GLFD_ABORT */
GLR_EOF, /* End of file reached */
GLR_ERROR /* An unexpected error caused gl_get_line() to abort */
} GlReturnStatus;
/*.......................................................................
* Ask gl_get_line() what caused it to return.
*
* Input:
* gl GetLine * The line editor resource object.
* Output:
* return GlReturnStatus The return status of the last call to
* gl_get_line().
*/
GlReturnStatus gl_return_status(GetLine *gl);
/*
* Enumerate the types of I/O that gl_get_line() can be waiting for
* in non-blocking sedrver I/O mode.
*/
typedef enum {
GLP_READ, /* gl_get_line() is waiting to write to the terminal */
GLP_WRITE /* gl_get_line() is waiting to read from the terminal */
} GlPendingIO;
/*.......................................................................
* In non-blocking server-I/O mode, this function should be called
* from the application's external event loop to see what type of
* terminal I/O is being waited for by gl_get_line(), and thus what
* direction of I/O to wait for with select() or poll().
*
* Input:
* gl GetLine * The resource object of gl_get_line().
* Output:
* return GlPendingIO The type of pending I/O being waited for.
*/
GlPendingIO gl_pending_io(GetLine *gl);
/*
* The following enumerators are returned by externally defined action
* functions to tell gl_get_line() how to procede after the action
* function returns.
*/
typedef enum {
GLA_ABORT, /* Cause gl_get_line() to return NULL */
GLA_RETURN, /* Return the line as though the user had pressed the */
/* return key. */
GLA_CONTINUE /* Resume command-line editing */
} GlAfterAction;
/*.......................................................................
* Functions of the following form implement external
* application-specific action functions, which can then be bound to
* sequences of terminal keys.
*
* Input:
* gl GetLine * The line editor resource object.
* data void * The anonymous 'data' argument that was
* passed to gl_external_action() when the
* callback function was registered.
* count int A positive repeat count specified by the user,
* or 1 if not specified. Action functions should
* ignore this if repeating the action multiple
* times isn't appropriate. Alternatively they
* can interpret it as a general numeric
* argument.
* curpos size_t The position of the cursor within the input
* line, expressed as the index of the
* corresponding character within the line[]
* array.
* line const char * A read-only copy of the current input line.
* Output
* return GlAfterAction What should gl_get_line() do when the action
* function returns?
* GLA_ABORT - Cause gl_get_line() to
* abort with an error (set
* errno if you need it).
* GLA_RETURN - Return the input line as
* though the user had typed
* the return key.
* GLA_CONTINUE - Resume waiting for keyboard
* input.
*/
#define GL_ACTION_FN(fn) GlAfterAction (fn)(GetLine *gl, void *data, \
int count, size_t curpos, const char *line)
typedef GL_ACTION_FN(GlActionFn);
/*.......................................................................
* Register an application-provided function as an action function.
* This should preferably be called before the first call to gl_get_line()
* so that the name of the action becomes defined before the user's
* configuration file is read.
*
* Input:
* gl GetLine * The resource object of the command-line input
* module.
* data void * Arbitrary application-specific callback
* data to be passed to the callback
* function, fn().
* fn GlActionFn * The application-specific function that
* implements the action. This will be invoked
* whenever the user presses any
* key-sequence which is bound to this action.
* name const char * The name with which users can refer to the
* binding in tecla configuration files.
* keyseq const char * The key sequence with which to invoke
* the binding. This should be specified in the
* same manner as key-sequences in tecla
* configuration files (eg. "M-^I").
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int gl_register_action(GetLine *gl, void *data, GlActionFn *fn,
const char *name, const char *keyseq);
/*.......................................................................
* This function is designed to be called by CPL_MATCH_FN() callback
* functions. It adds one possible completion of the token that is being
* completed to an array of completions. If the completion needs any
* special quoting to be valid when displayed in the input line, this
* quoting must be included in the string.
*
* Input:
* cpl WordCompletion * The argument of the same name that was passed
* to the calling CPL_MATCH_FN() callback function.
* line const char * The input line, as received by the callback
* function.
* word_start int The index within line[] of the start of the
* word that is being completed. If an empty
* string is being completed, set this to be
* the same as word_end.
* word_end int The index within line[] of the character which
* follows the incomplete word, as received by the
* callback function.
* suffix const char * The appropriately quoted string that could
* be appended to the incomplete token to complete
* it. A copy of this string will be allocated
* internally.
* type_suffix const char * When listing multiple completions, gl_get_line()
* appends this string to the completion to indicate
* its type to the user. If not pertinent pass "".
* Otherwise pass a literal or static string.
* cont_suffix const char * If this turns out to be the only completion,
* gl_get_line() will append this string as
* a continuation. For example, the builtin
* file-completion callback registers a directory
* separator here for directory matches, and a
* space otherwise. If the match were a function
* name you might want to append an open
* parenthesis, etc.. If not relevant pass "".
* Otherwise pass a literal or static string.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int cpl_add_completion(WordCompletion *cpl, const char *line,
int word_start, int word_end, const char *suffix,
const char *type_suffix, const char *cont_suffix);
/*
* Each possible completion string is recorded in an array element of
* the following type.
*/
typedef struct {
char *completion; /* The matching completion string */
char *suffix; /* The pointer into completion[] at which the */
/* string was extended. */
const char *type_suffix; /* A suffix to be added when listing completions */
/* to indicate the type of the completion. */
} CplMatch;
/*
* Completions are returned in a container of the following form.
*/
typedef struct {
char *suffix; /* The common initial part of all of the */
/* completion suffixes. */
const char *cont_suffix; /* Optional continuation string to be appended to */
/* the sole completion when nmatch==1. */
CplMatch *matches; /* The array of possible completion strings, */
/* sorted into lexical order. */
int nmatch; /* The number of elements in matches[] */
} CplMatches;
/*.......................................................................
* Given an input line and the point at which completion is to be
* attempted, return an array of possible completions.
*
* Input:
* cpl WordCompletion * The word-completion resource object.
* line const char * The current input line.
* word_end int The index of the character in line[] which
* follows the end of the token that is being
* completed.
* data void * Anonymous 'data' to be passed to match_fn().
* match_fn CplMatchFn * The function that will identify the prefix
* to be completed from the input line, and
* record completion suffixes.
* Output:
* return CplMatches * The container of the array of possible
* completions. The returned pointer refers
* to a container owned by the parent Completion
* object, and its contents thus potentially
* change on every call to cpl_complete_word().
*/
CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
int word_end, void *data,
CplMatchFn *match_fn);
/*.......................................................................
* Recall the return value of the last call to cpl_complete_word().
*
* Input:
* cpl WordCompletion * The completion resource object.
* Output:
* return CplMatches * The container of the array of possible
* completions, as returned by the last call to
* cpl_complete_word(). The returned pointer refers
* to a container owned by the parent WordCompletion
* object, and its contents thus potentially
* change on every call to cpl_complete_word().
* On error, either in the execution of this
* function, or in the last call to
* cpl_complete_word(), NULL is returned, and a
* description of the error can be acquired by
* calling cpl_last_error(cpl).
*/
CplMatches *cpl_recall_matches(WordCompletion *cpl);
/*.......................................................................
* Print out an array of matching completions.
*
* Input:
* result CplMatches * The container of the sorted array of
* completions.
* fp FILE * The output stream to write to.
* term_width int The width of the terminal.
* Output:
* return int 0 - OK.
* 1 - Error.
*/
int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);
/*.......................................................................
* Return a description of the error that occurred on the last call to
* cpl_complete_word() or cpl_add_completion().
*
* Input:
* cpl WordCompletion * The string-completion resource object.
* Output:
* return const char * The description of the last error.
*/
const char *cpl_last_error(WordCompletion *cpl);
/*
* PathCache objects encapsulate the resources needed to record
* files of interest from comma-separated lists of directories.
*/
typedef struct PathCache PathCache;
/*.......................................................................
* Create an object who's function is to maintain a cache of filenames
* found within a list of directories, and provide quick lookup and
* completion of selected files in this cache.
*
* Output:
* return PathCache * The new, initially empty cache, or NULL
* on error.
*/
PathCache *new_PathCache(void);
/*.......................................................................
* Delete a given cache of files, returning the resources that it
* was using to the system.
*
* Input:
* pc PathCache * The cache to be deleted (can be NULL).
* Output:
* return PathCache * The deleted object (ie. allways NULL).
*/
PathCache *del_PathCache(PathCache *pc);
/*.......................................................................
* Return a description of the last path-caching error that occurred.
*
* Input:
* pc PathCache * The filename cache that suffered the error.
* Output:
* return char * The description of the last error.
*/
const char *pca_last_error(PathCache *pc);
/*.......................................................................
* Build the list of files of interest contained in a given
* colon-separated list of directories.
*
* Input:
* pc PathCache * The cache in which to store the names of
* the files that are found in the list of
* directories.
* path const char * A colon-separated list of directory
* paths. Under UNIX, when searching for
* executables, this should be the return
* value of getenv("PATH").
* Output:
* return int 0 - OK.
* 1 - An error occurred.
*/
int pca_scan_path(PathCache *pc, const char *path);
/*.......................................................................
* If you want subsequent calls to pca_lookup_file() and
* pca_path_completions() to only return the filenames of certain
* types of files, for example executables, or filenames ending in
* ".ps", call this function to register a file-selection callback
* function. This callback function takes the full pathname of a file,
* plus application-specific data, and returns 1 if the file is of
* interest, and zero otherwise.
*
* Input:
* pc PathCache * The filename cache.
* check_fn CplCheckFn * The function to call to see if the name of
* a given file should be included in the
* cache. This determines what type of files
* will reside in the cache. To revert to
* selecting all files, regardless of type,
* pass 0 here.
* data void * You can pass a pointer to anything you
* like here, including NULL. It will be
* passed to your check_fn() callback
* function, for its private use.
*/
void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, void *data);
/*.......................................................................
* Given the simple name of a file, search the cached list of files
* in the order in which they where found in the list of directories
* previously presented to pca_scan_path(), and return the pathname
* of the first file which has this name.
*
* Input:
* pc PathCache * The cached list of files.
* name const char * The name of the file to lookup.
* name_len int The length of the filename substring at the
* beginning of name[], or -1 to assume that the
* filename occupies the whole of the string.
* literal int If this argument is zero, lone backslashes
* in name[] are ignored during comparison
* with filenames in the cache, under the
* assumption that they were in the input line
* soley to escape the special significance of
* characters like spaces. To have them treated
* as normal characters, give this argument a
* non-zero value, such as 1.
* Output:
* return char * The pathname of the first matching file,
* or NULL if not found. Note that the returned
* pointer points to memory owned by *pc, and
* will become invalid on the next call.
*/
char *pca_lookup_file(PathCache *pc, const char *name, int name_len,
int literal);
/*
* Objects of the following type can be used to change the default
* behavior of the pca_path_completions() callback function.
*/
typedef struct PcaPathConf PcaPathConf;
/*
* pca_path_completions() is a completion callback function for use directly
* with cpl_complete_word() or gl_customize_completions(), or indirectly
* from your own completion callback function. It requires that a PcaPathConf
* object be passed via its 'void *data' argument (see below).
*/
CPL_MATCH_FN(pca_path_completions);
/*.......................................................................
* Allocate and initialize a pca_path_completions() configuration object.
*
* Input:
* pc PathCache * The filename cache in which to look for
* file name completions.
* Output:
* return PcaPathConf * The new configuration structure, or NULL
* on error.
*/
PcaPathConf *new_PcaPathConf(PathCache *pc);
/*.......................................................................
* Deallocate memory, previously allocated by new_PcaPathConf().
*
* Input:
* ppc PcaPathConf * Any pointer previously returned by
* new_PcaPathConf() [NULL is allowed].
* Output:
* return PcaPathConf * The deleted structure (always NULL).
*/
PcaPathConf *del_PcaPathConf(PcaPathConf *ppc);
/*
* If backslashes in the prefix being passed to pca_path_completions()
* should be treated as literal characters, call the following function
* with literal=1. Otherwise the default is to treat them as escape
* characters which remove the special meanings of spaces etc..
*/
void ppc_literal_escapes(PcaPathConf *ppc, int literal);
/*
* Before calling pca_path_completions, call this function if you know
* the index at which the filename prefix starts in the input line.
* Otherwise by default, or if you specify start_index to be -1, the
* filename is taken to start after the first unescaped space preceding
* the cursor, or the start of the line, whichever comes first.
*/
void ppc_file_start(PcaPathConf *ppc, int start_index);
#ifdef __cplusplus
}
#endif
#endif