diff options
| author | Eric Norum <WENorum@lbl.gov> | 2002-11-08 22:42:51 +0000 |
|---|---|---|
| committer | Eric Norum <WENorum@lbl.gov> | 2002-11-08 22:42:51 +0000 |
| commit | 156944090b3f839559c15982b206d3f663ae84fa (patch) | |
| tree | b50531a961befc4597e375c3c3f1c094637d06ad | |
| parent | 0c4c585ee84aec3e632dd0715993a95fe97a3247 (diff) | |
Add to CVS repository.
66 files changed, 9238 insertions, 0 deletions
diff --git a/libtecla-1.4.1/html/changes.html b/libtecla-1.4.1/html/changes.html new file mode 100644 index 0000000..b309a7b --- /dev/null +++ b/libtecla-1.4.1/html/changes.html @@ -0,0 +1,1495 @@ +<HEAD><TITLE>The tecla library change log</TITLE></HEAD> +<BODY bgcolor=add8e6><PRE> +In the following log, modification dates are listed using the European +convention in which the day comes before the month (ie. DD/MM/YYYY). +The most recent modifications are listed first. + +25/05/2002 mcs@astro.caltech.edu (based on suggestions by Paul Smith) + pathutil.c + Apparently, under QNX pathconf("/",_PC_PATH_MAX) returns + EINVAL. At Paul's suggestion I have modified the code to + silently substitute the existing MAX_PATHLEN_FALLBACK + value if pathconf() returns an error of any kind. + homedir.c + Under QNX, sysconf(_SC_GETPW_R_SIZE_MAX) also apparently + returns EINVAL, so as with pathconf() I modified the code + to substitute a fallback default, rather than + complaining and failing. + enhance.c + Paul told me that the inclusion of sys/termios.h was + causing compilation of enhance.c to fail under QNX. This + line is a bug. The correct thing to do is include + termios.h without a sub-directory prefix, as I was + already doing futher up in the file, so I have just + removed the errant include line. + +12/02/2002 mcs@astro.caltech.edu + getline.c configure.in configure + Mac OS X doesn't have a term.h or termcap.h, but it does + define prototypes for tputs() and setupterm(), so the + default prototypes that I was including if no headers + where available, upset it. I've removed these prototypes. + I also now conditionally include whichever is found of + curses.h and ncurses/curses.h for both termcap and + terminfo (before I wasn't including curses.h when + termcap was selected). + +12/02/2002 mcs@astro.caltech.edu + Updated version number to 1.4.1, ready for a micro + release. + +12/02/2002 mcs@astro.caltech.edu + html/index.html + Added Mac OS X and Cygwin to the list of systems that + can compile libtecla. + +12/02/2002 mcs@astro.caltech.edu + getline.c + Under Mac OS X, the tputs() callback function returns + void, instead of the int return value used by other + systems. This declaration is now used if both __MACH__ + and __APPLE__ are defined. Hopefully these are the + correct system macros to check. Thanks for Stephan + Fiedler for providing information on Mac OS X. + +11/02/2002 mcs@astro.caltech.edu + configure.in configure getline.c + Some systems don't have term.h, and others have it hidden + in an ncurses sub-directory of the standard system include + directory. If term.h can't be found, simply don't include + it. If it is in an ncurses sub-directory, include + ncurses/term.h instead of term.h. + +04/02/2002 mcs@astro.caltech.edu + configure.in configure Makefile.in Makefile.rules + Use ranlib on systems that need it (Mac OS X). Also, + make all components of the installation directories where + needed, instead of assuming that they exist. + +04/02/2002 mcs@astro.caltech.edu + getline.c + When the tab completion binding was unbound from the tab + key, hitting the tab key caused gl_get_line() to ring the + bell instead of inserting a tab character. This is + problematic when using the 'enhance' program with + Jython, since tabs are important in Python. I have + corrected this. + +10/12/2001 Version 1.4.0 released. + +10/12/2001 mcs@astro.caltech.edu + getline.c + If the TIOCGWINSZ ioctl doesn't work, as is the case when + running in an emacs shell, leave the size unchanged, rather + than returning a fatal error. + +07/12/2001 mcs@astro.caltech.edu + configure.in configure + Now that the configure version of CFLAGS is included in + the makefile, I noticed that the optimization flags -g + and -O2 had been added. It turns out that if CFLAGS isn't + already set, the autoconf AC_PROG_CC macro initializes it + with these two optimization flags. Since this would break + backwards compatibility in embedded distributions that + already use the OPT= makefile argument, and because + turning debugging on needlessly bloats the library, I now + make sure that CFLAGS is set before calling this macro. + +07/12/2001 mcs@astro.caltech.edu + enhance.c + Use argv[0] in error reports instead of using a + hardcoded macro. + +07/12/2001 mcs@astro.caltech.edu + getline.c + The cut buffer wasn't being cleared after being + used as a work buffer by gl_load_history(). + +06/12/2001 mcs@astro.caltech.edu + configure.in configure + I removed my now redundant definition of SUN_TPUTS from + CFLAGS. I also added "-I/usr/include" to CFLAGS under + Solaris to prevent gcc from seeing conflicting versions + of system header files in /usr/local/include. + +06/12/2001 Markus Gyger (logged here by mcs) + Lots of files. + Lots of corrections to misspellings and typos in the + comments. + getline.c + Markus reverted a supposed fix that I added a day or two + ago. I had incorrectly thought that in Solaris 8, Sun had + finally brought their declaration of the callback + function of tputs() into line with other systems, but it + turned out that gcc was pulling in a GNU version of + term.h from /usr/local/include, and this was what + confused me. + +05/12/2001 mcs@astro.caltech.edu + Makefile.in + I added @CFLAGS@ to the CFLAGS assignment, so that + if CFLAGS is set as an environment variable when + configure is run, the corresponding make variable + includes its values in the output makefile. + +05/12/2001 mcs@astro.caltech.edu + getline.c libtecla.h libtecla.map man3/gl_get_line.3 + man3/gl_last_signal.3 + I added a function that programs can use to find out + which signal caused gl_get_line() to return EINTR. + +05/12/2001 mcs@astro.caltech.edu + getline.c + When the newline action was triggered by a printable + character, it failed to display that character. It now + does. Also, extra control codes that I had added, to + clear to the end of the display after the carriage return, + but before displaying the prompt, were confusing expect + scripts, so I have removed them. This step is now done + instead in gl_redisplay() after displaying the full input + line. + +05/12/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + A user convinced me that continuing to invoke meta + keybindings for meta characters that are printable is a + bad idea, as is allowing users to ask to have setlocale() + called behind the application's back. I have thus changed + this. The setlocale configuration option has gone, and + gl_get_line() is now completely 8-bit clean, by default. + This means that if a meta character is printable, it is + treated as a literal character, rather than a potential + M-c binding. Meta bindings can still be invoked via + their Esc-c equivalents, and indeed most terminal + emulators either output such escape pairs by default when + the meta character is pressed, or can be configured to do + so. I have documented how to configure xterm to do this, + in the man page. + +03/12/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + gl_get_line() by default now prints any 8-bit printable + characters that don't match keybindings. Previously + characters > 127 were only printed if preceded by the + literal-next action. Alternatively, by placing the + command literal_if_printable in the tecla configuration + file, all printable characters are treated as literal + characters, even if they are bound to action functions. + + For international users of programs written by + programmers that weren't aware of the need to call + setlocale() to support alternate character sets, the + configuration file can now also contain the single-word + command "setlocale", which tells gl_get_line() to remedy + this. + +27/11/2001 mcs@astro.caltech.edu + demo.c demo2.c enhance man3/gl_get_line.3 + All demos and programs now call setlocale(LC_CTYPE,""). + This makes them support character sets of different + locales, where specified with the LC_CTYPE, LC_ALL, or + LANG environment variables. I also added this to the demo + in the man page, and documented its effect. + +27/11/2001 mcs@astro.caltech.edu + getline.c + When displaying unsigned characters with values over + 127 literally, previously it was assumed that they would + all be displayable. Now isprint() is consulted, and if it + says that a character isn't printable, the character code + is displayed in octal like \307. In non-C locales, some + characters with values > 127 are displayable, and + isprint() tells gl_get_line() which are and which aren't. + +27/11/2001 mcs@astro.caltech.edu + getline.c pathutil.c history.c enhance.c demo2.c + All arguments of the ctype.h character class functions + are now cast to (int)(unsigned char). Previously they + were cast to (int), which doesn't correctly conform to + the requirements of the C standard, and could cause + problems for characters with values > 127 on systems + with signed char's. + +26/11/2001 mcs@astro.caltech.edu + man3/enhance.3 man3/libtecla.3 + I started writing a man page for the enhance program. + +26/11/2001 mcs@astro.caltech.edu + Makefile.in Makefile.rules INSTALL + It is now possible to specify whether the demos and other + programs are to be built, by overriding the default + values of the DEMOS, PROGRAMS and PROGRAMS_R variables. + I have also documented the BINDIR variable and the + install_bin makefile target. + +22/11/2001 mcs@astro.caltech.edu + getline.c libtecla.h libtecla.map man3/gl_get_line.3 + man3/gl_ignore_signal.3 man3/gl_trap_signal.3 + Signal handling has now been modified to be customizable. + Signals that are trapped by default can be removed from + the list of trapped signals, and signals that aren't + currently trapped, can be added to the list. Applications + can also specify the signal and terminal environments in + which an application's signal handler is invoked, and + what gl_get_line() does after the signal handler returns. + +13/11/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + Added half-bright, reverse-video and blinking text to the + available prompt formatting options. + getline.c + Removed ^O from the default VT100 sgr0 capability + string. Apparently it can cause problems with some + terminal emulators, and we don't need it, since it turns + off the alternative character set mode, which we don't + use. + getline.c + gl_tigetstr() and gl_tgetstr() didn't guard against the + error returns of tigetstr() and tgetstr() respectively. + They now do. + +11/11/2001 mcs@astro.caltech.edu + getline.c libtecla.h libtecla.map man3/gl_get_line.3 + man3/gl_prompt_style.3 + Although the default remains to display the prompt string + literally, the new gl_prompt_style() function can be used + to enable text attribute formatting directives in prompt + strings, such as underlining, bold font, and highlighting + directives. + +09/11/2001 mcs@astro.caltech.edu + enhance.c Makefile.rules configure.in configure + I added a new program to the distribution that allows one + to run most third party programs with the tecla library + providing command-line editing. + +08/11/2001 mcs@astro.caltech.edu + libtecla.h getline.c man3/gl_get_line.3 history.c history.h + I added a max_lines argument to gl_show_history() and + _glh_show_history(). This can optionally be used to + set a limit on the number of history lines displayed. + libtecla.h getline.c man3/gl_get_line.3 + I added a new function called gl_replace_prompt(). This + can be used by gl_get_line() callback functions to + request that a new prompt be use when they return. + +06/11/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + I implemented, bound and documented the list-history + action, used for listing historical lines of the current + history group. + getline.c man3/gl_get_line.3 man3/gl_echo_mode.3 + I wrote functions to specify and query whether subsequent + lines will be visible as they are being typed. + +28/10/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + For those cases where a terminal provides its own + high-level terminal editing facilities, you can now + specify an edit-mode argument of 'none'. This disables + all tecla key bindings, and by using canonical terminal + input mode instead of raw input mode, editing is left up + to the terminal driver. + +21/10/2001 mcs@astro.caltech.edu + libtecla.h getline.c history.c history.h + man3/gl_get_line.3 man3/gl_history_info.3 + I added the new gl_state_of_history(), + gl_range_of_history() and gl_size_of_history() + functions for querying information about the + history list. + history.c + While testing the new gl_size_of_history() + function, I noticed that when the history buffer + wrapped, any location nodes of old lines between + the most recent line and the end of the buffer + weren't being removed. This could result in bogus + entries appearing at the start of the history list. + Now fixed. + +20/10/2001 mcs@astro.caltech.edu + + libtecla.h getline.c history.c history.h + man3/gl_get_line.3 man3/gl_lookup_history.3 + I added a function called gl_lookup_history(), that + the application can use to lookup lines in the history + list. + libtecla.h getline.c history.c history.h man3/gl_get_line.3 + gl_show_history() now takes a format string argument + to control how the line is displayed, and with what + information. It also now provides the option of either + displaying all history lines or just those of the + current history group. + getline.c man3/gl_get_line.3 + gl_get_line() only archives lines in the history buffer + if the newline action was invoked by a newline or + carriage return character. + +16/10/2001 mcs@astro.caltech.edu + + history.c history.h getline.c libtecla.h libtecla.map + man3/gl_get_line.3 man3/gl_resize_history.3 + man3/gl_limit_history.3 man3/gl_clear_history.3 + man3/gl_toggle_history.3 + I added a number of miscellaneous history configuration + functions. You can now resize or delete the history + buffer, limit the number of lines that are allowed in the + buffer, clear either all history or just the history of + the current history group, and temporarily enable and + disable the history mechanism. + +13/10/2001 mcs@astro.caltech.edu + + getline.c + tputs_fp is now only declared if using termcap or + terminfo. + getline.c libtecla.map man3/gl_get_line.3 + man3/gl_terminal_size.3 + I added a public gl_terminal_size() function for + updating and querying the current size of the terminal. + update_version configure.in libtecla.h + A user noted that on systems where the configure script + couldn't be used, it was inconvenient to have the version + number macros set by the configure script, so they are + now specified in libtecla.h. To reduce the likelihood + that the various files where the version number now + appears might get out of sync, I have written the + update_version script, which changes the version number + in all of these files to a given value. + +01/10/2001 mcs@astro.caltech.edu + + getline.c history.c history.h man3/gl_get_line.3 + I added a max_lines argument to gl_save_history(), to + allow people to optionally place a ceiling on the number + of history lines saved. Specifying this as -1 sets the + ceiling to infinity. + +01/10/2001 mcs@astro.caltech.edu + + configure.in configure + Under digital unix, getline wouldn't compile with + _POSIX_C_SOURCE set, due to type definitions needed by + select being excluded by this flag. Defining the + _OSF_SOURCE macro as well on this system, resolved this. + +30/09/2001 mcs@astro.caltech.edu + + getline.c libtecla.h history.c history.h man3/gl_get_line.3 + man3/gl_group_history.3 + I implemented history streams. History streams + effectively allow multiple history lists to be stored in + a single history buffer. Lines in the buffer are tagged + with the current stream identification number, and + lookups only consider lines that are marked with the + current stream identifier. + getline.c libtecla.h history.c history.h man3/gl_get_line.3 + man3/gl_show_history.3 + The new gl_show_history function displays the current + history to a given stdio output stream. + +29/09/2001 mcs@astro.caltech.edu + + getline.c + Previously new_GetLine() installed a persistent signal + handler to be sure to catch the SIGWINCH (terminal size + change) signal between calls to gl_get_line(). This had + the drawback that if multiple GetLine objects were + created, only the first GetLine object used after the + signal was received, would see the signal and adapt to + the new terminal size. Instead of this, a signal handler + for sigwinch is only installed while gl_get_line() is + running, and just after installing this handler, + gl_get_line() checks for terminal size changes that + might have occurred while the signal handler wasn't + installed. + getline.c + Dynamically allocated copies of capability strings looked + up in the terminfo or termcap databases are now made, so + that calls to setupterm() etc for one GetLine object + don't get trashed when another GetLine object calls + setupterm() etc. It is now safe to allocate and use + multiple GetLine objects, albeit only within a single + thread. + +28/09/2001 mcs@astro.caltech.edu + + version.c Makefile.rules + I added a function for querying the version number of + the library. + +26/09/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + I added the new gl_watch_fd() function, which allows + applications to register callback functions to be invoked + when activity is seen on arbitrary file descriptors while + gl_get_line() is awaiting keyboard input from the user. + + keytab.c + If a request is received to delete a non-existent + binding, which happens to be an ambiguous prefix of other + bindings no complaint is now generated about it being + ambiguous. + +23/09/2001 mcs@astro.caltech.edu + + getline.c history.c history.h man3/gl_get_line.3 + libtecla.map demo.c + I added new public functions for saving and restoring the + contents of the history list. The demo program now uses + these functions to load and save history in ~/.demo_history. + +23/09/2001 mcs@astro.caltech.edu + + getline.c + On trying the demo for the first time on a KDE konsole + terminal, I discovered that the default M-O binding + to repeat history was hiding the arrow keys, which are + M-OA etc. I have removed this binding. The M-o (ie the + lower case version of this), is still bound. + +18/09/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 libtecla.map + Automatic reading of ~/.teclarc is now postponed until + the first call to gl_get_line(), to give the application + the chance to specify alternative configuration sources + with the new function gl_configure_getline(). The latter + function allows configuration to be done with a string, a + specified application-specific file, and/or a specified + user-specific file. I also added a read-init-files action + function, for re-reading the configuration files, if any. + This is by default bound to ^X^R. This is all documented + in gl_get_line.3. + +08/09/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + It is now possible to bind actions to key-sequences + that start with printable characters. Previously + keysequences were required to start with meta or control + characters. This is documented in gl_get_line.3. + + getline.c man3/gl_get_line.3 + A customized completion function can now arrange for + gl_get_line() to return the current input line whenever a + successful completion has been made. This is signalled by + setting the last character of the optional continuation + suffix to a newline character. This is documented in + gl_get_line.3. + +05/07/2001 Bug reported by Mike MacFaden, fixed by mcs + + configure.in + There was a bug in the configure script that only + revealed itself on systems without termcap but not + terminfo (eg. NetBSD). I traced the bug back to a lack of + sufficient quoting of multi-line m4 macro arguments in + configure.in, and have now fixed this and recreated the + configure script. + +05/07/2001 Bug reported and patched by Mike MacFaden (patch modified + by mcs to match original intentions). + + getline.c + getline.c wouldn't compile when termcap was selected as + the terminal information database. setupterm() was being + passed a non-existent variable, in place of the term[] + argument of gl_control_strings(). Also if + gl_change_terminal() is called with term==NULL, "ansi" + is now substituted. + +02/07/2001 Version 1.3.3 released. + +27/06/2001 mcs@astro.caltech.edu + + getline.c expand.c cplmatch.c + Added checks to fprintf() statements that write to the + terminal. + getline.c + Move the cursor to the end of the line before suspending, + so that the cursor doesn't get left in the middle of the + input line. + Makefile.in + On systems that don't support shared libraries, the + distclean target of make deleted libtecla.h. This has + now been fixed. + getline.c + gl_change_terminal() was being called by gl_change_editor(), + with the unwanted side effect that raw terminal modes were + stored as those to be restored later, if called by an + action function. gl_change_terminal() was being called in + this case to re-establish terminal-specific key bindings, + so I have just split this part of the function out into + a separate function for both gl_change_editor() and + gl_change_terminal() to call. + +12/06/2001 mcs@astro.caltech.edu + + getline.c + Signal handling has been improved. Many more signals are + now trapped, and instead of using a simple flag set by a + signal handler, race conditions are avoided by blocking + signals during most of the gl_get_line() code, and + unblocking them via calls to sigsetjmp(), just before + attempting to read each new character from the user. + The matching use of siglongjmp() in the signal + handlers ensures that signals are reblocked correctly + before they are handled. In most cases, signals cause + gl_get_line() to restore the terminal modes and signal + handlers of the calling application, then resend the + signal to the application. In the case of SIGINT, SIGHUP, + SIGPIPE, and SIGQUIT, if the process still exists after + the signals are resent, gl_get_line() immediately returns + with appropriate values assigned to errno. If SIGTSTP, + SIGTTIN or SIGTTOU signals are received, the process is + suspended. If any other signal is received, and the + process continues to exist after the signal is resent to + the calling application, line input is resumed after the + terminal is put back into raw mode, the gl_get_line() + signal handling is restored, and the input line redrawn. + man/gl_get_line(3) + I added a SIGNAL HANDLING section to the gl_get_line() + man page, describing the new signal handling features. + +21/05/2001 Version 1.3.2 released. + +21/05/2001 mcs@astro.caltech.edu + + getline.c + When vi-replace-char was used to replace the character at + the end of the line, it left the cursor one character to + its right instead of on top of it. Now rememdied. + getline.c + When undoing, to properly emulate vi, the cursor is now + left at the leftmost of the saved and current cursor + positions. + getline.c man3/gl_get_line.3 + Implemented find-parenthesis (%), delete-to-paren (M-d%), + vi-change-to-paren (M-c%), copy-to-paren (M-y%). + cplfile.c pcache.c + In three places I was comparing the last argument of + strncmp() to zero instead of the return value of + strncmp(). + +20/05/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + Implemented and documented the vi-repeat-change action, + bound to the period key. This repeats the last action + that modified the input line. + +19/05/2001 mcs@astro.caltech.edu + + man3/gl_get_line.3 + I documented the new action functions and bindings + provided by Tim Eliseo, plus the ring-bell action and + the new "nobeep" configuration option. + getline.c + I modified gl_change_editor() to remove and reinstate the + terminal settings as well as the default bindings, since + these have editor-specific differences. I also modified + it to not abort if a key-sequence can't be bound for some + reason. This allows the new vi-mode and emacs-mode + bindings to be used safely. + getline.c + When the line was re-displayed on receipt of a SIGWINCH + signal, the result wasn't visible until the next + character was typed, since a call to fflush() was needed. + gl_redisplay_line() now calls gl_flush_output() to remedy + this. + +17/05/2001 mcs@astro.catlech.edu + + getline.c + Under Linux, calling fflush(gl->output_fd) hangs if + terminal output has been suspended with ^S. With the + tecla library taking responsability for reading the stop + and start characters this was a problem, because once + hung in fflush(), the keyboard input loop wasn't entered, + so the user couldn't type the start character to resume + output. To remedy this, I now have the terminal process + these characters, rather than the library. + +12/05/2001 mcs@astro.caltech.edu + + getline.c + The literal-next action is now implemented as a single + function which reads the next character itself. + Previously it just set a flag which effected the + interpretation of the next character read by the input + loop. + getline.c + Added a ring-bell action function. This is currently + unbound to any key by default, but it is used internally, + and can be used by users that want to disable any of the + default key-bindings. + +12/05/2001 Tim Eliseo (logged here by mcs) + + getline.c + Don't reset gl->number until after calling an action + function. By looking at whether gl->number is <0 or + not, action functions can then tell whether the count + that they were passed was explicitly specified by the + user, as opposed to being defaulted to 1. + getline.c + In vi, the position at which input mode is entered + acts as a barrier to backward motion for the few + backward moving actions that are enabled in input mode. + Tim added this barrier to getline. + getline.c + In gl_get_line() after reading an input line, or + having the read aborted by a signal, the sig_atomic_t + gl_pending_signal was being compared to zero instead + of -1 to see if no signals had been received. + gl_get_line() will thus have been calling raise(-1), + which luckily didn't seem to do anything. Tim also + arranged for errno to be set to EINTR when a signal + aborts gl_get_line(). + getline.c + The test in gl_add_char_to_line() for detecting + when overwriting a character with a wider character, + had a < where it needed a >. Overwriting with a wider + character thus overwrote trailing characters. Tim also + removed a redundant copy of the character into the + line buffer. + getline.c + gl_cursor_left() and gl->cursor_right() were executing + a lot of redundant code, when the existing call to the + recently added gl_place_cursor() function, does all that + is necessary. + getline.c + Remove redundant code from backward_kill_line() by + re-implimenting in terms of gl_place_cursor() and + gl_delete_chars(). + getline.c + gl_forward_delete_char() now records characters in cut + buffer when in vi command mode. + getline.c + In vi mode gl_backward_delete_char() now only deletes + up to the point at which input mode was entered. Also + gl_delete_chars() restores from the undo buffer when + deleting in vi insert mode. + getline.c + Added action functions, vi-delete-goto-column, + vi-change-to-bol, vi-change-line, emacs-mode, vi-mode, + vi-forward-change-find, vi-backward-change-find, + vi-forward-change-to, vi-backward-change-to, + vi-change-goto-col, forward-delete-find, backward-delete-find, + forward-delete-to, backward-delete-to, + delete-refind, delete-invert-refind, forward-copy-find, + backward-copy-find, forward-copy-to, backward-copy-to + copy-goto-column, copy-rest-of-line, copy-to-bol, copy-line, + history-re-search-forward, history-re-search-backward. + +06/05/2001 Version 1.3.1 released. + +03/05/2001 mcs@astro.caltech.edu + + configure.in + Old versions of GNU ld don't accept version scripts. + Under Linux I thus added a test to try out ld with + the --version-script argument to see if it works. + If not, version scripts aren't used. + configure.in + My test for versions of Solaris earlier than 7 + failed when confronted by a three figure version + number (2.5.1). Fixed. + +30/04/2001 mcs@astro.caltech.edu + + getline.c + In vi mode, history-search-backward and + history-search-forward weren't doing anything when + invoked at the start of an empty line, whereas + they should have acted like up-history and down-history. + Makefile.in Makefile.rules + When shared libraries are being created, the build + procedure now arranges for any alternate library + links to be created as well, before linking the + demos. Without this the demos always linked to the + static libraries (which was perfectly ok, but wasn't a + good example). + Makefile.in Makefile.rules + On systems on which shared libraries were being created, + if there were no alternate list of names, make would + abort due to a Bourne shell 'for' statement that didn't + have any arguments. Currently there are no systems who's + shared library configurations would trigger this + problem. + Makefile.rules + The demos now relink to take account of changes to the + library. + configure.in configure + When determining whether the reentrant version of the + library should be compiled by default, the configure + script now attempts to compile a dummy program that + includes all of the appropriate system headers and + defines _POSIX_C_SOURCE. This should now be a robust test + on systems which use C macros to alias these function + names to other internal functions. + configure.in + Under Solaris 2.6 and earlier, the curses library is in + /usr/ccs/lib. Gcc wasn't finding this. In addition to + remedying this, I had to remove "-z text" from + LINK_SHARED under Solaris to get it to successfully + compile the shared library against the static curses + library. + configure.in + Under Linux the -soname directive was being used + incorrectly, citing the fully qualified name of the + library instead of its major version alias. This will + unfortunately mean that binaries linked with the 1.2.3 + and 1.2.4 versions of the shared library won't use + later versions of the library unless relinked. + +30/04/2001 mcs@astro.caltech.edu + + getline.c + In gl_get_input_line(), don't redundantly copy the + start_line if start_line == gl->line. + +30/04/2001 Version 1.3.0 released. + +28/04/2001 mcs@astro.caltech.edu + + configure.in + I removed the --no-undefined directive from the Linux + LINK_SHARED command. After recent patches to our RedHat + 7.0 systems ld started reporting some internal symbols of + libc as being undefined. Using nm on libc indicated that + the offending symbols are indeed defined, albeit as + "common" symbols, so there appears to be a bug in + RedHat's ld. Removing this flag allows the tecla shared + library to compile, and programs appear to function fine. + man3/gl_get_line.3 + The default key-sequence used to invoke the + read-from-file action was incorrectly cited as ^Xi + instead of ^X^F. + +26/04/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + A new vi-style editing mode was added. This involved + adding many new action functions, adding support for + specifying editing modes in users' ~/.teclarc files, + writing a higher level cursor motion function to support + the different line-end bounds required in vi command + mode, and a few small changes to support the fact that vi + has two modes, input mode and command mode with different + bindings. + + When vi editing mode is enabled, any binding that starts + with an escape or a meta character, is interpreted as a + command-mode binding, and switches the library to vi + command mode if not already in that mode. Once in command + mode the first character of all keysequences entered + until input mode is re-enabled, are quietly coerced to + meta characters before being looked up in the key-binding + table. So, for example, in the key-binding table, the + standard vi command-mode 'w' key, which moves the cursor + one word to the right, is represented by M-w. This + emulates vi's dual sets of bindings in a natural way + without needing large changes to the library, or new + binding syntaxes. Since cursor keys normally emit + keysequences which start with escape, it also does + something sensible when a cursor key is pressed during + input mode (unlike true vi, which gets upset). + + I also added a ^Xg binding for the new list-glob action + to both the emacs and vi key-binding tables. This lists + the files that match the wild-card expression that + precedes it on the command line. + + The function that reads in ~/.teclarc used to tell + new_GetLine() to abort if it encountered anything that it + didn't understand in this file. It now just reports an + error and continues onto the next line. + Makefile.in: + When passing LIBS=$(LIBS) to recursive invokations of + make, quotes weren't included around the $(LIBS) part. + This would cause problems if LIBS ever contained more + than one word (with the supplied configure script this + doesn't happen currently). I added these quotes. + expand.c man3/ef_expand_file.3: + I wrote a new public function called ef_list_expansions(), + to list the matching filenames returned by + ef_expand_file(). + + I also fixed the example in the man page, which cited + exp->file instead of exp->files, and changed the + dangerous name 'exp' with 'expn'. + keytab.c: + Key-binding tables start with 100 elements, and are + supposedly incremented in size by 100 elements whenever + the a table runs out of space. The realloc arguments to + do this were wrong. This would have caused problems if + anybody added a lot of personal bindings in their + ~/.teclarc file. I only noticed it because the number of + key bindings needed by the new vi mode exceeded this + number. + libtecla.map + ef_expand_file() is now reported as having been added in + the upcoming 1.3.0 release. + +25/03/2001 Markus Gyger (logged here by mcs) + + Makefile.in: + Make symbolic links to alternative shared library names + relative instead of absolute. + Makefile.rules: + The HP-UX libtecla.map.opt file should be made in the + compilation directory, to allow the source code directory + to be on a readonly filesystem. + cplmatch.c demo2.c history.c pcache.c + To allow the library to be compiled with a C++ compiler, + without generating warnings, a few casts were added where + void* return values were being assigned directly to + none void* pointer variables. + +25/03/2001 mcs@astro.caltech.edu + + libtecla.map: + Added comment header to explain the purpose of the file. + Also added cpl_init_FileArgs to the list of exported + symbols. This symbol is deprecated, and no longer + documented, but for backwards compatibility, it should + still be exported. + configure: + I had forgotten to run autoconf before releasing version + 1.2.4, so I have just belatedly done so. This enables + Markus' changes to "configure.in" documented previously, + (see 17/03/2001). + +20/03/2001 John Levon (logged here by mcs) + + libtecla.h + A couple of the function prototypes in libtecla.h have + (FILE *) argument declarations, which means that stdio.h + needs to be included. The header file should be self + contained, so libtecla.h now includes stdio.h. + +18/03/2001 Version 1.2.4 released. + + README html/index.html configure.in + Incremented minor version from 3 to 4. + +18/03/2001 mcs@astro.caltech.edu + + getline.c + The fix for the end-of-line problem that I released a + couple of weeks ago, only worked for the first line, + because I was handling this case when the cursor position + was equal to the last column, rather than when the cursor + position modulo ncolumn was zero. + Makefile.in Makefile.rules + The demos are now made by default, their rules now being + int Makefile.rules instead of Makefile.in. + INSTALL + I documented how to compile the library in a different + directory than the distribution directory. + I also documented features designed to facilitate + configuring and building the library as part of another + package. + +17/03/2001 Markus Gyger (logged here by mcs) + + getline.c + Until now cursor motions were done one at a time. Markus + has added code to make use the of the terminfo capability + that moves the cursor by more than one position at a + time. This greatly improves performance when editing near + the start of long lines. + getline.c + To further improve performance, Markus switched from + writing one character at a time to the terminal, using + the write() system call, to using C buffered output + streams. The output buffer is only flushed when + necessary. + Makefile.rules Makefile.in configure.in + Added support for compiling for different architectures + in different directories. Simply create another directory + and run the configure script located in the original + directory. + Makefile.in configure.in libtecla.map + Under Solaris, Linux and HP-UX, symbols that are to be + exported by tecla shared libraries are explicitly specified + via symbol map files. Only publicly documented functions + are thus visible to applications. + configure.in + When linking shared libraries under Solaris SPARC, + registers that are reserved for applications are marked + as off limits to the library, using -xregs=no%appl when + compiling with Sun cc, or -mno-app-regs when compiling + with gcc. Also removed -z redlocsym for Solaris, which + caused problems under some releases of ld. + homedir.c (after minor changes by mcs) + Under ksh, ~+ expands to the current value of the ksh + PWD environment variable, which contains the path of + the current working directory, including any symbolic + links that were traversed to get there. The special + username "+" is now treated equally by tecla, except + that it substitutes the return value of getcwd() if PWD + either isn't set, or if it points at a different + directory than that reported by getcwd(). + +08/03/2001 Version 1.2.3 released. + +08/03/2001 mcs@astro.caltech.edu + + getline.c + On compiling the library under HP-UX for the first time + I encountered and fixed a couple of bugs: + + 1. On all systems except Solaris, the callback function + required by tputs() takes an int argument for the + character that is to be printed. Under Solaris it + takes a char argument. The callback function was + passing this argument, regardless of type, to write(), + which wrote the first byte of the argument. This was + fine under Solaris and under little-endian systems, + because the first byte contained the character to be + written, but on big-endian systems, it always wrote + the zero byte at the other end of the word. As a + result, no control characters were being written to + the terminal. + 2. While attempting to start a newline after the user hit + enter, the library was outputting the control sequence + for moving the cursor down, instead of the newline + character. On many systems the control sequence for + moving the cursor down happends to be a newline + character, but under HP-UX it isn't. The result was + that no new line was being started under HP-UX. + +04/03/2001 mcs@astro.caltech.edu + + configure.in Makefile.in Makefile.stub configure config.guess + config.sub Makefile.rules install-sh PORTING README INSTALL + Configuration and compilation of the library is now + performed with the help of an autoconf configure + script. In addition to relieving the user of the need to + edit the Makefile, this also allows automatic compilation + of the reentrant version of the library on platforms that + can handle it, along with the creation of shared + libraries where configured. On systems that aren't known + to the configure script, just the static tecla library is + compiled. This is currently the case on all systems + except Linux, Solaris and HP-UX. In the hope that + installers will provide specific conigurations for other + systems, the configure.in script is heavily commented, + and instructions on how to use are included in a new + PORTING file. + +24/02/2001 Version 1.2b released. + +22/02/2001 mcs@astro.caltech.edu + + getline.c + It turns out that most terminals, but not all, on writing + a character in the rightmost column, don't wrap the + cursor onto the next line until the next character is + output. This library wasn't aware of this and thus if one + tried to reposition the cursor from the last column, + gl_get_line() thought that it was moving relative to a + point on the next line, and thus moved the cursor up a + line. The fix was to write one extra character when in + the last column to force the cursor onto the next line, + then backup the cursor to the start of the new line. + getline.c + On terminal initialization, the dynamic LINES and COLUMNS + environment variables were ignored unless + terminfo/termcap didn't return sensible dimensions. In + practice, when present they should override the static + versions in the terminfo/termcap databases. This is the + new behavior. In reality this probably won't have caused + many problems, because a SIGWINCH signal which informs of + terminal size changes is sent when the terminal is + opened, so the dimensions established during + initialization quickly get updated on most systems. + +18/02/2001 Version 1.2a released. + +18/02/2001 mcs@astro.caltech.edu + + getline.c + Three months ago I moved the point at which termios.h + was included in getline.c. Unfortunately, I didn't notice + that this moved it to after the test for TIOCGWINSZ being + defined. This resulted in SIGWINCH signals not being + trapped for, and thus terminal size changes went + unnoticed. I have now moved the test to after the + inclusion of termios.h. + +12/02/2001 Markus Gyger (described here by mcs) + + man3/pca_lookup_file.3 man3/gl_get_line.3 + man3/ef_expand_file.3 man3/cpl_complete_word.3 + In the 1.2 release of the library, all functions in the + library were given man pages. Most of these simply + include one of the above 4 man pages, which describe the + functions while describing the modules that they are in. + Markus added all of these function names to the lists in + the "NAME" headers of the respective man pages. + Previously only the primary function of each module was + named there. + +11/02/2001 mcs@astro.caltech.edu + + getline.c + On entering a line that wrapped over two or more + terminal, if the user pressed enter when the cursor + wasn't on the last of the wrapped lines, the text of the + wrapped lines that followed it got mixed up with the next + line written by the application, or the next input + line. Somehow this slipped through the cracks and wasn't + noticed until now. Anyway, it is fixed now. + +09/02/2001 Version 1.2 released. + +04/02/2001 mcs@astro.caltech.edu + + pcache.c libtecla.h + With all filesystems local, demo2 was very fast to start + up, but on a Sun system with one of the target + directories being on a remote nfs mounted filesystem, the + startup time was many seconds. This was due to the + executable selection callback being applied to all files + in the path at startup. To avoid this, all files are now + included in the cache, and the application specified + file-selection callback is only called on files as they + are matched. Whether the callback rejected or accepted + them is then cached so that the next time an already + checked file is looked at, the callback doesn't have to + be called. As a result, startup is now fast on all + systems, and since usually there are only a few matching + file completions at a time, the delay during completion + is also usually small. The only exception is if the user + tries to complete an empty string, at which point all + files have to be checked. Having done this once, however, + doing it again is fast. + man3/pca_lookup_file.3 + I added a man page documenting the new PathCache module. + man3/<many-new-files>.3 + I have added man pages for all of the functions in each + of the modules. These 1-line pages use the .so directive + to redirect nroff to the man page of the parent module. + man Makefile update_html + I renamed man to man3 to make it easier to test man page + rediction, and updated Makefile and update_html + accordingly. I also instructed update_html to ignore + 1-line man pages when making html equivalents of the man + pages. + cplmatch.c + In cpl_list_completions() the size_t return value of + strlen() was being used as the length argument of a "%*s" + printf directive. This ought to be an int, so the return + value of strlen() is now cast to int. This would have + caused problems on architectures where the size of a + size_t is not equal to the size of an int. + +02/02/2001 mcs@astro.caltech.edu + + getline.c + Under UNIX, certain terminal bindings are set using the + stty command. This, for example, specifies which control + key generates a user-interrupt (usually ^C or ^Y). What I + hadn't realized was that ASCII NUL is used as the way to + specify that one of these bindings is unset. I have now + modified the code to skip unset bindings, leaving the + corresponding action bound to the built-in default, or a + user provided binding. + +28/01/2001 mcs@astro.caltech.edu + + pcache.c libtecla.h + A new module was added which supports searching for files + in any colon separated list of directories, such as the + unix execution PATH environment variable. Files in these + directories, after being individually okayed for + inclusion via an application provided callback, are + cached in a PathCache object. You can then look up the + full pathname of a given filename, or you can use the + provided completion callback to list possible completions + in the path-list. The contents of relative directories, + such as ".", obviously can't be cached, so these + directories are read on the fly during lookups and + completions. The obvious application of this facility is + to provide Tab-completion of commands, and thus a + callback to place executable files in the cache, is + provided. + demo2.c + This new program demonstrates the new PathCache + module. It reads and processes lines of input until the + word 'exit' is entered, or C-d is pressed. The default + tab-completion callback is replaced with one which at the + start of a line, looks up completions of commands in the + user's execution path, and when invoked in other parts of + the line, reverts to normal filename completion. Whenever + a new line is entered, it extracts the first word on the + line, looks it up in the user's execution path to see if + it corresponds to a known command file, and if so, + displays the full pathname of the file, along with the + remaining arguments. + cplfile.c + I added an optional pair of callback function/data + members to the new cpl_file_completions() configuration + structure. Where provided, this callback is asked + on a file-by-file basis, which files should be included + in the list of file completions. For example, a callback + is provided for listing only completions of executable + files. + cplmatch.c + When listing completions, the length of the type suffix + of each completion wasn't being taken into account + correctly when computing the column widths. Thus the + listing appeared ragged sometimes. This is now fixed. + pathutil.c + I added a function for prepending a string to a path, + and another for testing whether a pathname referred to + an executable file. + +28/01/2001 mcs@astro.caltech.edu + + libtecla.h cplmatch.c man/cpl_complete_word.3 + The use of a publically defined structure to configure + the cpl_file_completions() callback was flawed, so a new + approach has been designed, and the old method, albeit + still supported, is no longer documented in the man + pages. The definition of the CplFileArgs structure in + libtecla.h is now accompanied by comments warning people + not to modify it, since modifications could break + applications linked to shared versions of the tecla + library. The new method involves an opaque CplFileConf + object, instances of which are returned by a provided + constructor function, configured with provided accessor + functions, and when no longer needed, deleted with a + provided destructor function. This is documented in the + cpl_complete_word man page. The cpl_file_completions() + callback distinguishes what type of configuration + structure it has been sent by virtue of a code placed at + the beginning of the CplFileConf argument by its + constructor. + +04/01/2001 mcs@astro.caltech.edu (Release of version 1.1j) + + getline.c + I added upper-case bindings for the default meta-letter + keysequences such as M-b. They thus continue to work + when the user has caps-lock on. + Makefile + I re-implemented the "install" target in terms of new + install_lib, install_inc and install_man targets. When + distributing the library with other packages, these new + targets allows for finer grained control of the + installation process. + +30/12/2000 mcs@astro.caltech.edu + + getline.c man/gl_get_line.3 + I realized that the recall-history action that I + implemented wasn't what Markus had asked me for. What he + actually wanted was for down-history to continue going + forwards through a previous history recall session if no + history recall session had been started while entering + the current line. I have thus removed the recall-history + action and modified the down-history action function + accordingly. + +24/12/2000 mcs@astro.caltech.edu + + getline.c + I modified gl_get_line() to allow the previously returned + line to be passed in the start_line argument. + getline.c man/gl_get_line.3 + I added a recall-history action function, bound to M^P. + This recalls the last recalled history line, regardless + of whether it was from the current or previous line. + +13/12/2000 mcs@astro.caltech.edu (Release of version 1.1i) + + getline.c history.h history.c man/gl_get_line.3 + I implemented the equivalent of the ksh Operate action. I + have named the tecla equivalent "repeat-history". This + causes the line that is to be edited to returned, and + arranges for the next most recent history line to be + preloaded on the next call to gl_get_line(). Repeated + invocations of this action thus result in successive + history lines being repeated - hence the + name. Implementing the ksh Operate action was suggested + by Markus Gyger. In ksh it is bound to ^O, but since ^O + is traditionally bound by the default terminal settings, + to stop-output, I have bound the tecla equivalent to M-o. + +01/12/2000 mcs@astro.caltech.edu (Release of version 1.1h) + + getline.c keytab.c keytab.h man/gl_get_line.3 + I added a digit-argument action, to allow repeat + counts for actions to be entered. As in both tcsh + and readline, this is bound by default to each of + M-0, M-1 through to M-9, the number being appended + to the current repeat count. Once one of these has been + pressed, the subsequent digits of the repeat count can be + typed with or without the meta key pressed. It is also + possible to bind digit-argument to other keys, with or + without a numeric final keystroke. See man page for + details. + + getline.c man/gl_get_line.3 + Markus noted that my choice of M-< for the default + binding of read-from-file, could be confusing, since + readline binds this to beginning-of-history. I have + thus rebound it to ^X^F (ie. like find-file in emacs). + + getline.c history.c history.h man/gl_get_line.3 + I have now implemented equivalents of the readline + beginning-of-history and end-of-history actions. + These are bound to M-< and M-> respectively. + + history.c history.h + I Moved the definition of the GlHistory type, and + its subordinate types from history.h to history.c. + There is no good reason for any other module to + have access to the innards of this structure. + +27/11/2000 mcs@astro.caltech.edu (Release of version 1.1g) + + getline.c man/gl_get_line.3 + I added a "read-from-file" action function and bound it + by default to M-<. This causes gl_get_line() to + temporarily return input from the file who's name + precedes the cursor. + +26/11/2000 mcs@astro.caltech.edu + + getline.c keytab.c keytab.h man/gl_get_line.3 + I have reworked some of the keybinding code again. + + Now, within key binding strings, in addition to the + previously existing notation, you can now use M-a to + denote meta-a, and C-a to denote control-a. For example, + a key binding which triggers when the user presses the + meta key, the control key and the letter [ + simultaneously, can now be denoted by M-C-[, or M-^[ or + \EC-[ or \E^[. + + I also updated the man page to use M- instead of \E in + the list of default bindings, since this looks cleaner. + + getline.c man/gl_get_line.3 + I added a copy-region-as-kill action function and + gave it a default binding to M-w. + +22/11/2000 mcs@astro.caltech.edu + + *.c + Markus Gyger sent me a copy of a previous version of + the library, with const qualifiers added in appropriate + places. I have done the same for the latest version. + Among other things, this gets rid of the warnings + that are generated if one tells the compiler to + const qualify literal strings. + + getline.c getline.h glconf.c + I have moved the contents of glconf.c and the declaration + of the GetLine structure into getline.c. This is cleaner, + since now only functions in getline.c can mess with the + innards of GetLine objects. It also clears up some problems + with system header inclusion order under Solaris, and also + the possibility that this might result in inconsistent + system macro definitions, which in turn could cause different + declarations of the structure to be seen in different files. + + hash.c + I wrote a wrapper function to go around strcmp(), such that + when hash.c is compiled with a C++ compiler, the pointer + to the wrapper function is a C++ function pointer. + This makes it compatible with comparison function pointer + recorded in the hash table. + + cplmatch.c getline.c libtecla.h + Markus noted that the Sun C++ compiler wasn't able to + match up the declaration of cpl_complete_word() in + libtecla.h, where it is surrounded by a extern "C" {} + wrapper, with the definition of this function in + cplmatch.c. My suspicion is that the compiler looks not + only at the function name, but also at the function + arguments to see if two functions match, and that the + match_fn() argument, being a fully blown function pointer + declaration, got interpetted as that of a C function in + one case, and a C++ function in the other, thus + preventing a match. + + To fix this I now define a CplMatchFn typedef in libtecla.h, + and use this to declare the match_fn callback. + +20/11/2000 (Changes suggested by Markus Gyger to support C++ compilers): + expand.c + Renamed a variable called "explicit" to "xplicit", to + avoid conflicts when compiling with C++ compilers. + *.c + Added explicit casts when converting from (void *) to + other pointer types. This isn't needed in C but it is + in C++. + getline.c + tputs() has a strange declaration under Solaris. I was + enabling this declaration when the SPARC feature-test + macro was set. Markus changed the test to hinge on the + __sun and __SVR4 macros. + direader.c glconf.c stringrp.c + I had omitted to include string.h in these two files. + + Markus also suggested some other changes, which are still + under discussion. With the just above changes however, the + library compiles without complaint using g++. + +19/11/2000 mcs@astro.caltech.edu + getline.h getline.c keytab.c keytab.h glconf.c + man/gl_get_line.3 + I added support for backslash escapes (include \e + for the keyboard escape key) and literal binary + characters to the characters allowed within key sequences + of key bindings. + + getline.h getline.c keytab.c keytab.h glconf.c + man/gl_get_line.3 + I introduced symbolic names for the arrow keys, and + modified the library to use the cursor key sequences + reported by terminfo/termcap in addition to the default + ANSI ones. Anything bound to the symbolically named arrow + keys also gets bound to the default and terminfo/termcap + cursor key sequences. Note that under Solaris + terminfo/termcap report the properties of hardware X + terminals when TERM is xterm instead of the terminal + emulator properties, and the cursor keys on these two + systems generate different key sequences. This is an + example of why extra default sequences are needed. + + getline.h getline.c keytab.c + For some reason I was using \e to represent the escape + character. This is supported by gcc, which thus doesn't + emit a warning except with the -pedantic flag, but isn't + part of standard C. I now use a macro to define escape + as \033 in getline.h, and this is now used wherever the + escape character is needed. + +17/11/2000 mcs@astro.caltech.edu (Release of version 1.1d) + + getline.c, man/gl_get_line(3), html/gl_get_line.html + In tcsh ^D is bound to a function which does different + things depending on where the cursor is within the input + line. I have implemented its equivalent in the tecla + library. When invoked at the end of the line this action + function displays possible completions. When invoked on + an empty line it causes gl_get_line() to return NULL, + thus signalling end of input. When invoked within a line + it invokes forward-delete-char, as before. The new action + function is called del-char-or-list-or-eof. + + getline.c, man/gl_get_line(3), html/gl_get_line.html + I found that the complete-word and expand-file actions + had underscores in their names instead of hyphens. This + made them different from all other action functions, so I + have changed the underscores to hyphens. + + homedir.c + On SCO UnixWare while getpwuid_r() is available, the + associated _SC_GETPW_R_SIZE_MAX macro used by sysconf() + to find out how big to make the buffer to pass to this + function to cater for any password entry, doesn't + exist. I also hadn't catered for the case where sysconf() + reports that this limit is indeterminate. I have thus + change the code to substitute a default limit of 1024 if + either the above macro isn't defined or if sysconf() says + that the associated limit is indeterminate. + +17/11/2000 mcs@astro.caltech.edu (Release of version 1.1c) + + getline.c, getline.h, history.c, history.h + I have modified the way that the history recall functions + operate, to make them better emulate the behavior of + tcsh. Previously the history search bindings always + searched for the prefix that preceded the cursor, then + left the cursor at the same point in the line, so that a + following search would search using the same prefix. This + isn't how tcsh operates. On finding a matching line, tcsh + puts the cursor at the end of the line, but arranges for + the followup search to continue with the same prefix, + unless the user does any cursor motion or character + insertion operations in between, in which case it changes + the search prefix to the new set of characters that are + before the cursor. There are other complications as well, + which I have attempted to emulate. As far as I can + tell, the tecla history recall facilities now fully + emulate those of tcsh. + +16/11/2000 mcs@astro.caltech.edu (Release of version 1.1b) + + demo.c: + One can now quit from the demo by typing exit. + + keytab.c: + The first entry of the table was getting deleted + by _kt_clear_bindings() regardless of the source + of the binding. This deleted the up-arrow binding. + Symptoms noted by gazelle@yin.interaccess.com. + + getline.h: + Depending on which system include files were include + before the inclusion of getline.h, SIGWINCH and + TIOCGWINSZ might or might not be defined. This resulted + in different definitions of the GetLine object in + different files, and thus some very strange bugs! I have + now added #includes for the necessary system header files + in getline.h itself. The symptom was that on creating a + ~/.teclarc file, the demo program complained of a NULL + argument to kt_set_keybinding() for the first line of the + file. + +15/11/2000 mcs@astro.caltech.edu (Release of version 1.1a) + + demo.c: + I had neglected to check the return value of + new_GetLine() in the demo program. Oops. + + getline.c libtecla.h: + I wrote gl_change_terminal(). This allows one to change to + a different terminal or I/O stream, by specifying the + stdio streams to use for input and output, along with the + type of terminal that they are connected to. + + getline.c libtecla.h: + Renamed GetLine::isterm to GetLine::is_term. Standard + C reserves names that start with "is" followed by + alphanumeric characters, so this avoids potential + clashes in the future. + + keytab.c keytab.h + Each key-sequence can now have different binding + functions from different sources, with the user provided + binding having the highest precedence, followed by the + default binding, followed by any terminal specific + binding. This allows gl_change_terminal() to redefine the + terminal-specific bindings each time that + gl_change_terminal() is called, without overwriting the + user specified or default bindings. In the future, it will + also allow for reconfiguration of user specified + bindings after the call to new_GetLine(). Ie. deleting a + user specified binding should reinstate any default or + terminal specific binding. + + man/cpl_complete_word.3 html/cpl_complete_word.html + man/ef_expand_file.3 html/ef_expand_file.html + man/gl_get_line.3 html/gl_get_line.html + I added sections on thread safety to the man pages of the + individual modules. + + man/gl_get_line.3 html/gl_get_line.html + I documented the new gl_change_terminal() function. + + man/gl_get_line.3 html/gl_get_line.html + In the description of the ~/.teclarc configuration file, + I had omitted the 'bind' command word in the example + entry. I have now remedied this. +</PRE></BODY> diff --git a/libtecla-1.4.1/html/cpl_complete_word.html b/libtecla-1.4.1/html/cpl_complete_word.html new file mode 100644 index 0000000..063359d --- /dev/null +++ b/libtecla-1.4.1/html/cpl_complete_word.html @@ -0,0 +1,423 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + cpl_complete_word, cfc_file_start, cfc_literal_escapes, + cfc_set_check_fn, cpl_add_completion, cpl_file_completions, + cpl_last_error, cpl_list_completions, cpl_record_error, + del_CplFileConf, del_WordCompletion, new_CplFileConf, + new_WordCompletion - lookup possible completions for a word + +</pre><h2>SYNOPSIS</h2><pre> + #include <stdio.h> + #include <libtecla.h> + + WordCompletion *new_WordCompletion(void); + + WordCompletion *del_WordCompletion(WordCompletion *cpl); + + #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \ + void *data, \ + const char *line, \ + int word_end) + typedef CPL_MATCH_FN(CplMatchFn); + + CPL_MATCH_FN(cpl_file_completions); + + CplMatches *cpl_complete_word(WordCompletion *cpl, + const char *line, + int word_end, void *data, + CplMatchFn *match_fn); + + int cpl_list_completions(CplMatches *result, FILE *fp, + int term_width); + + 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); + + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); + + const char *cpl_last_error(WordCompletion *cpl); + + + +</pre><h2>DESCRIPTION</h2><pre> + The cpl_complete_word() function is part of the tecla + library (see the <a href="libtecla.html">libtecla(3)</a> man page). It is usually called + behind the scenes by <a href="gl_get_line.html">gl_get_line(3)</a>, but can also be called + separately. + + Given an input line containing an incomplete word to be com- + pleted, it calls a user-provided callback function (or the + provided file-completion callback function) to look up all + possible completion suffixes for that word. The callback + function is expected to look backward in the line, starting + from the specified cursor position, to find the start of the + word to be completed, then to look up all possible comple- + tions of that word and record them, one at a time by calling + cpl_add_completion(). + + + Descriptions of the functions of this module are as follows: + + CompleteWord *new_CompleteWord(void) + + This function creates the resources used by the + cpl_complete_word() function. In particular, it maintains + the memory that is used to return the results of calling + cpl_complete_word(). + + CompleteWord *del_CompleteWord(CompleteWord *cpl) + + This function deletes the resources that were returned by a + previous call to new_CompleteWord(). It always returns NULL + (ie. a deleted object). It does nothing if the cpl argument + is NULL. + + The callback functions which lookup possible completions + should be defined with the following macro (which is defined + in libtecla.h). + + #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \ + void *data, \ + const char *line, \ + int word_end) + + Functions of this type are called by cpl_complete_word(), + and all of the arguments of the callback are those that were + passed to said function. In particular, the line argument + contains the input line containing the word to be completed, + and word_end is the index of the character that follows the + last character of the incomplete word within this string. + The callback is expected to look backwards from word_end for + the start of the incomplete word. What constitutes the start + of a word clearly depends on the application, so it makes + sense for the callback to take on this responsibility. For + example, the builtin filename completion function looks + backwards until it hits an unescaped space, or the start of + the line. Having found the start of the word, the callback + should then lookup all possible completions of this word, + and record each completion via separate calls to + cpl_add_completion(). If the callback needs access to an + application-specific symbol table, it can pass it and any + other data that it needs, via the data argument. This + removes any need for globals. + + The callback function should return 0 if no errors occur. On + failure it should return 1, and register a terse description + of the error by calling cpl_record_error(). + + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); + + The last error message recorded by calling + cpl_record_error(), can subsequently be queried by calling + cpl_last_error(), as described later. + + 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); + + The cpl_add_completion() function is called zero or more + times by the completion callback function to record each + possible completion in the specified WordCompletion object. + These completions are subsequently returned by + cpl_complete_word(), as described later. The cpl, line, and + word_end arguments should be those that were passed to the + callback function. The word_start argument should be the + index within the input line string of the start of the word + that is being completed. This should equal word_end if a + zero-length string is being completed. The suffix argument + is the string that would have to be appended to the incom- + plete word to complete it. If this needs any quoting (eg. + the addition of backslashes before special charaters) to be + valid within the displayed input line, this should be + included. A copy of the suffix string is allocated inter- + nally, so there is no need to maintain your copy of the + string after cpl_add_completion() returns. + + Note that in the array of possible completions which the + cpl_complete_word() function returns, the suffix recorded by + cpl_add_completion() is listed along with the concatentation + of this suffix with the word that lies between word_start + and word_end in the input line. + + The type_suffix argument specifies an optional string to be + appended to the completion if it is displayed as part of a + list of completions by cpl_list_completions(). The intention + is that this indicate to the user the type of each comple- + tion. For example, the file completion function places a + directory separator after completions that are directories, + to indicate their nature to the user. Similary, if the com- + pletion were a function, you could indicate this to the user + by setting type_suffix to "()". Note that the type_suffix + string isn't copied, so if the argument isn't a literal + string between speech marks, be sure that the string remains + valid for at least as long as the results of + cpl_complete_word() are needed. + + The cont_suffix is a continuation suffix to append to the + completed word in the input line if this is the only comple- + tion. This is something that isn't part of the completion + itself, but that gives the user an indication about how they + might continue to extend the token. For example, the file- + completion callback function adds a directory separator if + the completed word is a directory. If the completed word + were a function name, you could similarly aid the user by + arranging for an open parenthesis to be appended. + + CplMatches *cpl_complete_word(WordCompletion *cpl, + const char *line, + int word_end, void *data, + CplMatchFn *match_fn); + + The cpl_complete_word() is normally called behind the scenes + by <a href="gl_get_line.html">gl_get_line(3)</a>, but can also be called separately if you + separately allocate a WordCompletion object. It performs + word completion, as described at the beginning of this sec- + tion. Its first argument is a resource object previously + returned by new_CompleteWord(). The line argument is the + input line string, containing the word to be completed. The + word_end argument contains the index of the character in the + input line, that just follows the last character of the word + to be completed. When called by gl_get_line(), this is the + character over which the user pressed TAB. The match_fn + argument is the function pointer of the callback function + which will lookup possible completions of the word, as + described above, and the data argument provides a way for + the application to pass arbitrary data to the callback func- + tion. + + If no errors occur, the cpl_complete_word() function returns + a pointer to a CplMatches container, as defined below. This + container is allocated as part of the cpl object that was + passed to cpl_complete_word(), and will thus change on each + call which uses the same cpl argument. + + typedef struct { + char *completion; /* A matching completion */ + /* string */ + char *suffix; /* The part of the */ + /* completion string which */ + /* would have to be */ + /* appended to complete the */ + /* original word. */ + const char *type_suffix; /* A suffix to be added when */ + /* listing completions, to */ + /* indicate the type of the */ + /* completion. */ + } CplMatch; + + 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 */ + /* the above matches[] */ + /* array. */ + } CplMatches; + + If an error occurs during completion, cpl_complete_word() + returns NULL. A description of the error can be acquired by + calling the cpl_last_error() function. + + const char *cpl_last_error(WordCompletion *cpl); + + The cpl_last_error() function returns a terse description of + the error which occurred on the last call to + cpl_complete_word() or cpl_add_completion(). + + int cpl_list_completions(CplMatches *result, FILE *fp, + int terminal_width); + + When the cpl_complete_word() function returns multiple pos- + sible completions, the cpl_list_completions() function can + be called upon to list them, suitably arranged across the + available width of the terminal. It arranges for the + displayed columns of completions to all have the same width, + set by the longest completion. It also appends the + type_suffix strings that were recorded with each completion, + thus indicating their types to the user. + + +</pre><h2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</h2><pre> + By default the <a href="gl_get_line.html">gl_get_line(3)</a> function, passes the following + completion callback function to cpl_complete_word(). This + function can also be used separately, either by sending it + to cpl_complete_word(), or by calling it directly from your + own completion callback function. + + CPL_MATCH_FN(cpl_file_completions); + + Certain aspects of the behavior of this callback can be + changed via its data argument. If you are happy with its + default behavior you can pass NULL in this argument. Other- + wise it should be a pointer to a CplFileConf object, previ- + ously allocated by calling new_CplFileConf(). + + CplFileConf *new_CplFileConf(void); + + CplFileConf objects encapsulate the configuration parameters + of cpl_file_completions(). These parameters, which start out + with default values, can be changed by calling the accessor + functions described below. + + By default, the cpl_file_completions() callback function + searches backwards for the start of the filename being com- + pleted, looking for the first un-escaped space or the start + of the input line. If you wish to specify a different loca- + tion, call cfc_file_start() with the index at which the + filename starts in the input line. Passing start_index=-1 + re-enables the default behavior. + + void cfc_file_start(CplFileConf *cfc, int start_index); + + By default, when cpl_file_completions() looks at a filename + in the input line, each lone backslash in the input line is + interpreted as being a special character which removes any + special significance of the character which follows it, such + as a space which should be taken as part of the filename + rather than delimiting the start of the filename. These + backslashes are thus ignored while looking for completions, + and subsequently added before spaces, tabs and literal + backslashes in the list of completions. To have unescaped + backslashes treated as normal characters, call + cfc_literal_escapes() with a non-zero value in its literal + argument. + + void cfc_literal_escapes(CplFileConf *cfc, int literal); + + By default, cpl_file_completions() reports all files who's + names start with the prefix that is being completed. If you + only want a selected subset of these files to be reported in + the list of completions, you can arrange this by providing a + callback function which takes the full pathname of a file, + and returns 0 if the file should be ignored, or 1 if the + file should be included in the list of completions. To + register such a function for use by cpl_file_completions(), + call cfc_set_check_fn(), and pass it a pointer to the func- + tion, together with a pointer to any data that you would + like passed to this callback whenever it is called. Your + callback can make its decisions based on any property of the + file, such as the filename itself, whether the file is read- + able, writable or executable, or even based on what the file + contains. + + #define CPL_CHECK_FN(fn) int (fn)(void *data, \ + const char *pathname) + typedef CPL_CHECK_FN(CplCheckFn); + + void cfc_set_check_fn(CplFileConf *cfc, + CplCheckFn *chk_fn, void *chk_data); + + The cpl_check_exe() function is a provided callback of the + above type, for use with cpl_file_completions(). It returns + non-zero if the filename that it is given represents a nor- + mal file that the user has execute permission to. You could + use this to have cpl_file_completions() only list comple- + tions of executable files. + + When you have finished with a CplFileConf variable, you can + pass it to the del_CplFileConf() destructor function to + reclaim its memory. + + CplFileConf *del_CplFileConf(CplFileConf *cfc); + + + +</pre><h2>THREAD SAFETY</h2><pre> + In multi-threaded programs, you should use the libtecla_r.a + version of the library. This uses POSIX reentrant functions + where available (hence the _r suffix), and disables features + that rely on non-reentrant system functions. In the case of + this module, the only disabled feature is username comple- + tion in ~username/ expressions, in cpl_file_completions(). + + Using the libtecla_r.a version of the library, it is safe to + use the facilities of this module in multiple threads, pro- + vided that each thread uses a separately allocated WordCom- + pletion object. In other words, if two threads want to do + word completion, they should each call new_WordCompletion() + to allocate their own completion objects. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library + libtecla.h - The tecla header file. + + +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="ef_expand_file.html">ef_expand_file(3)</a>, + <a href="pca_lookup_file.html">pca_lookup_file(3)</a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> diff --git a/libtecla-1.4.1/html/ef_expand_file.html b/libtecla-1.4.1/html/ef_expand_file.html new file mode 100644 index 0000000..c1e71c7 --- /dev/null +++ b/libtecla-1.4.1/html/ef_expand_file.html @@ -0,0 +1,267 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + ef_expand_file, del_ExpandFile, ef_last_error, + ef_list_expansions, new_ExpandFile - expand filenames con- + taining ~user/$envvar and wildcard expressions + +</pre><h2>SYNOPSIS</h2><pre> + #include <libtecla.h> + + ExpandFile *new_ExpandFile(void); + + ExpandFile *del_ExpandFile(ExpandFile *ef); + + FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen); + + int ef_list_expansions(FileExpansion *result, FILE *fp, + int term_width); + + const char *ef_last_error(ExpandFile *ef); + + +</pre><h2>DESCRIPTION</h2><pre> + The ef_expand_file() function is part of the tecla library + (see the <a href="libtecla.html">libtecla(3)</a> man page). It expands a specified + filename, converting ~user/ and ~/ expressions at the start + of the filename 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. Backslashes in + the input filename are interpreted as escaping any special + meanings of the characters that follow them. Only + backslahes that are themselves preceded by backslashes are + preserved in the expanded filename. + + In the presence of wildcards, the returned list of filenames + only includes the names of existing files which match the + wildcards. Otherwise, the original filename is returned + after expansion of tilde and dollar expressions, and the + result is not checked against existing files. This mimics + the file-globbing behavior of the unix tcsh shell. + + 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. The ']' + character also looses its significance as the + terminator of the range expression if it + appears immediately after the opening '[', at + which point it is treated one of the + characters of the range. If you want both '-' + and ']' to be part of the range, the '-' + should come first and the ']' second. + + [^chars] - The same as [chars] except that it matches any + single character that doesn't appear in + 'chars'. + + Note that wildcards never match the initial dot in filenames + that start with '.'. The initial '.' must be explicitly + specified in the filename. This again mimics the globbing + behavior of most unix shells, and its rational is based in + the fact that in unix, files with names that start with '.' + are usually hidden configuration files, which are not listed + by default by the ls command. + + The following is a complete example of how to use the file + expansion function. + + #include <stdio.h> + #include <libtecla.h> + + int main(int argc, char *argv[]) + { + ExpandFile *ef; /* The expansion resource object */ + char *filename; /* The filename being expanded */ + FileExpansion *expn; /* The results of the expansion */ + int i; + + ef = new_ExpandFile(); + if(!ef) + return 1; + + for(arg = *(argv++); arg; arg = *(argv++)) { + if((expn = ef_expand_file(ef, arg, -1)) == NULL) { + fprintf(stderr, "Error expanding %s (%s).\n", arg, + ef_last_error(ef)); + } else { + printf("%s matches the following files:\n", arg); + for(i=0; i<expn->nfile; i++) + printf(" %s\n", expn->files[i]); + } + } + + ef = del_ExpandFile(ef); + return 0; + } + + Descriptions of the functions used above are as follows: + + ExpandFile *new_ExpandFile(void) + + This function creates the resources used by the + ef_expand_file() function. In particular, it maintains the + memory that is used to record the array of matching + filenames that is returned by ef_expand_file(). This array + is expanded as needed, so there is no built in limit to the + number of files that can be matched. + + ExpandFile *del_ExpandFile(ExpandFile *ef) + + This function deletes the resources that were returned by a + previous call to new_ExpandFile(). It always returns NULL + (ie a deleted object). It does nothing if the ef argument is + NULL. + + A container of the following type is returned by + ef_expand_file(). + + typedef struct { + int exists; /* True if the files in files[] exist */ + int nfile; /* The number of files in files[] */ + char **files; /* An array of 'nfile' filenames. */ + } FileExpansion; + + FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen) + + The ef_expand_file() function performs filename expansion, + as documented at the start of this section. Its first argu- + ment is a resource object returned by new_ExpandFile(). A + pointer to the start of the filename to be matched is passed + via the path argument. This must be a normal NUL terminated + string, but unless a length of -1 is passed in pathlen, only + the first pathlen characters will be used in the filename + expansion. If the length is specified as -1, the whole of + the string will be expanded. + + The function returns a pointer to a container who's contents + are the results of the expansion. If there were no wildcards + in the filename, the nfile member will be 1, and the exists + member should be queried if it is important to know if the + expanded file currently exists or not. If there were wild- + cards, then the contained files[] array will contain the + names of the nfile existing files that matched the wild- + carded filename, and the exists member will have the value + 1. Note that the returned container belongs to the specified + ef object, and its contents will change on each call, so if + you need to retain the results of more than one call to + ef_expand_file(), you should either make a private copy of + the returned results, or create multiple file-expansion + resource objects via multiple calls to new_ExpandFile(). + + On error, NULL is returned, and an explanation of the error + can be determined by calling ef_last_error(ef). + + const char *ef_last_error(ExpandFile *ef) + + This function returns the message which describes the error + that occurred on the last call to ef_expand_file(), for the + given (ExpandFile *ef) resource object. + + int ef_list_expansions(FileExpansion *result, FILE *fp, + int terminal_width); + + The ef_list_expansions() function provides a convenient way + to list the filename expansions returned by + ef_expand_file(). Like the unix ls command, it arranges the + filenames into equal width columns, each column having the + width of the largest file. The number of columns used is + thus determined by the length of the longest filename, and + the specified terminal width. Beware that filenames that are + longer than the specified terminal width are printed without + being truncated, so output longer than the specified termi- + nal width can occur. The list is written to the stdio stream + specified by the fp argument. + + +</pre><h2>THREAD SAFETY</h2><pre> + In multi-threaded programs, you should use the libtecla_r.a + version of the library. This uses POSIX reentrant functions + where available (hence the _r suffix), and disables features + that rely on non-reentrant system functions. Currently there + are no features disabled in this module. + + Using the libtecla_r.a version of the library, it is safe to + use the facilities of this module in multiple threads, pro- + vided that each thread uses a separately allocated Expand- + File object. In other words, if two threads want to do file + expansion, they should each call new_ExpandFile() to allo- + cate their own file-expansion objects. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library + libtecla.h - The tecla header file. + + +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="cpl_complete_word.html">cpl_complete_word(3)</a>, + <a href="pca_lookup_file.html">pca_lookup_file(3)</a> +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> diff --git a/libtecla-1.4.1/html/enhance.html b/libtecla-1.4.1/html/enhance.html new file mode 100644 index 0000000..9f6bb09 --- /dev/null +++ b/libtecla-1.4.1/html/enhance.html @@ -0,0 +1,111 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + enhance - A program that adds command-line editing to third + party programs. + +</pre><h2>SYNOPSIS</h2><pre> + enhance command [ argument ... ] + + +</pre><h2>DESCRIPTION</h2><pre> + The enhance program provides enhanced command-line editing + facilities to users of third party applications, to which + one doesn't have any source code. It does this by placing a + pseudo-terminal between the application and the real termi- + nal. It uses the tecla command-line editing library to read + input from the real terminal, then forwards each just com- + pleted input line to the application via the pseudo- + terminal. All output from the application is forwarded back + unchanged to the real terminal. + + Whenever the application stops generating output for more + than a tenth of a second, the enhance program treats the + latest incomplete output line as the prompt, and redisplays + any incompleted input line that the user has typed after it. + Note that the small delay, which is imperceptible to the + user, isn't necessary for correct operation of the program. + It is just an optimization, designed to stop the input line + from being redisplayed so often that it slows down output. + + +</pre><h2>DEFICIENCIES</h2><pre> + The one major problem that hasn't been solved yet, is how to + deal with applications that change whether typed input is + echo'd by their controlling terminal. For example, programs + that ask for a password, such as ftp and telnet, temporarily + tell their controlling terminal not to echo what the user + types. Since this request goes to the application side of + the psuedo terminal, the enhance program has no way of know- + ing that this has happened, and continues to echo typed + input to its controlling terminal, while the user types + their password. + + Furthermore, before executing the host application, the + enhance program initially sets the pseudo terminal to noecho + mode, so that everything that it sends to the program + doesn't get redundantly echoed. If a program that switches + to noecho mode explicitly restores echoing afterwards, + rather than restoring the terminal modes that were previ- + ously in force, then subsequently, every time that you enter + a new input line, a duplicate copy will be displayed on the + next line. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library. + ~/.teclarc - The tecla personal customization file. + + +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> diff --git a/libtecla-1.4.1/html/gl_get_line.html b/libtecla-1.4.1/html/gl_get_line.html new file mode 100644 index 0000000..dcc45a0 --- /dev/null +++ b/libtecla-1.4.1/html/gl_get_line.html @@ -0,0 +1,2295 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + gl_get_line, new_GetLine, del_GetLine, + gl_customize_completion, gl_change_terminal, + gl_configure_getline, gl_load_history, gl_save_history, + gl_group_history, gl_show_history, gl_watch_fd, + gl_terminal_size, gl_resize_history, gl_limit_history, + gl_clear_history, gl_toggle_history, gl_lookup_history, + gl_state_of_history, gl_range_of_history, + gl_size_of_history, gl_echo_mode, gl_replace_prompt, + gl_prompt_style, gl_ignore_signal, gl_trap_signal, + gl_last_signal - allow the user to compose an input line + +</pre><h2>SYNOPSIS</h2><pre> + #include <stdio.h> + #include <libtecla.h> + + GetLine *new_GetLine(size_t linelen, size_t histlen); + + GetLine *del_GetLine(GetLine *gl); + + char *gl_get_line(GetLine *gl, const char *prompt, + const char *start_line, int start_pos); + + int gl_customize_completion(GetLine *gl, void *data, + CplMatchFn *match_fn); + + int gl_change_terminal(GetLine *gl, FILE *input_fp, + FILE *output_fp, const char *term); + + int gl_configure_getline(GetLine *gl, + const char *app_string, + const char *app_file, + const char *user_file); + + 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); + + int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event, + GlFdEventFn *callback, void *data); + + int gl_group_history(GetLine *gl, unsigned stream); + + int gl_show_history(GetLine *gl, FILE *fp, + const char *fmt, int all_groups, + int max_lines); + + int gl_resize_history(GetLine *gl, size_t bufsize); + + void gl_limit_history(GetLine *gl, int max_lines); + void gl_clear_history(GetLine *gl, int all_groups); + + void gl_toggle_history(GetLine *gl, int enable); + + GlTerminalSize gl_terminal_size(GetLine *gl, + int def_ncolumn, + int def_nline); + + int gl_lookup_history(GetLine *gl, unsigned long id, + GlHistoryLine *hline); + + void gl_state_of_history(GetLine *gl, + GlHistoryState *state); + + void gl_range_of_history(GetLine *gl, + GlHistoryRange *range); + + void gl_size_of_history(GetLine *gl, GlHistorySize *size); + + void gl_echo_mode(GetLine *gl, int enable); + + void gl_replace_prompt(GetLine *gl, const char *prompt); + + void gl_prompt_style(GetLine *gl, GlPromptStyle style); + + int gl_ignore_signal(GetLine *gl, int signo); + + int gl_trap_signal(GetLine *gl, int signo, unsigned flags, + GlAfterSignal after, int errno_value); + + int gl_last_signal(const GetLine *gl); + + + +</pre><h2>DESCRIPTION</h2><pre> + The gl_get_line() function is part of the tecla library (see + the <a href="libtecla.html">libtecla(3)</a> man page). If the user is typing at a termi- + nal, it prompts them for an line of input, then provides + interactive editing facilities, similar to those of the unix + tcsh shell. In addition to simple command-line editing, it + supports recall of previously entered command lines, TAB + completion of file names, and in-line wild-card expansion of + filenames. + + +</pre><h2>AN EXAMPLE</h2><pre> + The following shows a complete example of how to use the + gl_get_line() function to get input from the user: + + #include <stdio.h> + #include <locale.h> + #include <libtecla.h> + int main(int argc, char *argv[]) + { + char *line; /* The line that the user typed */ + GetLine *gl; /* The gl_get_line() resource object */ + + setlocale(LC_CTYPE, ""); /* Adopt the user's choice */ + /* of character set. */ + + gl = new_GetLine(1024, 2048); + if(!gl) + return 1; + + while((line=gl_get_line(gl, "$ ", NULL, -1)) != NULL && + strcmp(line, "exit\n") != 0) + printf("You typed: %s\n", line); + + gl = del_GetLine(gl); + return 0; + } + + In the example, first the resources needed by the + gl_get_line() function are created by calling new_GetLine(). + This allocates the memory used in subsequent calls to the + gl_get_line() function, including the history buffer for + recording previously entered lines. Then one or more lines + are read from the user, until either an error occurs, or the + user types exit. Then finally the resources that were allo- + cated by new_GetLine(), are returned to the system by cal- + ling del_GetLine(). Note the use of the NULL return value of + del_GetLine() to make gl NULL. This is a safety precaution. + If the program subsequently attempts to pass gl to + gl_get_line(), said function will complain, and return an + error, instead of attempting to use the deleted resource + object. + + + +</pre><h2>THE FUNCTIONS USED IN THE EXAMPLE</h2><pre> + The descriptions of the functions used in the example are as + follows: + + GetLine *new_GetLine(size_t linelen, size_t histlen) + + This function creates the resources used by the + gl_get_line() function and returns an opaque pointer to the + object that contains them. The maximum length of an input + line is specified via the linelen argument, and the number + of bytes to allocate for storing history lines is set by the + histlen argument. History lines are stored back-to-back in a + single buffer of this size. Note that this means that the + number of history lines that can be stored at any given + time, depends on the lengths of the individual lines. If + you want to place an upper limit on the number of lines that + can be stored, see the gl_limit_history() function described + later. If you don't want history at all, specify histlen as + zero, and no history buffer will be allocated. + + On error, a message is printed to stderr and NULL is + returned. + + GetLine *del_GetLine(GetLine *gl) + + This function deletes the resources that were returned by a + previous call to new_GetLine(). It always returns NULL (ie a + deleted object). It does nothing if the gl argument is NULL. + + char *gl_get_line(GetLine *gl, const char *prompt, + const char *start_line, int start_pos); + + The gl_get_line() function can be called any number of times + to read input from the user. The gl argument must have been + previously returned by a call to new_GetLine(). The prompt + argument should be a normal NUL terminated string, specify- + ing the prompt to present the user with. By default prompts + are displayed literally, but if enabled with the + gl_prompt_style() function (see later), prompts can contain + directives to do underlining, switch to and from bold fonts, + or turn highlighting on and off. + + If you want to specify the initial contents of the line, for + the user to edit, pass the desired string via the start_line + argument. You can then specify which character of this line + the cursor is initially positioned over, using the start_pos + argument. This should be -1 if you want the cursor to follow + the last character of the start line. If you don't want to + preload the line in this manner, send start_line as NULL, + and set start_pos to -1. + + The gl_get_line() function returns a pointer to the line + entered by the user, or NULL on error or at the end of the + input. The returned pointer is part of the specified gl + resource object, and thus should not be free'd by the + caller, or assumed to be unchanging from one call to the + next. When reading from a user at a terminal, there will + always be a newline character at the end of the returned + line. When standard input is being taken from a pipe or a + file, there will similarly be a newline unless the input + line was too long to store in the internal buffer. In the + latter case you should call gl_get_line() again to read the + rest of the line. Note that this behavior makes + gl_get_line() similar to fgets(). In fact when stdin isn't + connected to a terminal,gl_get_line() just calls fgets(). + + +</pre><h2>OPTIONAL PROMPT FORMATTING</h2><pre> + Whereas by default the prompt string that you specify is + displayed literally, without any special interpretation of + the characters within it, the gl_prompt_style() function can + be used to enable optional formatting directives within the + prompt. + + void gl_prompt_style(GetLine *gl, GlPromptStyle style); + + The style argument, which specifies the formatting style, + can take any of the following values: + + GL_FORMAT_PROMPT - In this style, the formatting + directives described below, when + included in prompt strings, are + interpreted as follows: + + %B - Display subsequent + characters with a bold + font. + %b - Stop displaying characters + with the bold font. + %F - Make subsequent characters + flash. + %f - Turn off flashing + characters. + %U - Underline subsequent + characters. + %u - Stop underlining + characters. + %P - Switch to a pale (half + brightness) font. + %p - Stop using the pale font. + %S - Highlight subsequent + characters (also known as + standout mode). + %s - Stop highlighting + characters. + %V - Turn on reverse video. + %v - Turn off reverse video. + %% - Display a single % + character. + + For example, in this mode, a prompt + string like "%UOK%u$ " would + display the prompt "OK$ ", + but with the OK part + underlined. + + Note that although a pair of + characters that starts with a % + character, but doesn't match any of + the above directives is displayed + literally, if a new directive is + subsequently introduced which does + match, the displayed prompt will + change, so it is better to always + use %% to display a literal %. + + Also note that not all terminals + support all of these text + attributes, and that some substitute + a different attribute for missing + ones. + + GL_LITERAL_PROMPT - In this style, the prompt string is + printed literally. This is the + default style. + + + +</pre><h2>THE AVAILABLE KEY BINDING FUNCTIONS</h2><pre> + The gl_get_line() function provides a number of functions + which can be bound to key sequences. The names of these + functions, and what they do, are given below. + + user-interrupt - Send a SIGINT signal to the + parent process. + abort - Send a SIGABRT signal to the + parent process. + suspend - Suspend the parent process. + stop-output - Pause terminal output. + start-output - Resume paused terminal output. + literal-next - Arrange for the next character + to be treated as a normal + character. This allows control + characters to be entered. + cursor-right - Move the cursor one character + right. + cursor-left - Move the cursor one character + left. + insert-mode - Toggle between insert mode and + overwrite mode. + beginning-of-line - Move the cursor to the + beginning of the line. + end-of-line - Move the cursor to the end of + the line. + delete-line - Delete the contents of the + current line. + kill-line - Delete everything that follows + the cursor. + backward-kill-line - Delete all characters between + the cursor and the start of the + line. + forward-word - Move to the end of the word + which follows the cursor. + forward-to-word - Move the cursor to the start of + the word that follows the + cursor. + backward-word - Move to the start of the word + which precedes the cursor. + goto-column - Move the cursor to the + 1-relative column in the line + specified by any preceding + digit-argument sequences (see + ENTERING REPEAT COUNTS below). + find-parenthesis - If the cursor is currently + over a parenthesis character, + move it to the matching + parenthesis character. If not + over a parenthesis character + move right to the next close + parenthesis. + forward-delete-char - Delete the character under the + cursor. + backward-delete-char - Delete the character which + precedes the cursor. + list-or-eof - This is intended for binding + to ^D. When invoked when the + cursor is within the line it + displays all possible + completions then redisplays + the line unchanged. When + invoked on an empty line, it + signals end-of-input (EOF) to + the caller of gl_get_line(). + del-char-or-list-or-eof - This is intended for binding + to ^D. When invoked when the + cursor is within the line it + invokes forward-delete-char. + When invoked at the end of the + line it displays all possible + completions then redisplays + the line unchanged. When + invoked on an empty line, it + signals end-of-input (EOF) to + the caller of gl_get_line(). + forward-delete-word - Delete the word which follows + the cursor. + backward-delete-word - Delete the word which precedes + the cursor. + upcase-word - Convert all of the characters + of the word which follows the + cursor, to upper case. + downcase-word - Convert all of the characters + of the word which follows the + cursor, to lower case. + capitalize-word - Capitalize the word which + follows the cursor. + change-case - If the next character is upper + case, toggle it to lower case + and vice versa. + redisplay - Redisplay the line. + clear-screen - Clear the terminal, then + redisplay the current line. + transpose-chars - Swap the character under the + cursor with the character just + before the cursor. + set-mark - Set a mark at the position of + the cursor. + exchange-point-and-mark - Move the cursor to the last + mark that was set, and move + the mark to where the cursor + used to be. + kill-region - Delete the characters that lie + between the last mark that was + set, and the cursor. + copy-region-as-kill - Copy the text between the mark + and the cursor to the cut + buffer, without deleting the + original text. + yank - Insert the text that was last + deleted, just before the + current position of the cursor. + append-yank - Paste the current contents of + the cut buffer, after the + cursor. + up-history - Recall the next oldest line + that was entered. Note that + in vi mode you are left in + command mode. + down-history - Recall the next most recent + line that was entered. If no + history recall session is + currently active, the next + line from a previous recall + session is recalled. Note that + in vi mode you are left in + command mode. + history-search-backward - Recall the next oldest line + who's prefix matches the string + which currently precedes the + cursor (in vi command-mode the + character under the cursor is + also included in the search + string). Note that in vi mode + you are left in command mode. + history-search-forward - Recall the next newest line + who's prefix matches the string + which currently precedes the + cursor (in vi command-mode the + character under the cursor is + also included in the search + string). Note that in vi mode + you are left in command mode. + history-re-search-backward -Recall the next oldest line + who's prefix matches that + established by the last + invocation of either + history-search-forward or + history-search-backward. + history-re-search-forward - Recall the next newest line + who's prefix matches that + established by the last + invocation of either + history-search-forward or + history-search-backward. + complete-word - Attempt to complete the + incomplete word which + precedes the cursor. Unless + the host program has customized + word completion, filename + completion is attempted. In vi + commmand mode the character + under the cursor is also + included in the word being + completed, and you are left in + vi insert mode. + expand-filename - Within the command line, expand + wild cards, tilde expressions + and dollar expressions in the + filename which immediately + precedes the cursor. In vi + commmand mode the character + under the cursor is also + included in the filename being + expanded, and you are left in + vi insert mode. + list-glob - List any filenames which match + the wild-card, tilde and dollar + expressions in the filename + which immediately precedes the + cursor, then redraw the input + line unchanged. + list-history - Display the contents of the + history list for the current + history group. If a repeat + count of > 1 is specified, + only that many of the most + recent lines are displayed. + See the "ENTERING REPEAT + COUNTS" section. + read-from-file - Temporarily switch to reading + input from the file who's + name precedes the cursor. + read-init-files - Re-read teclarc configuration + files. + beginning-of-history - Move to the oldest line in the + history list. Note that in vi + mode you are left in command + mode. + end-of-history - Move to the newest line in the + history list (ie. the current + line). Note that in vi mode + this leaves you in command + mode. + digit-argument - Enter a repeat count for the + next key-binding function. + For details, see the ENTERING + REPEAT COUNTS section. + newline - Terminate and return the + current contents of the + line, after appending a + newline character. The newline + character is normally '\n', + but will be the first + character of the key-sequence + that invoked the newline + action, if this happens to be + a printable character. If the + action was invoked by the + '\n' newline character or the + '\r' carriage return + character, the line is + appended to the history + buffer. + repeat-history - Return the line that is being + edited, then arrange for the + next most recent entry in the + history buffer to be recalled + when gl_get_line() is + next called. Repeatedly + invoking this action causes + successive historical input + lines to be re-executed. Note + that this action is equivalent + to the 'Operate' action in + ksh. + ring-bell - Ring the terminal bell, unless + the bell has been silenced via + the nobeep configuration + option (see the THE TECLA + CONFIGURATION FILE section). + forward-copy-char - Copy the next character into + the cut buffer (NB. use repeat + counts to copy more than one). + backward-copy-char - Copy the previous character + into the cut buffer. + forward-copy-word - Copy the next word into the cut + buffer. + backward-copy-word - Copy the previous word into the + cut buffer. + forward-find-char - Move the cursor to the next + occurrence of the next + character that you type. + backward-find-char - Move the cursor to the last + occurrence of the next + character that you type. + forward-to-char - Move the cursor to the + character just before the next + occurrence of the next + character that the user types. + backward-to-char - Move the cursor to the + character just after the last + occurrence before the cursor + of the next character that the + user types. + repeat-find-char - Repeat the last + backward-find-char, + forward-find-char, + backward-to-char or + forward-to-char. + invert-refind-char - Repeat the last + backward-find-char, + forward-find-char, + backward-to-char, or + forward-to-char in the + opposite direction. + delete-to-column - Delete the characters from the + cursor up to the column that + is specified by the repeat + count. + delete-to-parenthesis - Delete the characters from the + cursor up to and including + the matching parenthesis, or + next close parenthesis. + forward-delete-find - Delete the characters from the + cursor up to and including the + following occurence of the + next character typed. + backward-delete-find - Delete the characters from the + cursor up to and including the + preceding occurence of the + next character typed. + forward-delete-to - Delete the characters from the + cursor up to, but not + including, the following + occurence of the next + character typed. + backward-delete-to - Delete the characters from the + cursor up to, but not + including, the preceding + occurence of the next + character typed. + delete-refind - Repeat the last *-delete-find + or *-delete-to action. + delete-invert-refind - Repeat the last *-delete-find + or *-delete-to action, in the + opposite direction. + copy-to-column - Copy the characters from the + cursor up to the column that + is specified by the repeat + count, into the cut buffer. + copy-to-parenthesis - Copy the characters from the + cursor up to and including + the matching parenthesis, or + next close parenthesis, into + the cut buffer. + forward-copy-find - Copy the characters from the + cursor up to and including the + following occurence of the + next character typed, into the + cut buffer. + backward-copy-find - Copy the characters from the + cursor up to and including the + preceding occurence of the + next character typed, into the + cut buffer. + forward-copy-to - Copy the characters from the + cursor up to, but not + including, the following + occurence of the next + character typed, into the cut + buffer. + backward-copy-to - Copy the characters from the + cursor up to, but not + including, the preceding + occurence of the next + character typed, into the cut + buffer. + copy-refind - Repeat the last *-copy-find + or *-copy-to action. + copy-invert-refind - Repeat the last *-copy-find + or *-copy-to action, in the + opposite direction. + vi-mode - Switch to vi mode from emacs + mode. + emacs-mode - Switch to emacs mode from vi + mode. + vi-insert - From vi command mode, switch to + insert mode. + vi-overwrite - From vi command mode, switch to + overwrite mode. + vi-insert-at-bol - From vi command mode, move the + cursor to the start of the line + and switch to insert mode. + vi-append-at-eol - From vi command mode, move the + cursor to the end of the line + and switch to append mode. + vi-append - From vi command mode, move the + cursor one position right, and + switch to insert mode. + vi-replace-char - From vi command mode, replace + the character under the cursor + with the the next character + entered. + vi-forward-change-char - From vi command mode, delete + the next character then enter + insert mode. + vi-backward-change-char - From vi command mode, delete + the preceding character then + enter insert mode. + vi-forward-change-word - From vi command mode, delete + the next word then enter + insert mode. + vi-backward-change-word - From vi command mode, delete + the preceding word then + enter insert mode. + vi-change-rest-of-line - From vi command mode, delete + from the cursor to the end of + the line, then enter insert + mode. + vi-change-line - From vi command mode, delete + the current line, then enter + insert mode. + vi-change-to-bol - From vi command mode, delete + all characters between the + cursor and the beginning of + the line, then enter insert + mode. + vi-change-to-column - From vi command mode, delete + the characters from the cursor + up to the column that is + specified by the repeat count, + then enter insert mode. + vi-change-to-parenthesis - Delete the characters from the + cursor up to and including + the matching parenthesis, or + next close parenthesis, then + enter vi insert mode. + vi-forward-change-find - From vi command mode, delete + the characters from the + cursor up to and including the + following occurence of the + next character typed, then + enter insert mode. + vi-backward-change-find - From vi command mode, delete + the characters from the + cursor up to and including the + preceding occurence of the + next character typed, then + enter insert mode. + vi-forward-change-to - From vi command mode, delete + the characters from the + cursor up to, but not + including, the following + occurence of the next + character typed, then enter + insert mode. + vi-backward-change-to - From vi command mode, delete + the characters from the + cursor up to, but not + including, the preceding + occurence of the next + character typed, then enter + insert mode. + vi-change-refind - Repeat the last + vi-*-change-find or + vi-*-change-to action. + vi-change-invert-refind - Repeat the last + vi-*-change-find or + vi-*-change-to action, in the + opposite direction. + vi-undo - In vi mode, undo the last + editing operation. + vi-repeat-change - In vi command mode, repeat the + last command that modified the + line. + + +</pre><h2>DEFAULT KEY BINDINGS IN EMACS MODE</h2><pre> + The following default key bindings, which can be overriden + by the tecla configuration file, are designed to mimic most + of the bindings of the unix tcsh shell, when it is in emacs + editing mode. + + This is the default editing mode of the tecla library. + + Note that a key sequence like ^A or C-a means hold the + control-key down while pressing the letter A, and that where + you see \E or M- in a binding, this represents the escape + key or the Meta modifier key. Also note that to + gl_get_line(), pressing the escape key before a key is + equivalent to pressing the meta key at the same time as that + key. Thus the key sequence M-p can be typed in two ways, by + pressing the escape key, followed by pressing p, or by + pressing the Meta key at the same time as p. + + Under UNIX the terminal driver sets a number of special keys + for certain functions. The tecla library attempts to use the + same keybindings to maintain consistency. The key sequences + shown for the following 6 bindings are thus just examples of + what they will probably be set to. If you have used the stty + command to change these keys, then the default bindings + should match. + + ^C -> user-interrupt + ^\ -> abort + ^Z -> suspend + ^Q -> start-output + ^S -> stop-output + ^V -> literal-next + + The cursor keys are refered to by name, as follows. This is + necessary because different types of terminals generate dif- + ferent key sequences when their cursor keys are pressed. + + right -> cursor-right + left -> cursor-left + up -> up-history + down -> down-history + + The remaining bindings don't depend on the terminal sett- + tings. + + ^F -> cursor-right + ^B -> cursor-left + M-i -> insert-mode + ^A -> beginning-of-line + ^E -> end-of-line + ^U -> delete-line + ^K -> kill-line + M-f -> forward-word + M-b -> backward-word + ^D -> del-char-or-list-or-eof + ^H -> backward-delete-char + ^? -> backward-delete-char + M-d -> forward-delete-word + M-^H -> backward-delete-word + M-^? -> backward-delete-word + M-u -> upcase-word + M-l -> downcase-word + M-c -> capitalize-word + ^R -> redisplay + ^L -> clear-screen + ^T -> transpose-chars + ^@ -> set-mark + ^X^X -> exchange-point-and-mark + ^W -> kill-region + M-w -> copy-region-as-kill + ^Y -> yank + ^P -> up-history + ^N -> down-history + M-p -> history-search-backward + M-n -> history-search-forward + ^I -> complete-word + ^X* -> expand-filename + ^X^F -> read-from-file + ^X^R -> read-init-files + ^Xg -> list-glob + ^Xh -> list-history + M-< -> beginning-of-history + M-> -> end-of-history + \n -> newline + \r -> newline + M-o -> repeat-history + M-^V -> vi-mode + + M-0, M-1, ... M-9 -> digit-argument (see below) + + Note that ^I is what the TAB key generates, and that ^@ can + be generated not only by pressing the control key and the @ + key simultaneously, but also by pressing the control key and + the space bar at the same time. + + +</pre><h2>DEFAULT KEY BINDINGS IN VI MODE</h2><pre> + The following default key bindings are designed to mimic the + vi style of editing as closely as possible. This means that + very few editing functions are provided in the initial char- + acter input mode, editing functions instead being provided + by the vi command mode. Vi command mode is entered whenever + the escape character is pressed, or whenever a key-sequence + that starts with a meta character is entered. In addition to + mimicing vi, libtecla provides bindings for tab completion, + wild-card expansion of file names, and historical line + recall. + + To learn how to tell the tecla library to use vi mode + instead of the default emacs editing mode, see the section + entitled THE TECLA CONFIGURATION FILE. + + As already mentioned above in the emacs section, Note that a + key sequence like ^A or C-a means hold the control-key down + while pressing the letter A, and that where you see \E or M- + in a binding, this represents the escape key or the Meta + modifier key. Also note that to gl_get_line(), pressing the + escape key before a key is equivalent to pressing the meta + key at the same time as that key. Thus the key sequence M-p + can be typed in two ways, by pressing the escape key, fol- + lowed by pressing p, or by pressing the Meta key at the same + time as p. + + Under UNIX the terminal driver sets a number of special keys + for certain functions. The tecla library attempts to use the + same keybindings to maintain consistency, binding them both + in input mode and in command mode. The key sequences shown + for the following 6 bindings are thus just examples of what + they will probably be set to. If you have used the stty com- + mand to change these keys, then the default bindings should + match. + + ^C -> user-interrupt + ^\ -> abort + ^Z -> suspend + ^Q -> start-output + ^S -> stop-output + ^V -> literal-next + M-^C -> user-interrupt + M-^\ -> abort + M-^Z -> suspend + M-^Q -> start-output + M-^S -> stop-output + + Note that above, most of the bindings are defined twice, + once as a raw control code like ^C and then a second time as + a meta character like M-^C. The former is the binding for vi + input mode, whereas the latter is the binding for vi command + mode. Once in command mode all key-sequences that the user + types that they don't explicitly start with an escape or a + meta key, have their first key secretly converted to a meta + character before the key sequence is looked up in the key + binding table. Thus, once in command mode, when you type the + letter i, for example, the tecla library actually looks up + the binding for M-i. + + The cursor keys are refered to by name, as follows. This is + necessary because different types of terminals generate dif- + ferent key sequences when their cursor keys are pressed. + + right -> cursor-right + left -> cursor-left + up -> up-history + down -> down-history + + The cursor keys normally generate a keysequence that start + with an escape character, so beware that using the arrow + keys will put you into command mode (if you aren't already + in command mode). + + The following are the terminal-independent key bindings for + vi input mode. + + ^D -> list-or-eof + ^G -> list-glob + ^H -> backward-delete-char + ^I -> complete-word + \r -> newline + \n -> newline + ^L -> clear-screen + ^N -> down-history + ^P -> up-history + ^R -> redisplay + ^U -> backward-kill-line + ^W -> backward-delete-word + ^X* -> expand-filename + ^X^F -> read-from-file + ^X^R -> read-init-files + ^? -> backward-delete-char + + The following are the key bindings that are defined in vi + command mode, this being specified by them all starting with + a meta character. As mentioned above, once in command mode + the initial meta character is optional. For example, you + might enter command mode by typing Esc, and then press h + twice to move the cursor two positions to the left. Both h + characters get quietly converted to M-h before being com- + pared to the key-binding table, the first one because Escape + followed by a character is always converted to the + equivalent meta character, and the second because command + mode was already active. + + M-\ -> cursor-right (Meta-space) + M-$ -> end-of-line + M-* -> expand-filename + M-+ -> down-history + M-- -> up-history + M-< -> beginning-of-history + M-> -> end-of-history + M-^ -> beginning-of-line + M-; -> repeat-find-char + M-, -> invert-refind-char + M-| -> goto-column + M-~ -> change-case + M-. -> vi-repeat-change + M-% -> find-parenthesis + M-a -> vi-append + M-A -> vi-append-at-eol + M-b -> backward-word + M-B -> backward-word + M-C -> vi-change-rest-of-line + M-cb -> vi-backward-change-word + M-cB -> vi-backward-change-word + M-cc -> vi-change-line + M-ce -> vi-forward-change-word + M-cE -> vi-forward-change-word + M-cw -> vi-forward-change-word + M-cW -> vi-forward-change-word + M-cF -> vi-backward-change-find + M-cf -> vi-forward-change-find + M-cT -> vi-backward-change-to + M-ct -> vi-forward-change-to + M-c; -> vi-change-refind + M-c, -> vi-change-invert-refind + M-ch -> vi-backward-change-char + M-c^H -> vi-backward-change-char + M-c^? -> vi-backward-change-char + M-cl -> vi-forward-change-char + M-c\ -> vi-forward-change-char (Meta-c-space) + M-c^ -> vi-change-to-bol + M-c0 -> vi-change-to-bol + M-c$ -> vi-change-rest-of-line + M-c| -> vi-change-to-column + M-c% -> vi-change-to-parenthesis + M-dh -> backward-delete-char + M-d^H -> backward-delete-char + M-d^? -> backward-delete-char + M-dl -> forward-delete-char + M-d -> forward-delete-char (Meta-d-space) + M-dd -> delete-line + M-db -> backward-delete-word + M-dB -> backward-delete-word + M-de -> forward-delete-word + M-dE -> forward-delete-word + M-dw -> forward-delete-word + M-dW -> forward-delete-word + M-dF -> backward-delete-find + M-df -> forward-delete-find + M-dT -> backward-delete-to + M-dt -> forward-delete-to + M-d; -> delete-refind + M-d, -> delete-invert-refind + M-d^ -> backward-kill-line + M-d0 -> backward-kill-line + M-d$ -> kill-line + M-D -> kill-line + M-d| -> delete-to-column + M-d% -> delete-to-parenthesis + M-e -> forward-word + M-E -> forward-word + M-f -> forward-find-char + M-F -> backward-find-char + M-- -> up-history + M-h -> cursor-left + M-H -> beginning-of-history + M-i -> vi-insert + M-I -> vi-insert-at-bol + M-j -> down-history + M-J -> history-search-forward + M-k -> up-history + M-K -> history-search-backward + M-l -> cursor-right + M-L -> end-of-history + M-n -> history-re-search-forward + M-N -> history-re-search-backward + M-p -> append-yank + M-P -> yank + M-r -> vi-replace-char + M-R -> vi-overwrite + M-s -> vi-forward-change-char + M-S -> vi-change-line + M-t -> forward-to-char + M-T -> backward-to-char + M-u -> vi-undo + M-w -> forward-to-word + M-W -> forward-to-word + M-x -> forward-delete-char + M-X -> backward-delete-char + M-yh -> backward-copy-char + M-y^H -> backward-copy-char + M-y^? -> backward-copy-char + M-yl -> forward-copy-char + M-y\ -> forward-copy-char (Meta-y-space) + M-ye -> forward-copy-word + M-yE -> forward-copy-word + M-yw -> forward-copy-word + M-yW -> forward-copy-word + M-yb -> backward-copy-word + M-yB -> backward-copy-word + M-yf -> forward-copy-find + M-yF -> backward-copy-find + M-yt -> forward-copy-to + M-yT -> backward-copy-to + M-y; -> copy-refind + M-y, -> copy-invert-refind + M-y^ -> copy-to-bol + M-y0 -> copy-to-bol + M-y$ -> copy-rest-of-line + M-yy -> copy-line + M-Y -> copy-line + M-y| -> copy-to-column + M-y% -> copy-to-parenthesis + M-^E -> emacs-mode + M-^H -> cursor-left + M-^? -> cursor-left + M-^L -> clear-screen + M-^N -> down-history + M-^P -> up-history + M-^R -> redisplay + M-^D -> list-or-eof + M-^I -> complete-word + M-\r -> newline + M-\n -> newline + M-^X^R -> read-init-files + M-^Xh -> list-history + + M-0, M-1, ... M-9 -> digit-argument (see below) + + Note that ^I is what the TAB key generates. + + +</pre><h2>ENTERING REPEAT COUNTS</h2><pre> + Many of the key binding functions described previously, take + an optional count, typed in before the target keysequence. + This is interpreted as a repeat count by most bindings. A + notable exception is the goto-column binding, which inter- + prets the count as a column number. + + By default you can specify this count argument by pressing + the meta key while typing in the numeric count. This relies + on the digit-argument action being bound to Meta-0, Meta-1 + etc. Once any one of these bindings has been activated, you + can optionally take your finger off the meta key to type in + the rest of the number, since every numeric digit thereafter + is treated as part of the number, unless it is preceded by + the literal-next binding. As soon as a non-digit, or literal + digit key is pressed the repeat count is terminated and + either causes the just typed character to be added to the + line that many times, or causes the next key-binding func- + tion to be given that argument. + + For example, in emacs mode, typing: + + M-12a + + causes the letter 'a' to be added to the line 12 times, + whereas + + M-4M-c + + Capitalizes the next 4 words. + + In vi command mode the Meta modifier is automatically added + to all characters typed in, so to enter a count in vi + command-mode, just involves typing in the number, just as at + it does in the vi editor itself. So for example, in vi com- + mand mode, typing: + + 4w2x + + moves the cursor four words to the right, then deletes two + characters. + + You can also bind digit-argument to other key sequences. If + these end in a numeric digit, that digit gets appended to + the current repeat count. If it doesn't end in a numeric + digit, a new repeat count is started with a value of zero, + and can be completed by typing in the number, after letting + go of the key which triggered the digit-argument action. + + +</pre><h2>THE TECLA CONFIGURATION FILE</h2><pre> + By default, the first call to gl_get_line() looks for a file + called .teclarc in your home directory (ie. ~/.teclarc). If + it finds this file, it reads it, interpreting each line as + defining a new key binding or an editing configuration + option. Since the emacs keybindings are installed by + default, if you want to use the non-default vi editing mode, + the most important item to go in this file is the following + line: + + edit-mode vi + + This will re-configure the default bindings for vi-mode. The + complete set of arguments that this command accepts are: + + vi - Install key-bindings like those of the vi + editor. + emacs - Install key-bindings like those of the emacs + editor. This is the default. + none - Use just the native line editing facilities + provided by the terminal driver. + + To prevent the terminal bell from being rung, such as when + an unrecognized control-sequence is typed, place the follow- + ing line in the configuration file: + + nobeep + + An example of a key binding line in the configuration file + is the following. + + bind M-[2~ insert-mode + + On many keyboards, the above key sequence is generated when + one presses the insert key, so with this keybinding, one can + toggle between the emacs-mode insert and overwrite modes by + hitting one key. One could also do it by typing out the + above sequence of characters one by one. As explained above, + the M- part of this sequence can be typed either by pressing + the escape key before the following key, or by pressing the + Meta key at the same time as the following key. Thus if you + had set the above key binding, and the insert key on your + keyboard didn't generate the above key sequence, you could + still type it in either of the following 2 ways. + + 1. Hit the escape key momentarily, then press '[', then '2', then + finally '~'. + + 2. Press the meta key at the same time as pressing the '[' key, + then press '2', then '~'. + + If you set a keybinding for a key-sequence that is already + bound to a function, the new binding overrides the old one. + If in the new binding you omit the name of the new function + to bind to the key-sequence, the original binding becomes + undefined. + + Starting with versions of libtecla later than 1.3.3 it is + now possible to bind keysequences that begin with a print- + able character. Previously key-sequences were required to + start with a control or meta character. + + Note that the special keywords "up", "down", "left" and + "right" refer to the arrow keys, and are thus not treated as + keysequences. So, for example, to rebind the up and down + arrow keys to use the history search mechanism instead of + the simple history recall method, you could place the fol- + lowing in your configuration file: + + bind up history-search-backwards + bind down history-search-backwards + + To unbind an existing binding, you can do this with the bind + command by omitting to name any action to rebind the key + sequence to. For example, by not specifying an action func- + tion, the following command unbinds the default beginning- + of-line action from the ^A key sequence: + + bind ^A + + +</pre><h2>ALTERNATE CONFIGURATION SOURCES</h2><pre> + As mentioned above, by default users have the option of con- + figuring the behavior of gl_get_line() via a configuration + file called .teclarc in their home directories. The fact + that all applications share this same configuration file is + both an advantage and a disadvantage. In most cases it is + an advantage, since it encourages uniformity, and frees the + user from having to configure each application separately. + In some applications, however, this single means of confi- + guration is a problem. This is particularly true of embedded + software, where there's no filesystem to read a configura- + tion file from, and also in applications where a radically + different choice of keybindings is needed to emulate a + legacy keyboard interface. To cater for such cases, the + following function allows the application to control where + configuration information is read from. + + + int gl_configure_getline(GetLine *gl, + const char *app_string, + const char *app_file, + const char *user_file); + + + It allows the configuration commands that would normally be + read from a user's ~/.teclarc file, to be read from any or + none of, a string, an application specific configuration + file, and/or a user-specific configuration file. If this + function is called before the first call to gl_get_line(), + the default behavior of reading ~/.teclarc on the first call + to gl_get_line() is disabled, so all configuration must be + achieved using the configuration sources specified with this + function. + + If app_string != NULL, then it is interpreted as a string + containing one or more configuration commands, separated + from each other in the string by embedded newline charac- + ters. If app_file != NULL then it is interpreted as the full + pathname of an application-specific configuration file. If + user_file != NULL then it is interpreted as the full path- + name of a user-specific configuration file, such as + ~/.teclarc. For example, in the following call, + + gl_configure_getline(gl, "edit-mode vi \n nobeep", + "/usr/share/myapp/teclarc", + "~/.teclarc"); + + the app_string argument causes the calling application to + start in vi edit-mode, instead of the default emacs mode, + and turns off the use of the terminal bell by the library. + It then attempts to read system-wide configuration commands + from an optional file called /usr/share/myapp/teclarc, then + finally reads user-specific configuration commands from an + optional .teclarc file in the user's home directory. Note + that the arguments are listed in ascending order of prior- + ity, with the contents of app_string being potentially over- + riden by commands in app_file, and commands in app_file + potentially being overriden by commands in user_file. + You can call this function as many times as needed, the + results being cumulative, but note that copies of any + filenames specified via the app_file and user_file arguments + are recorded internally for subsequent use by the read- + init-files key-binding function, so if you plan to call this + function multiple times, be sure that the last call speci- + fies the filenames that you want re-read when the user + requests that the configuration files be re-read. + + +</pre><h2>FILENAME AND TILDE COMPLETION</h2><pre> + With the default key bindings, pressing the TAB key (aka. + ^I) results in gl_get_line() attempting to complete the + incomplete filename that precedes the cursor. gl_get_line() + searches backwards from the cursor, looking for the start of + the filename, stopping when it hits either a space or the + start of the line. If more than one file has the specified + prefix, gl_get_line() completes the filename up to the point + at which the ambiguous matches start to differ, then lists + the possible matches. + + In addition to literally written filenames, gl_get_line() + can complete files that start with ~/ and ~user/ expressions + and that contain $envvar expressions. In particular, if you + hit TAB within an incomplete ~user, expression, + gl_get_line() will attempt to complete the username, listing + any ambiguous matches. + + The completion binding is implemented using the + cpl_word_completions() function, which is also available + separately to users of this library. See the + cpl_word_completions(3) man page for more details. + + +</pre><h2>CUSTOMIZED WORD COMPLETION</h2><pre> + If in your application, you would like to have TAB comple- + tion complete other things in addition to or instead of + filenames, you can arrange this by registering an alternate + completion callback function, via a call to the + gl_customize_completion() function. + + int gl_customize_completion(GetLine *gl, void *data, + CplMatchFn *match_fn); + + The data argument provides a way for your application to + pass arbitrary, application-specific information to the + callback function. This is passed to the callback every time + that it is called. It might for example, point to the symbol + table from which possible completions are to be sought. The + match_fn argument specifies the callback function to be + called. The CplMatchFn function type is defined in + libtecla.h, as is a CPL_MATCH_FN() macro that you can use to + declare and prototype callback functions. The declaration + and responsibilities of callback functions are described in + depth in the <a href="cpl_complete_word.html">cpl_complete_word(3)</a> man page. + + In brief, the callback function is responsible for looking + backwards in the input line, back from the point at which + the user pressed TAB, to find the start of the word being + completed. It then must lookup possible completions of this + word, and record them one by one in the WordCompletion + object that is passed to it as an argument, by calling the + cpl_add_completion() function. If the callback function + wishes to provide filename completion in addition to its own + specific completions, it has the option of itself calling + the builtin file-name completion callback. This also, is + documented in the <a href="cpl_complete_word.html">cpl_complete_word(3)</a> man page. + + Note that if you would like gl_get_line() to return the + current input line when a successful completion is been + made, you can arrange this when you call + cpl_add_completion(), by making the last character of the + continuation suffix a newline character. If you do this, the + input line will be updated to display the completion, + together with any contiuation suffix up to the newline char- + acter, then gl_get_line() will return this input line. + + +</pre><h2>FILENAME EXPANSION</h2><pre> + With the default key bindings, pressing ^X* causes + gl_get_line() to expand the filename that precedes the cur- + sor, replacing ~/ and ~user/ expressions with the + corresponding home directories, and replacing $envvar + expressions with the value of the specified environment + variable, then if there are any wildcards, replacing the so + far expanded filename with a space-separated list of the + files which match the wild cards. + + The expansion binding is implemented using the + ef_expand_file() function. See the <a href="ef_expand_file.html">ef_expand_file(3)</a> man + page for more details. + + +</pre><h2>RECALLING PREVIOUSLY TYPED LINES</h2><pre> + Every time that a new line is entered by the user, it is + appended to a list of historical input lines maintained + within the GetLine resource object. You can traverse up and + down this list using the up and down arrow keys. Alterna- + tively, you can do the same with the ^P, and ^N keys, and in + vi command mode you can alternatively use the k and j char- + acters. Thus pressing up-arrow once, replaces the current + input line with the previously entered line. Pressing up- + arrow again, replaces this with the line that was entered + before it, etc.. Having gone back one or more lines into the + history list, one can return to newer lines by pressing + down-arrow one or more times. If you do this sufficient + times, you will return to the original line that you were + entering when you first hit up-arrow. + + Note that in vi mode, all of the history recall functions + switch the library into command mode. + + In emacs mode the M-p and M-n keys work just like the ^P and + ^N keys, except that they skip all but those historical + lines which share the prefix that precedes the cursor. In vi + command mode the upper case K and J characters do the same + thing, except that the string that they search for includes + the character under the cursor as well as what precedes it. + + Thus for example, suppose that you were in emacs mode, and + you had just entered the following list of commands in the + order shown: + + ls ~/tecla/ + cd ~/tecla + ls -l getline.c + emacs ~/tecla/getline.c + + If you next typed: + + ls + + and then hit M-p, then rather than returning the previously + typed emacs line, which doesn't start with "ls", + gl_get_line() would recall the "ls -l getline.c" line. + Pressing M-p again would recall the "ls ~/tecla/" line. + + +</pre><h2>HISTORY FILES</h2><pre> + To save the contents of the history buffer before quitting + your application, and subsequently restore them when you + next start the application, the following functions are pro- + vided. + + + 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); + + + The filename argument specifies the name to give the history + file when saving, or the name of an existing history file, + when loading. This may contain home-directory and environ- + ment variable expressions, such as "~/.myapp_history" or + "$HOME/.myapp_history". + Along with each history line, extra information about it, + such as when it was entered by the user, and what its nest- + ing level is, is recorded as a comment preceding the line in + the history file. Writing this as a comment allows the his- + tory file to double as a command file, just in case you wish + to replay a whole session using it. Since comment prefixes + differ in different languages, the comment argument is pro- + vided for specifying the comment prefix. For example, if + your application were a unix shell, such as the bourne + shell, you would specify "#" here. Whatever you choose for + the comment character, you must specify the same prefix to + gl_load_history() that you used when you called + gl_save_history() to write the history file. + + The max_lines must be either -1 to specify that all lines in + the history list be saved, or a positive number specifying a + ceiling on how many of the most recent lines should be + saved. + + Both fuctions return non-zero on error, after writing an + error message to stderr. Note that gl_load_history() does + not consider the non-existence of a file to be an error. + + +</pre><h2>MULTIPLE HISTORY LISTS</h2><pre> + If your application uses a single GetLine object for enter- + ing many different types of input lines, you may wish + gl_get_line() to distinguish the different types of lines in + the history list, and only recall lines that match the + current type of line. To support this requirement, + gl_get_line() marks lines being recorded in the history list + with an integer identifier chosen by the application. Ini- + tially this identifier is set to 0 by new_GetLine(), but it + can be changed subsequently by calling gl_group_history(). + + + int gl_group_history(GetLine *gl, unsigned id); + + + The integer identifier id can be any number chosen by the + application, but note that gl_save_history() and + gl_load_history() preserve the association between identif- + iers and historical input lines between program invokations, + so you should choose fixed identifiers for the different + types of input line used by your application. + + Whenever gl_get_line() appends a new input line to the his- + tory list, the current history identifier is recorded with + it, and when it is asked to recall a historical input line, + it only recalls lines that are marked with the current iden- + tifier. + +</pre><h2>DISPLAYING HISTORY</h2><pre> + The history list can be displayed by calling + gl_show_history(). + + + int gl_show_history(GetLine *gl, FILE *fp, + const char *fmt, + int all_groups, + int max_lines); + + + This displays the current contents of the history list to + the stdio output stream fp. If the max_lines argument is + greater than or equal to zero, then no more than this number + of the most recent lines will be displayed. If the + all_groups argument is non-zero, lines from all history + groups are displayed. Otherwise just those of the currently + selected history group are displayed. The format string + argument, fmt, determines how the line is displayed. This + can contain arbitrary characters which are written verbatim, + interleaved with any of the following format directives: + + %D - The date on which the line was originally + entered, formatted like 2001-11-20. + %T - The time of day when the line was entered, + formatted like 23:59:59. + %N - The sequential entry number of the line in + the history buffer. + %G - The number of the history group which the + line belongs to. + %% - A literal % character. + %H - The history line itself. + + Thus a format string like "%D %T %H0 would output something + like: + + 2001-11-20 10:23:34 Hello world + + Note the inclusion of an explicit newline character in the + format string. + + +</pre><h2>LOOKING UP HISTORY</h2><pre> + The gl_lookup_history() function allows the calling applica- + tion to look up lines in the history list. + + + typedef struct { + const char *line; /* The requested historical */ + /* 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; + + int gl_lookup_history(GetLine *gl, unsigned long id, + GlHistoryLine *hline); + + + The id argument indicates which line to look up, where the + first line that was entered in the history list after + new_GetLine() was called, is denoted by 0, and subsequently + entered lines are denoted with successively higher numbers. + Note that the range of lines currently preserved in the his- + tory list can be queried by calling the + gl_range_of_history() function, described later. If the + requested line is in the history list, the details of the + line are recorded in the variable pointed to by the hline + argument, and 1 is returned. Otherwise 0 is returned, and + the variable pointed to by hline is left unchanged. + + Beware that the string returned in hline->line is part of + the history buffer, so it must not be modified by the + caller, and will be recycled on the next call to any func- + tion that takes gl as its argument. Therefore you should + make a private copy of this string if you need to keep it + around. + + +</pre><h2>MISCELLANEOUS HISTORY CONFIGURATION</h2><pre> + If you wish to change the size of the history buffer that + was originally specified in the call to new_GetLine(), you + can do so with the gl_resize_history() function. + + + int gl_resize_history(GetLine *gl, size_t histlen); + + + The histlen argument specifies the new size in bytes, and if + you specify this as 0, the buffer will be deleted. + + As mentioned in the discussion of new_GetLine(), the number + of lines that can be stored in the history buffer, depends + on the lengths of the individual lines. For example, a 1000 + byte buffer could equally store 10 lines of average length + 100 bytes, or 2 lines of average length 50 bytes. Although + the buffer is never expanded when new lines are added, a + list of pointers into the buffer does get expanded when + needed to accomodate the number of lines currently stored in + the buffer. To place an upper limit on the number of lines + in the buffer, and thus a ceiling on the amount of memory + used in this list, you can call the gl_limit_history() + function. + + + void gl_limit_history(GetLine *gl, int max_lines); + + + The max_lines should either be a positive number >= 0, + specifying an upper limit on the number of lines in the + buffer, or be -1 to cancel any previously specified limit. + When a limit is in effect, only the max_lines most recently + appended lines are kept in the buffer. Older lines are dis- + carded. + + To discard lines from the history buffer, use the + gl_clear_history() function. + + void gl_clear_history(GetLine *gl, int all_groups); + + The all_groups argument tells the function whether to delete + just the lines associated with the current history group + (see gl_group_history()), or all historical lines in the + buffer. + + The gl_toggle_history() function allows you to toggle his- + tory on and off without losing the current contents of the + history list. + + + void gl_toggle_history(GetLine *gl, int enable); + + + Setting the enable argument to 0 turns off the history + mechanism, and setting it to 1 turns it back on. When his- + tory is turned off, no new lines will be added to the his- + tory list, and history lookup key-bindings will act as + though there is nothing in the history buffer. + + +</pre><h2>QUERYING HISTORY INFORMATION</h2><pre> + The configured state of the history list can be queried with + the gl_history_state() function. + + + 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; + + void gl_state_of_history(GetLine *gl, + GlHistoryState *state); + + On return, the status information is recorded in the vari- + able pointed to by the state argument. + + The gl_range_of_history() function returns the number and + range of lines in the history list. + + + 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; + + void gl_range_of_history(GetLine *gl, GlHistoryRange *range); + + The return values are recorded in the variable pointed to by + the range argument. If the nlines member of this structure + is greater than zero, then the oldest and newest members + report the range of lines in the list, and + newest=oldest+nlines-1. Otherwise they are both zero. + + The gl_size_of_history() function returns the total size of + the history buffer and the amount of the buffer that is + currently occupied. + + 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; + + void gl_size_of_history(GetLine *gl, GlHistorySize *size); + + On return, the size information is recorded in the variable + pointed to by the size argument. + + +</pre><h2>CHANGING TERMINALS</h2><pre> + The new_GetLine() constructor function assumes that input is + to be read from stdin, and output written to stdout. The + following function allows you to switch to different input + and output streams. + + int gl_change_terminal(GetLine *gl, FILE *input_fp, + FILE *output_fp, const char *term); + + The gl argument is the object that was returned by + new_GetLine(). The input_fp argument specifies the stream + to read from, and output_fp specifies the stream to be writ- + ten to. Only if both of these refer to a terminal, will + interactive terminal input be enabled. Otherwise + gl_get_line() will simply call fgets() to read command + input. If both streams refer to a terminal, then they must + refer to the same terminal, and the type of this terminal + must be specified via the term argument. The value of the + term argument is looked up in the terminal information data- + base (terminfo or termcap), in order to determine which spe- + cial control sequences are needed to control various aspects + of the terminal. new_GetLine() for example, passes the + return value of getenv("TERM") in this argument. Note that + if one or both of input_fp and output_fp don't refer to a + terminal, then it is legal to pass NULL instead of a termi- + nal type. + + Note that if you want to pass file descriptors to + gl_change_terminal(), you can do this by creating stdio + stream wrappers using the POSIX fdopen() function. + + +</pre><h2>EXTERNAL EVENT HANDLING</h2><pre> + While gl_get_line() is waiting for keyboard input from the + user, you can ask it to also watch for activity on arbitrary + file descriptors, such as network sockets, pipes etc, and + have it call functions of your choosing when activity is + seen. This works on any system that has the select() system + call, which is most, if not all flavors of unix. Registering + a file descriptor to be watched by gl_get_line() involves + calling the gl_watch_fd() function. + + + int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event, + GlFdEventFn *callback, void *data); + + + If this returns non-zero, then it means that either your + arguments are invalid, or that this facility isn't supported + on the host system. + + The fd argument is the file descriptor to be watched. The + event argument specifies what type of activity is of + interest, chosen from the following enumerated values: + + + GLFD_READ - Watch for the arrival of data to be read. + GLFD_WRITE - Watch for the ability to write to the file + descriptor without blocking. + GLFD_URGENT - Watch for the arrival of urgent + out-of-band data on the file descriptor. + + + The callback argument is the function to call when the + selected activity is seen. It should be defined with the + following macro, which is defined in libtecla.h. + + + #define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, \ + void *data, int fd, \ + GlFdEvent event) + + The data argument of the gl_watch_fd() function is passed to + the callback function for its own use, and can point to any- + thing you like, including NULL. The file descriptor and the + event argument are also passed to the callback function, and + this potentially allows the same callback function to be + registered to more than one type of event and/or more than + one file descriptor. The return value of the callback func- + tion should be one of the following values. + + + GLFD_ABORT - Tell gl_get_line() to abort with an + error (errno won't be set, so set it + appropriately yourself if you need it). + GLFD_REFRESH - Redraw the input line then continue + waiting for input. Return this if + your callback wrote to the terminal. + GLFD_CONTINUE - Continue to wait for input, without + redrawing the line. + + Note that before calling the callback, gl_get_line() blocks + most signals, and leaves its own signal handlers installed, + so if you need to catch a particular signal you will need to + both temporarily install your own signal handler, and + unblock the signal. Be sure to re-block the signal (if it + was originally blocked) and reinstate the original signal + handler, if any, before returning. + + Your callback shouldn't try to read from the terminal, which + is left in raw mode as far as input is concerned. You can + however write to the terminal as usual, since features like + conversion of newline to carriage-return/linefeed are re- + enabled while the callback is running. If your callback + function does write to the terminal, be sure to output a + newline first, and when your callback returns, tell + gl_get_line() that the input line needs to be redrawn, by + returning the GLFD_REFRESH status code. + + To remove a callback function that you previously registered + for a given file descriptor and event, simply call + gl_watch_fd() with the same file descriptor and event argu- + ments, but with a callback argument of 0. The data argument + is ignored in this case. + + +</pre><h2>SIGNAL HANDLING DEFAULTS</h2><pre> + By default, the gl_get_line() function intercepts a number + of signals. This is particularly important for signals which + would by default terminate the process, since the terminal + needs to be restored to a usable state before this happens. + In this section, the signals that are trapped by default, + and how gl_get_line() responds to them, is described. Chang- + ing these defaults is the topic of the following section. + + When the following subset of signals are caught, + gl_get_line() first restores the terminal settings and sig- + nal handling to how they were before gl_get_line() was + called, resends the signal, to allow the calling + application's signal handlers to handle it, then if the pro- + cess still exists, gl_get_line() returns NULL and sets errno + as specified below. + + + SIGINT - This signal is generated both by the keyboard + interrupt key (usually ^C), and the keyboard + break key. + + errno=EINTR + + SIGHUP - This signal is generated when the controlling + terminal exits. + + errno=ENOTTY + + SIGPIPE - This signal is generated when a program attempts + to write to a pipe who's remote end isn't being + read by any process. This can happen for example + if you have called gl_change_terminal() to + redirect output to a pipe hidden under a pseudo + terminal. + + errno=EPIPE + + SIGQUIT - This signal is generated by the keyboard quit + key (usually ^\). + + errno=EINTR + + SIGABRT - This signal is generated by the standard C, + abort() function. By default it both + terminates the process and generates a core + dump. + + errno=EINTR + + SIGTERM - This is the default signal that the UN*X + kill command sends to processes. + + errno=EINTR + + Note that in the case of all of the above signals, POSIX + mandates that by default the process is terminated, with the + addition of a core dump in the case of the SIGQUIT signal. + In other words, if the calling application doesn't override + the default handler by supplying its own signal handler, + receipt of the corresponding signal will terminate the + application before gl_get_line() returns. + + If gl_get_line() aborts with errno set to EINTR, you can + find out what signal caused it to abort, by calling the fol- + lowing function. + + int gl_last_signal(const GetLine *gl); + + This returns the numeric code (eg. SIGINT) of the last sig- + nal that was received during the most recent call to + gl_get_line(), or -1 if no signals were received. + + On systems that support it, when a SIGWINCH (window change) + signal is received, gl_get_line() queries the terminal to + find out its new size, redraws the current input line to + accomodate the new size, then returns to waiting for key- + board input from the user. Unlike other signals, this signal + isn't resent to the application. + + Finally, the following signals cause gl_get_line() to first + restore the terminal and signal environment to that which + prevailed before gl_get_line() was called, then resend the + signal to the application. If the process still exists after + the signal has been delivered, then gl_get_line() then re- + establishes its own signal handlers, switches the terminal + back to raw mode, redisplays the input line, and goes back + to awaiting terminal input from the user. + + SIGCONT - This signal is generated when a suspended + process is resumed. + + SIGPWR - This signal is generated when a power failure + occurs (presumably when the system is on a + UPS). + + SIGALRM - This signal is generated when a timer + expires. + SIGUSR1 - An application specific signal. + + SIGUSR2 - Another application specific signal. + + SIGVTALRM - This signal is generated when a virtual + timer expires (see man setitimer(2)). + + SIGXCPU - This signal is generated when a process + exceeds its soft CPU time limit. + + SIGTSTP - This signal is generated by the terminal + suspend key, which is usually ^Z, or the + delayed terminal suspend key, which is + usually ^Y. + + SIGTTIN - This signal is generated if the program + attempts to read from the terminal while the + program is running in the background. + + SIGTTOU - This signal is generated if the program + attempts to write to the terminal while the + program is running in the background. + + + Obviously not all of the above signals are supported on all + systems, so code to support them is conditionally compiled + into the tecla library. + + Note that if SIGKILL, which by definition can't be caught, + or any of the hardware generated exception signals, such as + SIGSEGV, SIGBUS and SIGFPE, are received and unhandled while + gl_get_line() has the terminal in raw mode, the program will + be terminated without the terminal having been restored to a + usable state. In practice, job-control shells usually reset + the terminal settings when a process relinquishes the con- + trolling terminal, so this is only a problem with older + shells. + + +</pre><h2>CUSTOMIZED SIGNAL HANDLING</h2><pre> + The previous section listed the signals that gl_get_line() + traps by default, and described how it responds to them. + This section describes how to both add and remove signals + from the list of trapped signals, and how to specify how + gl_get_line() should respond to a given signal. + + If you don't need gl_get_line() to do anything in response + to a signal that it normally traps, you can tell to + gl_get_line() to ignore that signal by calling + gl_ignore_signal(). + + int gl_ignore_signal(GetLine *gl, int signo); + The signo argument is the number of the signal (eg. SIGINT) + that you want to have ignored. If the specified signal isn't + currently one of those being trapped, this function does + nothing. + + The gl_trap_signal() function allows you to either add a new + signal to the list that gl_get_line() traps, or modify how + it responds to a signal that it already traps. + + int gl_trap_signal(GetLine *gl, int signo, unsigned flags, + GlAfterSignal after, int errno_value); + + The signo argument is the number of the signal that you wish + to have trapped. The flags argument is a set of flags which + determine the environment in which the application's signal + handler is invoked, the after argument tells gl_get_line() + what to do after the application's signal handler returns, + and errno_value tells gl_get_line() what to set errno to if + told to abort. + + The flags argument is a bitwise OR of zero or more of the + following enumerators: + + GLS_RESTORE_SIG - Restore the caller's signal + environment while handling the + signal. + + GLS_RESTORE_TTY - Restore the caller's terminal settings + while handling the signal. + + GLS_RESTORE_LINE - Move the cursor to the start of the + line following the input line before + invoking the application's signal + handler. + + GLS_REDRAW_LINE - Redraw the input line when the + application's signal handler returns. + + GLS_UNBLOCK_SIG - Normally, if the calling program has + a signal blocked (man sigprocmask), + gl_get_line() does not trap that + signal. This flag tells gl_get_line() + to trap the signal and unblock it for + the duration of the call to + gl_get_line(). + + GLS_DONT_FORWARD - If this flag is included, the signal + will not be forwarded to the signal + handler of the calling program. + + Two commonly useful flag combinations are also enumerated as + follows: + GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | + GLS_REDRAW_LINE + + GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE + + + If your signal handler, or the default system signal handler + for this signal, if you haven't overriden it, never either + writes to the terminal, nor suspends or terminates the cal- + ling program, then you can safely set the flags argument to + 0. + + If your signal handler always writes to the terminal, reads + from it, or suspends or terminates the program, you should + specify the flags argument as GL_SUSPEND_INPUT, so that: + + 1. The cursor doesn't get left in the middle of the input + line. + 2. So that the user can type in input and have it echoed. + 3. So that you don't need to end each output line with + \r\n, instead of just \n. + + The GL_RESTORE_ENV combination is the same as + GL_SUSPEND_INPUT, except that it doesn't move the cursor, + and if your signal handler doesn't read or write anything to + the terminal, the user won't see any visible indication that + a signal was caught. This can be useful if you have a signal + handler that only occasionally writes to the terminal, where + using GL_SUSPEND_LINE would cause the input line to be + unnecessarily duplicated when nothing had been written to + the terminal. Such a signal handler, when it does write to + the terminal, should be sure to start a new line at the + start of its first write, by writing a new line before + returning. If the signal arrives while the user is entering + a line that only occupies a signal terminal line, or if the + cursor is on the last terminal line of a longer input line, + this will have the same effect as GL_SUSPEND_INPUT. Other- + wise it will start writing on a line that already contains + part of the displayed input line. This doesn't do any harm, + but it looks a bit ugly, which is why the GL_SUSPEND_INPUT + combination is better if you know that you are always going + to be writting to the terminal. + + The after argument, which determines what gl_get_line() does + after the application's signal handler returns (if it + returns), can take any one of the following values: + + GLS_RETURN - Return the completed input line, just as + though the user had pressed the return + key. + + GLS_ABORT - Cause gl_get_line() to return NULL. + GLS_CONTINUE - Resume command line editing. + + The errno_value argument is intended to be combined with the + GLS_ABORT option, telling gl_get_line() what to set the + standard errno variable to before returning NULL to the cal- + ling program. It can also, however, be used with the + GL_RETURN option, in case you wish to have a way to distin- + guish between an input line that was entered using the + return key, and one that was entered by the receipt of a + signal. + + +</pre><h2>THE TERMINAL SIZE</h2><pre> + On most systems the combination of the TIOCGWINSZ ioctl and + the SIGWINCH signal is used to maintain an accurate idea of + the terminal size. The terminal size is newly queried every + time that gl_get_line() is called and whenever a SIGWINCH + signal is received. + + On the few systems where this mechanism isn't available, at + startup new_GetLine() first looks for the LINES and COLUMNS + environment variables. If these aren't found, or they con- + tain unusable values, then if a terminal information data- + base like terminfo or termcap is available, the default size + of the terminal is looked up in this database. If this too + fails to provide the terminal size, a default size of 80 + columns by 24 lines is used. If this default isn't appropri- + ate for your system, gl_terminal_size() can be used to sup- + ply a different fallback. + + The gl_terminal_size() function allows you to query the + current size of the terminal, and install an alternate fall- + back size for cases where the size isn't available. Beware + that the terminal size won't be available if reading from a + pipe or a file, so the default values can be important even + on systems that do support ways of finding out the terminal + size. + + typedef struct { + int nline; /* The terminal has nline lines */ + int ncolumn; /* The terminal has ncolumn columns */ + } GlTerminalSize; + + GlTerminalSize gl_terminal_size(GetLine *gl, + int def_ncolumn, + int def_nline); + + This function first updates gl_get_line()'s idea of the ter- + minal size, then records its findings in the return value. + + The def_ncolumn and def_nline specify the default number of + terminal columns and lines to use if the terminal size can't + be determined. + + +</pre><h2>HIDING WHAT YOU TYPE</h2><pre> + When entering sensitive information, such as passwords, it + is best not to have the text that you are entering echoed on + the terminal. Furthermore, such text should not be recorded + in the history list, since somebody finding your terminal + unattended could then recall it, or somebody snooping + through your directories could see it in your history file. + With this in mind, the gl_echo_mode() function allows you to + toggle on and off the display and archival of any text that + is subsequently entered in calls to gl_get_line(). + + + int gl_echo_mode(GetLine *gl, int enable); + + + The enable argument specifies whether entered text should be + visible or not. If it is 0, then subsequently entered lines + will not be visible on the terminal, and will not be + recorded in the history list. If it is 1, then subsequent + input lines will be displayed as they are entered, and pro- + vided that history hasn't been turned off via a call to + gl_toggle_history(), then they will also be archived in the + history list. Finally, if the enable argument is -1, then + the echoing mode is left unchanged, which allows you to + non-destructively query the current setting via the return + value. In all cases, the return value of the function is 0 + if echoing was disabled before the function was called, and + 1 if it was enabled. + + When echoing is turned off, note that although tab comple- + tion will invisibly complete your prefix as far as possible, + ambiguous completions will not be displayed. + + +</pre><h2>CALLBACK FUNCTION FACILITIES</h2><pre> + Unless otherwise stated, callback functions, such as tab + completion callbacks and event callbacks should not call any + functions in this module. The following functions, however, + are designed specifically to be used by callback functions. + + Calling the gl_replace_prompt() function from a callback + tells gl_get_line() to display a different prompt when the + callback returns. It has no effect if called when + gl_get_line() is not being called. + + void gl_replace_prompt(GetLine *gl, const char *prompt); + + + +</pre><h2>INTERNATIONAL CHARACTER SETS</h2><pre> + Since libtecla version 1.4.0, gl_get_line() has been 8-bit + clean. This means that all 8-bit characters that are print- + able in the user's current locale are now displayed verbatim + and included in the returned input line. Assuming that the + calling program correctly contains a call like the follow- + ing, + + setlocale(LC_CTYPE, ""); + + then the current locale is determined by the first of the + environment variables LC_CTYPE, LC_ALL, and LANG, that is + found to contain a valid locale name. If none of these vari- + ables are defined, or the program neglects to call setlo- + cale, then the default C locale is used, which is US 7-bit + ASCII. On most unix-like platforms, you can get a list of + valid locales by typing the command: + + locale -a + + at the shell prompt. + + +</pre><h2> Meta keys and locales</h2><pre> + Beware that in most locales other than the default C locale, + meta characters become printable, and they are then no + longer considered to match M-c style key bindings. This + allows international characters to be entered with the com- + pose key without unexpectedly triggering meta key bindings. + You can still invoke meta bindings, since there are actually + two ways to do this. For example the binding M-c can also be + invoked by pressing the escape key momentarily, then press- + ing the c key, and this will work regardless of locale. + Moreover, many modern terminal emulators, such as gnome's + gnome-terminal's and KDE's konsole terminals, already gen- + erate escape pairs like this when you use the meta key, + rather than a real meta character, and other emulators usu- + ally have a way to request this behavior, so you can con- + tinue to use the meta key on most systems. + + For example, although xterm terminal emulators generate real + 8-bit meta characters by default when you use the meta key, + they can be configured to output the equivalent escape pair + by setting their EightBitInput X resource to False. You can + either do this by placing a line like the following in your + ~/.Xdefaults file, + + XTerm*EightBitInput: False + + or by starting an xterm with an -xrm '*EightBitInput: False' + command-line argument. In recent versions of xterm you can + toggle this feature on and off with the "Meta Sends Escape" + option in the menu that is displayed when you press the left + mouse button and the control key within an xterm window. In + CDE, dtterms can be similarly coerced to generate escape + pairs in place of meta characters, by setting the + Dtterm*KshMode resource to True. + + +</pre><h2> Entering international characters</h2><pre> + If you don't have a keyboard that generates all of the + international characters that you need, there is usually a + compose key that will allow you to enter special characters, + or a way to create one. For example, under X windows on + unix-like systems, if your keyboard doesn't have a compose + key, you can designate a redundant key to serve this purpose + with the xmodmap command. For example, on many PC keyboards + there is a microsoft-windows key, which is otherwise useless + under Linux. On my PC the xev program reports that pressing + this key generates keycode 115, so to turn this key into a + compose key, I do the following: + + xmodmap -e 'keycode 115 = Multi_key' + + I can then enter an i with a umlaut over it by typing this + key, followed by ", followed by i. + + +</pre><h2>THREAD SAFETY</h2><pre> + In a multi-threaded program, you should use the libtecla_r.a + version of the library. This uses reentrant versions of sys- + tem functions, where available. Unfortunately neither ter- + minfo nor termcap were designed to be reentrant, so you + can't safely use the functions of the getline module in mul- + tiple threads (you can use the separate file-expansion and + word-completion modules in multiple threads, see the + corresponding man pages for details). However due to the use + of POSIX reentrant functions for looking up home directories + etc, it is safe to use this module from a single thread of a + multi-threaded program, provided that your other threads + don't use any termcap or terminfo functions. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library + libtecla.h - The tecla header file. + ~/.teclarc - The personal tecla customization file. + + +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a>, <a href="ef_expand_file.html">ef_expand_file(3)</a>, <a href="cpl_complete_word.html">cpl_complete_word(3)</a>, + <a href="pca_lookup_file.html">pca_lookup_file(3)</a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> diff --git a/libtecla-1.4.1/html/index.html b/libtecla-1.4.1/html/index.html new file mode 100644 index 0000000..f75a90f --- /dev/null +++ b/libtecla-1.4.1/html/index.html @@ -0,0 +1,116 @@ +<HEAD><TITLE>The tecla command-line editing library.</TITLE></HEAD> +<BODY bgcolor=add8e6> +<H1>The Tecla command-line editing library.</H1> + +The tecla library provides UNIX and LINUX programs with interactive +command line editing facilities, similar to those of the UNIX tcsh +shell. In addition to simple command-line editing, it supports recall +of previously entered command lines, TAB completion of file names or +other tokens, and in-line wild-card expansion of filenames. The +internal functions which perform file-name completion and wild-card +expansion are also available externally for optional use by programs. +<P> +In addition, the library includes a path-searching module. This +allows an application to provide completion and lookup of files +located in UNIX style paths. Although not built into the line editor +by default, it can easily be called from custom tab-completion +callback functions. This was originally conceived for completing the +names of executables and providing a way to look up their locations in +the user's PATH environment variable, but it can easily be asked to +look up and complete other types of files in any list of directories. + +<P> +Note that special care has been taken to allow the use of this library +in threaded programs. The option to enable this is discussed in the +Makefile, and specific discussions of thread safety are presented in +the included man pages. +<P> +The current version is version 1.4.1. This may be obtained from: +<P> + <a href="libtecla-1.4.1.tar.gz">http://www.astro.caltech.edu/~mcs/tecla/libtecla-1.4.1.tar.gz</a> +<P> + +For the sake of automated scripts, the following URL always points to +the latest version. Note that the version number can be found in the +README file. + +<P> + <a href="libtecla.tar.gz">http://www.astro.caltech.edu/~mcs/tecla/libtecla.tar.gz</a> +<P> + +The library is distributed under a permissive non-copyleft +<a href="LICENSE.TERMS">free software license</a> (the X11 license with +the name of the copyright holder changed). This is compatible with, +but not as restrictive as the GNU GPL. + +<H2>Release notes</H2> + +The list of major changes that accompany each new release can be found +<a href="release.html">here</a>. + +<H2>Modifications</H2> + +The gory details of changes in the latest and previous versions of the +library can be found <a href="changes.html">here</a>. + +<H2>Library documentation</H2> + +The following are html versions of the libtecla man pages: + +<UL> +<LI> <a href="libtecla.html">libtecla(3)</a> - An introduction to the tecla library. +<LI> <a href="gl_get_line.html">gl_get_line(3)</a> - The interactive line-input function. +<LI> <a href="cpl_complete_word.html">cpl_complete_word(3)</a> - The word (eg. filename) completion function. +<LI> <a href="ef_expand_file.html">ef_expand_file(3)</a> - The filename expansion function. +<LI> <a href="pca_lookup_file.html">pca_lookup_file(3)</a> - A directory-list based filename lookup and completion module. +<LI> <a href="enhance.html">enhance(3)</a> - A program that adds command-line editing to third party programs. +</UL> + +<H2>Portability</H2> + +In principle, the standard version of the library should compile +without any problems on any UNIX or UNIX like system. So far it has +been reported to work on the following systems: + +<pre> + Sun Solaris 2.5,2.6,7,8, with any of gcc, Sun C, or g++. + Mandrake Linux 7.1 etc.., gcc + Red Hat Linux 7 etc.., gcc + Suse Linux 6.4, gcc + IBM AIX 4.3.3, gcc + HP-UX 10.20, HP-UX 11, gcc, c89 + SCO UnixWare 7.1.1 + FreeBSD, gcc + Alpha OSF1, cc, gcc + Mac OS X + Cygwin (running under Windows) + QNX +</pre> + +There haven't been many reports concerning the POSIX reentrant +version, so the absence of any of the above from the following list of +systems on which the reentrant version is known to work, shouldn't be +taken as an indication that the reentrant version doesn't work. + +<pre> + Sun Solaris 2.5,2.6,7,8, with any of gcc, Sun C, or g++. + Mandrake Linux 7.1, gcc + RedHat Linux 7.0,7.1, gcc + SuSe Linux 6.4, gcc + HP-UX 11, gcc + IBM AIX 4.3.3, gcc + Alpha OSF1, cc +</pre> + +The only system that is known to have issues with the reentrant +version of the library is SCO UnixWare 7.1.1. The problem is in the +system provided signal.h, which breaks when POSIX_C_SOURCE is +defined. It has been reported that this can be fixed by editing +signal.h. + +<P> +If you compile the library on a system that isn't mentioned above, +please send E-mail to <b>mcs@astro.caltech.edu</b>. +<HR> +Martin Shepherd (25-May-2002) +</BODY> diff --git a/libtecla-1.4.1/html/libtecla.html b/libtecla-1.4.1/html/libtecla.html new file mode 100644 index 0000000..914c1e9 --- /dev/null +++ b/libtecla-1.4.1/html/libtecla.html @@ -0,0 +1,163 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + libtecla - An interactive command-line input library. + +</pre><h2>SYNOPSIS</h2><pre> + gcc ... -ltecla -lcurses + + +</pre><h2>DESCRIPTION</h2><pre> + The tecla library provides programs with interactive command + line editing facilities, similar to those of the unix tcsh + shell. In addition to simple command-line editing, it sup- + ports recall of previously entered command lines, TAB com- + pletion of file names or other tokens, and in-line wild-card + expansion of filenames. The internal functions which perform + file-name completion and wild-card expansion are also avail- + able externally for optional use by the calling program. + + The various parts of the library are documented in the fol- + lowing man pages: + + <a href="gl_get_line.html">gl_get_line(3)</a> - The interactive line-input module. + <a href="cpl_complete_word.html">cpl_complete_word(3)</a> - The word completion module. + <a href="ef_expand_file.html">ef_expand_file(3)</a> - The filename expansion module. + <a href="pca_lookup_file.html">pca_lookup_file(3)</a> - A directory-list based filename + lookup and completion module. + + In addition there is one optional application distributed + with the library: + + <a href="enhance.html">enhance(3)</a> - Add command-line editing to third + party applications. + + +</pre><h2>THREAD SAFETY</h2><pre> + If the library is compiled with -D_POSIX_C_SOURCE=199506L, + reentrant versions of as many functions as possible are + used. This includes using getpwuid_r() and getpwnam_r() + instead of getpwuid() and getpwnam() when looking up the + home directories of specific users in the password file (for + ~user/ expansion), and readdir_r() instead of readdir() for + reading directory entries when doing filename completion. + The reentrant version of the library is usually called + libtecla_r.a instead of libtecla.a, so if only the latter is + available, it probably isn't the correct version to link + with threaded programs. + + Reentrant functions for iterating through the password file + aren't available, so when the library is compiled to be + reentrant, TAB completion of incomplete usernames in ~user- + name/ expressions is disabled. This doesn't disable expan- + sion of complete ~username expressions, which can be done + reentrantly, or expansion of the parts of filenames that + follow them, so this doesn't remove much functionality. + + The terminfo functions setupterm(), tigetstr(), tigetnum() + and tputs() also aren't reentrant, but very few programs + will want to interact with multiple terminals, so this + shouldn't prevent this library from being used in threaded + programs. + + +</pre><h2>LIBRARY VERSION NUMBER</h2><pre> + The version number of the library can be queried using the + following function. + + void libtecla_version(int *major, int *minor, int *micro); + + + On return, this function records the three components of the + libtecla version number in *major, *minor, *micro. The for- + mal meaning of the three components is as follows. + + + major - Incrementing this number implies that a change has + been made to the library's public interface, which + makes it binary incompatible with programs that + were linked with previous shared versions of the + tecla library. + + minor - This number is incremented by one whenever + additional functionality, such as new functions or + modules, are added to the library. + + micro - This is incremented whenever modifications to the + library are made which make no changes to the + public interface, but which fix bugs and/or improve + the behind-the-scenes implementation. + + + +</pre><h2>TRIVIA</h2><pre> + In Spanish, a "tecla" is the key of a keyboard. Since this + library centers on keyboard input, and given that I wrote + much of the library while working in Chile, this seemed like + a suitable name. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library. + libtecla.h - The tecla header file. + ~/.teclarc - The tecla personal customization file. + + + +</pre><h2>SEE ALSO</h2><pre> + <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="ef_expand_file.html">ef_expand_file(3)</a>, <a href="cpl_complete_word.html">cpl_complete_word(3)</a>, + <a href="pca_lookup_file.html">pca_lookup_file(3)</a>, <a href="enhance.html">enhance(3)</a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + +</pre><h2>ACKNOWLEDGMENTS</h2><pre> + Markus Gyger - Lots of assistance, including help with + shared libraries, configuration information, + particularly for Solaris; modifications to + support C++ compilers, improvements for ksh + users, faster cursor motion, output + buffering, and changes to make gl_get_line() + 8-bit clean. + Mike MacFaden - Suggestions, feedback and testing that led + to many of the major new functions that were + added in version 1.4.0. + Tim Eliseo - Many vi-mode bindings and fixes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> diff --git a/libtecla-1.4.1/html/pca_lookup_file.html b/libtecla-1.4.1/html/pca_lookup_file.html new file mode 100644 index 0000000..40c9f2b --- /dev/null +++ b/libtecla-1.4.1/html/pca_lookup_file.html @@ -0,0 +1,371 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + pca_lookup_file, del_PathCache, del_PcaPathConf, + new_PathCache, new_PcaPathConf, pca_last_error, + pca_path_completions, pca_scan_path, pca_set_check_fn, + ppc_file_start, ppc_literal_escapes - lookup a file in a + list of directories + +</pre><h2>SYNOPSIS</h2><pre> + #include <libtecla.h> + + PathCache *new_PathCache(void); + + PathCache *del_PathCache(PathCache *pc); + + int pca_scan_path(PathCache *pc, const char *path); + + void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, + void *data); + + char *pca_lookup_file(PathCache *pc, const char *name, + int name_len, int literal); + + const char *pca_last_error(PathCache *pc); + + CPL_MATCH_FN(pca_path_completions); + + + +</pre><h2>DESCRIPTION</h2><pre> + The PathCache object is part of the tecla library (see the + <a href="libtecla.html">libtecla(3)</a> man page). + + PathCache objects allow an application to search for files + in any colon separated list of directories, such as the unix + execution PATH environment variable. Files in absolute + directories are cached in a PathCache object, whereas rela- + tive directories are scanned as needed. Using a PathCache + object, you can look up the full pathname of a simple + filename, or you can obtain a list of the possible comple- + tions of a given filename prefix. By default all files in + the list of directories are targets for lookup and comple- + tion, but a versatile mechanism is provided for only select- + ing specific types of files. The obvious application of this + facility is to provide Tab-completion and lookup of execut- + able commands in the unix PATH, so an optional callback + which rejects all but executable files, is provided. + + +</pre><h2>AN EXAMPLE</h2><pre> + Under UNIX, the following example program looks up and + displays the full pathnames of each of the command names on + the command line. + #include <stdio.h> + #include <stdlib.h> + #include <libtecla.h> + + int main(int argc, char *argv[]) + { + int i; + /* + * Create a cache for executable files. + */ + PathCache *pc = new_PathCache(); + if(!pc) + exit(1); + /* + * Scan the user's PATH for executables. + */ + if(pca_scan_path(pc, getenv("PATH"))) { + fprintf(stderr, "%s\n", pca_last_error(pc)); + exit(1); + } + /* + * Arrange to only report executable files. + */ + pca_set_check_fn(pc, cpl_check_exe, NULL); + /* + * Lookup and display the full pathname of each of the + * commands listed on the command line. + */ + for(i=1; i<argc; i++) { + char *cmd = pca_lookup_file(pc, argv[i], -1, 0); + printf("The full pathname of '%s' is %s\n", argv[i], + cmd ? cmd : "unknown"); + } + pc = del_PathCache(pc); /* Clean up */ + return 0; + } + + The following is an example of what this does on my laptop + under linux: + + $ ./example less more blob + The full pathname of 'less' is /usr/bin/less + The full pathname of 'more' is /bin/more + The full pathname of 'blob' is unknown + $ + + +</pre><h2>FUNCTION DESCRIPTIONS</h2><pre> + In order to use the facilities of this module, you must + first allocate a PathCache object by calling the + new_PathCache() constructor function. + + PathCache *new_PathCache(void) + + This function creates the resources needed to cache and + lookup files in a list of directories. It returns NULL on + error. + + +</pre><h2>POPULATING THE CACHE</h2><pre> + Once you have created a cache, it needs to be populated with + files. To do this, call the pca_scan_path() function. + + int pca_scan_path(PathCache *pc, const char *path); + + Whenever this function is called, it discards the current + contents of the cache, then scans the list of directories + specified in its path argument for files. The path argument + must be a string containing a colon-separated list of direc- + tories, such as "/usr/bin:/home/mcs/bin:.". This can include + directories specified by absolute pathnames such as + "/usr/bin", as well as sub-directories specified by relative + pathnames such as "." or "bin". Files in the absolute direc- + tories are immediately cached in the specified PathCache + object, whereas sub-directories, whose identities obviously + change whenever the current working directory is changed, + are marked to be scanned on the fly whenever a file is + looked up. + + On success this function return 0. On error it returns 1, + and a description of the error can be obtained by calling + pca_last_error(pc). + + +</pre><h2>LOOKING UP FILES</h2><pre> + Once the cache has been populated with files, you can look + up the full pathname of a file, simply by specifying its + filename to pca_lookup_file(). + + char *pca_lookup_file(PathCache *pc, const char *name, + int name_len, int literal); + + To make it possible to pass this function a filename which + is actually part of a longer string, the name_len argument + can be used to specify the length of the filename at the + start of the name[] argument. If you pass -1 for this + length, the length of the string will be determined with + strlen(). If the name[] string might contain backslashes + that escape the special meanings of spaces and tabs within + the filename, give the literal argument, the value 0. Other- + wise, if backslashes should be treated as normal characters, + pass 1 for the value of the literal argument. + + +</pre><h2>FILENAME COMPLETION</h2><pre> + Looking up the potential completions of a filename-prefix in + the filename cache, is achieved by passing the provided + pca_path_completions() callback function to the + cpl_complete_word() function (see the <a href="cpl_complete_word.html">cpl_complete_word(3)</a> + man page). + + CPL_MATCH_FN(pca_path_completions); + + This callback requires that its data argument be a pointer + to a PcaPathConf object. Configuration objects of this type + are allocated by calling new_PcaPathConf(). + + PcaPathConf *new_PcaPathConf(PathCache *pc); + + This function returns an object initialized with default + configuration parameters, which determine how the + cpl_path_completions() callback function behaves. The func- + tions which allow you to individually change these parame- + ters are discussed below. + + By default, the pca_path_completions() callback function + searches backwards for the start of the filename being com- + pleted, looking for the first un-escaped space or the start + of the input line. If you wish to specify a different loca- + tion, call ppc_file_start() with the index at which the + filename starts in the input line. Passing start_index=-1 + re-enables the default behavior. + + void ppc_file_start(PcaPathConf *ppc, int start_index); + + By default, when pca_path_completions() looks at a filename + in the input line, each lone backslash in the input line is + interpreted as being a special character which removes any + special significance of the character which follows it, such + as a space which should be taken as part of the filename + rather than delimiting the start of the filename. These + backslashes are thus ignored while looking for completions, + and subsequently added before spaces, tabs and literal + backslashes in the list of completions. To have unescaped + backslashes treated as normal characters, call + ppc_literal_escapes() with a non-zero value in its literal + argument. + + void ppc_literal_escapes(PcaPathConf *ppc, int literal); + + When you have finished with a PcaPathConf variable, you can + pass it to the del_PcaPathConf() destructor function to + reclaim its memory. + + PcaPathConf *del_PcaPathConf(PcaPathConf *ppc); + +</pre><h2>BEING SELECTIVE</h2><pre> + If you are only interested in certain types or files, such + as, for example, executable files, or files whose names end + in a particular suffix, you can arrange for the file comple- + tion and lookup functions to be selective in the filenames + that they return. This is done by registering a callback + function with your PathCache object. Thereafter, whenever a + filename is found which either matches a filename being + looked up, or matches a prefix which is being completed, + your callback function will be called with the full pathname + of the file, plus any application-specific data that you + provide, and if the callback returns 1 the filename will be + reported as a match, and if it returns 0, it will be + ignored. Suitable callback functions and their prototypes + should be declared with the following macro. The CplCheckFn + typedef is also provided in case you wish to declare + pointers to such functions. + + #define CPL_CHECK_FN(fn) int (fn)(void *data, \ + const char *pathname) + typedef CPL_CHECK_FN(CplCheckFn); + + Registering one of these functions involves calling the + pca_set_check_fn() function. In addition to the callback + function, passed via the check_fn argument, you can pass a + pointer to anything via the data argument. This pointer will + be passed on to your callback function, via its own data + argument, whenever it is called, so this provides a way to + pass appplication specific data to your callback. + + void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, + void *data); + + Note that these callbacks are passed the full pathname of + each matching file, so the decision about whether a file is + of interest can be based on any property of the file, not + just its filename. As an example, the provided + cpl_check_exe() callback function looks at the executable + permissions of the file and the permissions of its parent + directories, and only returns 1 if the user has execute per- + mission to the file. This callback function can thus be used + to lookup or complete command names found in the directories + listed in the user's PATH environment variable. The example + program given earlier in this man page provides a demonstra- + tion of this. + + Beware that if somebody tries to complete an empty string, + your callback will get called once for every file in the + cache, which could number in the thousands. If your callback + does anything time consuming, this could result in an unac- + ceptable delay for the user, so callbacks should be kept + short. + To improve performance, whenever one of these callbacks is + called, the choice that it makes is cached, and the next + time the corresponding file is looked up, instead of calling + the callback again, the cached record of whether it was + accepted or rejected is used. Thus if somebody tries to com- + plete an empty string, and hits tab a second time when noth- + ing appears to happen, there will only be one long delay, + since the second pass will operate entirely from the cached + dispositions of the files. These cached dipositions are dis- + carded whenever pca_scan_path() is called, and whenever + pca_set_check_fn() is called with changed callback function + or data arguments. + + +</pre><h2>ERROR HANDLING</h2><pre> + If pca_scan_path() reports that an error occurred by return- + ing 1, you can obtain a terse description of the error by + calling pca_last_error(pc). This returns an internal string + containing an error message. + + const char *pca_last_error(PathCache *pc); + + + +</pre><h2>CLEANING UP</h2><pre> + Once you have finished using a PathCache object, you can + reclaim its resources by passing it to the del_PathCache() + destructor function. This takes a pointer to one of these + objects, and always returns NULL. + + PathCache *del_PathCache(PathCache *pc); + + +</pre><h2>THREAD SAFETY</h2><pre> + In multi-threaded programs, you should use the libtecla_r.a + version of the library. This uses POSIX reentrant functions + where available (hence the _r suffix), and disables features + that rely on non-reentrant system functions. In the case of + this module, the only disabled feature is username comple- + tion in ~username/ expressions, in cpl_path_completions(). + + Using the libtecla_r.a version of the library, it is safe to + use the facilities of this module in multiple threads, pro- + vided that each thread uses a separately allocated PathCache + object. In other words, if two threads want to do path + searching, they should each call new_PathCache() to allocate + their own caches. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library + libtecla.h - The tecla header file. +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="ef_expand_file.html">ef_expand_file(3)</a>, + <a href="cpl_complete_word.html">cpl_complete_word(3)</a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> diff --git a/libtecla-1.4.1/html/release.html b/libtecla-1.4.1/html/release.html new file mode 100644 index 0000000..e0d219c --- /dev/null +++ b/libtecla-1.4.1/html/release.html @@ -0,0 +1,360 @@ +<HEAD><TITLE>The tecla library release notes</TITLE></HEAD> +<BODY bgcolor=add8e6><PRE> +This file lists major changes which accompany each new release. + +Version 1.4.1: + + This is a maintenance release. It includes minor changes to support + Mac OS X (Darwin), the QNX real-time operating system, and Cygwin + under Windows. It also fixes an oversight that was preventing the + tab key from inserting tab characters when users unbound the + complete-word action from it. + +Version 1.4.0: + + The contents of the history list can now be saved and restored with + the new gl_save_history() and gl_load_history() functions. + + Event handlers can now be registered to watch for and respond to I/O + on arbitrary file descriptors while gl_get_line() is waiting for + terminal input from the user. See the gl_get_line(3) man page + for details on gl_watch_fd(). + + As an optional alternative to getting configuration information only + from ~/.teclarc, the new gl_configure_getline() function allows + configuration commands to be taken from any of, a string, a + specified application-specific file, and/or a specified + user-specific file. See the gl_get_line(3) man page for details. + + The version number of the library can now be queried using the + libtecla_version() function. See the libtecla(3) man page. + + The new gl_group_history() function allows applications to group + different types of input line in the history buffer, and arrange for + only members of the appropriate group to be recalled on a given call + to gl_get_line(). See the gl_get_line(3) man page. + + The new gl_show_history() function displays the current history list + to a given stdio output stream. See the gl_get_line(3) man page. + + new_GetLine() now allows you to specify a history buffer size of + zero, thus requesting that no history buffer be allocated. You can + subsequently resize or delete the history buffer at any time, by + calling gl_resize_history(), limit the number of lines that are + allowed in the buffer by calling gl_limit_history(), clear either + all history lines from the history list, or just the history lines + that are associated with the current history group, by calling + gl_clear_history, and toggle the history mechanism on and off by + calling gl_toggle_history(). + + The new gl_terminal_size() function can be used to query the + current terminal size. It can also be used to supply a default + terminal size on systems where no mechanism is available for + looking up the size. + + The contents and configuration of the history list can now be + obtained by the calling application, by calling the new + gl_lookup_history(), gl_state_of_history(), gl_range_of_history() + and gl_size_of_history() functions. See the gl_get_line(3) man page. + + Echoing of the input line as it is typed, can now be turned on and + off via the new gl_echo_mode() function. While echoing is disabled, + newly entered input lines are omitted from the history list. See + the gl_get_line(3) man page. + + While the default remains to display the prompt string literally, + the new gl_prompt_style() function can be used to enable text + attribute formatting directives in prompt strings, such as + underlining, bold font, and highlighting directives. + + Signal handling in gl_get_line() is now customizable. The default + signal handling behavior remains essentially the same, except that + the SIGTSTP, SIGTTIN and SIGTTOU are now forwarded to the + corresponding signal handler of the calling program, instead of + causing a SIGSTOP to be sent to the application. It is now possible + to remove signals from the list that are trapped by gl_get_line(), + as well as add new signals to this list. The signal and terminal + environments in which the signal handler of the calling program is + invoked, and what gl_get_line() does after the signal handler + returns, is now customizable on a per signal basis. You can now also + query the last signal that was caught by gl_get_line(). This is + useful when gl_get_line() aborts with errno=EINTR, and you need to + know which signal caused it to abort. + + Key-sequences bound to action functions can now start with printable + characters. Previously only keysequences starting with control or + meta characters were permitted. + + gl_get_line() is now 8-bit clean. If the calling program has + correctly called setlocale(LC_CTYPE,""), then the user can select an + alternate locale by setting the standard LC_CTYPE, LC_ALL, or LANG + environment variables, and international characters can then be + entered directly, either by using a non-US keyboard, or by using a + compose key on a standard US keyboard. Note that in locales in which + meta characters become printable, meta characters no longer match + M-c bindings, which then have to be entered using their escape-c + equivalents. Fortunately most modern terminal emulators either + output the escape-c version by default when the meta key is used, or + can be configured to do so (see the gl_get_line(3) man page), so in + most cases you can continue to use the meta key. + + Completion callback functions can now tell gl_get_line() to return + the input line immediately after a successful tab completion, simply + by setting the last character of the optional continuation suffix to + a newline character (ie. in the call to cpl_add_completion()). + + It is now safe to create and use multiple GetLine objects, albeit + still only from a single thread. In conjunction with the new + gl_configure_getline() function, this optionally allows multiple + GetLine objects with different bindings to be used to implement + different input modes. + + The edit-mode configuration command now accepts the argument, + none. This tells gl_get_line() to revert to using just the native + line editing facilities provided by the terminal driver. This could + be used if the termcap or terminfo entry of the host terminal were + badly corrupted. + + Application callback functions invoked by gl_get_line() can now + change the displayed prompt using the gl_replace_prompt() function. + + Their is now an optional program distributed with the library. This + is a beta release of a program which adds tecla command-line editing + to virtually any third party application without the application + needing to be linked to the library. See the enhance(3) man page for + further details. Although built and installed by default, the + INSTALL document explains how to prevent this. + + The INSTALL document now explains how you can stop the demo programs + from being built and installed. + + NetBSD/termcap fixes. Mike MacFaden reported two problems that he + saw when compiling libtecla under NetBSD. Both cases were related to + the use of termcap. Most systems use terminfo, so this problem has + gone unnoticed until now, and won't have affected the grand majority + of users. The configure script had a bug which prevented the check + for CPP working properly, and getline.c wouldn't compile due to an + undeclared variable when USE_TERMCAP was defined. Both problems have + now been fixed. Note that if you successfully compiled version + 1.3.3, this problem didn't affect you. + + An unfortunate and undocumented binding of the key-sequence M-O was + shadowing the arrow-key bindings on systems that use ^[OA etc. I + have removed this binding (the documented lower case M-o binding + remains bound). Under the KDE konsole terminal this was causing the + arrow keys to do something other than expected. + + There was a bug in the history list code which could result in + strange entries appearing at the start of the history list once + enough history lines had been added to the list to cause the + circular history buffer to wrap. This is now fixed. + +Version 1.3.3: + + Signal handling has been re-written, and documentation of its + behaviour has been added to the gl_get_line(3) man page. In addition + to eliminating race conditions, and appropriately setting errno for + those signals that abort gl_get_line(), many more signals are now + intercepted, making it less likely that the terminal will be left in + raw mode by a signal that isn't trapped by gl_get_line(). + + A bug was also fixed that was leaving the terminal in raw mode if + the editing mode was changed interactively between vi and emacs. + This was only noticeable when running programs from old shells that + don't reset terminal modes. + +Version 1.3.2: + + Tim Eliseo contributed a number of improvements to vi mode, + including a fuller set of vi key-bindings, implementation of the vi + constraint that the cursor can't backup past the point at which + input mode was entered, and restoration of overwritten characters + when backspacing in overwrite mode. There are also now new bindings + to allow users to toggle between vi and emacs modes interactively. + The terminal bell is now used in some circumstances, such as when an + unrecognized key sequence is entered. This can be turned off by the + new nobeep option in the tecla configuration file. + + Unrelated to the above, a problem under Linux which prevented ^Q + from being used to resume terminal output after the user had pressed + ^S, has been fixed. + +Version 1.3.1: + + In vi mode a bug was preventing the history-search-backward and + history-search-forward actions from doing anything when invoked on + empty lines. On empty lines they now act like up-history and + down-history respectively, as in emacs mode. + + When creating shared libraries under Linux, the -soname directive + was being used incorrectly. The result is that Linux binaries linked + with the 1.2.3, 1.2.4 and 1.3.0 versions of the tecla shared + libraries, will refuse to see other versions of the shared library + until relinked with version 1.3.1 or higher. + + The configure script can now handle the fact that under Solaris-2.6 + and earlier, the only curses library is a static one that hides in + /usr/ccs/lib. Under Linux it now also caters for old versions of GNU + ld which don't accept version scripts. + + The demos are now linked against the shared version of the library + if possible. Previously they were always linked with the static + version. + +Version 1.3.0: + + The major change in this release is the addition of an optional vi + command-line editing mode in gl_get_line(), along with lots of new + action functions to support its bindings. To enable this, first + create a ~/.teclarc file if you don't already have one, then add the + following line to it. + + edit-mode vi + + The default vi bindings, which are designed to mimic those of the vi + editor as closely as possible, are described in the gl_get_line(3) + man page. + + A new convenience function called ef_list_expansions() has been + added for listing filename expansions. See the ef_list_expansions(3) + man page for details. This is used in a new list-glob binding, bound + to ^Xg in emacs mode, and ^G in vi input mode. + + A bug has been fixed in the key-binding table expansion code. This + bug would have caused problems to anybody who defined more than + about 18 personalized key-bindings in their ~/.teclarc file. + +Version 1.2.4: + + Buffered I/O is now used for writing to terminals, and where + supported, cursor motion is done with move-n-positions terminfo + capabilities instead of doing lots of move-1-position requests. This + greatly improves how the library feels over slow links. + + You can now optionally compile different architectures in different + directories, without having to make multiple copies of the + distribution. This is documented in the INSTALL file. + + The ksh ~+ directive is now supported. + + Thanks to Markus Gyger for the above improvements. + + Documentation has been added to the INSTALL file describing features + designed to facilitate configuration and installation of the library + as part of larger packages. These features are intended to remove + the need to modify the tecla distribution's configuration and build + procedures when embedding the libtecla distribution in other package + distributions. + + A previous fix to stop the cursor from warping when the last + character of the input line was in the last column of the terminal, + was only being used for the first terminal line of the input line. + It is now used for all subsequent lines as well, as originally + intended. + +Version 1.2.3: + + The installation procedure has been better automated with the + addition of an autoconf configure script. This means that installers + can now compile and install the library by typing: + + ./configure + make + make install + + On all systems this makes at least the normal static version of the + tecla library. It also makes the reentrant version if reentrant + POSIX functions are detected. Under Solaris, Linux and HP-UX the + configuration script arranges for shared libraries to be compiled in + addition to the static libraries. It is hoped that installers will + return information about how to compile shared libraries on other + systems, for inclusion in future releases, and to this end, a new + PORTING guide has been provided. + + The versioning number scheme has been changed. This release would + have been 1.2c, but instead will be refered to as 1.2.3. The + versioning scheme, based on conventions used by Sun Microsystems, is + described in configure.in. + + The library was also tested under HP-UX, and this revealed two + serious bugs, both of which have now been fixed. + + The first bug prevented the library from writing control codes to + terminals on big-endian machines, with the exception of those + running under Solaris. This was due to an int variable being used + where a char was needed. + + The second bug had the symptom that on systems that don't use the + newline character as the control code for moving the cursor down a + line, a newline wasn't started when the user hit enter. + +Version 1.2b: + + Two more minor bug fixes: + + Many terminals don't wrap the cursor to the next line when a + character is written to the rightmost terminal column. Instead, they + delay starting a new line until one more character is written, at + which point they move the cursor two positions. gl_get_line() + wasn't aware of this, so cursor repositionings just after writing + the last character of a column, caused it to erroneously go up a + line. This has now been remedied, using a method that should work + regardless of whether a terminal exhibits this behavior or not. + + Some systems dynamically record the current terminal dimensions in + environment variables called LINES and COLUMNS. On such systems, + during the initial terminal setup, these values should override the + static values read from the terminal information databases, and now + do. Previously they were only used if the dimensions returned by + terminfo/termcap looked bogus. + +Version 1.2a: + + This minor release fixes the following two bugs: + + The initial terminal size and subsequent changes thereto, weren't + being noticed by gl_get_line(). This was because the test for the + existence of TIOCWINSZ was erroneously placed before the inclusion + of termios.h. One of the results was that on input lines that + spanned more than one terminal line, the cursor occasionally jumped + unexpectedly to the previous terminal line. + + On entering a line that wrapped over multiple terminal lines, + gl_get_line() simply output a carriage-return line-feed at the point + at which the user pressed return. Thus if one typed in such a line, + then moved back onto one of the earlier terminal lines before + hitting return, the cursor was left on a line containing part of the + line that had just been entered. This didn't do any harm, but it + looked a mess. + +Version 1.2: + + A new facility for looking up and completing filenames in UNIX-style + paths has now been added (eg. you can search for, or complete + commands using the UNIX PATH environment variable). See the + pca_lookup_file(3) man page. + + The already existing filename completion callback can now be made + selective in what types of files it lists. See the + cpl_complete_word(3) man page. + + Due to its potential to break applications when changed, the use of + the publically defined CplFileArgs structure to configure the + cpl_file_completions() callback is now deprecated. The definition + of this structure has been frozen, and its documentation has been + removed from the man pages. It will remain supported, but if you + have used it, you are recommended to switch to the new method, which + involves a new opaque configuration object, allocated via a provided + constructor function, configured via accessor functions, and + eventually deleted with a provided destructor function. The + cpl_file_completions() callback distinguishes which structure type + it has been sent by virtue of a code placed at the start of the new + structure by the constructor. It is assumed that no existing + applications set the boolean 'escaped' member of the CplFileArgs + structure to 4568. The new method is documented in the + cpl_complete_word(3) man page. + +Version 1.1j + + This was the initial public release on freshmeat.org. +</PRE></BODY> diff --git a/libtecla-1.4.1/man3/cfc_file_start.3 b/libtecla-1.4.1/man3/cfc_file_start.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cfc_file_start.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cfc_literal_escapes.3 b/libtecla-1.4.1/man3/cfc_literal_escapes.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cfc_literal_escapes.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cfc_set_check_fn.3 b/libtecla-1.4.1/man3/cfc_set_check_fn.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cfc_set_check_fn.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cpl_add_completion.3 b/libtecla-1.4.1/man3/cpl_add_completion.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cpl_add_completion.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cpl_complete_word.3 b/libtecla-1.4.1/man3/cpl_complete_word.3 new file mode 100644 index 0000000..ae76439 --- /dev/null +++ b/libtecla-1.4.1/man3/cpl_complete_word.3 @@ -0,0 +1,405 @@ +.\" 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. +.TH cpl_complete_word 3 +.SH NAME +cpl_complete_word, cfc_file_start, cfc_literal_escapes, cfc_set_check_fn, cpl_add_completion, cpl_file_completions, cpl_last_error, cpl_list_completions, cpl_record_error, del_CplFileConf, del_WordCompletion, new_CplFileConf, new_WordCompletion \- lookup possible completions for a word +.SH SYNOPSIS +.nf +#include <stdio.h> +#include <libtecla.h> + +WordCompletion *new_WordCompletion(void); + +WordCompletion *del_WordCompletion(WordCompletion *cpl); + +#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \\ + void *data, \\ + const char *line, \\ + int word_end) +typedef CPL_MATCH_FN(CplMatchFn); + +CPL_MATCH_FN(cpl_file_completions); + +CplMatches *cpl_complete_word(WordCompletion *cpl, + const char *line, + int word_end, void *data, + CplMatchFn *match_fn); + +int cpl_list_completions(CplMatches *result, FILE *fp, + int term_width); + +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); + +void cpl_record_error(WordCompletion *cpl, + const char *errmsg); + +const char *cpl_last_error(WordCompletion *cpl); + +.fi + +.SH DESCRIPTION + +The \f3cpl_complete_word()\f1 function is part of the tecla library +(see the libtecla(3) man page). It is usually called behind the scenes +by \f3gl_get_line(3)\f1, but can also be called separately. + +Given an input line containing an incomplete word to be completed, it +calls a user-provided callback function (or the provided +file-completion callback function) to look up all possible completion +suffixes for that word. The callback function is expected to look +backward in the line, starting from the specified cursor position, to +find the start of the word to be completed, then to look up all +possible completions of that word and record them, one at a time by +calling \f3cpl_add_completion()\f1. + +.sp +Descriptions of the functions of this module are as follows: +.sp +.nf + CompleteWord *new_CompleteWord(void) +.fi +.sp +This function creates the resources used by the \f3cpl_complete_word()\f1 +function. In particular, it maintains the memory that is used to +return the results of calling \f3cpl_complete_word()\f1. +.sp +.nf + CompleteWord *del_CompleteWord(CompleteWord *cpl) +.fi +.sp +This function deletes the resources that were returned by a previous +call to \f3new_CompleteWord()\f1. It always returns \f3NULL\f1 (ie. a +deleted object). It does nothing if the \f3cpl\f1 argument is +\f3NULL\f1. +.sp +The callback functions which lookup possible completions should be +defined with the following macro (which is defined in libtecla.h). +.sp +.nf + #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \\ + void *data, \\ + const char *line, \\ + int word_end) +.fi +.sp +Functions of this type are called by \f3cpl_complete_word()\f1, and +all of the arguments of the callback are those that were passed to +said function. In particular, the \f3line\f1 argument contains the +input line containing the word to be completed, and \f3word_end\f1 is +the index of the character that follows the last character of the +incomplete word within this string. The callback is expected to look +backwards from \f3word_end\f1 for the start of the incomplete +word. What constitutes the start of a word clearly depends on the +application, so it makes sense for the callback to take on this +responsibility. For example, the builtin filename completion function +looks backwards until it hits an unescaped space, or the start of the +line. Having found the start of the word, the callback should then +lookup all possible completions of this word, and record each +completion via separate calls to \f3cpl_add_completion()\f1. If the +callback needs access to an application-specific symbol table, it can +pass it and any other data that it needs, via the \f3data\f1 +argument. This removes any need for globals. +.sp +The callback function should return 0 if no errors occur. On failure +it should return 1, and register a terse description of the error by +calling \f3cpl_record_error()\f1. +.sp +.nf + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); +.fi +.sp +The last error message recorded by calling \f3cpl_record_error()\f1, +can subsequently be queried by calling \f3cpl_last_error()\f1, as +described later. +.sp +.nf + 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); +.fi +.sp +The \f3cpl_add_completion()\f1 function is called zero or more times +by the completion callback function to record each possible completion +in the specified \f3WordCompletion\f1 object. These completions are +subsequently returned by \f3cpl_complete_word()\f1, as described +later. The \f3cpl\f1, \f3line\f1, and \f3word_end\f1 arguments should +be those that were passed to the callback function. The +\f3word_start\f1 argument should be the index within the input line +string of the start of the word that is being completed. This should +equal \f3word_end\f1 if a zero-length string is being completed. The +\f3suffix\f1 argument is the string that would have to be appended to +the incomplete word to complete it. If this needs any quoting +(eg. the addition of backslashes before special charaters) to be valid +within the displayed input line, this should be included. A copy of +the suffix string is allocated internally, so there is no need to +maintain your copy of the string after \f3cpl_add_completion()\f1 +returns. +.sp +Note that in the array of possible completions which the +\f3cpl_complete_word()\f1 function returns, the suffix recorded by +\f3cpl_add_completion()\f1 is listed along with the concatentation of +this suffix with the word that lies between \f3word_start\f1 and +\f3word_end\f1 in the input line. +.sp +The \f3type_suffix\f1 argument specifies an optional string to be +appended to the completion if it is displayed as part of a list of +completions by \f3cpl_list_completions()\f1. The intention is that +this indicate to the user the type of each completion. For example, +the file completion function places a directory separator after +completions that are directories, to indicate their nature to the +user. Similary, if the completion were a function, you could indicate +this to the user by setting \f3type_suffix\f1 to "()". Note that the +\f3type_suffix\f1 string isn't copied, so if the argument isn't a +literal string between speech marks, be sure that the string remains +valid for at least as long as the results of \f3cpl_complete_word()\f1 +are needed. +.sp +The \f3cont_suffix\f1 is a continuation suffix to append to the +completed word in the input line if this is the only completion. This +is something that isn't part of the completion itself, but that gives +the user an indication about how they might continue to extend the +token. For example, the file-completion callback function adds a +directory separator if the completed word is a directory. If the +completed word were a function name, you could similarly aid the user +by arranging for an open parenthesis to be appended. +.sp +.nf + CplMatches *cpl_complete_word(WordCompletion *cpl, + const char *line, + int word_end, void *data, + CplMatchFn *match_fn); +.fi +.sp +The \f3cpl_complete_word()\f1 is normally called behind the scenes by +\f3gl_get_line(3)\f1, but can also be called separately if you +separately allocate a \f3WordCompletion\f1 object. It performs word +completion, as described at the beginning of this section. Its first +argument is a resource object previously returned by +\f3new_CompleteWord()\f1. The \f3line\f1 argument is the input line +string, containing the word to be completed. The \f3word_end\f1 +argument contains the index of the character in the input line, that +just follows the last character of the word to be completed. When +called by \f3gl_get_line()\f1, this is the character over which the +user pressed \f3TAB\f1. The \f3match_fn\f3 argument is the function +pointer of the callback function which will lookup possible +completions of the word, as described above, and the \f3data\f1 +argument provides a way for the application to pass arbitrary data to +the callback function. +.sp +If no errors occur, the \f3cpl_complete_word()\f1 function returns a +pointer to a \f3CplMatches\f1 container, as defined below. This +container is allocated as part of the \f3cpl\f1 object that was passed +to \f3cpl_complete_word()\f1, and will thus change on each call which +uses the same \f3cpl\f1 argument. +.sp +.nf + typedef struct { + char *completion; /* A matching completion */ + /* string */ + char *suffix; /* The part of the */ + /* completion string which */ + /* would have to be */ + /* appended to complete the */ + /* original word. */ + const char *type_suffix; /* A suffix to be added when */ + /* listing completions, to */ + /* indicate the type of the */ + /* completion. */ + } CplMatch; + + 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 */ + /* the above matches[] */ + /* array. */ + } CplMatches; +.fi +.sp +If an error occurs during completion, \f3cpl_complete_word()\f1 +returns NULL. A description of the error can be acquired by calling +the \f3cpl_last_error()\f3 function. +.sp +.nf + const char *cpl_last_error(WordCompletion *cpl); +.fi +.sp +The \f3cpl_last_error()\f3 function returns a terse description of the +error which occurred on the last call to \f3cpl_complete_word()\f1 or +\f3cpl_add_completion()\f1. +.sp +.nf + int cpl_list_completions(CplMatches *result, FILE *fp, + int terminal_width); +.fi +.sp +When the \f3cpl_complete_word()\f1 function returns multiple possible +completions, the \f3cpl_list_completions()\f1 function can be called +upon to list them, suitably arranged across the available width of the +terminal. It arranges for the displayed columns of completions to all +have the same width, set by the longest completion. It also appends +the \f3type_suffix\f1 strings that were recorded with each completion, +thus indicating their types to the user. + +.SH THE BUILT-IN FILENAME-COMPLETION CALLBACK + +By default the \f3gl_get_line(3)\f1 function, passes the following +completion callback function to \f3cpl_complete_word()\f1. This +function can also be used separately, either by sending it to +\f3cpl_complete_word()\f1, or by calling it directly from your +own completion callback function. +.sp +.nf + CPL_MATCH_FN(cpl_file_completions); +.fi +.sp +Certain aspects of the behavior of this callback can be changed via +its \f3data\f1 argument. If you are happy with its default behavior +you can pass \f3NULL\f1 in this argument. Otherwise it should be a +pointer to a \f3CplFileConf\f1 object, previously allocated by calling +\f3new_CplFileConf()\f1. +.sp +.nf + CplFileConf *new_CplFileConf(void); +.fi +.sp +\f3CplFileConf\f1 objects encapsulate the configuration parameters of +\f3cpl_file_completions()\f1. These parameters, which start out with +default values, can be changed by calling the accessor functions +described below. +.sp +By default, the \f3cpl_file_completions()\f3 callback function +searches backwards for the start of the filename being completed, +looking for the first un-escaped space or the start of the input +line. If you wish to specify a different location, call +\f3cfc_file_start()\f1 with the index at which the filename starts in +the input line. Passing start_index=-1 re-enables the default +behavior. +.sp +.nf + void cfc_file_start(CplFileConf *cfc, int start_index); +.fi +.sp +By default, when \f3cpl_file_completions()\f1 looks at a filename in +the input line, each lone backslash in the input line is interpreted +as being a special character which removes any special significance of +the character which follows it, such as a space which should be taken +as part of the filename rather than delimiting the start of the +filename. These backslashes are thus ignored while looking for +completions, and subsequently added before spaces, tabs and literal +backslashes in the list of completions. To have unescaped backslashes +treated as normal characters, call \f3cfc_literal_escapes()\f1 with a +non-zero value in its \f3literal\f1 argument. +.sp +.nf + void cfc_literal_escapes(CplFileConf *cfc, int literal); +.fi +.sp +By default, \f3cpl_file_completions()\f1 reports all files who's names +start with the prefix that is being completed. If you only want a +selected subset of these files to be reported in the list of +completions, you can arrange this by providing a callback function +which takes the full pathname of a file, and returns \f30\f1 if the +file should be ignored, or \f31\f1 if the file should be included in +the list of completions. To register such a function for use by +\f3cpl_file_completions()\f1, call \f3cfc_set_check_fn()\f1, and pass +it a pointer to the function, together with a pointer to any data that +you would like passed to this callback whenever it is called. Your +callback can make its decisions based on any property of the file, +such as the filename itself, whether the file is readable, writable or +executable, or even based on what the file contains. +.sp +.nf + #define CPL_CHECK_FN(fn) int (fn)(void *data, \\ + const char *pathname) + typedef CPL_CHECK_FN(CplCheckFn); + + void cfc_set_check_fn(CplFileConf *cfc, + CplCheckFn *chk_fn, void *chk_data); +.fi +.sp +The \f3cpl_check_exe()\f1 function is a provided callback of the above +type, for use with \f3cpl_file_completions()\f1. It returns non-zero +if the filename that it is given represents a normal file that the +user has execute permission to. You could use this to have +\f3cpl_file_completions()\f1 only list completions of executable +files. +.sp +When you have finished with a \f3CplFileConf\f1 variable, you can pass +it to the \f3del_CplFileConf()\f1 destructor function to reclaim its +memory. +.sp +.nf + CplFileConf *del_CplFileConf(CplFileConf *cfc); +.fi +.sp + +.SH THREAD SAFETY + +In multi-threaded programs, you should use the \f3libtecla_r.a\f1 +version of the library. This uses POSIX reentrant functions where +available (hence the \f3_r\f1 suffix), and disables features that rely +on non-reentrant system functions. In the case of this module, the +only disabled feature is username completion in \f3~username/\f1 +expressions, in \f3cpl_file_completions()\f1. + +Using the \f3libtecla_r.a\f1 version of the library, it is safe to use +the facilities of this module in multiple threads, provided that each +thread uses a separately allocated \f3WordCompletion\f1 object. In +other words, if two threads want to do word completion, they should +each call \f3new_WordCompletion()\f1 to allocate their own completion +objects. + +.SH FILES +.nf +libtecla.a - The tecla library +libtecla.h - The tecla header file. +.fi + +.SH SEE ALSO +libtecla(3), gl_get_line(3), ef_expand_file(3), pca_lookup_file(3) + +.SH AUTHOR +Martin Shepherd (mcs@astro.caltech.edu) diff --git a/libtecla-1.4.1/man3/cpl_file_completions.3 b/libtecla-1.4.1/man3/cpl_file_completions.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cpl_file_completions.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cpl_last_error.3 b/libtecla-1.4.1/man3/cpl_last_error.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cpl_last_error.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cpl_list_completions.3 b/libtecla-1.4.1/man3/cpl_list_completions.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cpl_list_completions.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/cpl_record_error.3 b/libtecla-1.4.1/man3/cpl_record_error.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/cpl_record_error.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/del_CplFileConf.3 b/libtecla-1.4.1/man3/del_CplFileConf.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/del_CplFileConf.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/del_ExpandFile.3 b/libtecla-1.4.1/man3/del_ExpandFile.3 new file mode 100644 index 0000000..f4299df --- /dev/null +++ b/libtecla-1.4.1/man3/del_ExpandFile.3 @@ -0,0 +1 @@ +.so man3/ef_expand_file.3 diff --git a/libtecla-1.4.1/man3/del_GetLine.3 b/libtecla-1.4.1/man3/del_GetLine.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/del_GetLine.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/del_PathCache.3 b/libtecla-1.4.1/man3/del_PathCache.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/del_PathCache.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/del_PcaPathConf.3 b/libtecla-1.4.1/man3/del_PcaPathConf.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/del_PcaPathConf.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/del_WordCompletion.3 b/libtecla-1.4.1/man3/del_WordCompletion.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/del_WordCompletion.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/ef_expand_file.3 b/libtecla-1.4.1/man3/ef_expand_file.3 new file mode 100644 index 0000000..88c2d54 --- /dev/null +++ b/libtecla-1.4.1/man3/ef_expand_file.3 @@ -0,0 +1,245 @@ +.\" 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. +.TH ef_expand_file 3 +.SH NAME +ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile \- expand filenames containing ~user/$envvar and wildcard expressions +.SH SYNOPSIS +.nf +#include <libtecla.h> + +ExpandFile *new_ExpandFile(void); + +ExpandFile *del_ExpandFile(ExpandFile *ef); + +FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen); + +int ef_list_expansions(FileExpansion *result, FILE *fp, + int term_width); + +const char *ef_last_error(ExpandFile *ef); +.fi + +.SH DESCRIPTION + +The \f3ef_expand_file()\f1 function is part of the tecla library +(see the libtecla(3) man page). It expands a specified filename, +converting \f3~user/\f1 and \f3~/\f1 expressions at the start of the +filename to the corresponding home directories, replacing +\f3$envvar\f1 with the value of the corresponding environment +variable, and then, if there are any wildcards, matching these against +existing filenames. Backslashes in the input filename are interpreted +as escaping any special meanings of the characters that follow them. +Only backslahes that are themselves preceded by backslashes are +preserved in the expanded filename. +.sp +In the presence of wildcards, the returned list of filenames only +includes the names of existing files which match the +wildcards. Otherwise, the original filename is returned after +expansion of tilde and dollar expressions, and the result is not +checked against existing files. This mimics the file-globbing behavior +of the unix \f3tcsh\f1 shell. +.sp +The supported wildcards and their meanings are: +.nf + * - 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. The ']' + character also looses its significance as the + terminator of the range expression if it + appears immediately after the opening '[', at + which point it is treated one of the + characters of the range. If you want both '-' + and ']' to be part of the range, the '-' + should come first and the ']' second. + + [^chars] - The same as [chars] except that it matches any + single character that doesn't appear in + 'chars'. +.fi + +Note that wildcards never match the initial dot in filenames that +start with '.'. The initial '.' must be explicitly specified in the +filename. This again mimics the globbing behavior of most unix shells, +and its rational is based in the fact that in unix, files with names +that start with '.' are usually hidden configuration files, which are +not listed by default by the ls command. +.sp +The following is a complete example of how to use the file expansion +function. + +.nf + #include <stdio.h> + #include <libtecla.h> + + int main(int argc, char *argv[]) + { + ExpandFile *ef; /* The expansion resource object */ + char *filename; /* The filename being expanded */ + FileExpansion *expn; /* The results of the expansion */ + int i; + + ef = new_ExpandFile(); + if(!ef) + return 1; + + for(arg = *(argv++); arg; arg = *(argv++)) { + if((expn = ef_expand_file(ef, arg, -1)) == NULL) { + fprintf(stderr, "Error expanding %s (%s).\\n", arg, + ef_last_error(ef)); + } else { + printf("%s matches the following files:\\n", arg); + for(i=0; i<expn->nfile; i++) + printf(" %s\\n", expn->files[i]); + } + } + + ef = del_ExpandFile(ef); + return 0; + } +.fi +.sp +Descriptions of the functions used above are as follows: +.sp +.nf + ExpandFile *new_ExpandFile(void) +.fi +.sp +This function creates the resources used by the \f3ef_expand_file()\f1 +function. In particular, it maintains the memory that is used to record the +array of matching filenames that is returned by \f3ef_expand_file()\f1. This +array is expanded as needed, so there is no built in limit to the number of +files that can be matched. +.sp +.nf + ExpandFile *del_ExpandFile(ExpandFile *ef) +.fi +.sp +This function deletes the resources that were returned by a previous call to +\f3new_ExpandFile()\f1. It always returns \f3NULL\f1 (ie a deleted object). It +does nothing if the \f3ef\f1 argument is \f3NULL\f1. +.sp +A container of the following type is returned by \f3ef_expand_file()\f1. +.sp +.nf + typedef struct { + int exists; /* True if the files in files[] exist */ + int nfile; /* The number of files in files[] */ + char **files; /* An array of 'nfile' filenames. */ + } FileExpansion; +.fi +.sp +.nf + FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen) +.fi +.sp +The \f3ef_expand_file()\f1 function performs filename expansion, as documented +at the start of this section. Its first argument is a resource object returned +by \f3new_ExpandFile()\f1. A pointer to the start of the filename to be matched +is passed via the \f3path\f1 argument. This must be a normal \f3NUL\f1 +terminated string, but unless a length of -1 is passed in \f3pathlen\f1, only +the first \f3pathlen\f1 characters will be used in the filename expansion. If +the length is specified as -1, the whole of the string will be +expanded. +.sp +The function returns a pointer to a container who's contents are the +results of the expansion. If there were no wildcards in the filename, +the \f3nfile\f1 member will be 1, and the \f3exists\f1 member should +be queried if it is important to know if the expanded file currently +exists or not. If there were wildcards, then the contained +\f3files[]\f1 array will contain the names of the \f3nfile\f1 existing +files that matched the wildcarded filename, and the \f3exists\f1 +member will have the value 1. Note that the returned container belongs +to the specified \f3ef\f1 object, and its contents will change on each +call, so if you need to retain the results of more than one call to +\f3ef_expand_file()\f1, you should either make a private copy of the +returned results, or create multiple file-expansion resource objects +via multiple calls to \f3new_ExpandFile()\f1. +.sp +On error, \f3NULL\f1 is returned, and an explanation of the error can +be determined by calling \f3ef_last_error(ef)\f1. +.sp +.nf + const char *ef_last_error(ExpandFile *ef) +.fi +.sp +This function returns the message which describes the error that +occurred on the last call to \f3ef_expand_file()\f1, for the given +\f3(ExpandFile *ef)\f1 resource object. +.sp +.nf + int ef_list_expansions(FileExpansion *result, FILE *fp, + int terminal_width); +.fi +.sp +The \f3ef_list_expansions()\f1 function provides a convenient way to +list the filename expansions returned by \f3ef_expand_file()\f1. Like +the unix \f3ls\f1 command, it arranges the filenames into equal width +columns, each column having the width of the largest file. The number +of columns used is thus determined by the length of the longest +filename, and the specified terminal width. Beware that filenames that +are longer than the specified terminal width are printed without being +truncated, so output longer than the specified terminal width can +occur. The list is written to the stdio stream specified by the +\f3fp\f1 argument. + +.SH THREAD SAFETY + +In multi-threaded programs, you should use the \f3libtecla_r.a\f1 +version of the library. This uses POSIX reentrant functions where +available (hence the \f3_r\f1 suffix), and disables features that rely +on non-reentrant system functions. Currently there are no features +disabled in this module. + +Using the \f3libtecla_r.a\f1 version of the library, it is safe to use +the facilities of this module in multiple threads, provided that each +thread uses a separately allocated \f3ExpandFile\f1 object. In other +words, if two threads want to do file expansion, they should each call +\f3new_ExpandFile()\f1 to allocate their own file-expansion objects. + +.SH FILES +.nf +libtecla.a - The tecla library +libtecla.h - The tecla header file. +.fi + +.SH SEE ALSO +libtecla(3), gl_get_line(3), cpl_complete_word(3), pca_lookup_file(3) + +.SH AUTHOR +Martin Shepherd (mcs@astro.caltech.edu) diff --git a/libtecla-1.4.1/man3/ef_last_error.3 b/libtecla-1.4.1/man3/ef_last_error.3 new file mode 100644 index 0000000..f4299df --- /dev/null +++ b/libtecla-1.4.1/man3/ef_last_error.3 @@ -0,0 +1 @@ +.so man3/ef_expand_file.3 diff --git a/libtecla-1.4.1/man3/ef_list_expansions.3 b/libtecla-1.4.1/man3/ef_list_expansions.3 new file mode 100644 index 0000000..f4299df --- /dev/null +++ b/libtecla-1.4.1/man3/ef_list_expansions.3 @@ -0,0 +1 @@ +.so man3/ef_expand_file.3 diff --git a/libtecla-1.4.1/man3/enhance.3 b/libtecla-1.4.1/man3/enhance.3 new file mode 100644 index 0000000..648ef34 --- /dev/null +++ b/libtecla-1.4.1/man3/enhance.3 @@ -0,0 +1,86 @@ +.\" 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. +.TH libtecla 3 +.SH NAME +enhance - A program that adds command-line editing to third party programs. +.SH SYNOPSIS +.nf +enhance command [ argument ... ] +.fi + +.SH DESCRIPTION + +The \f3enhance\f1 program provides enhanced command-line editing +facilities to users of third party applications, to which one doesn't +have any source code. It does this by placing a pseudo-terminal +between the application and the real terminal. It uses the tecla +command-line editing library to read input from the real terminal, +then forwards each just completed input line to the application via +the pseudo-terminal. All output from the application is forwarded +back unchanged to the real terminal. +.sp +Whenever the application stops generating output for more than a tenth +of a second, the \f3enhance\f1 program treats the latest incomplete +output line as the prompt, and redisplays any incompleted input line +that the user has typed after it. Note that the small delay, which is +imperceptible to the user, isn't necessary for correct operation of +the program. It is just an optimization, designed to stop the input +line from being redisplayed so often that it slows down output. + +.SH DEFICIENCIES + +The one major problem that hasn't been solved yet, is how to deal with +applications that change whether typed input is echo'd by their +controlling terminal. For example, programs that ask for a password, +such as ftp and telnet, temporarily tell their controlling terminal +not to echo what the user types. Since this request goes to the +application side of the psuedo terminal, the \f3enhance\f1 program has +no way of knowing that this has happened, and continues to echo typed +input to its controlling terminal, while the user types their +password. +.sp +Furthermore, before executing the host application, the \f3enhance\f1 +program initially sets the pseudo terminal to noecho mode, so that +everything that it sends to the program doesn't get redundantly +echoed. If a program that switches to noecho mode explicitly restores +echoing afterwards, rather than restoring the terminal modes that were +previously in force, then subsequently, every time that you enter a +new input line, a duplicate copy will be displayed on the next line. + +.SH FILES +.nf +libtecla.a - The tecla library. +~/.teclarc - The tecla personal customization file. +.fi + +.SH SEE ALSO +libtecla(3) + +.SH AUTHOR +Martin Shepherd (mcs@astro.caltech.edu) diff --git a/libtecla-1.4.1/man3/gl_change_terminal.3 b/libtecla-1.4.1/man3/gl_change_terminal.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_change_terminal.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_clear_history.3 b/libtecla-1.4.1/man3/gl_clear_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_clear_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_configure_getline.3 b/libtecla-1.4.1/man3/gl_configure_getline.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_configure_getline.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_customize_completion.3 b/libtecla-1.4.1/man3/gl_customize_completion.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_customize_completion.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_echo_mode.3 b/libtecla-1.4.1/man3/gl_echo_mode.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_echo_mode.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_get_line.3 b/libtecla-1.4.1/man3/gl_get_line.3 new file mode 100644 index 0000000..51fc9d8 --- /dev/null +++ b/libtecla-1.4.1/man3/gl_get_line.3 @@ -0,0 +1,2329 @@ +.\" 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. +.TH gl_get_line 3 +.SH NAME +gl_get_line, new_GetLine, del_GetLine, gl_customize_completion, gl_change_terminal, gl_configure_getline, gl_load_history, gl_save_history, gl_group_history, gl_show_history, gl_watch_fd, gl_terminal_size, gl_resize_history, gl_limit_history, gl_clear_history, gl_toggle_history, gl_lookup_history, gl_state_of_history, gl_range_of_history, gl_size_of_history, gl_echo_mode, gl_replace_prompt, gl_prompt_style, gl_ignore_signal, gl_trap_signal, gl_last_signal \- allow the user to compose an input line +.SH SYNOPSIS +.nf +#include <stdio.h> +#include <libtecla.h> + +GetLine *new_GetLine(size_t linelen, size_t histlen); + +GetLine *del_GetLine(GetLine *gl); + +char *gl_get_line(GetLine *gl, const char *prompt, + const char *start_line, int start_pos); + +int gl_customize_completion(GetLine *gl, void *data, + CplMatchFn *match_fn); + +int gl_change_terminal(GetLine *gl, FILE *input_fp, + FILE *output_fp, const char *term); + +int gl_configure_getline(GetLine *gl, + const char *app_string, + const char *app_file, + const char *user_file); + +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); + +int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event, + GlFdEventFn *callback, void *data); + +int gl_group_history(GetLine *gl, unsigned stream); + +int gl_show_history(GetLine *gl, FILE *fp, + const char *fmt, int all_groups, + int max_lines); + +int gl_resize_history(GetLine *gl, size_t bufsize); + +void gl_limit_history(GetLine *gl, int max_lines); + +void gl_clear_history(GetLine *gl, int all_groups); + +void gl_toggle_history(GetLine *gl, int enable); + +GlTerminalSize gl_terminal_size(GetLine *gl, + int def_ncolumn, + int def_nline); + +int gl_lookup_history(GetLine *gl, unsigned long id, + GlHistoryLine *hline); + +void gl_state_of_history(GetLine *gl, + GlHistoryState *state); + +void gl_range_of_history(GetLine *gl, + GlHistoryRange *range); + +void gl_size_of_history(GetLine *gl, GlHistorySize *size); + +void gl_echo_mode(GetLine *gl, int enable); + +void gl_replace_prompt(GetLine *gl, const char *prompt); + +void gl_prompt_style(GetLine *gl, GlPromptStyle style); + +int gl_ignore_signal(GetLine *gl, int signo); + +int gl_trap_signal(GetLine *gl, int signo, unsigned flags, + GlAfterSignal after, int errno_value); + +int gl_last_signal(const GetLine *gl); + +.fi + +.SH DESCRIPTION + +The \f3gl_get_line()\f1 function is part of the tecla library (see +the libtecla(3) man page). If the user is typing at a terminal, it +prompts them for an line of input, then provides interactive editing +facilities, similar to those of the unix \f3tcsh\f1 shell. In addition +to simple command-line editing, it supports recall of previously +entered command lines, TAB completion of file names, and in-line +wild-card expansion of filenames. +.sp +.SH AN EXAMPLE + +The following shows a complete example of how to use the +\f3gl_get_line()\f1 function to get input from the user: + +.nf + #include <stdio.h> + #include <locale.h> + #include <libtecla.h> + + int main(int argc, char *argv[]) + { + char *line; /* The line that the user typed */ + GetLine *gl; /* The gl_get_line() resource object */ + + setlocale(LC_CTYPE, ""); /* Adopt the user's choice */ + /* of character set. */ + + gl = new_GetLine(1024, 2048); + if(!gl) + return 1; + + while((line=gl_get_line(gl, "$ ", NULL, -1)) != NULL && + strcmp(line, "exit\\n") != 0) + printf("You typed: %s\\n", line); + + gl = del_GetLine(gl); + return 0; + } +.fi +.sp +In the example, first the resources needed by the \f3gl_get_line()\f1 function +are created by calling \f3new_GetLine()\f1. This allocates the memory used in +subsequent calls to the \f3gl_get_line()\f1 function, including the history +buffer for recording previously entered lines. Then one or more lines are read +from the user, until either an error occurs, or the user types \f3exit\f1. Then +finally the resources that were allocated by \f3new_GetLine()\f1, are returned +to the system by calling \f3del_GetLine()\f1. Note the use of the \f3NULL\f1 +return value of \f3del_GetLine()\f1 to make \f3gl\f1 \f3NULL\f1. This is a +safety precaution. If the program subsequently attempts to pass \f3gl\f1 to +\f3gl_get_line()\f1, said function will complain, and return an error, instead of +attempting to use the deleted resource object. + +.sp +.SH THE FUNCTIONS USED IN THE EXAMPLE +The descriptions of the functions used in the example are as follows: +.sp +.nf + GetLine *new_GetLine(size_t linelen, size_t histlen) +.fi +.sp +This function creates the resources used by the \f3gl_get_line()\f1 +function and returns an opaque pointer to the object that contains +them. The maximum length of an input line is specified via the +\f3linelen\f1 argument, and the number of bytes to allocate for +storing history lines is set by the \f3histlen\f1 argument. History +lines are stored back-to-back in a single buffer of this size. Note +that this means that the number of history lines that can be stored at +any given time, depends on the lengths of the individual lines. If +you want to place an upper limit on the number of lines that can be +stored, see the \f3gl_limit_history()\f1 function described later. If +you don't want history at all, specify \f3histlen\f1 as zero, and no +history buffer will be allocated. +.sp +On error, a message is printed to \f3stderr\f1 and \f3NULL\f1 is returned. +.sp +.nf + GetLine *del_GetLine(GetLine *gl) +.fi +.sp +This function deletes the resources that were returned by a previous +call to \f3new_GetLine()\f1. It always returns \f3NULL\f1 (ie a +deleted object). It does nothing if the \f3gl\f1 argument is +\f3NULL\f1. +.sp +.nf + char *gl_get_line(GetLine *gl, const char *prompt, + const char *start_line, int start_pos); +.fi +.sp +The \f3gl_get_line()\f1 function can be called any number of +times to read input from the user. The \f3gl\f1 argument +must have been previously returned by a call to +\f3new_GetLine()\f1. The \f3prompt\f1 argument should be a +normal \f3NUL\f1 terminated string, specifying the prompt to +present the user with. By default prompts are displayed +literally, but if enabled with the \f3gl_prompt_style()\f1 +function (see later), prompts can contain directives to do +underlining, switch to and from bold fonts, or turn +highlighting on and off. + +If you want to specify the initial contents of the line, for +the user to edit, pass the desired string via the +\f3start_line\f1 argument. You can then specify which +character of this line the cursor is initially positioned +over, using the \f3start_pos\f1 argument. This should be -1 +if you want the cursor to follow the last character of the +start line. If you don't want to preload the line in this +manner, send \f3start_line\f1 as \f3NULL\f1, and set +\f3start_pos\f1 to -1. + +The \f3gl_get_line()\f1 function returns a pointer to the line entered +by the user, or \f3NULL\f1 on error or at the end of the input. The +returned pointer is part of the specified \f3gl\f1 resource object, +and thus should not be free'd by the caller, or assumed to be +unchanging from one call to the next. When reading from a user at a +terminal, there will always be a newline character at the end of the +returned line. When standard input is being taken from a pipe or a +file, there will similarly be a newline unless the input line was too +long to store in the internal buffer. In the latter case you should +call \f3gl_get_line()\f1 again to read the rest of the line. Note that +this behavior makes \f3gl_get_line()\f1 similar to \f3fgets()\f1. In +fact when \f3stdin\f1 isn't connected to a terminal,\f3gl_get_line()\f1 +just calls \f3fgets()\f1. + +.SH OPTIONAL PROMPT FORMATTING + +Whereas by default the prompt string that you specify is +displayed literally, without any special interpretation of +the characters within it, the \f3gl_prompt_style()\f1 +function can be used to enable optional formatting +directives within the prompt. +.sp +.nf + void gl_prompt_style(GetLine *gl, GlPromptStyle style); +.fi +.sp +The \f3style\f1 argument, which specifies the formatting +style, can take any of the following values: +.sp +.nf + GL_FORMAT_PROMPT - In this style, the formatting + directives described below, when + included in prompt strings, are + interpreted as follows: + + %B - Display subsequent + characters with a bold + font. + %b - Stop displaying characters + with the bold font. + %F - Make subsequent characters + flash. + %f - Turn off flashing + characters. + %U - Underline subsequent + characters. + %u - Stop underlining + characters. + %P - Switch to a pale (half + brightness) font. + %p - Stop using the pale font. + %S - Highlight subsequent + characters (also known as + standout mode). + %s - Stop highlighting + characters. + %V - Turn on reverse video. + %v - Turn off reverse video. + %% - Display a single % + character. + + For example, in this mode, a prompt + string like \f3"%UOK%u$ "\f1 would + display the prompt \f3"OK$ "\f1, + but with the \f3OK\f1 part + underlined. + + Note that although a pair of + characters that starts with a % + character, but doesn't match any of + the above directives is displayed + literally, if a new directive is + subsequently introduced which does + match, the displayed prompt will + change, so it is better to always + use %% to display a literal %. + + Also note that not all terminals + support all of these text + attributes, and that some substitute + a different attribute for missing + ones. + + GL_LITERAL_PROMPT - In this style, the prompt string is + printed literally. This is the + default style. +.fi +.sp + +.SH THE AVAILABLE KEY BINDING FUNCTIONS + +The \f3gl_get_line()\f1 function provides a number of functions which +can be bound to key sequences. The names of these functions, and what +they do, are given below. + +.nf + user-interrupt - Send a SIGINT signal to the + parent process. + abort - Send a SIGABRT signal to the + parent process. + suspend - Suspend the parent process. + stop-output - Pause terminal output. + start-output - Resume paused terminal output. + literal-next - Arrange for the next character + to be treated as a normal + character. This allows control + characters to be entered. + cursor-right - Move the cursor one character + right. + cursor-left - Move the cursor one character + left. + insert-mode - Toggle between insert mode and + overwrite mode. + beginning-of-line - Move the cursor to the + beginning of the line. + end-of-line - Move the cursor to the end of + the line. + delete-line - Delete the contents of the + current line. + kill-line - Delete everything that follows + the cursor. + backward-kill-line - Delete all characters between + the cursor and the start of the + line. + forward-word - Move to the end of the word + which follows the cursor. + forward-to-word - Move the cursor to the start of + the word that follows the + cursor. + backward-word - Move to the start of the word + which precedes the cursor. + goto-column - Move the cursor to the + 1-relative column in the line + specified by any preceding + digit-argument sequences (see + ENTERING REPEAT COUNTS below). + find-parenthesis - If the cursor is currently + over a parenthesis character, + move it to the matching + parenthesis character. If not + over a parenthesis character + move right to the next close + parenthesis. + forward-delete-char - Delete the character under the + cursor. + backward-delete-char - Delete the character which + precedes the cursor. + list-or-eof - This is intended for binding + to ^D. When invoked when the + cursor is within the line it + displays all possible + completions then redisplays + the line unchanged. When + invoked on an empty line, it + signals end-of-input (EOF) to + the caller of gl_get_line(). + del-char-or-list-or-eof - This is intended for binding + to ^D. When invoked when the + cursor is within the line it + invokes forward-delete-char. + When invoked at the end of the + line it displays all possible + completions then redisplays + the line unchanged. When + invoked on an empty line, it + signals end-of-input (EOF) to + the caller of gl_get_line(). + forward-delete-word - Delete the word which follows + the cursor. + backward-delete-word - Delete the word which precedes + the cursor. + upcase-word - Convert all of the characters + of the word which follows the + cursor, to upper case. + downcase-word - Convert all of the characters + of the word which follows the + cursor, to lower case. + capitalize-word - Capitalize the word which + follows the cursor. + change-case - If the next character is upper + case, toggle it to lower case + and vice versa. + redisplay - Redisplay the line. + clear-screen - Clear the terminal, then + redisplay the current line. + transpose-chars - Swap the character under the + cursor with the character just + before the cursor. + set-mark - Set a mark at the position of + the cursor. + exchange-point-and-mark - Move the cursor to the last + mark that was set, and move + the mark to where the cursor + used to be. + kill-region - Delete the characters that lie + between the last mark that was + set, and the cursor. + copy-region-as-kill - Copy the text between the mark + and the cursor to the cut + buffer, without deleting the + original text. + yank - Insert the text that was last + deleted, just before the + current position of the cursor. + append-yank - Paste the current contents of + the cut buffer, after the + cursor. + up-history - Recall the next oldest line + that was entered. Note that + in vi mode you are left in + command mode. + down-history - Recall the next most recent + line that was entered. If no + history recall session is + currently active, the next + line from a previous recall + session is recalled. Note that + in vi mode you are left in + command mode. + history-search-backward - Recall the next oldest line + who's prefix matches the string + which currently precedes the + cursor (in vi command-mode the + character under the cursor is + also included in the search + string). Note that in vi mode + you are left in command mode. + history-search-forward - Recall the next newest line + who's prefix matches the string + which currently precedes the + cursor (in vi command-mode the + character under the cursor is + also included in the search + string). Note that in vi mode + you are left in command mode. + history-re-search-backward -Recall the next oldest line + who's prefix matches that + established by the last + invocation of either + history-search-forward or + history-search-backward. + history-re-search-forward - Recall the next newest line + who's prefix matches that + established by the last + invocation of either + history-search-forward or + history-search-backward. + complete-word - Attempt to complete the + incomplete word which + precedes the cursor. Unless + the host program has customized + word completion, filename + completion is attempted. In vi + commmand mode the character + under the cursor is also + included in the word being + completed, and you are left in + vi insert mode. + expand-filename - Within the command line, expand + wild cards, tilde expressions + and dollar expressions in the + filename which immediately + precedes the cursor. In vi + commmand mode the character + under the cursor is also + included in the filename being + expanded, and you are left in + vi insert mode. + list-glob - List any filenames which match + the wild-card, tilde and dollar + expressions in the filename + which immediately precedes the + cursor, then redraw the input + line unchanged. + list-history - Display the contents of the + history list for the current + history group. If a repeat + count of > 1 is specified, + only that many of the most + recent lines are displayed. + See the "ENTERING REPEAT + COUNTS" section. + read-from-file - Temporarily switch to reading + input from the file who's + name precedes the cursor. + read-init-files - Re-read teclarc configuration + files. + beginning-of-history - Move to the oldest line in the + history list. Note that in vi + mode you are left in command + mode. + end-of-history - Move to the newest line in the + history list (ie. the current + line). Note that in vi mode + this leaves you in command + mode. + digit-argument - Enter a repeat count for the + next key-binding function. + For details, see the ENTERING + REPEAT COUNTS section. + newline - Terminate and return the + current contents of the + line, after appending a + newline character. The newline + character is normally '\\n', + but will be the first + character of the key-sequence + that invoked the newline + action, if this happens to be + a printable character. If the + action was invoked by the + '\\n' newline character or the + '\\r' carriage return + character, the line is + appended to the history + buffer. + repeat-history - Return the line that is being + edited, then arrange for the + next most recent entry in the + history buffer to be recalled + when \f3gl_get_line()\f1 is + next called. Repeatedly + invoking this action causes + successive historical input + lines to be re-executed. Note + that this action is equivalent + to the 'Operate' action in + ksh. + ring-bell - Ring the terminal bell, unless + the bell has been silenced via + the \f3nobeep\f1 configuration + option (see the THE TECLA + CONFIGURATION FILE section). + forward-copy-char - Copy the next character into + the cut buffer (NB. use repeat + counts to copy more than one). + backward-copy-char - Copy the previous character + into the cut buffer. + forward-copy-word - Copy the next word into the cut + buffer. + backward-copy-word - Copy the previous word into the + cut buffer. + forward-find-char - Move the cursor to the next + occurrence of the next + character that you type. + backward-find-char - Move the cursor to the last + occurrence of the next + character that you type. + forward-to-char - Move the cursor to the + character just before the next + occurrence of the next + character that the user types. + backward-to-char - Move the cursor to the + character just after the last + occurrence before the cursor + of the next character that the + user types. + repeat-find-char - Repeat the last + backward-find-char, + forward-find-char, + backward-to-char or + forward-to-char. + invert-refind-char - Repeat the last + backward-find-char, + forward-find-char, + backward-to-char, or + forward-to-char in the + opposite direction. + delete-to-column - Delete the characters from the + cursor up to the column that + is specified by the repeat + count. + delete-to-parenthesis - Delete the characters from the + cursor up to and including + the matching parenthesis, or + next close parenthesis. + forward-delete-find - Delete the characters from the + cursor up to and including the + following occurence of the + next character typed. + backward-delete-find - Delete the characters from the + cursor up to and including the + preceding occurence of the + next character typed. + forward-delete-to - Delete the characters from the + cursor up to, but not + including, the following + occurence of the next + character typed. + backward-delete-to - Delete the characters from the + cursor up to, but not + including, the preceding + occurence of the next + character typed. + delete-refind - Repeat the last *-delete-find + or *-delete-to action. + delete-invert-refind - Repeat the last *-delete-find + or *-delete-to action, in the + opposite direction. + copy-to-column - Copy the characters from the + cursor up to the column that + is specified by the repeat + count, into the cut buffer. + copy-to-parenthesis - Copy the characters from the + cursor up to and including + the matching parenthesis, or + next close parenthesis, into + the cut buffer. + forward-copy-find - Copy the characters from the + cursor up to and including the + following occurence of the + next character typed, into the + cut buffer. + backward-copy-find - Copy the characters from the + cursor up to and including the + preceding occurence of the + next character typed, into the + cut buffer. + forward-copy-to - Copy the characters from the + cursor up to, but not + including, the following + occurence of the next + character typed, into the cut + buffer. + backward-copy-to - Copy the characters from the + cursor up to, but not + including, the preceding + occurence of the next + character typed, into the cut + buffer. + copy-refind - Repeat the last *-copy-find + or *-copy-to action. + copy-invert-refind - Repeat the last *-copy-find + or *-copy-to action, in the + opposite direction. + vi-mode - Switch to vi mode from emacs + mode. + emacs-mode - Switch to emacs mode from vi + mode. + vi-insert - From vi command mode, switch to + insert mode. + vi-overwrite - From vi command mode, switch to + overwrite mode. + vi-insert-at-bol - From vi command mode, move the + cursor to the start of the line + and switch to insert mode. + vi-append-at-eol - From vi command mode, move the + cursor to the end of the line + and switch to append mode. + vi-append - From vi command mode, move the + cursor one position right, and + switch to insert mode. + vi-replace-char - From vi command mode, replace + the character under the cursor + with the the next character + entered. + vi-forward-change-char - From vi command mode, delete + the next character then enter + insert mode. + vi-backward-change-char - From vi command mode, delete + the preceding character then + enter insert mode. + vi-forward-change-word - From vi command mode, delete + the next word then enter + insert mode. + vi-backward-change-word - From vi command mode, delete + the preceding word then + enter insert mode. + vi-change-rest-of-line - From vi command mode, delete + from the cursor to the end of + the line, then enter insert + mode. + vi-change-line - From vi command mode, delete + the current line, then enter + insert mode. + vi-change-to-bol - From vi command mode, delete + all characters between the + cursor and the beginning of + the line, then enter insert + mode. + vi-change-to-column - From vi command mode, delete + the characters from the cursor + up to the column that is + specified by the repeat count, + then enter insert mode. + vi-change-to-parenthesis - Delete the characters from the + cursor up to and including + the matching parenthesis, or + next close parenthesis, then + enter vi insert mode. + vi-forward-change-find - From vi command mode, delete + the characters from the + cursor up to and including the + following occurence of the + next character typed, then + enter insert mode. + vi-backward-change-find - From vi command mode, delete + the characters from the + cursor up to and including the + preceding occurence of the + next character typed, then + enter insert mode. + vi-forward-change-to - From vi command mode, delete + the characters from the + cursor up to, but not + including, the following + occurence of the next + character typed, then enter + insert mode. + vi-backward-change-to - From vi command mode, delete + the characters from the + cursor up to, but not + including, the preceding + occurence of the next + character typed, then enter + insert mode. + vi-change-refind - Repeat the last + vi-*-change-find or + vi-*-change-to action. + vi-change-invert-refind - Repeat the last + vi-*-change-find or + vi-*-change-to action, in the + opposite direction. + vi-undo - In vi mode, undo the last + editing operation. + vi-repeat-change - In vi command mode, repeat the + last command that modified the + line. +.fi + +.SH DEFAULT KEY BINDINGS IN EMACS MODE + +The following default key bindings, which can be overriden by +the tecla configuration file, are designed to mimic most of +the bindings of the unix \f3tcsh\f1 shell, when it is in +emacs editing mode. +.sp +This is the default editing mode of the tecla library. +.sp +Note that a key sequence like \f3^A\f1 or \f3C-a\f1 means hold the control-key +down while pressing the letter \f3A\f1, and that where you see \f3\\E\f1 or +\f3M-\f1 in a binding, this represents the escape key or the Meta modifier +key. Also note that to \f3gl_get_line()\f1, pressing the escape key before a +key is equivalent to pressing the meta key at the same time as that key. Thus +the key sequence \f3M-p\f1 can be typed in two ways, by pressing the escape +key, followed by pressing \f3p\f1, or by pressing the Meta key at the same time +as \f3p\f1. +.sp +Under UNIX the terminal driver sets a number of special keys for certain +functions. The tecla library attempts to use the same keybindings to maintain +consistency. The key sequences shown for the following 6 bindings are thus just +examples of what they will probably be set to. If you have used the \f3stty\f1 +command to change these keys, then the default bindings should match. + +.nf + ^C -> user-interrupt + ^\\ -> abort + ^Z -> suspend + ^Q -> start-output + ^S -> stop-output + ^V -> literal-next +.fi + +The cursor keys are refered to by name, as follows. This is necessary +because different types of terminals generate different key sequences +when their cursor keys are pressed. + + right -> cursor-right + left -> cursor-left + up -> up-history + down -> down-history + +The remaining bindings don't depend on the terminal setttings. + +.nf + ^F -> cursor-right + ^B -> cursor-left + M-i -> insert-mode + ^A -> beginning-of-line + ^E -> end-of-line + ^U -> delete-line + ^K -> kill-line + M-f -> forward-word + M-b -> backward-word + ^D -> del-char-or-list-or-eof + ^H -> backward-delete-char + ^? -> backward-delete-char + M-d -> forward-delete-word + M-^H -> backward-delete-word + M-^? -> backward-delete-word + M-u -> upcase-word + M-l -> downcase-word + M-c -> capitalize-word + ^R -> redisplay + ^L -> clear-screen + ^T -> transpose-chars + ^@ -> set-mark + ^X^X -> exchange-point-and-mark + ^W -> kill-region + M-w -> copy-region-as-kill + ^Y -> yank + ^P -> up-history + ^N -> down-history + M-p -> history-search-backward + M-n -> history-search-forward + ^I -> complete-word + ^X* -> expand-filename + ^X^F -> read-from-file + ^X^R -> read-init-files + ^Xg -> list-glob + ^Xh -> list-history + M-< -> beginning-of-history + M-> -> end-of-history + \\n -> newline + \\r -> newline + M-o -> repeat-history + M-^V -> vi-mode + + M-0, M-1, ... M-9 -> digit-argument (see below) +.fi + +Note that ^I is what the TAB key generates, and that ^@ can be +generated not only by pressing the control key and the @ key +simultaneously, but also by pressing the control key and the space bar +at the same time. + +.SH DEFAULT KEY BINDINGS IN VI MODE + +The following default key bindings are designed to mimic the +vi style of editing as closely as possible. This means that +very few editing functions are provided in the initial +character input mode, editing functions instead being +provided by the vi command mode. Vi command mode is entered +whenever the escape character is pressed, or whenever a +key-sequence that starts with a meta character is entered. In +addition to mimicing vi, libtecla provides bindings for tab +completion, wild-card expansion of file names, and historical +line recall. +.sp +To learn how to tell the tecla library to use vi mode instead +of the default emacs editing mode, see the section entitled +THE TECLA CONFIGURATION FILE. +.sp +As already mentioned above in the emacs section, Note that a +key sequence like \f3^A\f1 or \f3C-a\f1 means hold the +control-key down while pressing the letter \f3A\f1, and that +where you see \f3\\E\f1 or \f3M-\f1 in a binding, this +represents the escape key or the Meta modifier key. Also note +that to \f3gl_get_line()\f1, pressing the escape key before a +key is equivalent to pressing the meta key at the same time +as that key. Thus the key sequence \f3M-p\f1 can be typed in +two ways, by pressing the escape key, followed by pressing +\f3p\f1, or by pressing the Meta key at the same time as +\f3p\f1. +.sp +Under UNIX the terminal driver sets a number of special keys +for certain functions. The tecla library attempts to use the +same keybindings to maintain consistency, binding them both +in input mode and in command mode. The key sequences shown +for the following 6 bindings are thus just examples of what +they will probably be set to. If you have used the \f3stty\f1 +command to change these keys, then the default bindings +should match. + +.nf + ^C -> user-interrupt + ^\\ -> abort + ^Z -> suspend + ^Q -> start-output + ^S -> stop-output + ^V -> literal-next + M-^C -> user-interrupt + M-^\\ -> abort + M-^Z -> suspend + M-^Q -> start-output + M-^S -> stop-output +.fi + +Note that above, most of the bindings are defined twice, once +as a raw control code like \f3^C\f1 and then a second time as +a meta character like \f3M-^C\f1. The former is the binding +for vi input mode, whereas the latter is the binding for vi +command mode. Once in command mode all key-sequences that the +user types that they don't explicitly start with an escape or +a meta key, have their first key secretly converted to a meta +character before the key sequence is looked up in the key +binding table. Thus, once in command mode, when you type the +letter \f3i\f1, for example, the tecla library actually looks +up the binding for \f3M-i\f1. + +The cursor keys are refered to by name, as follows. This is necessary +because different types of terminals generate different key sequences +when their cursor keys are pressed. + + right -> cursor-right + left -> cursor-left + up -> up-history + down -> down-history + +The cursor keys normally generate a keysequence that start +with an escape character, so beware that using the arrow keys +will put you into command mode (if you aren't already in +command mode). +.sp +The following are the terminal-independent key bindings for vi input +mode. + +.nf + ^D -> list-or-eof + ^G -> list-glob + ^H -> backward-delete-char + ^I -> complete-word + \\r -> newline + \\n -> newline + ^L -> clear-screen + ^N -> down-history + ^P -> up-history + ^R -> redisplay + ^U -> backward-kill-line + ^W -> backward-delete-word + ^X* -> expand-filename + ^X^F -> read-from-file + ^X^R -> read-init-files + ^? -> backward-delete-char +.fi + +The following are the key bindings that are defined in vi +command mode, this being specified by them all starting with +a meta character. As mentioned above, once in command mode +the initial meta character is optional. For example, you +might enter command mode by typing Esc, and then press h +twice to move the cursor two positions to the left. Both h +characters get quietly converted to M-h before being compared +to the key-binding table, the first one because Escape +followed by a character is always converted to the equivalent +meta character, and the second because command mode was +already active. + +.nf + M-\\ -> cursor-right (Meta-space) + M-$ -> end-of-line + M-* -> expand-filename + M-+ -> down-history + M-- -> up-history + M-< -> beginning-of-history + M-> -> end-of-history + M-^ -> beginning-of-line + M-; -> repeat-find-char + M-, -> invert-refind-char + M-| -> goto-column + M-~ -> change-case + M-. -> vi-repeat-change + M-% -> find-parenthesis + M-a -> vi-append + M-A -> vi-append-at-eol + M-b -> backward-word + M-B -> backward-word + M-C -> vi-change-rest-of-line + M-cb -> vi-backward-change-word + M-cB -> vi-backward-change-word + M-cc -> vi-change-line + M-ce -> vi-forward-change-word + M-cE -> vi-forward-change-word + M-cw -> vi-forward-change-word + M-cW -> vi-forward-change-word + M-cF -> vi-backward-change-find + M-cf -> vi-forward-change-find + M-cT -> vi-backward-change-to + M-ct -> vi-forward-change-to + M-c; -> vi-change-refind + M-c, -> vi-change-invert-refind + M-ch -> vi-backward-change-char + M-c^H -> vi-backward-change-char + M-c^? -> vi-backward-change-char + M-cl -> vi-forward-change-char + M-c\\ -> vi-forward-change-char (Meta-c-space) + M-c^ -> vi-change-to-bol + M-c0 -> vi-change-to-bol + M-c$ -> vi-change-rest-of-line + M-c| -> vi-change-to-column + M-c% -> vi-change-to-parenthesis + M-dh -> backward-delete-char + M-d^H -> backward-delete-char + M-d^? -> backward-delete-char + M-dl -> forward-delete-char + M-d -> forward-delete-char (Meta-d-space) + M-dd -> delete-line + M-db -> backward-delete-word + M-dB -> backward-delete-word + M-de -> forward-delete-word + M-dE -> forward-delete-word + M-dw -> forward-delete-word + M-dW -> forward-delete-word + M-dF -> backward-delete-find + M-df -> forward-delete-find + M-dT -> backward-delete-to + M-dt -> forward-delete-to + M-d; -> delete-refind + M-d, -> delete-invert-refind + M-d^ -> backward-kill-line + M-d0 -> backward-kill-line + M-d$ -> kill-line + M-D -> kill-line + M-d| -> delete-to-column + M-d% -> delete-to-parenthesis + M-e -> forward-word + M-E -> forward-word + M-f -> forward-find-char + M-F -> backward-find-char + M-- -> up-history + M-h -> cursor-left + M-H -> beginning-of-history + M-i -> vi-insert + M-I -> vi-insert-at-bol + M-j -> down-history + M-J -> history-search-forward + M-k -> up-history + M-K -> history-search-backward + M-l -> cursor-right + M-L -> end-of-history + M-n -> history-re-search-forward + M-N -> history-re-search-backward + M-p -> append-yank + M-P -> yank + M-r -> vi-replace-char + M-R -> vi-overwrite + M-s -> vi-forward-change-char + M-S -> vi-change-line + M-t -> forward-to-char + M-T -> backward-to-char + M-u -> vi-undo + M-w -> forward-to-word + M-W -> forward-to-word + M-x -> forward-delete-char + M-X -> backward-delete-char + M-yh -> backward-copy-char + M-y^H -> backward-copy-char + M-y^? -> backward-copy-char + M-yl -> forward-copy-char + M-y\\ -> forward-copy-char (Meta-y-space) + M-ye -> forward-copy-word + M-yE -> forward-copy-word + M-yw -> forward-copy-word + M-yW -> forward-copy-word + M-yb -> backward-copy-word + M-yB -> backward-copy-word + M-yf -> forward-copy-find + M-yF -> backward-copy-find + M-yt -> forward-copy-to + M-yT -> backward-copy-to + M-y; -> copy-refind + M-y, -> copy-invert-refind + M-y^ -> copy-to-bol + M-y0 -> copy-to-bol + M-y$ -> copy-rest-of-line + M-yy -> copy-line + M-Y -> copy-line + M-y| -> copy-to-column + M-y% -> copy-to-parenthesis + M-^E -> emacs-mode + M-^H -> cursor-left + M-^? -> cursor-left + M-^L -> clear-screen + M-^N -> down-history + M-^P -> up-history + M-^R -> redisplay + M-^D -> list-or-eof + M-^I -> complete-word + M-\\r -> newline + M-\\n -> newline + M-^X^R -> read-init-files + M-^Xh -> list-history + + M-0, M-1, ... M-9 -> digit-argument (see below) +.fi + +Note that ^I is what the TAB key generates. + +.SH ENTERING REPEAT COUNTS + +Many of the key binding functions described previously, take +an optional count, typed in before the target +keysequence. This is interpreted as a repeat count by most +bindings. A notable exception is the goto-column binding, +which interprets the count as a column number. +.sp +By default you can specify this count argument by pressing +the meta key while typing in the numeric count. This relies +on the \f3digit-argument\f1 action being bound to Meta-0, +Meta-1 etc. Once any one of these bindings has been +activated, you can optionally take your finger off the meta +key to type in the rest of the number, since every numeric +digit thereafter is treated as part of the number, unless it +is preceded by the \f3literal-next\f1 binding. As soon as a +non-digit, or literal digit key is pressed the repeat count +is terminated and either causes the just typed character to +be added to the line that many times, or causes the next +key-binding function to be given that argument. +.sp +For example, in emacs mode, typing: +.sp +.nf + M-12a +.fi +.sp +causes the letter 'a' to be added to the line 12 times, +whereas +.sp +.nf + M-4M-c +.fi +.sp +Capitalizes the next 4 words. +.sp +In vi command mode the Meta modifier is automatically added +to all characters typed in, so to enter a count in vi +command-mode, just involves typing in the number, just as at +it does in the vi editor itself. So for example, in vi +command mode, typing: +.sp +.nf + 4w2x +.fi +.sp +moves the cursor four words to the right, then deletes two characters. +.sp +You can also bind \f3digit-argument\f1 to other key sequences. If +these end in a numeric digit, that digit gets appended to the current +repeat count. If it doesn't end in a numeric digit, a new repeat count +is started with a value of zero, and can be completed by typing in the +number, after letting go of the key which triggered the digit-argument +action. + +.SH THE TECLA CONFIGURATION FILE + +By default, the first call to \f3gl_get_line()\f1 looks for a file +called \f3\&.teclarc\f1 in your home directory (ie. \f3~/.teclarc\f1). +If it finds this file, it reads it, interpreting each line as defining +a new key binding or an editing configuration option. Since the emacs +keybindings are installed by default, if you want to use the +non-default vi editing mode, the most important item to go in this +file is the following line: + +.nf + edit-mode vi +.fi + +This will re-configure the default bindings for vi-mode. The +complete set of arguments that this command accepts are: +.sp +.nf + vi - Install key-bindings like those of the vi + editor. + emacs - Install key-bindings like those of the emacs + editor. This is the default. + none - Use just the native line editing facilities + provided by the terminal driver. +.fi +.sp +To prevent the terminal bell from being rung, such as when +an unrecognized control-sequence is typed, place the +following line in the configuration file: + +.nf + nobeep +.fi + +An example of a key binding line in the configuration file is +the following. + +.nf + bind M-[2~ insert-mode +.fi + +On many keyboards, the above key sequence is generated when one +presses the \f3insert\f1 key, so with this keybinding, one can toggle +between the emacs-mode insert and overwrite modes by hitting one +key. One could also do it by typing out the above sequence of +characters one by one. As explained above, the \f3M-\f1 part of this +sequence can be typed either by pressing the escape key before the +following key, or by pressing the Meta key at the same time as the +following key. Thus if you had set the above key binding, and the +insert key on your keyboard didn't generate the above key sequence, +you could still type it in either of the following 2 ways. + +.nf + 1. Hit the escape key momentarily, then press '[', then '2', then + finally '~'. + + 2. Press the meta key at the same time as pressing the '[' key, + then press '2', then '~'. +.fi + +If you set a keybinding for a key-sequence that is already bound to a function, +the new binding overrides the old one. If in the new binding you omit the name +of the new function to bind to the key-sequence, the original binding becomes +undefined. +.sp +Starting with versions of libtecla later than 1.3.3 it is now possible +to bind keysequences that begin with a printable character. Previously +key-sequences were required to start with a control or meta character. +.sp +Note that the special keywords "up", "down", "left" and "right" refer +to the arrow keys, and are thus not treated as keysequences. So, for +example, to rebind the up and down arrow keys to use the history +search mechanism instead of the simple history recall method, you +could place the following in your configuration file: + +.nf + bind up history-search-backwards + bind down history-search-backwards +.fi +.sp +To unbind an existing binding, you can do this with the bind command +by omitting to name any action to rebind the key sequence to. For +example, by not specifying an action function, the following command +unbinds the default beginning-of-line action from the ^A key sequence: + +.nf + bind ^A +.fi + +.SH ALTERNATE CONFIGURATION SOURCES + +As mentioned above, by default users have the option of configuring +the behavior of \f3gl_get_line()\f1 via a configuration file called +\f3\&.teclarc\f1 in their home directories. The fact that all +applications share this same configuration file is both an advantage +and a disadvantage. In most cases it is an advantage, since it +encourages uniformity, and frees the user from having to configure +each application separately. In some applications, however, this +single means of configuration is a problem. This is particularly true +of embedded software, where there's no filesystem to read a +configuration file from, and also in applications where a radically +different choice of keybindings is needed to emulate a legacy keyboard +interface. To cater for such cases, the following function allows the +application to control where configuration information is read from. + +.sp +.nf + int gl_configure_getline(GetLine *gl, + const char *app_string, + const char *app_file, + const char *user_file); +.fi +.sp + +It allows the configuration commands that would normally be read from +a user's \f3~/.teclarc\f1 file, to be read from any or none of, a +string, an application specific configuration file, and/or a +user-specific configuration file. If this function is called before +the first call to \f3gl_get_line()\f1, the default behavior of +reading \f3~/.teclarc\f1 on the first call to \f3gl_get_line()\f1 is +disabled, so all configuration must be achieved using the +configuration sources specified with this function. + +If \f3app_string != NULL\f1, then it is interpreted as a string +containing one or more configuration commands, separated from each +other in the string by embedded newline characters. If \f3app_file != +NULL\f1 then it is interpreted as the full pathname of an +application-specific configuration file. If \f3user_file != NULL\f1 +then it is interpreted as the full pathname of a user-specific +configuration file, such as \f3~/.teclarc\f1. For example, in the +following call, + + gl_configure_getline(gl, "edit-mode vi \\n nobeep", + "/usr/share/myapp/teclarc", + "~/.teclarc"); + +the \f3app_string\f1 argument causes the calling application to start +in vi edit-mode, instead of the default emacs mode, and turns off the +use of the terminal bell by the library. It then attempts to read +system-wide configuration commands from an optional file called +\f3/usr/share/myapp/teclarc\f1, then finally reads user-specific +configuration commands from an optional \f3\&.teclarc\f1 file in the +user's home directory. Note that the arguments are listed in ascending +order of priority, with the contents of \f3app_string\f1 being +potentially overriden by commands in \f3app_file\f1, and commands in +\f3app_file\f1 potentially being overriden by commands in +\f3user_file\f1. +.sp +You can call this function as many times as needed, the results being +cumulative, but note that copies of any filenames specified via the +\f3app_file\f1 and \f3user_file\f1 arguments are recorded internally +for subsequent use by the \f3read-init-files\f1 key-binding function, +so if you plan to call this function multiple times, be sure that the +last call specifies the filenames that you want re-read when the user +requests that the configuration files be re-read. + +.SH FILENAME AND TILDE COMPLETION + +With the default key bindings, pressing the TAB key (aka. ^I) results +in \f3gl_get_line()\f1 attempting to complete the incomplete filename +that precedes the cursor. \f3gl_get_line()\f1 searches backwards from +the cursor, looking for the start of the filename, stopping when it +hits either a space or the start of the line. If more than one file +has the specified prefix, \f3gl_get_line()\f1 completes the filename +up to the point at which the ambiguous matches start to differ, then +lists the possible matches. +.sp +In addition to literally written filenames, \f3gl_get_line()\f1 can +complete files that start with \f3~/\f1 and \f3~user/\f1 expressions +and that contain \f3$envvar\f1 expressions. In particular, if you hit +TAB within an incomplete \f3~user\f1, expression, \f3gl_get_line()\f1 +will attempt to complete the username, listing any ambiguous matches. +.sp +The completion binding is implemented using the +\f3cpl_word_completions()\f1 function, which is also available +separately to users of this library. See the +\f3cpl_word_completions(3)\f1 man page for more details. + +.SH CUSTOMIZED WORD COMPLETION + +If in your application, you would like to have TAB completion complete +other things in addition to or instead of filenames, you can arrange +this by registering an alternate completion callback function, via a +call to the \f3gl_customize_completion()\f1 function. +.sp +.nf + int gl_customize_completion(GetLine *gl, void *data, + CplMatchFn *match_fn); +.fi +.sp +The \f3data\f1 argument provides a way for your application to pass +arbitrary, application-specific information to the callback +function. This is passed to the callback every time that it is +called. It might for example, point to the symbol table from which +possible completions are to be sought. The \f3match_fn\f1 argument +specifies the callback function to be called. The \f3CplMatchFn\f1 +function type is defined in \f3libtecla.h\f1, as is a +\f3CPL_MATCH_FN()\f1 macro that you can use to declare and prototype +callback functions. The declaration and responsibilities of callback +functions are described in depth in the \f1cpl_complete_word(3)\f1 man +page. +.sp +In brief, the callback function is responsible for looking backwards +in the input line, back from the point at which the user pressed TAB, +to find the start of the word being completed. It then must lookup +possible completions of this word, and record them one by one in the +\f3WordCompletion\f1 object that is passed to it as an argument, by +calling the \f3cpl_add_completion()\f1 function. If the callback +function wishes to provide filename completion in addition to its own +specific completions, it has the option of itself calling the builtin +file-name completion callback. This also, is documented in the +\f3cpl_complete_word(3)\f1 man page. +.sp +Note that if you would like \f3gl_get_line()\f1 to return the current +input line when a successful completion is been made, you can arrange +this when you call \f3cpl_add_completion()\f1, by making the last +character of the continuation suffix a newline character. If you do +this, the input line will be updated to display the completion, +together with any contiuation suffix up to the newline character, then +\f3gl_get_line()\f1 will return this input line. + +.SH FILENAME EXPANSION + +With the default key bindings, pressing \f3^X*\f1 causes +\f3gl_get_line()\f1 to expand the filename that precedes the cursor, +replacing \f3~/\f1 and \f3~user/\f1 expressions with the corresponding +home directories, and replacing \f3$envvar\f1 expressions with the +value of the specified environment variable, then if there are any +wildcards, replacing the so far expanded filename with a +space-separated list of the files which match the wild cards. +.sp +The expansion binding is implemented using the \f3ef_expand_file()\f1 function. +See the \f3ef_expand_file(3)\f1 man page for more details. + +.SH RECALLING PREVIOUSLY TYPED LINES + +Every time that a new line is entered by the user, it is appended to a +list of historical input lines maintained within the GetLine resource +object. You can traverse up and down this list using the up and down +arrow keys. Alternatively, you can do the same with the \f3^P\f1, and +\f3^N\f1 keys, and in vi command mode you can alternatively use the k +and j characters. Thus pressing up-arrow once, replaces the current +input line with the previously entered line. Pressing up-arrow again, +replaces this with the line that was entered before it, etc.. Having +gone back one or more lines into the history list, one can return to +newer lines by pressing down-arrow one or more times. If you do this +sufficient times, you will return to the original line that you were +entering when you first hit up-arrow. +.sp +Note that in vi mode, all of the history recall functions switch the +library into command mode. +.sp +In emacs mode the \f3M-p\f1 and \f3M-n\f1 keys work just like the +\f3^P\f1 and \f3^N\f1 keys, except that they skip all but those +historical lines which share the prefix that precedes the cursor. In +vi command mode the upper case \f3K\f1 and \f3J\f1 characters do the +same thing, except that the string that they search for includes the +character under the cursor as well as what precedes it. +.sp +Thus for example, suppose that you were in emacs mode, and you had +just entered the following list of commands in the order shown: + +.nf + ls ~/tecla/ + cd ~/tecla + ls -l getline.c + emacs ~/tecla/getline.c +.fi + +If you next typed: + +.nf + ls +.fi + +and then hit \f3M-p\f1, then rather than returning the previously +typed emacs line, which doesn't start with "ls", \f3gl_get_line()\f1 +would recall the "ls -l getline.c" line. Pressing \f3M-p\f1 again +would recall the "ls ~/tecla/" line. + +.SH HISTORY FILES + +To save the contents of the history buffer before quitting your +application, and subsequently restore them when you next start the +application, the following functions are provided. + +.sp +.nf + 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); +.fi +.sp + +The \f3filename\f1 argument specifies the name to give the history +file when saving, or the name of an existing history file, when +loading. This may contain home-directory and environment variable +expressions, such as "~/.myapp_history" or "$HOME/.myapp_history". +.sp +Along with each history line, extra information about it, such as when +it was entered by the user, and what its nesting level is, is recorded +as a comment preceding the line in the history file. Writing this as a +comment allows the history file to double as a command file, just in +case you wish to replay a whole session using it. Since comment +prefixes differ in different languages, the \f3comment\f1 argument is +provided for specifying the comment prefix. For example, if your +application were a unix shell, such as the bourne shell, you would +specify "#" here. Whatever you choose for the comment character, you +must specify the same prefix to \f3gl_load_history()\f1 that you used +when you called \f3gl_save_history()\f1 to write the history file. +.sp +The \f3max_lines\f1 must be either -1 to specify that all lines in the +history list be saved, or a positive number specifying a ceiling on +how many of the most recent lines should be saved. +.sp +Both fuctions return non-zero on error, after writing an error message +to stderr. Note that \f3gl_load_history()\f1 does not consider the +non-existence of a file to be an error. + +.SH MULTIPLE HISTORY LISTS + +If your application uses a single \f3GetLine\f1 object for entering +many different types of input lines, you may wish \f3gl_get_line()\f1 +to distinguish the different types of lines in the history list, and +only recall lines that match the current type of line. To support this +requirement, \f3gl_get_line()\f1 marks lines being recorded in the +history list with an integer identifier chosen by the application. +Initially this identifier is set to \f10\f3 by \f3new_GetLine()\f1, +but it can be changed subsequently by calling +\f3gl_group_history()\f1. + +.sp +.nf + int gl_group_history(GetLine *gl, unsigned id); +.fi +.sp + +The integer identifier \f3id\f1 can be any number chosen by the +application, but note that \f3gl_save_history()\f1 and +\f3gl_load_history()\f1 preserve the association between identifiers +and historical input lines between program invokations, so you should +choose fixed identifiers for the different types of input line used by +your application. +.sp +Whenever \f3gl_get_line()\f1 appends a new input line to the history +list, the current history identifier is recorded with it, and when it +is asked to recall a historical input line, it only recalls lines that +are marked with the current identifier. + +.SH DISPLAYING HISTORY + +The history list can be displayed by calling \f3gl_show_history()\f1. + +.sp +.nf + int gl_show_history(GetLine *gl, FILE *fp, + const char *fmt, + int all_groups, + int max_lines); +.fi +.sp + +This displays the current contents of the history list to the stdio +output stream \f3fp\f1. If the \f3max_lines\f1 argument is greater +than or equal to zero, then no more than this number of the most +recent lines will be displayed. If the \f3all_groups\f1 argument is +non-zero, lines from all history groups are displayed. Otherwise just +those of the currently selected history group are displayed. The +format string argument, \f3fmt\f1, determines how the line is +displayed. This can contain arbitrary characters which are written +verbatim, interleaved with any of the following format directives: + +.nf + %D - The date on which the line was originally + entered, formatted like 2001-11-20. + %T - The time of day when the line was entered, + formatted like 23:59:59. + %N - The sequential entry number of the line in + the history buffer. + %G - The number of the history group which the + line belongs to. + %% - A literal % character. + %H - The history line itself. +.fi + +Thus a format string like \f3"%D %T %H\n"\f1 would output something like: + +.nf + 2001-11-20 10:23:34 Hello world +.fi + +Note the inclusion of an explicit newline character in the format +string. + +.SH LOOKING UP HISTORY + +The \f3gl_lookup_history()\f1 function allows the calling application +to look up lines in the history list. + +.sp +.nf + typedef struct { + const char *line; /* The requested historical */ + /* 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; + + int gl_lookup_history(GetLine *gl, unsigned long id, + GlHistoryLine *hline); +.fi +.sp + +The \f3id\f1 argument indicates which line to look up, where the first +line that was entered in the history list after \f3new_GetLine()\f1 +was called, is denoted by 0, and subsequently entered lines are +denoted with successively higher numbers. Note that the range of lines +currently preserved in the history list can be queried by calling the +\f3gl_range_of_history()\f1 function, described later. If the +requested line is in the history list, the details of the line are +recorded in the variable pointed to by the \f3hline\f1 argument, and +\f31\f1 is returned. Otherwise \f30\f1 is returned, and the variable +pointed to by \f3hline\f1 is left unchanged. +.sp +Beware that the string returned in \f3hline->line\f1 is part of the +history buffer, so it must not be modified by the caller, and will be +recycled on the next call to any function that takes \f3gl\f1 as its +argument. Therefore you should make a private copy of this string if +you need to keep it around. + +.SH MISCELLANEOUS HISTORY CONFIGURATION + +If you wish to change the size of the history buffer that was +originally specified in the call to \f3new_GetLine()\f1, you can do so +with the \f3gl_resize_history()\f1 function. + +.sp +.nf + int gl_resize_history(GetLine *gl, size_t histlen); +.fi +.sp + +The \f3histlen\f1 argument specifies the new size in bytes, and if you +specify this as 0, the buffer will be deleted. +.sp +As mentioned in the discussion of \f3new_GetLine()\f1, the number of +lines that can be stored in the history buffer, depends on the lengths +of the individual lines. For example, a 1000 byte buffer could equally +store 10 lines of average length 100 bytes, or 2 lines of average +length 50 bytes. Although the buffer is never expanded when new lines +are added, a list of pointers into the buffer does get expanded when +needed to accomodate the number of lines currently stored in the +buffer. To place an upper limit on the number of lines in the buffer, +and thus a ceiling on the amount of memory used in this list, you can +call the \f3gl_limit_history()\f1 function. + +.sp +.nf + void gl_limit_history(GetLine *gl, int max_lines); +.fi +.sp + +The \f3max_lines\f1 should either be a positive number \f3>= 0\f1, +specifying an upper limit on the number of lines in the buffer, or be +\f3-1\f1 to cancel any previously specified limit. When a limit is in +effect, only the \f3max_lines\f1 most recently appended lines are kept +in the buffer. Older lines are discarded. +.sp +To discard lines from the history buffer, use the +\f3gl_clear_history()\f1 function. +.sp +.nf + void gl_clear_history(GetLine *gl, int all_groups); +.fi +.sp +The \f3all_groups\f1 argument tells the function whether to delete +just the lines associated with the current history group (see +\f3gl_group_history()\f1), or all historical lines in the buffer. +.sp +The \f3gl_toggle_history()\f1 function allows you to toggle history on +and off without losing the current contents of the history list. + +.sp +.nf + void gl_toggle_history(GetLine *gl, int enable); +.fi +.sp + +Setting the \f3enable\f1 argument to 0 turns off the history +mechanism, and setting it to 1 turns it back on. When history is +turned off, no new lines will be added to the history list, and +history lookup key-bindings will act as though there is nothing in the +history buffer. + +.SH QUERYING HISTORY INFORMATION + +The configured state of the history list can be queried with the +\f3gl_history_state()\f1 function. + +.sp +.nf + 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; + + void gl_state_of_history(GetLine *gl, + GlHistoryState *state); +.fi +.sp +On return, the status information is recorded in the variable pointed +to by the \f3state\f1 argument. +.sp +The \f3gl_range_of_history()\f1 function returns the number and +range of lines in the history list. + +.sp +.nf +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; + +void gl_range_of_history(GetLine *gl, GlHistoryRange *range); +.fi +.sp +The return values are recorded in the variable pointed to by the +\f3range\f1 argument. If the \f3nlines\f1 member of this structure is +greater than zero, then the \f3oldest\f1 and \f3newest\f1 members +report the range of lines in the list, and \f3newest=oldest+nlines-1\f1. +Otherwise they are both zero. +.sp +The \f3gl_size_of_history()\f1 function returns the total size of the +history buffer and the amount of the buffer that is currently +occupied. +.sp +.nf + 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; + + void gl_size_of_history(GetLine *gl, GlHistorySize *size); +.fi +.sp +On return, the size information is recorded in the variable pointed to +by the \f3size\f1 argument. + +.SH CHANGING TERMINALS + +The \f3new_GetLine()\f1 constructor function assumes that input is to +be read from \f3stdin\f1, and output written to \f3stdout\f1. The +following function allows you to switch to different input and output +streams. +.sp +.nf + int gl_change_terminal(GetLine *gl, FILE *input_fp, + FILE *output_fp, const char *term); +.fi +.sp +The \f3gl\f1 argument is the object that was returned by +\f3new_GetLine()\f1. The \f3input_fp\f1 argument specifies the stream +to read from, and \f3output_fp\f1 specifies the stream to be written +to. Only if both of these refer to a terminal, will interactive +terminal input be enabled. Otherwise \f3gl_get_line()\f1 will simply +call \f3fgets()\f1 to read command input. If both streams refer to a +terminal, then they must refer to the same terminal, and the type of +this terminal must be specified via the \f3term\f1 argument. The value +of the \f3term\f1 argument is looked up in the terminal information +database (terminfo or termcap), in order to determine which special +control sequences are needed to control various aspects of the +terminal. \f3new_GetLine()\f1 for example, passes the return value of +\f3getenv("TERM")\f1 in this argument. Note that if one or both of +\f3input_fp\f1 and \f3output_fp\f1 don't refer to a terminal, then it +is legal to pass \f3NULL\f1 instead of a terminal type. +.sp +Note that if you want to pass file descriptors to +\f3gl_change_terminal()\f1, you can do this by creating stdio stream +wrappers using the POSIX \f3fdopen()\f1 function. + +.SH EXTERNAL EVENT HANDLING + +While \f3gl_get_line()\f1 is waiting for keyboard input from the user, +you can ask it to also watch for activity on arbitrary file +descriptors, such as network sockets, pipes etc, and have it call +functions of your choosing when activity is seen. This works on any +system that has the \f3select()\f1 system call, which is most, if not +all flavors of unix. Registering a file descriptor to be watched by +\f3gl_get_line()\f1 involves calling the \f3gl_watch_fd()\f1 function. + +.sp +.nf + int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event, + GlFdEventFn *callback, void *data); +.fi +.sp + +If this returns non-zero, then it means that either your arguments are +invalid, or that this facility isn't supported on the host system. +.sp +The \f3fd\f1 argument is the file descriptor to be watched. The +\f3event\f1 argument specifies what type of activity is of interest, +chosen from the following enumerated values: + +.sp +.nf + GLFD_READ - Watch for the arrival of data to be read. + GLFD_WRITE - Watch for the ability to write to the file + descriptor without blocking. + GLFD_URGENT - Watch for the arrival of urgent + out-of-band data on the file descriptor. +.fi +.sp + +The \f3callback\f1 argument is the function to call when the selected +activity is seen. It should be defined with the following macro, which +is defined in libtecla.h. + +.sp +.nf + #define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, \\ + void *data, int fd, \\ + GlFdEvent event) +.fi +.sp +The \f3data\f1 argument of the \f3gl_watch_fd()\f1 function is passed +to the callback function for its own use, and can point to anything +you like, including \f3NULL\f1. The file descriptor and the event +argument are also passed to the callback function, and this +potentially allows the same callback function to be registered to more +than one type of event and/or more than one file descriptor. The +return value of the callback function should be one of the following +values. + +.sp +.nf + GLFD_ABORT - Tell gl_get_line() to abort with an + error (errno won't be set, so set it + appropriately yourself if you need it). + GLFD_REFRESH - Redraw the input line then continue + waiting for input. Return this if + your callback wrote to the terminal. + GLFD_CONTINUE - Continue to wait for input, without + redrawing the line. +.fi +.sp +Note that before calling the callback, \f3gl_get_line()\f1 blocks most +signals, and leaves its own signal handlers installed, so if you need +to catch a particular signal you will need to both temporarily install +your own signal handler, and unblock the signal. Be sure to re-block +the signal (if it was originally blocked) and reinstate the original +signal handler, if any, before returning. +.sp +Your callback shouldn't try to read from the terminal, which is left +in raw mode as far as input is concerned. You can however write to the +terminal as usual, since features like conversion of newline to +carriage-return/linefeed are re-enabled while the callback is +running. If your callback function does write to the terminal, be sure +to output a newline first, and when your callback returns, tell +\f3gl_get_line()\f1 that the input line needs to be redrawn, by +returning the \f3GLFD_REFRESH\f1 status code. +.sp +To remove a callback function that you previously registered for a +given file descriptor and event, simply call \f3gl_watch_fd()\f1 with +the same file descriptor and \f3event\f1 arguments, but with a +\f3callback\f1 argument of \f30\f1. The \f3data\f1 argument is ignored +in this case. + +.SH SIGNAL HANDLING DEFAULTS + +By default, the \f3gl_get_line()\f1 function intercepts a +number of signals. This is particularly important for +signals which would by default terminate the process, since +the terminal needs to be restored to a usable state before +this happens. In this section, the signals that are trapped +by default, and how gl_get_line() responds to them, is +described. Changing these defaults is the topic of the +following section. +.sp +When the following subset of signals are caught, \f3gl_get_line()\f1 +first restores the terminal settings and signal handling to how they +were before \f3gl_get_line()\f1 was called, resends the signal, to +allow the calling application's signal handlers to handle it, then if +the process still exists, \f3gl_get_line()\f1 returns \f3NULL\f1 and +sets \f3errno\f1 as specified below. + +.sp +.nf + SIGINT - This signal is generated both by the keyboard + interrupt key (usually ^C), and the keyboard + break key. + + errno=EINTR + + SIGHUP - This signal is generated when the controlling + terminal exits. + + errno=ENOTTY + + SIGPIPE - This signal is generated when a program attempts + to write to a pipe who's remote end isn't being + read by any process. This can happen for example + if you have called \f3gl_change_terminal()\f1 to + redirect output to a pipe hidden under a pseudo + terminal. + + errno=EPIPE + + SIGQUIT - This signal is generated by the keyboard quit + key (usually ^\\). + + errno=EINTR + + SIGABRT - This signal is generated by the standard C, + abort() function. By default it both + terminates the process and generates a core + dump. + + errno=EINTR + + SIGTERM - This is the default signal that the UN*X + kill command sends to processes. + + errno=EINTR +.fi +.sp +Note that in the case of all of the above signals, POSIX mandates that +by default the process is terminated, with the addition of a core dump +in the case of the \f3SIGQUIT\f1 signal. In other words, if the +calling application doesn't override the default handler by supplying +its own signal handler, receipt of the corresponding signal will +terminate the application before \f3gl_get_line()\f1 returns. +.sp +If gl_get_line() aborts with errno set to EINTR, you can find out what +signal caused it to abort, by calling the following function. +.sp +.nf + int gl_last_signal(const GetLine *gl); +.fi +.sp +This returns the numeric code (eg. \f3SIGINT\f1) of the last signal +that was received during the most recent call to \f3gl_get_line()\f1, +or \f3-1\f1 if no signals were received. +.sp +On systems that support it, when a SIGWINCH (window change) signal is +received, \f3gl_get_line()\f1 queries the terminal to find out its new +size, redraws the current input line to accomodate the new size, then +returns to waiting for keyboard input from the user. Unlike other +signals, this signal isn't resent to the application. +.sp +Finally, the following signals cause \f3gl_get_line()\f1 to first +restore the terminal and signal environment to that which prevailed +before \f3gl_get_line()\f1 was called, then resend the signal to the +application. If the process still exists after the signal has been +delivered, then \f3gl_get_line()\f1 then re-establishes its own signal +handlers, switches the terminal back to raw mode, redisplays the input +line, and goes back to awaiting terminal input from the user. +.sp +.nf + SIGCONT - This signal is generated when a suspended + process is resumed. + + SIGPWR - This signal is generated when a power failure + occurs (presumably when the system is on a + UPS). + + SIGALRM - This signal is generated when a timer + expires. + + SIGUSR1 - An application specific signal. + + SIGUSR2 - Another application specific signal. + + SIGVTALRM - This signal is generated when a virtual + timer expires (see man setitimer(2)). + + SIGXCPU - This signal is generated when a process + exceeds its soft CPU time limit. + + SIGTSTP - This signal is generated by the terminal + suspend key, which is usually ^Z, or the + delayed terminal suspend key, which is + usually ^Y. + + SIGTTIN - This signal is generated if the program + attempts to read from the terminal while the + program is running in the background. + + SIGTTOU - This signal is generated if the program + attempts to write to the terminal while the + program is running in the background. +.fi +.sp + +Obviously not all of the above signals are supported on all systems, +so code to support them is conditionally compiled into the tecla +library. +.sp +Note that if \f3SIGKILL\f1, which by definition can't be caught, or +any of the hardware generated exception signals, such as +\f3SIGSEGV\f1, \f3SIGBUS\f1 and \f3SIGFPE\f1, are received and +unhandled while \f3gl_get_line()\f1 has the terminal in raw mode, the +program will be terminated without the terminal having been restored +to a usable state. In practice, job-control shells usually reset the +terminal settings when a process relinquishes the controlling +terminal, so this is only a problem with older shells. + +.SH CUSTOMIZED SIGNAL HANDLING + +The previous section listed the signals that +\f3gl_get_line()\f1 traps by default, and described how it +responds to them. This section describes how to both add and +remove signals from the list of trapped signals, and how to +specify how \f3gl_get_line()\f1 should respond to a given +signal. +.sp +If you don't need \f3gl_get_line()\f1 to do anything in +response to a signal that it normally traps, you can tell to +\f3gl_get_line()\f1 to ignore that signal by calling +\f3gl_ignore_signal()\f1. +.sp +.nf + int gl_ignore_signal(GetLine *gl, int signo); +.fi +.sp +The \f3signo\f1 argument is the number of the signal +(eg. \f3SIGINT\f1) that you want to have ignored. If the +specified signal isn't currently one of those being trapped, +this function does nothing. +.sp +The \f3gl_trap_signal()\f1 function allows you to either add +a new signal to the list that \f3gl_get_line()\f1 traps, or +modify how it responds to a signal that it already traps. +.sp +.nf + int gl_trap_signal(GetLine *gl, int signo, unsigned flags, + GlAfterSignal after, int errno_value); +.fi +.sp +The \f3signo\f1 argument is the number of the signal that +you wish to have trapped. The \f3flags\f1 argument is a set +of flags which determine the environment in which the +application's signal handler is invoked, the \f3after\f1 +argument tells \f3gl_get_line()\f1 what to do after the +application's signal handler returns, and \f3errno_value\f1 +tells \f3gl_get_line()\f1 what to set \f3errno\f1 to if told +to abort. +.sp +The \f3flags\f1 argument is a bitwise OR of zero or more of +the following enumerators: +.sp +.nf + GLS_RESTORE_SIG - Restore the caller's signal + environment while handling the + signal. + + GLS_RESTORE_TTY - Restore the caller's terminal settings + while handling the signal. + + GLS_RESTORE_LINE - Move the cursor to the start of the + line following the input line before + invoking the application's signal + handler. + + GLS_REDRAW_LINE - Redraw the input line when the + application's signal handler returns. + + GLS_UNBLOCK_SIG - Normally, if the calling program has + a signal blocked (man sigprocmask), + gl_get_line() does not trap that + signal. This flag tells gl_get_line() + to trap the signal and unblock it for + the duration of the call to + gl_get_line(). + + GLS_DONT_FORWARD - If this flag is included, the signal + will not be forwarded to the signal + handler of the calling program. +.fi +.sp +Two commonly useful flag combinations are also enumerated as +follows: +.sp +.nf + GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | + GLS_REDRAW_LINE + + GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE +.fi +.sp + +If your signal handler, or the default system signal +handler for this signal, if you haven't overriden it, never +either writes to the terminal, nor suspends or terminates +the calling program, then you can safely set the \f3flags\f1 +argument to \f30\f1. +.sp +If your signal handler always writes to the terminal, reads +from it, or suspends or terminates the program, you should +specify the \f3flags\f1 argument as \f3GL_SUSPEND_INPUT\f1, +so that: +.sp +.nf +1. The cursor doesn't get left in the middle of the input + line. +2. So that the user can type in input and have it echoed. +3. So that you don't need to end each output line with + \f3\\r\\n\f1, instead of just \f3\\n\f1. +.fi +.sp +The \f3GL_RESTORE_ENV\f1 combination is the same as +\f3GL_SUSPEND_INPUT\f1, except that it doesn't move the +cursor, and if your signal handler doesn't read or write +anything to the terminal, the user won't see any visible +indication that a signal was caught. This can be useful if +you have a signal handler that only occasionally writes to +the terminal, where using \f3GL_SUSPEND_LINE\f1 would cause +the input line to be unnecessarily duplicated when nothing +had been written to the terminal. Such a signal handler, +when it does write to the terminal, should be sure to start +a new line at the start of its first write, by writing a +'\\n' character, and should be sure to leave the cursor on a +new line before returning. If the signal arrives while the +user is entering a line that only occupies a signal terminal +line, or if the cursor is on the last terminal line of a +longer input line, this will have the same effect as +\f3GL_SUSPEND_INPUT\f1. Otherwise it will start writing on a +line that already contains part of the displayed input line. +This doesn't do any harm, but it looks a bit ugly, which is +why the \f3GL_SUSPEND_INPUT\f1 combination is better if you +know that you are always going to be writting to the +terminal. +.sp +The \f3after\f1 argument, which determines what +\f3gl_get_line()\f1 does after the application's signal +handler returns (if it returns), can take any one of the +following values: +.sp +.nf + GLS_RETURN - Return the completed input line, just as + though the user had pressed the return + key. + + GLS_ABORT - Cause gl_get_line() to return \f3NULL\f1. + + GLS_CONTINUE - Resume command line editing. +.fi +.sp +The \f3errno_value\f1 argument is intended to be combined +with the \f3GLS_ABORT\f1 option, telling \f3gl_get_line()\f1 +what to set the standard \f3errno\f1 variable to before +returning \f3NULL\f1 to the calling program. It can also, +however, be used with the \f3GL_RETURN\f1 option, in case +you wish to have a way to distinguish between an input line +that was entered using the return key, and one that was +entered by the receipt of a signal. + +.SH THE TERMINAL SIZE + +On most systems the combination of the \f3TIOCGWINSZ\f1 ioctl and the +\f3SIGWINCH\f1 signal is used to maintain an accurate idea of the +terminal size. The terminal size is newly queried every time that +\f3gl_get_line()\f1 is called and whenever a \f3SIGWINCH\f1 signal is +received. +.sp +On the few systems where this mechanism isn't available, at +startup \f3new_GetLine()\f1 first looks for the \f3LINES\f1 +and \f3COLUMNS\f1 environment variables. If these aren't +found, or they contain unusable values, then if a terminal +information database like terminfo or termcap is available, +the default size of the terminal is looked up in this +database. If this too fails to provide the terminal size, a +default size of 80 columns by 24 lines is used. If this +default isn't appropriate for your system, +\f3gl_terminal_size()\f1 can be used to supply a different +fallback. +.sp +The \f3gl_terminal_size()\f1 function allows you to query +the current size of the terminal, and install an alternate +fallback size for cases where the size isn't available. +Beware that the terminal size won't be available if reading +from a pipe or a file, so the default values can be +important even on systems that do support ways of finding +out the terminal size. +.sp +.nf + typedef struct { + int nline; /* The terminal has nline lines */ + int ncolumn; /* The terminal has ncolumn columns */ + } GlTerminalSize; + + GlTerminalSize gl_terminal_size(GetLine *gl, + int def_ncolumn, + int def_nline); +.fi +.sp +This function first updates \f3gl_get_line()\f1's idea of +the terminal size, then records its findings in the return +value. +.sp +The \f3def_ncolumn\f1 and \f3def_nline\f1 specify the +default number of terminal columns and lines to use if the +terminal size can't be determined. + +.SH HIDING WHAT YOU TYPE + +When entering sensitive information, such as passwords, it is best not +to have the text that you are entering echoed on the terminal. +Furthermore, such text should not be recorded in the history list, +since somebody finding your terminal unattended could then recall it, +or somebody snooping through your directories could see it in your +history file. With this in mind, the \f3gl_echo_mode()\f1 +function allows you to toggle on and off the display and archival of +any text that is subsequently entered in calls to \f3gl_get_line()\f1. + +.sp +.nf + int gl_echo_mode(GetLine *gl, int enable); +.fi +.sp + +The \f3enable\f1 argument specifies whether entered text +should be visible or not. If it is \f30\f1, then +subsequently entered lines will not be visible on the +terminal, and will not be recorded in the history list. If +it is \f31\f1, then subsequent input lines will be displayed +as they are entered, and provided that history hasn't been +turned off via a call to \f3gl_toggle_history()\f1, then +they will also be archived in the history list. Finally, if +the \f3enable\f1 argument is \f3-1\f1, then the echoing mode +is left unchanged, which allows you to non-destructively +query the current setting via the return value. In all +cases, the return value of the function is \f30\f1 if +echoing was disabled before the function was called, and +\f31\f1 if it was enabled. +.sp +When echoing is turned off, note that although tab +completion will invisibly complete your prefix as far as +possible, ambiguous completions will not be displayed. + +.SH CALLBACK FUNCTION FACILITIES + +Unless otherwise stated, callback functions, such as tab +completion callbacks and event callbacks should not call any +functions in this module. The following functions, however, +are designed specifically to be used by callback functions. +.sp +Calling the \f3gl_replace_prompt()\f1 function from a +callback tells \f3gl_get_line() to display a different +prompt when the callback returns. It has no effect if called +when \f3gl_get_line()\f1 is not being called. +.sp +.nf + void gl_replace_prompt(GetLine *gl, const char *prompt); +.fi +.sp + +.SH INTERNATIONAL CHARACTER SETS + +Since libtecla version 1.4.0, \f3gl_get_line()\f1 has been 8-bit +clean. This means that all 8-bit characters that are printable in the +user's current locale are now displayed verbatim and included in the +returned input line. Assuming that the calling program correctly +contains a call like the following, +.sp +.nf + setlocale(LC_CTYPE, ""); +.fi +.sp +then the current locale is determined by the first of the environment +variables \f3LC_CTYPE\f1, \f3LC_ALL\f1, and \f3LANG\f1, that is found +to contain a valid locale name. If none of these variables are +defined, or the program neglects to call setlocale, then the default +\f3C\f1 locale is used, which is US 7-bit ASCII. On most unix-like +platforms, you can get a list of valid locales by typing the command: +.sp +.nf + locale -a +.fi +.sp +at the shell prompt. +.sp +.SS "Meta keys and locales" + +Beware that in most locales other than the default C locale, meta +characters become printable, and they are then no longer considered to +match \f3M-c\f1 style key bindings. This allows international +characters to be entered with the compose key without unexpectedly +triggering meta key bindings. You can still invoke meta bindings, +since there are actually two ways to do this. For example the binding +\f3M-c\f1 can also be invoked by pressing the escape key momentarily, +then pressing the \f3c\f1 key, and this will work regardless of +locale. Moreover, many modern terminal emulators, such as gnome's +gnome-terminal's and KDE's konsole terminals, already generate escape +pairs like this when you use the meta key, rather than a real meta +character, and other emulators usually have a way to request this +behavior, so you can continue to use the meta key on most systems. +.sp +For example, although xterm terminal emulators generate real 8-bit +meta characters by default when you use the meta key, they can be +configured to output the equivalent escape pair by setting their +\f3EightBitInput\f1 X resource to \f3False\f1. You can either do this +by placing a line like the following in your \f3~/.Xdefaults\f1 file, +.sp +.nf + XTerm*EightBitInput: False +.sp +.fi +or by starting an xterm with an \f3-xrm '*EightBitInput: False'\f1 +command-line argument. In recent versions of xterm you can toggle this +feature on and off with the \f3"Meta Sends Escape"\f1 option in the +menu that is displayed when you press the left mouse button and the +control key within an xterm window. In CDE, dtterms can be similarly +coerced to generate escape pairs in place of meta characters, by +setting the \f3Dtterm*KshMode\f1 resource to \f3True\f1. +.sp +.SS "Entering international characters" + +If you don't have a keyboard that generates all of the international +characters that you need, there is usually a compose key that will +allow you to enter special characters, or a way to create one. For +example, under X windows on unix-like systems, if your keyboard +doesn't have a compose key, you can designate a redundant key to serve +this purpose with the xmodmap command. For example, on many PC +keyboards there is a microsoft-windows key, which is otherwise useless +under Linux. On my PC the \f3xev\f1 program reports that pressing this +key generates keycode 115, so to turn this key into a compose key, I +do the following: +.sp +.nf + xmodmap -e 'keycode 115 = Multi_key' +.fi +.sp +I can then enter an i with a umlaut over it by typing this key, +followed by \f3"\f1, followed by i. + +.SH THREAD SAFETY + +In a multi-threaded program, you should use the libtecla_r.a version +of the library. This uses reentrant versions of system functions, +where available. Unfortunately neither terminfo nor termcap were +designed to be reentrant, so you can't safely use the functions of the +getline module in multiple threads (you can use the separate +file-expansion and word-completion modules in multiple threads, see +the corresponding man pages for details). However due to the use of +POSIX reentrant functions for looking up home directories etc, it is +safe to use this module from a single thread of a multi-threaded +program, provided that your other threads don't use any termcap or +terminfo functions. + +.SH FILES +.nf +libtecla.a - The tecla library +libtecla.h - The tecla header file. +~/.teclarc - The personal tecla customization file. +.fi + +.SH SEE ALSO +libtecla(3), ef_expand_file(3), cpl_complete_word(3), pca_lookup_file(3) + +.SH AUTHOR +Martin Shepherd (mcs@astro.caltech.edu) diff --git a/libtecla-1.4.1/man3/gl_group_history.3 b/libtecla-1.4.1/man3/gl_group_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_group_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_ignore_signal.3 b/libtecla-1.4.1/man3/gl_ignore_signal.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_ignore_signal.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_last_signal.3 b/libtecla-1.4.1/man3/gl_last_signal.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_last_signal.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_limit_history.3 b/libtecla-1.4.1/man3/gl_limit_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_limit_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_load_history.3 b/libtecla-1.4.1/man3/gl_load_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_load_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_lookup_history.3 b/libtecla-1.4.1/man3/gl_lookup_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_lookup_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_prompt_style.3 b/libtecla-1.4.1/man3/gl_prompt_style.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_prompt_style.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_range_of_history.3 b/libtecla-1.4.1/man3/gl_range_of_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_range_of_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_resize_history.3 b/libtecla-1.4.1/man3/gl_resize_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_resize_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_save_history.3 b/libtecla-1.4.1/man3/gl_save_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_save_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_show_history.3 b/libtecla-1.4.1/man3/gl_show_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_show_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_size_of_history.3 b/libtecla-1.4.1/man3/gl_size_of_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_size_of_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_state_of_history.3 b/libtecla-1.4.1/man3/gl_state_of_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_state_of_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_terminal_size.3 b/libtecla-1.4.1/man3/gl_terminal_size.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_terminal_size.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_toggle_history.3 b/libtecla-1.4.1/man3/gl_toggle_history.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_toggle_history.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_trap_signal.3 b/libtecla-1.4.1/man3/gl_trap_signal.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_trap_signal.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/gl_watch_fd.3 b/libtecla-1.4.1/man3/gl_watch_fd.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/gl_watch_fd.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/libtecla.3 b/libtecla-1.4.1/man3/libtecla.3 new file mode 100644 index 0000000..611eb57 --- /dev/null +++ b/libtecla-1.4.1/man3/libtecla.3 @@ -0,0 +1,160 @@ +.\" 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. +.TH libtecla 3 +.SH NAME +libtecla - An interactive command-line input library. +.SH SYNOPSIS +.nf +gcc ... -ltecla -lcurses +.fi + +.SH DESCRIPTION + +The \f3tecla\f1 library provides programs with interactive command +line editing facilities, similar to those of the unix \f3tcsh\f1 +shell. In addition to simple command-line editing, it supports recall +of previously entered command lines, TAB completion of file names or +other tokens, and in-line wild-card expansion of filenames. The +internal functions which perform file-name completion and wild-card +expansion are also available externally for optional use by the +calling program. +.sp +The various parts of the library are documented in the following man +pages: + +.nf + gl_get_line(3) - The interactive line-input module. + cpl_complete_word(3) - The word completion module. + ef_expand_file(3) - The filename expansion module. + pca_lookup_file(3) - A directory-list based filename + lookup and completion module. +.fi + +In addition there is one optional application distributed +with the library: + +.nf + enhance(3) - Add command-line editing to third + party applications. +.fi + +.SH THREAD SAFETY + +If the library is compiled with -D_POSIX_C_SOURCE=199506L, reentrant +versions of as many functions as possible are used. This includes +using getpwuid_r() and getpwnam_r() instead of getpwuid() and +getpwnam() when looking up the home directories of specific users in +the password file (for ~user/ expansion), and readdir_r() instead of +readdir() for reading directory entries when doing filename +completion. The reentrant version of the library is usually called +libtecla_r.a instead of libtecla.a, so if only the latter is +available, it probably isn't the correct version to link with +threaded programs. + +Reentrant functions for iterating through the password file aren't +available, so when the library is compiled to be reentrant, TAB +completion of incomplete usernames in \f3~username/\f1 expressions is +disabled. This doesn't disable expansion of complete \f3~username\f1 +expressions, which can be done reentrantly, or expansion of the parts +of filenames that follow them, so this doesn't remove much +functionality. + +The terminfo functions setupterm(), tigetstr(), tigetnum() and tputs() +also aren't reentrant, but very few programs will want to interact +with multiple terminals, so this shouldn't prevent this library from +being used in threaded programs. + +.SH LIBRARY VERSION NUMBER + +The version number of the library can be queried using the following +function. +.sp +.nf + void libtecla_version(int *major, int *minor, int *micro); +.fi +.sp + +On return, this function records the three components of the libtecla +version number in \f3*major\f1, \f3*minor\f1, \f3*micro\f1. The formal +meaning of the three components is as follows. + +.sp +.nf + major - Incrementing this number implies that a change has + been made to the library's public interface, which + makes it binary incompatible with programs that + were linked with previous shared versions of the + tecla library. + + minor - This number is incremented by one whenever + additional functionality, such as new functions or + modules, are added to the library. + + micro - This is incremented whenever modifications to the + library are made which make no changes to the + public interface, but which fix bugs and/or improve + the behind-the-scenes implementation. +.fi +.sp + +.SH TRIVIA + +In Spanish, a "tecla" is the key of a keyboard. Since this library +centers on keyboard input, and given that I wrote much of the library +while working in Chile, this seemed like a suitable name. + +.SH FILES +.nf +libtecla.a - The tecla library. +libtecla.h - The tecla header file. +~/.teclarc - The tecla personal customization file. +.fi + +.SH SEE ALSO +gl_get_line(3), ef_expand_file(3), cpl_complete_word(3), +pca_lookup_file(3), enhance(3) + +.SH AUTHOR +Martin Shepherd (mcs@astro.caltech.edu) + +.SH ACKNOWLEDGMENTS + +.nf +Markus Gyger - Lots of assistance, including help with + shared libraries, configuration information, + particularly for Solaris; modifications to + support C++ compilers, improvements for ksh + users, faster cursor motion, output + buffering, and changes to make gl_get_line() + 8-bit clean. +Mike MacFaden - Suggestions, feedback and testing that led + to many of the major new functions that were + added in version 1.4.0. +Tim Eliseo - Many vi-mode bindings and fixes. +.fi diff --git a/libtecla-1.4.1/man3/libtecla_version.3 b/libtecla-1.4.1/man3/libtecla_version.3 new file mode 100644 index 0000000..2c9c2c7 --- /dev/null +++ b/libtecla-1.4.1/man3/libtecla_version.3 @@ -0,0 +1 @@ +.so man3/libtecla.3 diff --git a/libtecla-1.4.1/man3/new_CplFileConf.3 b/libtecla-1.4.1/man3/new_CplFileConf.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/new_CplFileConf.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/new_ExpandFile.3 b/libtecla-1.4.1/man3/new_ExpandFile.3 new file mode 100644 index 0000000..f4299df --- /dev/null +++ b/libtecla-1.4.1/man3/new_ExpandFile.3 @@ -0,0 +1 @@ +.so man3/ef_expand_file.3 diff --git a/libtecla-1.4.1/man3/new_GetLine.3 b/libtecla-1.4.1/man3/new_GetLine.3 new file mode 100644 index 0000000..6bd3d1f --- /dev/null +++ b/libtecla-1.4.1/man3/new_GetLine.3 @@ -0,0 +1 @@ +.so man3/gl_get_line.3 diff --git a/libtecla-1.4.1/man3/new_PathCache.3 b/libtecla-1.4.1/man3/new_PathCache.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/new_PathCache.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/new_PcaPathConf.3 b/libtecla-1.4.1/man3/new_PcaPathConf.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/new_PcaPathConf.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/new_WordCompletion.3 b/libtecla-1.4.1/man3/new_WordCompletion.3 new file mode 100644 index 0000000..36c83a3 --- /dev/null +++ b/libtecla-1.4.1/man3/new_WordCompletion.3 @@ -0,0 +1 @@ +.so man3/cpl_complete_word.3 diff --git a/libtecla-1.4.1/man3/pca_last_error.3 b/libtecla-1.4.1/man3/pca_last_error.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/pca_last_error.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/pca_lookup_file.3 b/libtecla-1.4.1/man3/pca_lookup_file.3 new file mode 100644 index 0000000..131394a --- /dev/null +++ b/libtecla-1.4.1/man3/pca_lookup_file.3 @@ -0,0 +1,361 @@ +.\" Copyright (C) 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. +.TH pca_lookup_file 3 +.SH NAME +pca_lookup_file, del_PathCache, del_PcaPathConf, new_PathCache, new_PcaPathConf, pca_last_error, pca_path_completions, pca_scan_path, pca_set_check_fn, ppc_file_start, ppc_literal_escapes \- lookup a file in a list of directories +.SH SYNOPSIS +.nf +#include <libtecla.h> + +PathCache *new_PathCache(void); + +PathCache *del_PathCache(PathCache *pc); + +int pca_scan_path(PathCache *pc, const char *path); + +void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, + void *data); + +char *pca_lookup_file(PathCache *pc, const char *name, + int name_len, int literal); + +const char *pca_last_error(PathCache *pc); + +CPL_MATCH_FN(pca_path_completions); + +.fi + +.SH DESCRIPTION + +The \f3PathCache\f1 object is part of the tecla library (see the +libtecla(3) man page). +.sp +\f3PathCache\f1 objects allow an application to search for files in +any colon separated list of directories, such as the unix execution +PATH environment variable. Files in absolute directories are cached in +a \f3PathCache\f1 object, whereas relative directories are scanned as +needed. Using a \f3PathCache\f1 object, you can look up the full +pathname of a simple filename, or you can obtain a list of the +possible completions of a given filename prefix. By default all files +in the list of directories are targets for lookup and completion, but +a versatile mechanism is provided for only selecting specific types of +files. The obvious application of this facility is to provide +Tab-completion and lookup of executable commands in the unix PATH, so +an optional callback which rejects all but executable files, is +provided. +.sp +.SH AN EXAMPLE + +Under UNIX, the following example program looks up and displays the +full pathnames of each of the command names on the command line. +.sp +.nf + #include <stdio.h> + #include <stdlib.h> + #include <libtecla.h> + + int main(int argc, char *argv[]) + { + int i; + /* + * Create a cache for executable files. + */ + PathCache *pc = new_PathCache(); + if(!pc) + exit(1); + /* + * Scan the user's PATH for executables. + */ + if(pca_scan_path(pc, getenv("PATH"))) { + fprintf(stderr, "%s\\n", pca_last_error(pc)); + exit(1); + } + /* + * Arrange to only report executable files. + */ + pca_set_check_fn(pc, cpl_check_exe, NULL); + /* + * Lookup and display the full pathname of each of the + * commands listed on the command line. + */ + for(i=1; i<argc; i++) { + char *cmd = pca_lookup_file(pc, argv[i], -1, 0); + printf("The full pathname of '%s' is %s\\n", argv[i], + cmd ? cmd : "unknown"); + } + pc = del_PathCache(pc); /* Clean up */ + return 0; + } +.fi +.sp +The following is an example of what this does on my laptop under +linux: +.sp +.nf + $ ./example less more blob + The full pathname of 'less' is /usr/bin/less + The full pathname of 'more' is /bin/more + The full pathname of 'blob' is unknown + $ +.fi +.sp +.SH FUNCTION DESCRIPTIONS + +In order to use the facilities of this module, you must first allocate +a \f3PathCache\f1 object by calling the \f3new_PathCache()\f1 +constructor function. +.sp +.nf + PathCache *new_PathCache(void) +.fi +.sp +This function creates the resources needed to cache and lookup files +in a list of directories. It returns \f3NULL\f1 on error. +.sp +.SH POPULATING THE CACHE +Once you have created a cache, it needs to be populated with files. +To do this, call the \f3pca_scan_path()\f1 function. +.sp +.nf + int pca_scan_path(PathCache *pc, const char *path); +.fi +.sp +Whenever this function is called, it discards the current contents of +the cache, then scans the list of directories specified in its +\f3path\f1 argument for files. The \f3path\f1 argument must be a +string containing a colon-separated list of directories, such as +\f3"/usr/bin:/home/mcs/bin:."\f1. This can include directories +specified by absolute pathnames such as \f3"/usr/bin"\f1, as well as +sub-directories specified by relative pathnames such as \f3"."\f1 or +\f3"bin"\f1. Files in the absolute directories are immediately cached +in the specified \f3PathCache\f1 object, whereas sub-directories, +whose identities obviously change whenever the current working +directory is changed, are marked to be scanned on the fly whenever a +file is looked up. +.sp +On success this function return \f30\f1. On error it returns \f31\f1, +and a description of the error can be obtained by calling +\f3pca_last_error(pc)\f1. +.sp +.SH LOOKING UP FILES + +Once the cache has been populated with files, you can look up the full +pathname of a file, simply by specifying its filename to +\f3pca_lookup_file()\f1. +.sp +.nf + char *pca_lookup_file(PathCache *pc, const char *name, + int name_len, int literal); +.fi +.sp +To make it possible to pass this function a filename which is actually +part of a longer string, the \f3name_len\f1 argument can be used to +specify the length of the filename at the start of the \f3name[]\f1 +argument. If you pass \f3-1\f1 for this length, the length of the +string will be determined with \f3strlen()\f1. If the \f3name[]\f1 +string might contain backslashes that escape the special meanings of +spaces and tabs within the filename, give the \f3literal\f1 argument, +the value \f30\f1. Otherwise, if backslashes should be treated as +normal characters, pass \f31\f1 for the value of the \f3literal\f1 +argument. + +.SH FILENAME COMPLETION + +Looking up the potential completions of a filename-prefix in the +filename cache, is achieved by passing the provided +\f3pca_path_completions()\f1 callback function to the +\f3cpl_complete_word()\f1 function (see the \f3cpl_complete_word(3)\f1 +man page). +.sp +.nf + CPL_MATCH_FN(pca_path_completions); +.fi +.sp +This callback requires that its \f3data\f1 argument be a pointer to a +\f3PcaPathConf\f1 object. Configuration objects of this type are +allocated by calling \f3new_PcaPathConf()\f1. +.sp +.nf + PcaPathConf *new_PcaPathConf(PathCache *pc); +.fi +.sp +This function returns an object initialized with default configuration +parameters, which determine how the \f3cpl_path_completions()\f1 +callback function behaves. The functions which allow you to +individually change these parameters are discussed below. +.sp +By default, the \f3pca_path_completions()\f1 callback function +searches backwards for the start of the filename being completed, +looking for the first un-escaped space or the start of the input +line. If you wish to specify a different location, call +\f3ppc_file_start()\f1 with the index at which the filename starts in +the input line. Passing \f3start_index=-1\f1 re-enables the default +behavior. +.sp +.nf + void ppc_file_start(PcaPathConf *ppc, int start_index); +.fi +.sp +By default, when \f3pca_path_completions()\f1 looks at a filename in +the input line, each lone backslash in the input line is interpreted +as being a special character which removes any special significance of +the character which follows it, such as a space which should be taken +as part of the filename rather than delimiting the start of the +filename. These backslashes are thus ignored while looking for +completions, and subsequently added before spaces, tabs and literal +backslashes in the list of completions. To have unescaped backslashes +treated as normal characters, call \f3ppc_literal_escapes()\f1 with a +non-zero value in its \f3literal\f1 argument. +.sp +.nf + void ppc_literal_escapes(PcaPathConf *ppc, int literal); +.fi +.sp +When you have finished with a \f3PcaPathConf\f1 variable, you can pass +it to the \f3del_PcaPathConf()\f1 destructor function to reclaim its +memory. +.sp +.nf + PcaPathConf *del_PcaPathConf(PcaPathConf *ppc); +.fi +.sp + +.SH BEING SELECTIVE +If you are only interested in certain types or files, such as, for +example, executable files, or files whose names end in a particular +suffix, you can arrange for the file completion and lookup functions +to be selective in the filenames that they return. This is done by +registering a callback function with your \f3PathCache\f1 +object. Thereafter, whenever a filename is found which either matches +a filename being looked up, or matches a prefix which is being +completed, your callback function will be called with the full +pathname of the file, plus any application-specific data that you +provide, and if the callback returns \f31\f1 the filename will be +reported as a match, and if it returns \f30\f1, it will be ignored. +Suitable callback functions and their prototypes should be declared +with the following macro. The \f3CplCheckFn\f1 \f3typedef\f1 is also +provided in case you wish to declare pointers to such functions. +.sp +.nf + #define CPL_CHECK_FN(fn) int (fn)(void *data, \\ + const char *pathname) + typedef CPL_CHECK_FN(CplCheckFn); +.fi +.sp +Registering one of these functions involves calling the +\f3pca_set_check_fn()\f1 function. In addition to the callback +function, passed via the \f3check_fn\f1 argument, you can pass a +pointer to anything via the \f3data\f1 argument. This pointer will be +passed on to your callback function, via its own \f3data\f1 argument, +whenever it is called, so this provides a way to pass appplication +specific data to your callback. +.sp +.nf + void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, + void *data); +.fi +.sp +Note that these callbacks are passed the full pathname of each +matching file, so the decision about whether a file is of interest can +be based on any property of the file, not just its filename. As an +example, the provided \f3cpl_check_exe()\f1 callback function looks at +the executable permissions of the file and the permissions of its +parent directories, and only returns \f31\f1 if the user has execute +permission to the file. This callback function can thus be used to +lookup or complete command names found in the directories listed in +the user's \f3PATH\f1 environment variable. The example program given +earlier in this man page provides a demonstration of this. +.sp +Beware that if somebody tries to complete an empty string, your +callback will get called once for every file in the cache, which could +number in the thousands. If your callback does anything time +consuming, this could result in an unacceptable delay for the user, so +callbacks should be kept short. +.sp +To improve performance, whenever one of these callbacks is called, the +choice that it makes is cached, and the next time the corresponding +file is looked up, instead of calling the callback again, the cached +record of whether it was accepted or rejected is used. Thus if +somebody tries to complete an empty string, and hits tab a second time +when nothing appears to happen, there will only be one long delay, +since the second pass will operate entirely from the cached +dispositions of the files. These cached dipositions are discarded +whenever \f3pca_scan_path()\f1 is called, and whenever +\f3pca_set_check_fn()\f1 is called with changed callback function or +data arguments. + +.SH ERROR HANDLING + +If \f3pca_scan_path()\f1 reports that an error occurred by returning +\f31\f1, you can obtain a terse description of the error by calling +\f3pca_last_error(pc)\f1. This returns an internal string containing +an error message. +.sp +.nf + const char *pca_last_error(PathCache *pc); +.fi +.sp + +.SH CLEANING UP + +Once you have finished using a \f3PathCache\f1 object, you can reclaim +its resources by passing it to the \f3del_PathCache()\f1 destructor +function. This takes a pointer to one of these objects, and always +returns \f3NULL\f1. +.sp +.nf + PathCache *del_PathCache(PathCache *pc); +.fi +.sp +.SH THREAD SAFETY + +In multi-threaded programs, you should use the \f3libtecla_r.a\f1 +version of the library. This uses POSIX reentrant functions where +available (hence the \f3_r\f1 suffix), and disables features that rely +on non-reentrant system functions. In the case of this module, the +only disabled feature is username completion in \f3~username/\f1 +expressions, in \f3cpl_path_completions()\f1. + +Using the \f3libtecla_r.a\f1 version of the library, it is safe to use +the facilities of this module in multiple threads, provided that each +thread uses a separately allocated \f3PathCache\f1 object. In other +words, if two threads want to do path searching, they should each call +\f3new_PathCache()\f1 to allocate their own caches. + +.SH FILES +.nf +libtecla.a - The tecla library +libtecla.h - The tecla header file. +.fi + +.SH SEE ALSO +libtecla(3), gl_get_line(3), ef_expand_file(3), cpl_complete_word(3) + +.SH AUTHOR +Martin Shepherd (mcs@astro.caltech.edu) diff --git a/libtecla-1.4.1/man3/pca_path_completions.3 b/libtecla-1.4.1/man3/pca_path_completions.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/pca_path_completions.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/pca_scan_path.3 b/libtecla-1.4.1/man3/pca_scan_path.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/pca_scan_path.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/pca_set_check_fn.3 b/libtecla-1.4.1/man3/pca_set_check_fn.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/pca_set_check_fn.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/ppc_file_start.3 b/libtecla-1.4.1/man3/ppc_file_start.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/ppc_file_start.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 diff --git a/libtecla-1.4.1/man3/ppc_literal_escapes.3 b/libtecla-1.4.1/man3/ppc_literal_escapes.3 new file mode 100644 index 0000000..e5a136e --- /dev/null +++ b/libtecla-1.4.1/man3/ppc_literal_escapes.3 @@ -0,0 +1 @@ +.so man3/pca_lookup_file.3 |