diff options
Diffstat (limited to 'libtecla-1.4.1/libtecla.h')
| -rw-r--r-- | libtecla-1.4.1/libtecla.h | 1194 |
1 files changed, 0 insertions, 1194 deletions
diff --git a/libtecla-1.4.1/libtecla.h b/libtecla-1.4.1/libtecla.h deleted file mode 100644 index f124dd0..0000000 --- a/libtecla-1.4.1/libtecla.h +++ /dev/null @@ -1,1194 +0,0 @@ -#ifndef libtecla_h -#define libtecla_h - -/* - * Copyright (c) 2000, 2001 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. - */ - -#ifdef __cplusplus -extern "C" { -#endif - -#include <stdio.h> /* FILE * */ -#include <stdlib.h> /* size_t */ -#include <time.h> /* time_t */ - -/* - * 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 4 -#define TECLA_MICRO_VER 1 - -/*....................................................................... - * 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); - -/* - * 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 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); - -/*....................................................................... - * 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; - -/*....................................................................... - * 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_watch_time(). 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); - -/*....................................................................... - * 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); - -/* - * 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); - -/*....................................................................... - * 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); - -/*....................................................................... - * 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(const GetLine *gl); - -/*....................................................................... - * 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_matches(). - */ -CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line, - int word_end, void *data, - CplMatchFn *match_fn); - -/*....................................................................... - * 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 |