summaryrefslogtreecommitdiffstats
path: root/libtecla-1.6.1/html
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2011-04-08 17:36:40 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2011-04-08 17:36:40 +0000
commit124da02af7a348eed58d7e3580d5176421171070 (patch)
tree8f2b8978157de21be5434e9ec5b4b5f87c46ef21 /libtecla-1.6.1/html
parent2011-04-08 Joel Sherrill <joel.sherrill@oarcorp.com> (diff)
downloadrtems-addon-packages-124da02af7a348eed58d7e3580d5176421171070.tar.bz2
2011-04-08 Joel Sherrill <joel.sherrill@oarcorp.com>
* bit: Update to libtecl-1.6.1 * libtecla-1.6.1/CHANGES, libtecla-1.6.1/INSTALL, libtecla-1.6.1/LICENSE.TERMS, libtecla-1.6.1/Makefile, libtecla-1.6.1/Makefile.in, libtecla-1.6.1/Makefile.rules, libtecla-1.6.1/Makefile.stub, libtecla-1.6.1/PORTING, libtecla-1.6.1/README, libtecla-1.6.1/RELEASE.NOTES, libtecla-1.6.1/chrqueue.c, libtecla-1.6.1/chrqueue.h, libtecla-1.6.1/config.guess, libtecla-1.6.1/config.sub, libtecla-1.6.1/configure, libtecla-1.6.1/configure.in, libtecla-1.6.1/cplfile.c, libtecla-1.6.1/cplfile.h, libtecla-1.6.1/cplmatch.c, libtecla-1.6.1/cplmatch.h, libtecla-1.6.1/demo.c, libtecla-1.6.1/demo2.c, libtecla-1.6.1/demo3.c, libtecla-1.6.1/direader.c, libtecla-1.6.1/direader.h, libtecla-1.6.1/enhance.c, libtecla-1.6.1/errmsg.c, libtecla-1.6.1/errmsg.h, libtecla-1.6.1/expand.c, libtecla-1.6.1/expand.h, libtecla-1.6.1/freelist.c, libtecla-1.6.1/freelist.h, libtecla-1.6.1/getline.c, libtecla-1.6.1/getline.h, libtecla-1.6.1/hash.c, libtecla-1.6.1/hash.h, libtecla-1.6.1/history.c, libtecla-1.6.1/history.h, libtecla-1.6.1/homedir.c, libtecla-1.6.1/homedir.h, libtecla-1.6.1/install-sh, libtecla-1.6.1/ioutil.c, libtecla-1.6.1/ioutil.h, libtecla-1.6.1/keytab.c, libtecla-1.6.1/keytab.h, libtecla-1.6.1/libtecla.h, libtecla-1.6.1/libtecla.map, libtecla-1.6.1/pathutil.c, libtecla-1.6.1/pathutil.h, libtecla-1.6.1/pcache.c, libtecla-1.6.1/stringrp.c, libtecla-1.6.1/stringrp.h, libtecla-1.6.1/strngmem.c, libtecla-1.6.1/strngmem.h, libtecla-1.6.1/update_html, libtecla-1.6.1/update_version, libtecla-1.6.1/version.c, libtecla-1.6.1/html/changes.html, libtecla-1.6.1/html/cpl_complete_word.html, libtecla-1.6.1/html/ef_expand_file.html, libtecla-1.6.1/html/enhance.html, libtecla-1.6.1/html/gl_get_line.html, libtecla-1.6.1/html/gl_io_mode.html, libtecla-1.6.1/html/index.html, libtecla-1.6.1/html/libtecla.html, libtecla-1.6.1/html/pca_lookup_file.html, libtecla-1.6.1/html/release.html, libtecla-1.6.1/html/tecla.html, libtecla-1.6.1/man/file/teclarc.in, libtecla-1.6.1/man/func/cfc_file_start.in, libtecla-1.6.1/man/func/cfc_literal_escapes.in, libtecla-1.6.1/man/func/cfc_set_check_fn.in, libtecla-1.6.1/man/func/cpl_add_completion.in, libtecla-1.6.1/man/func/cpl_complete_word.in, libtecla-1.6.1/man/func/cpl_file_completions.in, libtecla-1.6.1/man/func/cpl_last_error.in, libtecla-1.6.1/man/func/cpl_list_completions.in, libtecla-1.6.1/man/func/cpl_recall_matches.in, libtecla-1.6.1/man/func/cpl_record_error.in, libtecla-1.6.1/man/func/del_CplFileConf.in, libtecla-1.6.1/man/func/del_ExpandFile.in, libtecla-1.6.1/man/func/del_GetLine.in, libtecla-1.6.1/man/func/del_PathCache.in, libtecla-1.6.1/man/func/del_PcaPathConf.in, libtecla-1.6.1/man/func/del_WordCompletion.in, libtecla-1.6.1/man/func/ef_expand_file.in, libtecla-1.6.1/man/func/ef_last_error.in, libtecla-1.6.1/man/func/ef_list_expansions.in, libtecla-1.6.1/man/func/gl_abandon_line.in, libtecla-1.6.1/man/func/gl_bind_keyseq.in, libtecla-1.6.1/man/func/gl_catch_blocked.in, libtecla-1.6.1/man/func/gl_change_terminal.in, libtecla-1.6.1/man/func/gl_clear_history.in, libtecla-1.6.1/man/func/gl_completion_action.in, libtecla-1.6.1/man/func/gl_configure_getline.in, libtecla-1.6.1/man/func/gl_customize_completion.in, libtecla-1.6.1/man/func/gl_display_text.in, libtecla-1.6.1/man/func/gl_echo_mode.in, libtecla-1.6.1/man/func/gl_erase_terminal.in, libtecla-1.6.1/man/func/gl_error_message.in, libtecla-1.6.1/man/func/gl_get_line.in, libtecla-1.6.1/man/func/gl_group_history.in, libtecla-1.6.1/man/func/gl_handle_signal.in, libtecla-1.6.1/man/func/gl_ignore_signal.in, libtecla-1.6.1/man/func/gl_inactivity_timeout.in, libtecla-1.6.1/man/func/gl_io_mode.in, libtecla-1.6.1/man/func/gl_last_signal.in, libtecla-1.6.1/man/func/gl_limit_history.in, libtecla-1.6.1/man/func/gl_list_signals.in, libtecla-1.6.1/man/func/gl_load_history.in, libtecla-1.6.1/man/func/gl_lookup_history.in, libtecla-1.6.1/man/func/gl_normal_io.in, libtecla-1.6.1/man/func/gl_pending_io.in, libtecla-1.6.1/man/func/gl_prompt_style.in, libtecla-1.6.1/man/func/gl_query_char.in, libtecla-1.6.1/man/func/gl_range_of_history.in, libtecla-1.6.1/man/func/gl_raw_io.in, libtecla-1.6.1/man/func/gl_read_char.in, libtecla-1.6.1/man/func/gl_register_action.in, libtecla-1.6.1/man/func/gl_resize_history.in, libtecla-1.6.1/man/func/gl_return_status.in, libtecla-1.6.1/man/func/gl_save_history.in, libtecla-1.6.1/man/func/gl_set_term_size.in, libtecla-1.6.1/man/func/gl_show_history.in, libtecla-1.6.1/man/func/gl_size_of_history.in, libtecla-1.6.1/man/func/gl_state_of_history.in, libtecla-1.6.1/man/func/gl_terminal_size.in, libtecla-1.6.1/man/func/gl_toggle_history.in, libtecla-1.6.1/man/func/gl_trap_signal.in, libtecla-1.6.1/man/func/gl_tty_signals.in, libtecla-1.6.1/man/func/gl_watch_fd.in, libtecla-1.6.1/man/func/libtecla_version.in, libtecla-1.6.1/man/func/new_CplFileConf.in, libtecla-1.6.1/man/func/new_ExpandFile.in, libtecla-1.6.1/man/func/new_GetLine.in, libtecla-1.6.1/man/func/new_PathCache.in, libtecla-1.6.1/man/func/new_PcaPathConf.in, libtecla-1.6.1/man/func/new_WordCompletion.in, libtecla-1.6.1/man/func/pca_last_error.in, libtecla-1.6.1/man/func/pca_lookup_file.in, libtecla-1.6.1/man/func/pca_path_completions.in, libtecla-1.6.1/man/func/pca_scan_path.in, libtecla-1.6.1/man/func/pca_set_check_fn.in, libtecla-1.6.1/man/func/ppc_file_start.in, libtecla-1.6.1/man/func/ppc_literal_escapes.in, libtecla-1.6.1/man/libr/libtecla.in, libtecla-1.6.1/man/misc/tecla.in, libtecla-1.6.1/man/prog/enhance.in: New files. * libtecla-1.4.1/CHANGES, libtecla-1.4.1/INSTALL, libtecla-1.4.1/LICENSE.TERMS, libtecla-1.4.1/Makefile, libtecla-1.4.1/Makefile.in, libtecla-1.4.1/Makefile.rules, libtecla-1.4.1/Makefile.stub, libtecla-1.4.1/PORTING, libtecla-1.4.1/README, libtecla-1.4.1/RELEASE.NOTES, libtecla-1.4.1/config.guess, libtecla-1.4.1/config.sub, libtecla-1.4.1/configure, libtecla-1.4.1/configure.in, libtecla-1.4.1/cplfile.c, libtecla-1.4.1/cplfile.h, libtecla-1.4.1/cplmatch.c, libtecla-1.4.1/demo.c, libtecla-1.4.1/demo2.c, libtecla-1.4.1/direader.c, libtecla-1.4.1/direader.h, libtecla-1.4.1/enhance.c, libtecla-1.4.1/expand.c, libtecla-1.4.1/freelist.c, libtecla-1.4.1/freelist.h, libtecla-1.4.1/getline.c, libtecla-1.4.1/getline.h, libtecla-1.4.1/hash.c, libtecla-1.4.1/hash.h, libtecla-1.4.1/history.c, libtecla-1.4.1/history.h, libtecla-1.4.1/homedir.c, libtecla-1.4.1/homedir.h, libtecla-1.4.1/install-sh, libtecla-1.4.1/keytab.c, libtecla-1.4.1/keytab.h, libtecla-1.4.1/libtecla.h, libtecla-1.4.1/libtecla.map, libtecla-1.4.1/pathutil.c, libtecla-1.4.1/pathutil.h, libtecla-1.4.1/pcache.c, libtecla-1.4.1/stringrp.c, libtecla-1.4.1/stringrp.h, libtecla-1.4.1/strngmem.c, libtecla-1.4.1/strngmem.h, libtecla-1.4.1/update_html, libtecla-1.4.1/update_version, libtecla-1.4.1/version.c, libtecla-1.4.1/html/changes.html, libtecla-1.4.1/html/cpl_complete_word.html, libtecla-1.4.1/html/ef_expand_file.html, libtecla-1.4.1/html/enhance.html, libtecla-1.4.1/html/gl_get_line.html, libtecla-1.4.1/html/index.html, libtecla-1.4.1/html/libtecla.html, libtecla-1.4.1/html/pca_lookup_file.html, libtecla-1.4.1/html/release.html, libtecla-1.4.1/man3/cfc_file_start.3, libtecla-1.4.1/man3/cfc_literal_escapes.3, libtecla-1.4.1/man3/cfc_set_check_fn.3, libtecla-1.4.1/man3/cpl_add_completion.3, libtecla-1.4.1/man3/cpl_complete_word.3, libtecla-1.4.1/man3/cpl_file_completions.3, libtecla-1.4.1/man3/cpl_last_error.3, libtecla-1.4.1/man3/cpl_list_completions.3, libtecla-1.4.1/man3/cpl_record_error.3, libtecla-1.4.1/man3/del_CplFileConf.3, libtecla-1.4.1/man3/del_ExpandFile.3, libtecla-1.4.1/man3/del_GetLine.3, libtecla-1.4.1/man3/del_PathCache.3, libtecla-1.4.1/man3/del_PcaPathConf.3, libtecla-1.4.1/man3/del_WordCompletion.3, libtecla-1.4.1/man3/ef_expand_file.3, libtecla-1.4.1/man3/ef_last_error.3, libtecla-1.4.1/man3/ef_list_expansions.3, libtecla-1.4.1/man3/enhance.3, libtecla-1.4.1/man3/gl_change_terminal.3, libtecla-1.4.1/man3/gl_clear_history.3, libtecla-1.4.1/man3/gl_configure_getline.3, libtecla-1.4.1/man3/gl_customize_completion.3, libtecla-1.4.1/man3/gl_echo_mode.3, libtecla-1.4.1/man3/gl_get_line.3, libtecla-1.4.1/man3/gl_group_history.3, libtecla-1.4.1/man3/gl_ignore_signal.3, libtecla-1.4.1/man3/gl_last_signal.3, libtecla-1.4.1/man3/gl_limit_history.3, libtecla-1.4.1/man3/gl_load_history.3, libtecla-1.4.1/man3/gl_lookup_history.3, libtecla-1.4.1/man3/gl_prompt_style.3, libtecla-1.4.1/man3/gl_range_of_history.3, libtecla-1.4.1/man3/gl_resize_history.3, libtecla-1.4.1/man3/gl_save_history.3, libtecla-1.4.1/man3/gl_show_history.3, libtecla-1.4.1/man3/gl_size_of_history.3, libtecla-1.4.1/man3/gl_state_of_history.3, libtecla-1.4.1/man3/gl_terminal_size.3, libtecla-1.4.1/man3/gl_toggle_history.3, libtecla-1.4.1/man3/gl_trap_signal.3, libtecla-1.4.1/man3/gl_watch_fd.3, libtecla-1.4.1/man3/libtecla.3, libtecla-1.4.1/man3/libtecla_version.3, libtecla-1.4.1/man3/new_CplFileConf.3, libtecla-1.4.1/man3/new_ExpandFile.3, libtecla-1.4.1/man3/new_GetLine.3, libtecla-1.4.1/man3/new_PathCache.3, libtecla-1.4.1/man3/new_PcaPathConf.3, libtecla-1.4.1/man3/new_WordCompletion.3, libtecla-1.4.1/man3/pca_last_error.3, libtecla-1.4.1/man3/pca_lookup_file.3, libtecla-1.4.1/man3/pca_path_completions.3, libtecla-1.4.1/man3/pca_scan_path.3, libtecla-1.4.1/man3/pca_set_check_fn.3, libtecla-1.4.1/man3/ppc_file_start.3, libtecla-1.4.1/man3/ppc_literal_escapes.3: Removed.
Diffstat (limited to 'libtecla-1.6.1/html')
-rw-r--r--libtecla-1.6.1/html/changes.html2761
-rw-r--r--libtecla-1.6.1/html/cpl_complete_word.html382
-rw-r--r--libtecla-1.6.1/html/ef_expand_file.html213
-rw-r--r--libtecla-1.6.1/html/enhance.html75
-rw-r--r--libtecla-1.6.1/html/gl_get_line.html1996
-rw-r--r--libtecla-1.6.1/html/gl_io_mode.html509
-rw-r--r--libtecla-1.6.1/html/index.html122
-rw-r--r--libtecla-1.6.1/html/libtecla.html138
-rw-r--r--libtecla-1.6.1/html/pca_lookup_file.html312
-rw-r--r--libtecla-1.6.1/html/release.html590
-rw-r--r--libtecla-1.6.1/html/tecla.html1120
11 files changed, 8218 insertions, 0 deletions
diff --git a/libtecla-1.6.1/html/changes.html b/libtecla-1.6.1/html/changes.html
new file mode 100644
index 0000000..9be5251
--- /dev/null
+++ b/libtecla-1.6.1/html/changes.html
@@ -0,0 +1,2761 @@
+<html><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.
+
+31/10/2004 mcs@astro.caltech.edu (problem reported by Godfrey van der Linden)
+ getline.c
+ The gl_event_handler() function had the endif of a
+ conditional compilation clause in the wrong place. This
+ only upset the compiler on unusual systems that don't
+ have select(). The problem was seen under Mac OS X, due
+ to the configuration problem in 1.6.0 that caused the
+ configure script to mistakenly report that select wasn't
+ available.
+
+31/10/2004 mcs@astro.caltech.edu (info provided by Ivan Rayner)
+ configure.in configure Makefile.in
+ Ivan reported that under IRIX 6.5 it is necessary to add
+ -D_XOPEN_SOURCE=500 to the compiler flags, when compiling
+ the reentrant version of the library. Thus, whereas
+ previously I hardwired the value of DEFINES_R in
+ Makefile.in, I have now made this a variable in the
+ configure script, which is augmented with the above
+ addition, within an IRIX-specific switch clause.
+
+ Also apparently configure leaves the RANLIB variable
+ blank, instead of setting it to ":", so I have now
+ explicitly set this to ":", within the new IRIX clause of
+ the configure script.
+
+31/10/2004 mcs@astro.caltech.edu (info provided by Ivan Rayner)
+ getline.c
+ Under IRIX, the compiler warned that gl_read_unmasked()
+ was returning an int, which was then being assigned to an
+ enumeration type. This is techically fine, but it
+ highlighted the fact that I had meant to declare
+ gl_read_unmasked() to directly return the enumerated
+ type. I have now done so.
+
+26/09/2004 mcs@astro.caltech.edu
+ getline.c
+ Users can now turn off interactive command-line editing
+ by setting the TERM environment variable to the word "dumb".
+
+18/07/2004 mcs@astro.caltech.edu (problem noted by Michael MacFaden)
+ getline.c
+ Calling gl_terminal_size() on a system without support
+ for SIGWINCH caused a divide-by-zero error in an unintended
+ call to gl_erase_line(), because gl_update_size() was
+ incorrectly being called to query the terminal size,
+ instead of gl_query_size().
+
+18/07/2004 Padraig Brady (documented here by mcs@astro.caltech.edu)
+ getline.c
+ The suspend and termination signal-handlers installed by
+ gl_tty_signals(), were being installed swapped.
+
+03/06/2004 Mike Meaney (documented here by mcs@astro.caltech.edu)
+ getline.c
+ Mike pointed out the fact that the curses setupterm()
+ function is actually documented to exit the application
+ if an error occurs while its optional errret argument is
+ NULL. I hadn't noticed this, and because I didn't need
+ the extra information returned in the errret argument, I
+ was passing it a NULL. As suggested by Mike, I now pass
+ this argument a pointer to a dummy errret variable.
+
+23/05/2004 mcs@astro.caltech.edu (problem noted by John Beck)
+ man/func/cpl_complete_word.in
+ Some of the prototypes of functions and types documented
+ by the cpl_complete_word man page, weren't listed in the
+ Synopsis section of this man page. They are now listed
+ there.
+
+23/05/2004 mcs@astro.caltech.edu
+ getline.c man/func/gl_get_line.in
+ I have now added support for calling gl_normal_io() from
+ any callback functions that the application installs by
+ calling either gl_inactivity_timeout(), or gl_watch_fd().
+ Previously, if one of these callback functions called
+ gl_normal_io(), then after returning to gl_get_line(),
+ gl_get_line() would incorrectly assume that the terminal
+ was still in raw I/O mode. Now, gl_get_line() checks to
+ see if gl_normal_io() was called by the callback, and
+ if so, calls _gl_raw_io() to reinstate raw I/O mode.
+
+21/05/2004 mcs@astro.caltech.edu
+ configure.in configure
+ On Mac OS X the code that the configure script used to
+ check for select() failed due to missing symbols in
+ sys/select.h. Moving the inclusion of sys/select.h to
+ after the inclusion of sys/time.h, sys/types.h and
+ sys/unistd.h fixed this.
+
+11/05/2004 mcs@astro.caltech.edu
+ getline.c man/func/gl_get_line.in
+ If the line buffer returned by one call to gl_get_line()
+ was passed as the start_line argument of the next call to
+ gl_get_line(), then instead of the just-entered line
+ being presented back to the user for further editing, the
+ start_line argument was effectively ignored, because the
+ line buffer whose pointer was being passed back, was
+ being cleared before the start_line pointer was examined.
+ This appears to have been a case of me incorrectly
+ thinking that I had forgotten to initialize gl-&gt;line[]
+ and gl-&gt;ntotal in the gl_reset_input_line() function, and
+ then "fixing" this supposed omission. Removing this
+ erroneous fix, restored things to how they were meant to
+ be. To make it unlikely that I will make the same mistake
+ again, I have renamed the function from
+ gl_reset_input_line() to gl_reset_editor(), to stop it
+ looking as though it is meant to reset the contents of
+ the input line (that is what gl_truncate_buffer() is
+ for), explicitly stated that it doesn't clear the input
+ line, in the header comments of the function, and added a
+ prominent warning comment in the body of the function.
+
+ Also, since support for passing back the returned line
+ pointer via the start_line argument of the next call to
+ gl_get_line(), wasn't documented in the man page, but was
+ meant to be supported, and definitely used to work, I
+ have now amended the man page documentation of
+ gl_get_line() to explicitly state that this feature is
+ officially supported.
+
+2?/04/2004 Released 1.6.0
+
+22/04/2004 mcs@astro.caltech.edu (Fixed a bug reported by John Beck)
+ getline.c
+ When an error, signal, or other abnormal event aborted
+ gl_get_line(), the cleanup code that restored the
+ terminal to a sane state, also overwrote the value of
+ errno that was associated with the aborting event. An
+ I/O error occurring in the cleanup code would have also
+ overwritten the value to be returned by
+ gl_return_status(), and thus remove any possibility of
+ the caller finding out what really caused gl_get_line()
+ to abort. I have now written a new internal function
+ called, gl_record_status(), which records the completion
+ status to be returned by gl_return_status(), and the
+ value to assign to errno just before gl_get_line()
+ returns. This is called wherever code detects conditions
+ that require gl_get_line() to return early. The function
+ ensures that once an abnormal completion status has been
+ recorded for return, subsequent completions statuses
+ aren't recorded. This ensures that the caller sees the
+ original cause of the abnormal return, rather than any
+ error that occurs during cleaning up from this before
+ return.
+
+17/04/2004 mcs@astro.caltech.edu
+ getline.c
+ If an application's callback called gl_read_char() after
+ calling gl_normal_io(), it would inappropriately
+ redisplay the input line, when it called _gl_raw_io() to
+ temporarily switch the terminal back into raw mode.
+
+ To fix this, _gl_raw_io() now takes a new 'redisplay'
+ argument, which specifies whether or not to queue a
+ redisplay of the input line. I also created a new
+ gl-&gt;postpone flag, which is set by gl_normal_io(), and
+ cleared by _gl_raw_io() (when its redisplay argument is
+ true). When this flag is set, gl_flush_output() ignores
+ queued redisplays, as it generally should between calls
+ to gl_normal_io() and gl_raw_io(). Thus its effect is to
+ postpone redisplays while line editing is suspended.
+
+11/04/2004 mcs@astro.caltech.edu
+ history.c man/misc/tecla.in
+ History searches can now include the globbing operators
+ *, ?, []. When a search prefix is found to have at least
+ one of these characters, then only history lines that
+ completely match that pattern are returned.
+
+11/04/2004 mcs@astro.caltech.edu (issue raised by Mark Coiley)
+ getline.c ioutil.c
+ There appears to be a bug in Solaris's terminal I/O.
+ When the terminal file descriptor is placed in
+ non-blocking I/O mode, and the terminal is switched from
+ canonical to raw mode, characters that were previously
+ entered in canonical I/O mode don't become available to
+ be read until the user types one character more. Select()
+ incorrectly says that there are no characters available,
+ and read() returns EAGAIN. This is only a problem for
+ gl_get_line() when gl_get_line() is in non-blocking
+ server I/O mode, so most users won't have experienced any
+ problems with this.
+
+ The only way that I have found to get read() to return
+ the characters, without the user first having to type
+ another character, is to turn off non-blocking I/O before
+ calling read(). Select() still claims that there are no
+ characters available to be read, but read happily returns
+ them anyway. Fortunately, one can perform non-blocking
+ terminal reads without setting the non-blocking I/O flag
+ of the file descriptor, simply by setting the VTIME
+ terminal attribute to zero (which I already was
+ doing). Thus, when in non-blocking server I/O, I now turn
+ off the non-blocking I/O flag, attempt to read one
+ character and only if this fails, do I then call the
+ select() based event handler to implement any configured
+ non-zero timeout, before attempting the read again. Of
+ course the non-blocking I/O flag is still needed for
+ writing, so I only turn it off temporarily while reading.
+
+25/03/2004 mcs@astro.caltech.edu (bug reported by Gregory Harris)
+ Makefile.in
+ It appears that when in February, I patched Makefile.in
+ to add abolute paths to the install-sh shell-script,
+ I accidentally replaced install-sh with install.sh. I
+ corrected the name in the Makefile.
+
+25/03/2004 Gregory Harris (documented here by mcs)
+ configure.in configure
+ Greg added the configuration parameters needed to build
+ the shared version of the libtecla library under FreeBSD.
+
+25/03/2004 mcs@astro.caltech.edu
+ getline.c libtecla.h libtecla.map man/func/gl_get_line.in
+ man/func/gl_read_char.in
+ I wrote a public function called gl_read_char(). Unlike
+ gl_query_char(), this function neither prompts the user
+ for input, nor displays the character that was entered.
+ In fact it doesn't write anything to the terminal, and
+ takes pains not to disturb any incompletely entered
+ input line, and can safely be called from application
+ callback functions.
+
+21/03/2004 mcs@astro.caltech.edu
+ getline.c libtecla.h libtecla.map man/func/gl_get_line.in
+ man/func/gl_query_char.in
+ I wrote a public function called gl_query_char(), which
+ prompts the user and awaits a single-character reply,
+ without the user having to hit return.
+
+23/02/2004 mcs@astro.caltech.edu (bug reported by Gregory Harris)
+ configure.in configure getline.c enhance.c demo3.c
+ The configure script now checks for the sys/select.h
+ header file, and arranges for a C macro called
+ HAVE_SYS_SELECT_H to be set if it exists. Thus the files
+ that use select() now use this macro to conditionally
+ include sys/select.h where available. Apparently this
+ header is required under FreeBSD 5.1.
+
+23/02/2004 mcs@astro.caltech.edu
+ getline.c libtecla.h man/func/gl_get_line.in
+ I wrote two new public functions, gl_append_history() and
+ gl_automatic_history(). Together these allow the
+ application to take over the responsibility of adding
+ lines to the history list from gl_get_line(). I then
+ documented their functionality in the gl_get_line man
+ page.
+ Version 1.6.0
+ I incremented the minor version number of the library, to
+ comply with the requirement to do so when additions are
+ made to the public interface. See libtecla.map for
+ details.
+ libtecla.map
+ I added a new 1.6.0 group for the new minor version, and
+ added the above pair of functions to it.
+
+15/02/2004 mcs@astro.caltech.edu (fixes a bug reported by Satya Sahoo)
+ history.c
+ Calling gl_load_history() multiple times, eventually led
+ to a segmentation fault. This was due to the head of the
+ list of unused history string segments not getting
+ reset when the history buffer was cleared. While
+ debugging this problem I also noticed that the history
+ resizing function was way too complicated to verify, so
+ after fixing the above bug, I heavily simplified the
+ history resizing function, trading off a small reduction
+ in memory efficiency, for greatly improved clarity, and
+ thus made it much more verifiable and maintainable.
+
+14/02/2004 mcs@astro.caltech.edu (fixes a bug reported by Tim Burress).
+ getline.c
+ If gl_change_terminal() was first used to tell
+ gl_get_line to read input from a file, then called later
+ to tell it to read subsequent input from a terminal, no
+ prompt would be displayed for the first line of
+ interactive input. The problem was that on reaching the
+ end of the input file, gl_get_line() should have called
+ gl_abandon_line(), to tell the next call to gl_get_line()
+ to start inputting a new line from scratch. I have added
+ this now.
+
+14/02/2004 Krister Walfridsson (documented here by mcs@astro.caltech.edu)
+ Makefile.in
+ Krister noticed that I had failed to put $(srcdir)/ in front
+ of some invokations of install.sh. I have remedied this.
+ config.guess config.sub
+ I hadn't updated these for a long time, so apparently they
+ didn't recognise the BSD system that Krister was using.
+ I have now updated them to the versions that come with
+ autoconf-2.59.
+
+22/01/2004 mcs@astro.caltech.edu
+ keytab.c
+ When parsing key-binding specifications, backslash escaped
+ characters following ^ characters were not being expanded.
+ Thus ^\\ got interpretted as a control-\ character followed
+ by a \ character, rather than simply as a control-\
+ character.
+
+12/01/2004 mcs@astro.caltech.edu
+ cplfile.c cplmatch.c demo2.c demo3.c demo.c direader.c
+ expand.c getline.c history.c homedir.c pathutil.c pcache.c
+ configure.in configure INSTALL
+ The configuration script now takes a
+ "--without-file-system" argument. This is primarily for
+ intended for embedded systems that either don't have
+ filesystems, or where the file-system code in libtecla is
+ unwanted bloat. It sets the WITHOUT_FILE_SYSTEM
+ macro. This removes all code related to filesystem
+ access, including the entire public file-expansion,
+ file-completion and path-lookup facilities. Note that the
+ general word completion facility is still included, but
+ without the normally bundled file completion
+ callback. Actually the callback is still there, but it
+ reports no completions, regardless of what string you ask
+ it to complete.
+
+ This option is described in the INSTALL document.
+
+12/01/2004 mcs@astro.caltech.edu
+ getline.c configure.in configure INSTALL
+ The configuration script now takes a
+ "--without-file-actions" argument. This allows an
+ application author/installer to prevent users of
+ gl_get_line() from accessing the filesystem from the
+ builtin actions of gl_get_line(). It defines a macro
+ called HIDE_FILE_SYSTEM. This causes the
+ "expand-filename", "read-from-file", "read-init-files",
+ and "list-glob" action functions to be completely
+ removed. It also changes the default behavior of actions
+ such as "complete-word" and "list-or-eof" to show no
+ completions, instead of the normal default of showing
+ filename completions.
+
+ This option is described in the INSTALL document.
+
+11/01/2004 mcs@astro.caltech.edu
+ getline.c man/func/gl_get_line.in
+ In case an application's customized completion handler
+ needs to write to the terminal for some unforseen reason,
+ there needs to be a way for the it to cleanly suspend raw
+ line editing, before writing to the terminal, and the
+ caller then needs to be aware that it may need to
+ resurrect the input line when the callback returns. I
+ have now arranged that the completion callback functions
+ can call the gl_normal_io() function for this purpose,
+ and documented this in the gl_get_line() man page.
+
+11/01/2004 mcs@astro.caltech.edu (In response to a bug report by Satya Sahoo)
+ getline.c
+ The gl_configure_getline() function makes a malloc'd copy
+ of the names of the configuration files that it is asked
+ to read. Before the bug fix, if the application made one
+ or more calls to this function, the memory allocated by
+ the final call that it made before calling del_GetLine(),
+ wasn't being freed. Note that memory allocated in all but
+ the final call was being correctly freed, so the maximum
+ extent of the memory leak was the length of the file
+ name(s) passed in the final call to
+ gl_configure_getline(), and an application that didn't
+ call gl_configure_getline() didn't suffer any leak.
+
+20/12/2003 mcs@astro.caltech.edu
+ history.c
+ Ellen tested the history fix that I reported below, and
+ pointed out that it still had a problem. This turned out
+ to be because getline.c was making some incorrect
+ assumptions about the new behavior of history.c. This
+ problem and the previous one both revolved around how
+ search prefixes were stored and discarded, so I have now
+ re-written this part of the code. Previously the search
+ prefix was retained by looking for a line with that
+ prefix, and keeping a pointer to that line. This saved
+ memory, compared to storing a separate copy of the
+ prefix, but it led to all kinds of hairy
+ interdependencies, so I have now changed the code to keep
+ a separate copy of search prefixes. To keep the memory
+ requirements constant, the search prefix is stored in the
+ history buffer, like normal history lines, but not
+ referenced by the time-ordered history list. The prefix
+ can now be kept around indefinitely, until a new search
+ prefix is specified, regardless of changes to the
+ archived lines in the history buffer. This is actually
+ necessary to make the vi-mode re-search actions work
+ correctly. In particular, I no longer discard the search
+ prefix whenever a history search session ends. Also,
+ rather than have getline.c keep its own record of when a
+ history session is in progress, it now consults
+ history.c, so that failed assumptions can't cause the
+ kind of discrepancy that occurred before. For this to
+ work, getline.c now explicitly tells history.c to cancel
+ search sessions whenever it executes any non-history
+ action.
+
+14/12/2003 mcs@astro.caltech.edu (bug reported by Ellen Oschmann)
+ history.c
+ If one searched backwards for a prefix, then returned to
+ the original line, changed that line, then started
+ another backwards prefix search, getline incorrectly
+ discarded the new search prefix in the process of
+ throwing away its cached copy of the previous pre-search
+ input line. In other words getline was belatedly
+ cancelling a previous search, after a new search had
+ already partially begun, and thus messed up the new
+ search. The obvious fix was to arrange for the current
+ search to be cancelled whenever the history pointer
+ returns to its starting point, rather than waiting for
+ the next search to begin from there.
+
+14/12/2003 mcs@astro.caltech.edu
+ history.c
+ _glh_recall_line() was returning the last line in the
+ history buffer instead of the line requested by the
+ caller. This only affected the obscure "repeat-history"
+ action-function, which probably isn't used by anybody.
+
+09/12/2003 Version 1.5.0 released.
+
+28/09/2003 mcs@astro.caltech.edu
+ homedir.c
+ When the home directory of the login user is requested,
+ see if the HOME environment variable exists, and if so
+ return its value, rather than looking up the user's home
+ directory in the password file. This seems to be the
+ convention adopted by other unix programs that perform
+ tilde expansion, and it works around a strange problem,
+ where a third-party libtecla program, statically compiled
+ under an old version of RedHat, unexpectedly complained
+ that getpwd() returned an error when the program was run
+ under RedHat 9.
+
+01/09/2003 mcs@astro.caltech.edu
+ getline.c libtecla.h libtecla.map man/func/gl_get_line.in
+ man/func/gl_register_action.in.
+ It is now possible for an application to register
+ external functions as action functions. These actions are
+ initially bound to specified key-sequences, but if they
+ are registered before the user's configuration file is
+ loaded, they can also be re-bound by the user to
+ different key-sequences. The function used to register a
+ new action, is called gl_register_action(). Action
+ functions are passed a readonly copy of the input line
+ and the cursor position. They can display text to the
+ terminal, or perform other operations on the application
+ environment. Currently, they can't edit the input line or
+ move the cursor. This will require the future addition of
+ functions to queue the invokation of the built-in action
+ functions.
+
+26/08/2003 mcs@astro.caltech.edu
+ getline.c
+ I modified gl_update_buffer() to ensure that the cursor
+ stays within the input line after external line
+ modifications, and to queue a redisplay of the
+ potentially modified input line.
+
+21/07/2003 mcs@astro.caltech.edu
+ configure.in configure Makefile.in Makefile.stub INSTALL
+ By specifying --without-man-pages or --with-man-pages=no
+ as command-line arguments to the configure script, it is
+ now possible to have the configure script skip the
+ man-page preprocessing step, and arrange for the man-page
+ installation targets in the Makefile to do nothing. This
+ option is designed for people who embed libtecla within
+ other packages. It is also used by Makefile.stub when
+ the distclean target is specified.
+
+21/07/2003 mcs@astro.caltech.edu
+ configure.in configure
+ The previous workaround for recent versions of gcc
+ placing /usr/local/include at the start of the system
+ inlcude-file search path, broke something else. The fix
+ placed /usr/include before gcc's include area, which
+ meant that gcc's modified version of stdarg.h was being
+ ignored in deference to the version in /usr/include. I
+ have changed the fix to have gcc report the search path,
+ then have awk add options to CFLAGS to reorder this path,
+ plaing /usr/local/include at the end.
+
+ Also, under Solaris 9, including term.h without first
+ including curses.h results in complaints about undefined
+ symbols, such as bool. As a result the configure script's
+ test for term.h was failing. I have now modified it to
+ include curses.h in the test code that it uses to check
+ for term.h. In the process I also improved the tests for
+ curses.h and term.h to prevent an ncurses version of
+ term.h from being used with the system-default version of
+ curses.h.
+
+29/06/2003 mcs@astro.caltech.edu
+ Makefile.in direader.c homedir.c
+ On some systems (eg. linux) the _POSIX_C_SOURCE
+ feature-test macro is set by system headers, rather than
+ being an option set by a project's Makefile at
+ compilation time. In software, such as tecla, where the
+ definition of this macro is used as an indication of
+ whether to use the non-reentrant or reentrant versions of
+ system functions, this means that the reentrant functions
+ are always used, regardless of whether this macro is set
+ or not by the project Makefile. Thus, on such systems the
+ reentrant and non-reentrant versions of the tecla library
+ are essentially identical. This has a couple of
+ drawbacks. First, since thread-safe functions for
+ traversing the password file don't exist, the supposedly
+ non-reentrant version of the tecla library can't support
+ ambiguous tab-completion of usernames in ~username/
+ constructions. Secondly, on some systems the use of
+ reentrant system functions dictates the use of a shared
+ library that isn't needed for the non-reentrant
+ functions, thus making it more difficult to distribute
+ binary versions of the library.
+
+ To remedy this situation I have modified the DEFINES_R
+ variable in Makefile.in to arrange for the compiler to
+ define a C macro called PREFER_REENTRANT when it is
+ compiling the reentrant version of the tecla library.
+ This macro is now used in the source code to determine
+ when to require reentrant code. Whithin the source code,
+ wherever a potentially non-reentrant interface is used,
+ the existance of both this macro and a suitably valued
+ _POSIX_C_SOURCE macro, are tested for to see if a
+ reentrant alternative to the problem code should be used.
+
+22/06/2003 mcs@astro.caltech.edu
+ getline.c
+ I changed the way that redisplays are requested and
+ performed. Redisplays are now queued by calling
+ gl_queue_redisplay(), and subsequently performed by
+ gl_flush_output(), when the queue of already pending
+ output has been completely dispatched. This was necessary
+ to prevent event handlers from filling up the output
+ queue with redisplays, and it also simplifies a number of
+ things. In the process I removed the gl_queue_display()
+ function. I also wrote a gl_line_erased() function, which
+ is now called by all functions that erase the input
+ line. I also split the gl_abandon_line() function into
+ public and private callable parts, and used the private
+ version internally to arrange to discard the input line
+ after errors.
+
+ The raw_mode flag was not being initialized by new_GetLine().
+ It is now initialized to zero.
+
+ I removed the zapline flag, since using the endline flag to
+ communicate the desire to terminate the line, did the same
+ thing.
+
+ gl_terminal_move_cursor() now does nothing when the input
+ line isn't displayed.
+
+18/03/2003 mcs@astro.caltech.edu
+ getline.c
+ Fixed bug which was causing newlines not to be output
+ at the end of each newly entered line. I was
+ interpreting the gl-&gt;endline flag in conflicting ways in
+ two places. To fix this I have created a gl-&gt;displayed
+ flag. This flags whether an input line is currently
+ displayed.
+
+17/03/2003 mcs@astro.caltech.edu
+ getline.c libtecla.h man/func/gl_get_line.in
+ man/func/gl_erase_terminal.in libtecla.map
+ I added a new function that programs can call to clear
+ the terminal between calls to gl_get_line().
+
+11/03/2003 mcs@astro.caltech.edu
+ configure.in configure
+ Under linux when _POSIX_C_SOURCE is defined, getpwent()
+ and associated functions become undefined, because
+ _SVID_SOURCE and _BSD_SOURCE become undefined. Adding
+ these feature macros back to CFLAGS resolves this.
+
+06/03/2003 mcs@astro.caltech.edu
+ getline.c libtecla.map man/func/gl_get_line.in
+ Following the lead of Edward Chien, I wrote a function
+ called gl_bind_keyseq(), which binds a specified
+ key-sequence to a given action, or unbinds the
+ key-sequence.
+
+24/02/2003 mcs@astro.caltech.edu
+ getline.c libtecla.map man/func/cpl_complete_word.in
+ I implemented a simple function called
+ cpl_recall_matches(). This recalls the return value of
+ the last call to cpl_complete_word().
+
+19/01/2003 mcs@astro.caltech.edu
+ getline.c
+ The documented signal handling, fd event-handling,
+ inactivity timeout handling, and server-mode non-blocking
+ I/O features are now implemented for non-interactive
+ input streams, such as pipes and files.
+
+19/01/2003 mcs@astro.caltech.edu
+ getline.c libtecla.h man/func/gl_get_line.in demo3.c
+ I added a new return status enumerator to report
+ when an end-of-file condition causes gl_get_line()
+ to return NULL.
+
+13/01/2003 mcs@astro.caltech.edu
+ history.c
+ I rewrote the history facility. The previous
+ circular buffer implementation was a nightmare to change,
+ and it couldn't efficiently support certain newly
+ requested features. The new implementation stores history
+ lines in linked lists of fixed sized string segments,
+ taken from the buffer, with each line being reference
+ counted and recorded in a hash table. If the user enters
+ a line multiple times, only one copy of the line is now
+ stored. Not only does this make better use of the
+ available buffer space, but it also makes it easy to
+ ensure that a line whose prefix matches the current
+ search prefix, isn't returned more than once in sequence,
+ since we can simply see if the latest search result has
+ the same hash-table pointer as the previous one, rather
+ than having to compare strings. Another plus is that due
+ to the use of linked lists of nodes of fixed size line
+ segments, there is no longer any need to continually
+ shuffle the contents of the buffer in order to defragment
+ it. As far as the user is concerned, the visible
+ differences are as follows:
+
+ 1. If the user enters a given line multiple times in a
+ row, each one will be recorded in the history list,
+ and will thus be listed by gl_show_history(), and
+ saved in the history file. Previously only one line
+ was recorded when consecutive duplicates were entered.
+ This was a kludge to prevent history recall from
+ recalling the same line multiple times in a row. This
+ only achieved the desired result when not recalling by
+ prefix.
+
+ 2. Not only simple recall, but prefix-based history line
+ recalls now don't return the same line multiple times
+ in a row. As mentioned in (1) above, previously this
+ only worked when performing a simple recall, without a
+ search prefix.
+
+28/12/2002 mcs@astro.caltech.edu
+ getline.c
+ The one-line function, gl_buff_curpos_to_term_curpos()
+ was only being used by gl_place_cursor(), so I inlined it
+ in that function, and removed it.
+
+28/12/2002 mcs@astro.caltech.edu
+ getline.c
+ gl_suspend_process() was calling the application-level
+ gl_normal_io() and gl_raw_io() functions, where it should
+ have been calling the internal versions _gl_normal_io()
+ and _gl_raw_io().
+ Also gl_handle_signal() was masking and unmasking just
+ the signals of the first element of the gl[] array
+ argument. It now masks and unmasks all trappable signals.
+
+28/12/2002 mcs@astro.caltech.edu
+ getline.c
+ Now that the number of terminal characters used to
+ display the current input line, is recorded, the relative
+ line on which the last character of the input line
+ resides can be determined without having to call
+ gl_buff_curpos_to_term_curpos(). This is now used by
+ gl_normal_io() via gl_start_newline(), so there is now no
+ need for gl_buff_curpos_to_term_curpos() to be
+ async-signal safe. I have thus removed the annoying
+ gl-&gt;cwidth[] array, and gl_buff_curpos_to_term_curpos()
+ now calls gl_width_of_char() directly again. There is
+ also now no need for the gl_line_of_char_start() and
+ gl_line_of_char_end() functions, so I have removed them.
+
+28/12/2002 mcs@astro.caltech.edu
+ getline.c
+ Unfortunately it turns out that the terminfo/termcap
+ control sequence which is defined to delete everything
+ from the current position to the end of the terminal, is
+ only defined to work when at the start of a terminal
+ line. In gnome terminals in RedHat 8.0, if it is used
+ within a terminal line, it erases the whole terminal
+ line, rather than just what follows the cursor. Thus to
+ portably truncate the displayed input line it is
+ necessary to first use the control sequence which deletes
+ from the cursor position to the end of the line, then if
+ there are more terminal lines, move to the start of the
+ next line, and use the delete to end-of-terminal control
+ sequence, then restore the cursor position. This requires
+ that one know how many physical terminal lines are used
+ by the current input line, so I now keep a record of the
+ number of characters so far displayed to the terminal
+ following the start of the prompt, and the new
+ gl_truncate_display() function uses this information to
+ truncate the displayed input line from the current cursor
+ position.
+
+28/12/2002 mcs@astro.caltech.edu
+ getline.c
+ gl_start_newline() now moves to an empty line following
+ the input line, rather than just to the next line. It
+ also arranges for the input line to be redisplayed before
+ editing resumes. A major user of this is gl_print_info(),
+ which now need not be followed by an explicit call to
+ gl_redisplay(), since the terminal input loop in
+ gl_get_input_line() ensures that gl_redisplay() is called
+ after any action function that asserts gl-&gt;redisplay.
+ Also, all functions that erase the displayed input line
+ can now call the gl_erase_line() function, which is
+ designed to work correctly even when a terminal resize
+ invalidates the horizontal cursor position. Finally, the
+ new gl_queue_display() function is now used by functions
+ that need to arrange for the input line to be displayed
+ from scratch after the displayed line has been erased or
+ invalidated by other text being written to the terminal.
+ All of these changes are aimed at reducing the number of
+ places that directly modify gl-&gt;term_curpos and
+ gl-&gt;redisplay.
+
+22/12/2002 Markus Gyger (logged here by mcs)
+ Makefile.in update_html
+ In places where echo and sed were being used to extract
+ the base names of files, Markus substituted the basename
+ command. He also replaced explicit cp and chmod commands
+ with invokations of the install-sh script.
+ configure.in
+ Use $target_os and $target_cpu, where appropriate,
+ instead of $target.
+ configure.in
+ The Solaris man function and library man pages should
+ be in sections 3lib and 3tecla respectively, only in
+ Solaris version 2.8 and above.
+ configure.in
+ Markus provided values for the man page configuration
+ variables for HPUX.
+ man/*/*.in
+ I had missed parameterizing man page section numbers in
+ the man page titles, Markus corrected this.
+ man/func/libtecla_version.in
+ Fixed incorrect section number in the link to the
+ libtecla man page.
+ homedir.c
+ When compiled to be reentrant, although one can't use the
+ non-reentrant getpwent() function to scan the password
+ file for username completions, one can at least see if
+ the prefix being completed is a valid username, and if
+ the username of the current user minimally matches the
+ prefix, and if so list them. I simplified Markus'
+ modification by adding a prefix argument to the
+ _hd_scan_user_home_dirs() function, and redefining the
+ function description accordingly, such that now it
+ reports only those password file entries who's usernames
+ minimally match the specified prefix. Without this, it
+ would have been necessary to peak inside the private data
+ argument passed in by cf_complete_username().
+ Markus also provided code which under Solaris uses the
+ non-reentrant interfaces if the reentrant version of the
+ library isn't linked with the threads library.
+
+19/12/2002 mcs@astro.caltech.edu
+ Makefile.in
+ Markus pointed out that LDFLAGS was being picked up by
+ the configure script, but not then being interpolated
+ into te Makefile. I have thus added the necessary
+ assignment to Makefile.in and arranged for the value of
+ LDFLAGS to be passed on to recursive make's. I also did
+ the same for CPPFLAGS, which had also been omitted.
+
+18/12/2002 mcs@astro.caltech.edu
+ man/* man/*/* configure.in configure Makefile.in
+ update_html
+ It turns out that the assignment of man page sections to
+ topics differs somewhat from system to system, so this is
+ another thing that needs to be configured by the main
+ configuration script, rather than being hardwired. All
+ man pages have now been moved into suitably named
+ topic-specific sub-directories of the top-level man
+ directory, and instead of having a numeric suffix, now
+ have the .in suffix, since they are now preprocessed by
+ the configure script, in the same fashion as Makefile.in.
+ Whithin these *.in versions of the man pages, and within
+ Makefile.in, the installation subdirectory (eg. man1) and
+ the file-name suffix (eg. 1), are written using
+ configuration macros, so that they get expanded to the
+ appropriate tokens when the configure script is run. In
+ principle, the man pages could also take advantage of
+ other configuration macros, such as the one which expands
+ to the library installation directory, to include full
+ path names to installed files in the documentation, so in
+ the future this feature could have more uses than just
+ that of parameterizing man page sections.
+
+18/12/2002 mcs@astro.caltech.edu
+ man3 man3/* Makefile.in html/index.html update_html
+ Markus suggested splitting the gl_get_line(3) man page
+ into user and developer sections, and also pointed out
+ that the enhance man page should be in section 1, not
+ section 3. I have thus created a top-level man
+ directory in which to place the various sections, and
+ moved the man3 directory into it. The enhance.3 man page
+ is now in man/man1/enhance.1. I have extracted all
+ user-oriented sections from the gl_get_line(3) man page
+ and placed them in a new man7/tecla.7 man page.
+
+18/12/2002 mcs@astro.caltech.edu
+ getline.c
+ Terminal resizing was broken in normal mode, due to
+ me forcing the terminal cursor position to zero in the
+ wrong place in gl_check_caught_signal().
+
+14/12/2002 Markus Gyger (logged here by mcs)
+ configure.in configure
+ Under Solaris, recent versions of gcc search
+ /usr/local/include for header files before the system
+ directories. This caused a problem if ncurses was
+ installed under Solaris, since the termcap.h include file
+ in /usr/local/include ended up being used at compile
+ time, whereas the system default version of the curses
+ library was used at link time. Since the two libraries
+ declare tputs() differently, this evoked a complaint from
+ gcc. Markus came up with a way to force Gnu cpp to move
+ /usr/local/include to the end of the system-include-file
+ search path, where it belongs.
+
+13/12/2002 mcs@astro.caltech.edu
+ man3/gl_io_mode.3
+ I rewrote the man page which documents the new non-blocking
+ server I/O mode.
+
+12/12/2002 mcs@astro.caltech.edu
+ demo3.c
+ I wrote a new version of demo3.c, using signal handlers
+ that call gl_handle_signal() and gl_abandon_line(), where
+ previously in this demo, these functions were called from
+ the application code.
+
+05/12/2002 mcs@astro.caltech.edu
+ getline.c
+ gl_normal_io(), gl_raw_io() and gl_handle_signal() and
+ gl_abandon_line() are now signal safe, provided that
+ signal handlers that call them are installed with sa_mask's
+ that block all other signals who's handlers call them.
+ This is the case if gl_tty_signals() is used to install
+ signal handlers that call any of these functions.
+
+ A major stumbling block that had to be overcome was that
+ gl_displayed_char_width() calls isprint(), which can't
+ safely be called from a signal handler (eg. under linux,
+ the is*() functions all use thread-specific data
+ facilities to support per-thread locales, and the
+ thread-specific data facilities aren't signal safe). To
+ work around this, all functions that modify the
+ input-line buffer, now do so via accessor functions which
+ also maintain a parallel array of character widths, for
+ use by gl_buff_curpos_to_term_curpos() in place of
+ gl_displayed_char_width(). Other minor problems were the
+ need to avoid tputs(), who's signal safety isn't defined.
+
+05/12/2002 Eric Norum (logged here by mcs@astro.caltech.edu)
+ configure.in
+ Eric provided the configuration information needed
+ to build shared libraries under Darwin (Max OS X).
+
+05/12/2002 Richard Mlynarik (logged here by mcs@astro.caltech.edu)
+ configure.in
+ AC_PROG_RANLIB gets the wrong version of ranlib when
+ cross compiling, so has now been replaced by an
+ invokation of AC_CHECK_TOOL. In addition, AC_CHECK_TOOL
+ is also now used to find an appropriate version of LD.
+
+05/12/2002 mcs@astro.caltech.edu (based on patch by Pankaj Rathore)
+ getline.c libtecla.h libtecla.map man3/gl_get_line.3
+ The new gl_set_term_size() function provides a way
+ to tell gl_get_line() about changes in the size of
+ the terminal in cases where the values returned by
+ ioctl(TIOCGWINSZ) isn't correct.
+
+05/12/2002 mcs@astro.caltech.edu
+ getline.c
+ Rather than calling sprintf() to see how much space would
+ be needed to print a given number in octal, I wrote a
+ gl_octal_width() function, for use by
+ gl_displayed_char_width(). This makes the latter
+ function async signal safe.
+
+05/12/2002 mcs@astro.caltech.edu
+ chrqueue.c
+ Whenever the buffer is exhausted, and getting a new
+ buffer node would require a call to malloc(), attempt
+ to flush the buffer to the terminal. In blocking I/O
+ mode this means that the buffer never grows. In
+ non-blocking I/O mode, it just helps keep the buffer
+ size down.
+
+05/12/2002 mcs@astro.caltech.edu
+ freelist.h freelist.c
+ The new _idle_FreeListNodes() function queries the
+ number of nodes in the freelist which aren't currently
+ in use.
+
+05/12/2002 mcs@astro.caltech.edu
+ Makefile.stub
+ This now accepts all of the targets that the configured
+ makefile does, and after configuring the latter makefile,
+ it invokes it with the same options.
+
+03/12/2002 mcs@astro.caltech.edu
+ mans3/gl_io_mode.3
+ I completed the man page for all of the new functions
+ related to non-blocking I/O.
+
+01/12/2002 mcs@astro.caltech.edu
+ man3/gl_get_line.3
+ I wrote a long section on reliable signal handling,
+ explaining how gl_get_line() does this, how to make
+ use of this in a program, and how to handle signals
+ reliably when faced with other blocking functions.
+ This basically documents what I have learnt about
+ signal handling while working on this library.
+
+01/12/2002 mcs@astro.caltech.edu
+ getline.c man3/gl_get_line.3
+ In non-blocking server mode, the gl_replace_prompt()
+ function can now be used between calls to gl_get_line()
+ if the application wants to change the prompt of the
+ line that is being edited.
+
+01/12/2002 mcs@astro.caltech.edu
+ man3/gl_get_line.3
+ I documented the new gl_return_status() and
+ gl_error_message() functions.
+
+01/12/2002 mcs@astro.caltech.edu
+ getline.c man3/gl_get_line.3
+ Added SIGPOLL and SIGXFSZ to the list of signals that
+ are trapped by default. These are process termination
+ signals, so the terminal needs to be restored to a
+ usable state before they terminate the process.
+
+27/11/2002 mcs@astro.caltech.edu
+ getline.c libtecla.h
+ Completed the essential changes needed to support
+ non-blocking server-I/O mode.
+
+ The new gl_io_mode() function allows one to switch to
+ and from non-blocking server-I/O mode.
+
+ The new gl_raw_io() function is used in non-blocking
+ server-I/O mode to switch the terminal into non-blocking
+ raw I/O mode.
+
+ The new gl_normal_io() function is used in non-blocking
+ server-I/O mode to switch the restore the terminal to
+ a normal, blocking state. This is used to suspend line
+ input before suspending the process or writing messages
+ to the terminal.
+
+ The new gl_tty_signals() function installs specified
+ signals handlers for all signals that suspend, terminate
+ or resume processes, and also for signals that indicate
+ that the terminal has been resized. This not only saves
+ the application from having to keep its own ifdef'd list
+ of such signals, of which there are many, but it also
+ makes sure that these signal handlers are registered
+ correctly. This includes using the sa_mask member of each
+ sigaction structure to ensure that only one of these
+ handlers runs at a time. This is essential to avoid the
+ signal handlers all trying to simultaneously modify
+ shared global data.
+
+ The new gl_handle_signal() function is provided for
+ responding (from application level) to signals caught by
+ the application. It handles process suspension, process
+ termination and terminal resize signals.
+
+ The new gl_pending_io() function tells the application
+ what direction of I/O gl_get_line() is currently waiting
+ for.
+
+ In non-blocking server I/O mode, the new
+ gl_abandon_line() function can be called between calls to
+ gl_get_line() to discard an input line and force the next
+ call to gl_get_line() to start the input of a new line.
+
+ Also, in non-blocking server-I/O gl_get_line() doesn't
+ attempt to do anything but return when one of the signals
+ that it is configured to catch is caught. This is
+ necessary because when in this mode, the application is
+ required to handle these signals when gl_get_line() is
+ running, and the default configuration of most of these
+ signals in gl_get_line() is to restore the terminal then
+ call the application signal handlers. This would be a
+ case of too many cooks spoiling the broth, so in this
+ mode, gl_get_line() always defers to the application's
+ signal handlers.
+
+26/11/2002 mcs@astro.caltech.edu
+ getline.c libtecla.h
+ I implemented a couple of new functions to support
+ reliable signal handling, as now documented
+ (see above) in the gl_get_line(3) man page.
+
+ The new gl_catch_blocked() function tells gl_get_line()
+ to unblock all configured signals around calls to
+ long-running functions, not only those that aren't
+ blocked when gl_get_line() is called. This allows
+ the caller to implement reliable signal handling,
+ since the unblocking is only done from within code
+ protected by sigsetjmp(), which avoids race conditions.
+
+ The new gl_list_signals() function fills a provided
+ sigset_t with the set of signals that gl_get_line() is
+ currently configured to catch. This allows callers to
+ block said signals, such that they are only unblocked by
+ gl_get_line() when it is waiting for I/O. When used in
+ conjunction with the gl_catch_blocked() function, this
+ removes the potential for race conditions.
+
+ Also, when gl_get_line() installs its signal handler,
+ it uses the sa_mask member of the sigaction structure
+ to ensure that only one instance of this signal handler
+ will ever be executing at a time.
+
+25/11/2002 mcs@astro.caltech.edu (bug reported by Pankaj Rathore)
+ getline.c
+ When any history recall action was invoked when the
+ input line buffer was full, an error message would be
+ displayed complaining about the length of the string
+ in the line input buffer being inconsistent with the
+ specified allocated size. This was because instead of
+ sending the allocated size of the input line, I was
+ sending the length excluding the element that is
+ reserved for the '\0' terminator. Sending it the
+ correct size corrected the problem.
+
+24/11/2002 mcs@astro.caltech.edu
+ getline.c
+ All public functions which take GetLine objects as
+ arguments now block signals on entry and restore the
+ signal mask on return. This was an attempt to make it
+ safe to call getline functions from signal handlers, but
+ the fact is that the functions that I really wanted this
+ to apply to, potentially call malloc(), so this currently
+ isn't the case.
+
+23/11/2002 mcs@astro.caltech.edu
+ getline.c libtecla.h
+ The new gl_return_status() function returns an enumerated
+ return status which can be used to query what caused
+ gl_get_line() to return.
+
+22/11/2002 mcs@astro.caltech.edu
+ Most existing .c and .h files, plus errmsg.c errmsg.h
+ Makefile.rules
+ Until now, many library functions would report error
+ messages to stderr. This isn't appropriate for library
+ functions, so in place of this behavior, error messages
+ are now recorded in internal ErrMsg objects, and passed
+ between modules via new module-specific error querying
+ functions. In addition, errno is now set appropriately.
+ Thus when gl_get_line() and related functions return an
+ error, strerror() can be used to look up system errors,
+ and gl_error_message() can be used to recover a higher level
+ error message. Note that error messages that are
+ responses to user actions continue to be reported to the
+ terminal, as before.
+
+21/11/2002 mcs@astro.caltech.edu
+ getline.c keytab.h keytab.c Makefile.rules
+ I wrote a new version of _kt_lookup_binding() that didn't
+ require the caller to have access to the innards of a
+ KeyTab object. This then enabled me to move the definition
+ of KeyTab objects into keytab.c and make the typedef in
+ keytab.h opaque. Many nested includes were also moved from
+ keytab.h into keytab.c.
+
+05/11/2002 mcs@astro.caltech.edu
+ getline.c libtecla.map libtecla.h demo3.c
+ I split the old gl_resize_terminal() function into
+ two parts, gl_query_size() and gl_update_size(), with
+ the latter calling the former to get the new terminal
+ size.
+
+05/11/2002 mcs@astro.caltech.edu
+ getline.c
+ I fixed a long time bug in the terminal resizing code.
+ When the cursor wasn't on the last terminal line of the
+ input line, the resizing code would redisplay the
+ the line one or more lines above where it should be
+ restored. This was due to an error in the calculation of
+ the number of lines above the cursor position.
+
+04/11/2002 mcs@astro.caltech.edu
+ demo.c demo2.c demo3.c
+ I used the new gl_display_text() function to display
+ introductory text at the startup of each of the demo
+ programs. The text is enclosed within a box of asterixes,
+ drawn dynamically to fit within the confines of the
+ available terminal width.
+
+04/11/2002 mcs@astro.caltech.edu
+ libtecla.h getline.c ioutil.c ioutil.h Makefile.rules
+ libtecla.map man3/gl_get_line.3 man3/gl_display_text.3
+ Needing a way to display introductory text intelligently
+ in the demo programs, I wrote and documented the
+ gl_display_text() function. This justifies arbitrary
+ length text within the bounds of the terminal width,
+ with or without optional indentation, prefixes and
+ suffixes.
+
+03/11/2002 mcs@astro.caltech.edu
+ demo3.c Makefile.rules
+ I wrote a new demonstration program. This program acts
+ exactly like the main demonstration program, except that
+ it uses an external event loop instead of using the
+ gl_get_line() internal event loop. This is thus an example
+ of the new non-blocking server I/O facility.
+
+02/11/2002 mcs@astro.caltech.edu
+ getline.c keytab.c keytab.h libtecla.h man3/gl_get_line.3
+ man3/gl_completion_action.3
+ I added the ability to register additional word
+ completion actions via the new function
+ gl_completion_action(). All action functions now take a
+ new (void *data) argument, which is stored with the
+ function in the symbol table of actions. The new
+ gl_completion_action() function uses this feature to
+ record dynamically allocated objects containing the
+ specified completion function and callback data along
+ with either the gl_complete_word() action function, or
+ the gl_list_completions() action function. These two
+ actions continue to use the builtin completion functions
+ when their data pointer is NULL.
+
+20/10/2002 mcs@astro.caltech.edu
+ The following are changes merged from the non-blocking
+ gl_get_line() development branch.
+
+ getline.c
+ I wrote a gl_start_newline() function, to replace all of
+ the explicit calls to output \r\n to stdout.
+
+ Informational messages are now written to the terminal
+ using a new variadic function called gl_print_info().
+ This starts a newline, writes string arguments until a
+ special argument, GL_END_INFO, is seen, then starts
+ another newline.
+
+ Changed _output_ to _print_ in the following function
+ names gl_output_control_sequence(), gl_output_char(),
+ gl_output_string() and gl_output_raw_string().
+
+ gl_print_raw_string() now has a length argument, so that
+ strings that aren't terminated with '\0' can be printed.
+
+ The display of the initial contents of a new line to be
+ edited has been moved into a new function called
+ gl_present_line().
+
+ The gl_get_input_line() function now takes the prompt
+ string as an argument so that gl_replace_prompt() can be
+ called from within this function instead of from
+ gl_get_line().
+
+ Keyboard input is now buffered in a persistent buffer in
+ the parent GetLine object. gl_read_character() checks
+ this for unprocessed characters in preference to calling
+ gl_read_terminal() to append characters to it. A new
+ function, gl_discard_chars(), removes processed
+ characters from this buffer. This change is in
+ preparation for a non-blocking version of gl_get_line(),
+ where partially input key-sequences must be stored
+ between calls to gl_get_line().
+
+ getline.c getline.h history.c history.h cplmatch.c \
+ cplmatch.h expand.c expand.h
+ All terminal output from gl_get_line() is now routed
+ through a GL_WRITE_FN() callback function called
+ gl_write_fn. Internal functions in cplmatch.c,
+ expand.c and history.c have been created which take
+ such callbacks to write output. These are used both
+ by functions in getline.c, to display file completions,
+ expansions, history etc, and as the internals of existing
+ public functions in these files that print to stdio
+ streams. In the latter case an internal stdio
+ GL_WRITE_FN() callback is substituted, so that the
+ functions behave as before.
+
+ getline.c chrqueue.c chrqueue.h
+ The gl_write_fn() callback used by gl_get_line() now
+ writes to a queue, implemented in chrqueue.c. This queue
+ is implemented as a list of blocks of buffer segments,
+ the number of which shrink and grow as
+ needed. The contents of the queue are flushed to the
+ terminal via another GL_WRITE_FN() callback passed to the
+ queue object. Currently gl_get_line() passes an internal
+ function assigned to gl-&gt;flush_fn, called
+ gl_flush_terminal(), which writes the contents of the
+ queue to the terminal, and knows how to handle both
+ blocking and non-blocking I/O. The output queue is
+ designed to be flushed to the terminal incrementally, and
+ thereby also facilitates non-blocking I/O.
+
+ getline.c getline.h
+ gl_get_line() now reads all input via the GL_READ_FN()
+ callback, assigned to gl-&gt;read_fn. Currently this is
+ set to an internal function called gl_read_terminal(),
+ which knows how to handle both blocking and
+ non-blocking I/O.
+
+ getline.c libtecla.h
+ The new gl_set_nonblocking() function can be used to
+ enable or disable non-blocking I/O. The default is still
+ blocking I/O. In non-blocking mode, the terminal is told
+ not to wait when either reading or writing would block.
+ gl_get_line() then returns, with a return value of NULL,
+ but with the terminal left in raw mode, so that the
+ caller's event loop can detect key presses. The caller
+ should call gl_return_status() to check whether the NULL
+ return value was due to an error, lack of input, or
+ inability to write to the terminal without waiting. If
+ either reading or writing was said to have blocked, the
+ user then should check for I/O readiness in the specified
+ direction before calling gl_get_line() again to
+ incrementally build up the input line.
+
+05/08/2002 mcs@astro.caltech.edu
+ man3/gl_get_line.3 man3/gl_inactivity_timeout.3
+ I documented the new gl_inactivity_timeout() function.
+
+08/07/2002 mcs@astro.caltech.edu
+ libtecla.h getline.c libtecla.map
+ I added a new gl_inactivity_timeout() function. On
+ systems that have the select system call, this provides
+ the option of registering a function that is then called
+ whenever no I/O activity has been seen for more than a
+ specified period of time. Like the gl_watch_fd()
+ facility, timeout callbacks return a code which tells
+ gl_get_line() how to proceed after the timeout has been
+ handled.
+
+04/07/2002 mcs@astro.caltech.edu (based on a bug report from Michael MacFaden)
+ getline.c
+ The internal event handler wasn't responding to write
+ events on client file descriptors, due to a typo which
+ resulted in read events being checked for twice, and
+ writes not checked for at all.
+ pathutil.c
+ The amount of space to allocate for pathnames is supposed
+ to come from PATH_MAX in limits.h, but I had neglected to
+ include limits.h. This went unnoticed because on most
+ systems the equivalent number is deduced by calling
+ pathconf(). Apparently under NetBSD this function doesn't
+ work correctly over NFS mounts.
+
+30/05/2002 Version 1.4.1 released.
+
+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.
+
+07/05/2002 mcs@astro.caltech.edu (async development branch only)
+ getline.c
+ gl_read_character() now caches and reads unprocessed
+ characters from a key-press lookahead buffer. Whenever
+ gl_intepret_char() receives a new character which makes
+ an initially promising key-sequence no longer match the
+ prefix of any binding, it now simply discards the first
+ character from the key-press buffer and resets the buffer
+ pointer so that the next call to gl_read_character()
+ returns the character that followed it, from the buffer.
+ getline.c
+ The part of gl_get_input_line() which preloads, displays
+ and prepares to edit a new input line, has now been moved
+ into a function called gl_present_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 &gt; 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 &gt; 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 &gt; 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-&gt;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-&gt;number until after calling an action
+ function. By looking at whether gl-&gt;number is &lt;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 &lt; where it needed a &gt;. 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-&gt;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-&gt;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-&gt;file instead of exp-&gt;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/&lt;many-new-files&gt;.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-&lt; 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-&lt; and M-&gt; 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-&lt;. 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></html>
diff --git a/libtecla-1.6.1/html/cpl_complete_word.html b/libtecla-1.6.1/html/cpl_complete_word.html
new file mode 100644
index 0000000..0c976c0
--- /dev/null
+++ b/libtecla-1.6.1/html/cpl_complete_word.html
@@ -0,0 +1,382 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="cpl_complete_word.html"><b>cpl_complete_word</b></a> <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>
+
+
+
+</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_recall_matches,
+ cpl_record_error, del_CplFileConf, del_WordCompletion, new_CplFileConf,
+ new_WordCompletion - lookup possible completions for a word
+
+</pre><h2>SYNOPSIS</h2><pre>
+ #include &lt;stdio.h&gt;
+ #include &lt;libtecla.h&gt;
+
+ 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);
+
+ CplMatches *cpl_recall_matches(WordCompletion *cpl);
+
+ 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);
+
+
+ #define CPL_CHECK_FN(fn) int (fn)(void *data, \
+ const char *pathname)
+
+ typedef CPL_CHECK_FN(CplCheckFn);
+
+ CPL_CHECK_FN(cpl_check_exe);
+
+ CplFileConf *new_CplFileConf(void);
+
+ CplFileConf *del_CplFileConf(CplFileConf *cfc);
+
+ void cfc_literal_escapes(CplFileConf *cfc, int literal);
+
+ void cfc_file_start(CplFileConf *cfc, int start_index);
+
+ void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
+ void *chk_data);
+
+
+
+</pre><h2>DESCRIPTION</h2><pre>
+ The cpl_complete_word() function is part of the tecla library (see the
+ <a href="libtecla.html"><b>libtecla</b></a> man page). It is usually called behind the
+ scenes by <a href="gl_get_line.html"><b>gl_get_line</b></a>, but can also be called sepa-
+ rately.
+
+ Given an input line containing an incomplete word to be completed, it
+ calls a user-provided callback function (or the provided file-comple-
+ tion 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 cpl_add_comple-
+ tion().
+
+
+ Descriptions of the functions of this module are as follows:
+
+ WordCompletion *new_WordCompletion(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().
+
+ WordCompletion *del_WordCompletion(WordCompletion *cpl)
+
+ This function deletes the resources that were returned by a previous
+ call to new_WordCompletion(). 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 func-
+ tion. In particular, the line argument contains the input line contain-
+ ing the word to be completed, and word_end is the index of the charac-
+ ter 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 com-
+ pletion function looks backwards until it hits an unescaped space, or
+ the start of the line. Having found the start of the word, the call-
+ back 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 call-
+ ing cpl_record_error().
+
+ void cpl_record_error(WordCompletion *cpl,
+ const char *errmsg);
+
+ The last error message recorded by calling cpl_record_error(), can sub-
+ sequently 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
+ 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 cpl_add_completion() returns.
+
+ Note that in the array of possible completions which the cpl_com-
+ plete_word() function returns, the suffix recorded by cpl_add_comple-
+ tion() 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 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 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_com-
+ plete_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 completion. This is some-
+ thing 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 separa-
+ tor 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"><b>gl_get_line</b></a>, but can also be called separately if you
+ separately allocate a WordCompletion object. It performs word comple-
+ tion, as described at the beginning of this section. Its first argument
+ is a resource object previously returned by new_WordCompletion(). The
+ line argument is the input line string, containing the word to be com-
+ pleted. 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 function.
+
+ If no errors occur, the cpl_complete_word() function returns a pointer
+ to a CplMatches container, as defined below. This container is allo-
+ cated 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_com-
+ pletion().
+
+ CplMatches *cpl_recall_matches(WordCompletion *cpl);
+
+ As a convenience, the return value of the last call to cpl_com-
+ plete_word() can be recalled at a later time by calling
+ cpl_recall_matches(). If cpl_complete_word() returned NULL, so will
+ cpl_recall_matches().
+
+ int cpl_list_completions(CplMatches *result, FILE *fp,
+ int terminal_width);
+
+ When the cpl_complete_word() function returns multiple possible comple-
+ tions, 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"><b>gl_get_line</b></a> function, passes the follow-
+ ing completion callback function to cpl_complete_word(). This function
+ can also be used separately, either by sending it to cpl_com-
+ plete_word(), or by calling it directly from your own completion call-
+ back 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. Otherwise it should be a pointer to a CplFile-
+ Conf object, previously 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 back-
+ wards 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 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 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.
+
+ #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 file-
+ name that it is given represents a normal file that the user has exe-
+ cute permission to. You could use this to have cpl_file_completions()
+ only list completions 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 completion in ~username/ expressions, in cpl_file_comple-
+ tions().
+
+ Using the libtecla_r.a 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 WordCompletion 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"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
+ <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/ef_expand_file.html b/libtecla-1.6.1/html/ef_expand_file.html
new file mode 100644
index 0000000..c780cf6
--- /dev/null
+++ b/libtecla-1.6.1/html/ef_expand_file.html
@@ -0,0 +1,213 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="ef_expand_file.html"><b>ef_expand_file</b></a> <a href="ef_expand_file.html"><b>ef_expand_file</b></a>
+
+
+
+</pre><h2>NAME</h2><pre>
+ ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions,
+ new_ExpandFile - expand filenames containing ~user/$envvar and wildcard
+ expressions
+
+</pre><h2>SYNOPSIS</h2><pre>
+ #include &lt;libtecla.h&gt;
+
+ 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"><b>libtecla</b></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. Other-
+ wise, 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 &lt;stdio.h&gt;
+ #include &lt;libtecla.h&gt;
+
+ 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&lt;expn-&gt;nfile; i++)
+ printf(" %s\n", expn-&gt;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() func-
+ tion. 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 num-
+ ber 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 docu-
+ mented at the start of this section. Its first argument 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 wildcards, then the contained files[] array will contain
+ the names of the nfile existing files that matched the wildcarded file-
+ name, 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 (Expand-
+ File *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 com-
+ mand, 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 speci-
+ fied 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 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, provided that each
+ thread uses a separately allocated ExpandFile object. In other words,
+ if two threads want to do file expansion, they should each call
+ new_ExpandFile() to allocate 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"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>,
+ <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="ef_expand_file.html"><b>ef_expand_file</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/enhance.html b/libtecla-1.6.1/html/enhance.html
new file mode 100644
index 0000000..62b4e2f
--- /dev/null
+++ b/libtecla-1.6.1/html/enhance.html
@@ -0,0 +1,75 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="enhance.html"><b>enhance</b></a> <a href="enhance.html"><b>enhance</b></a>
+
+
+
+</pre><h2>NAME</h2><pre>
+ enhance - A program that adds command-line editing to third party pro-
+ grams.
+
+</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 terminal. It uses the tecla command-line edit-
+ ing 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.
+
+ 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 impercep-
+ tible to the user, isn't necessary for correct operation of the pro-
+ gram. It is just an optimization, designed to stop the input line from
+ being redisplayed so often that it slows down output.
+
+ Note that the user-level command-line editing facilities provided by
+ the Tecla library are documented in the <a href="tecla.html"><b>tecla</b></a> man page
+
+
+</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 con-
+ trolling 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 knowing
+ that this has happened, and continues to echo typed input to its con-
+ trolling 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 pro-
+ gram that switches to noecho mode explicitly restores echoing after-
+ wards, 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.
+
+
+</pre><h2>FILES</h2><pre>
+ libtecla.a - The tecla library.
+ ~/.teclarc - The tecla personal customization file.
+
+
+</pre><h2>SEE ALSO</h2><pre>
+ <a href="tecla.html"><b>tecla</b></a>, <a href="libtecla.html"><b>libtecla</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="enhance.html"><b>enhance</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/gl_get_line.html b/libtecla-1.6.1/html/gl_get_line.html
new file mode 100644
index 0000000..3df39d6
--- /dev/null
+++ b/libtecla-1.6.1/html/gl_get_line.html
@@ -0,0 +1,1996 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="gl_get_line.html"><b>gl_get_line</b></a> <a href="gl_get_line.html"><b>gl_get_line</b></a>
+
+
+
+</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_his-
+ tory, gl_group_history, gl_show_history, gl_watch_fd, gl_inactiv-
+ ity_timeout, gl_terminal_size, gl_set_term_size, gl_resize_history,
+ gl_limit_history, gl_clear_history, gl_toggle_history, gl_lookup_his-
+ tory, 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, gl_completion_action, gl_display_text,
+ gl_return_status, gl_error_message, gl_catch_blocked, gl_list_signals,
+ gl_bind_keyseq, gl_erase_terminal, gl_automatic_history, gl_append_his-
+ tory, gl_query_char, gl_read_char - allow the user to compose an input
+ line
+
+</pre><h2>SYNOPSIS</h2><pre>
+ #include &lt;stdio.h&gt;
+ #include &lt;libtecla.h&gt;
+
+ 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_query_char(GetLine *gl, const char *prompt,
+ char defchar);
+
+ int gl_read_char(GetLine *gl);
+
+ 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_bind_keyseq(GetLine *gl, GlKeyOrigin origin,
+ const char *keyseq, const char *action);
+
+ 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_inactivity_timeout(GetLine *gl, GlTimeoutFn *callback,
+ void *data, unsigned long sec,
+ unsigned long nsec);
+
+ 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_set_term_size(GetLine *gl, int ncolumn, int 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(GetLine *gl);
+
+ int gl_completion_action(GetLine *gl,
+ void *data, CplMatchFn *match_fn,
+ int list_only, const char *name,
+ const char *keyseq);
+
+ int gl_register_action(GetLine *gl, void *data,
+ GlActionFn *fn, const char *name,
+ const char *keyseq);
+
+ int gl_display_text(GetLine *gl, int indentation,
+ const char *prefix,
+ const char *suffix, int fill_char,
+ int def_width, int start,
+ const char *string);
+
+ GlReturnStatus gl_return_status(GetLine *gl);
+
+ const char *gl_error_message(GetLine *gl, char *buff,
+ size_t n);
+
+ void gl_catch_blocked(GetLine *gl);
+
+ int gl_list_signals(GetLine *gl, sigset_t *set);
+
+ int gl_append_history(GetLine *gl, const char *line);
+
+ int gl_automatic_history(GetLine *gl, int enable);
+
+
+
+</pre><h2>DESCRIPTION</h2><pre>
+ The gl_get_line() function is part of the tecla library (see the libte-
+ cla(@LIBR_MANEXT@) man page). If the user is typing at a terminal, each
+ call prompts them for an line of input, then provides interactive edit-
+ ing 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. Documentation of both the user-level command-
+ line editing features and all user configuration options, can be found
+ in the <a href="tecla.html"><b>tecla</b></a> man page. This man page concerns itself
+ with documentation for programmers interested in using this library in
+ their application.
+
+
+</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 &lt;stdio.h&gt;
+ #include &lt;locale.h&gt;
+ #include &lt;libtecla.h&gt;
+
+ 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 &amp;&amp;
+ 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() func-
+ tion 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 allocated by new_Get-
+ Line(), are returned to the system by calling 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 num-
+ ber 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, specifying 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 posi-
+ tioned 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. Note that the line pointer returned by one
+ call to gl_get_line() can be passed back to the next call to
+ gl_get_line() via the start_line. This allows the application to take
+ the last entered line, and if it contains an error, to then present it
+ back to the user for re-editing, with the cursor initially positioned
+ where the error was encountered.
+
+ 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 termi-
+ nal,gl_get_line() just calls fgets().
+
+
+</pre><h2>THE RETURN STATUS OF GL_GET_LINE</h2><pre>
+ As described above, the gl_get_line() function has two possible return
+ values; a pointer to the completed input line, or NULL. Extra informa-
+ tion about what caused gl_get_line() to return is available both by
+ inspecting errno, and by calling the gl_return_status() function.
+
+
+ GlReturnStatus gl_return_status(GetLine *gl);
+
+
+ The following are the possible enumerated values that this function
+ returns.
+
+
+ GLR_NEWLINE - The last call to gl_get_line()
+ successfully returned a completed
+ input line.
+
+ GLR_BLOCKED - gl_get_line() was in non-blocking
+ server mode, and returned early to
+ avoid blocking the process while
+ waiting for terminal I/O. The
+ gl_pending_io() function can be
+ used to see what type of I/O
+ gl_get_line() was waiting for.
+ (see the <a href="gl_io_mode.html"><b>gl_io_mode</b></a> man page
+ for details).
+
+ GLR_SIGNAL - A signal was caught by
+ gl_get_line() that had an
+ after-signal disposition of
+ GLS_ABORT (See gl_trap_signal()).
+
+ GLR_TIMEOUT - The inactivity timer expired while
+ gl_get_line() was waiting for
+ input, and the timeout callback
+ function returned GLTO_ABORT.
+ See gl_inactivity_timeout() for
+ information about timeouts.
+
+ GLR_FDABORT - An application I/O callack returned
+ GLFD_ABORT (see gl_watch_fd()).
+
+ GLR_EOF - End of file reached. This can happen
+ when input is coming from a file or a
+ pipe, instead of the terminal. It also
+ occurs if the user invokes the
+ list-or-eof or del-char-or-list-or-eof
+ actions at the start of a new line.
+
+ GLR_ERROR - An unexpected error caused
+ gl_get_line() to abort (consult
+ errno and/or
+ gl_error_message() for details.
+
+
+ When gl_return_status() returns GLR_ERROR, and the value of errno isn't
+ sufficient to explain what happened, you can use the gl_error_message()
+ function to request a description of the last error that occurred.
+
+
+ const char *gl_error_message(GetLine *gl, char *buff,
+ size_t n);
+
+
+ The return value is a pointer to the message that occurred. If the buff
+ argument is NULL, this will be a pointer to a buffer within gl, who's
+ value will probably change on the next call to any function associated
+ with gl_get_line(). Otherwise, if a non-NULL buff argument is provided,
+ the error message, including a '\0' terminator, will be written within
+ the first n elements of this buffer, and the return value will be a
+ pointer to the first element of this buffer. If the message won't fit
+ in the provided buffer, it will be truncated to fit.
+
+
+</pre><h2>OPTIONAL PROMPT FORMATTING</h2><pre>
+ Whereas by default the prompt string that you specify is displayed lit-
+ erally, without any special interpretation of the characters within it,
+ the gl_prompt_style() function can be used to enable optional format-
+ ting 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>ALTERNATE CONFIGURATION SOURCES</h2><pre>
+ As mentioned above, by default users have the option of configuring 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 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 informa-
+ tion 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 config-
+ uration 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 characters. If app_file != NULL then it is
+ interpreted as the full pathname of an application-specific configura-
+ tion file. If user_file != NULL then it is interpreted as the full
+ pathname 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 configura-
+ tion commands from an optional .teclarc file in the user's home direc-
+ tory. Note that the arguments are listed in ascending order of prior-
+ ity, with the contents of app_string being potentially overriden by
+ commands in app_file, and commands in app_file potentially being over-
+ riden 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 specifies the
+ filenames that you want re-read when the user requests that the config-
+ uration files be re-read.
+
+ Individual key sequences can also be bound and unbound using the
+ gl_bind_keyseq() function.
+
+
+ int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin,
+ const char *keyseq,
+ const char *action);
+
+
+ The origin argument specifies the priority of the binding, according to
+ who it is being established for, and must be one of the following two
+ values.
+
+ GL_USER_KEY - The user requested this key-binding.
+ GL_APP_KEY - This is a default binding set by the
+ application.
+
+ When both user and application bindings for a given key-sequence have
+ been specified, the user binding takes precedence. The application's
+ binding is subsequently reinstated if the user's binding is later
+ unbound via either another to this function, or a call to gl_config-
+ ure_getline().
+
+ The keyseq argument specifies the key-sequence to be bound or unbound,
+ and is expressed in the same way as in a ~/.teclarc configuration file.
+ The action argument must either be a string containing the name of the
+ action to bind the key-sequence to, or it must be NULL or "" to unbind
+ the key-sequence.
+
+
+</pre><h2>CUSTOMIZED WORD COMPLETION</h2><pre>
+ 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 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 arbi-
+ trary, 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 call-
+ back functions. The declaration and responsibilities of callback func-
+ tions are described in depth in the <a href="cpl_complete_word.html"><b>cpl_complete_word</b></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 possi-
+ ble completions of this word, and record them one by one in the Word-
+ Completion object that is passed to it as an argument, by calling the
+ cpl_add_completion() function. If the callback function wishes to pro-
+ vide 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 cpl_com-
+ plete_word(@FUNC_MANEXT@) 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 character, then gl_get_line() will
+ return this input line.
+
+
+ If, for some reason, your callback function needs to write something to
+ the terminal, it must call gl_normal_io() before doing so. This will
+ start a new line after the input line that is currently being edited,
+ reinstate normal terminal I/O, and tell gl_get_line() that the input
+ line will need to be redrawn when the callback returns.
+
+
+</pre><h2>ADDING COMPLETION ACTIONS</h2><pre>
+ In the previous section the ability to customize the behavior of the
+ only default completion action, complete-word, was described. In this
+ section the ability to install additional action functions, so that
+ different types of word completion can be bound to different key-
+ sequences, is described. This is achieved by using the gl_comple-
+ tion_action() function.
+
+
+ int gl_completion_action(GetLine *gl,
+ void *data, CplMatchFn *match_fn,
+ int list_only, const char *name,
+ const char *keyseq);
+
+
+ The data and match_fn arguments are as described in the cpl_com-
+ plete_word man page, and specify the callback function that should be
+ invoked to identify possible completions. The list_only argument
+ determines whether the action that is being defined should attempt to
+ complete the word as far as possible in the input line before display-
+ ing any possible ambiguous completions, or whether it should simply
+ display the list of possible completions without touching the input
+ line. The former option is selected by specifying a value of 0, and the
+ latter by specifying a value of 1. The name argument specifies the name
+ by which configuration files and future invokations of this function
+ should refer to the action. This must either be the name of an existing
+ completion action to be changed, or be a new unused name for a new
+ action. Finally, the keyseq argument specifies the default key-sequence
+ to bind the action to. If this is NULL, no new keysequence will be
+ bound to the action.
+
+ Beware that in order for the user to be able to change the key-sequence
+ that is bound to actions that are installed in this manner, when you
+ call gl_completion_action() to install a given action for the first
+ time, you should do this between calling new_GetLine() and the first
+ call to gl_get_line(). Otherwise, when the user's configuration file
+ is read on the first call to gl_get_line(), the name of the your addi-
+ tional action won't be known, and any reference to it in the configura-
+ tion file will generate an error.
+
+ As discussed for gl_customize_completion(), if your callback function,
+ for some reason, needs to write anything to the terminal, it must call
+ gl_normal_io() before doing so.
+
+
+</pre><h2>DEFINING CUSTOM ACTIONS</h2><pre>
+ Although the built-in key-binding actions are sufficient for the needs
+ of most applications, occasionally a specialized application may need
+ to define one or more custom actions, bound to application-specific
+ key-sequences. For example, a sales application would benefit from hav-
+ ing a key-sequence that displayed the part name that corresponded to a
+ part number preceding the cursor. Such a feature is clearly beyond the
+ scope of the built-in action functions. So for such special cases, the
+ gl_register_action() function is provided.
+
+
+ int gl_register_action(GetLine *gl, void *data,
+ GlActionFn *fn, const char *name,
+ const char *keyseq);
+
+
+ This function lets the application register an external function, fn,
+ that will thereafter be called whenever either the specified key-
+ sequence, keyseq, is entered by the user, or the user enters any other
+ key-sequence that the user subsequently binds to the specified action
+ name, name, in their configuration file. The data argument can be a
+ pointer to anything that the application wishes to have passed to the
+ action function, fn, whenever that function is invoked.
+
+ The action function, fn, should be declared using the following macro,
+ which is defined in libtecla.h.
+
+
+ #define GL_ACTION_FN(fn) GlAfterAction (fn)(GetLine *gl, \
+ void *data, int count, size_t curpos, \
+ const char *line)
+
+
+ The gl and data arguments are those that were previously passed to
+ gl_register_action() when the action function was registered. The count
+ argument is a numeric argument which the user has the option of enter-
+ ing using the digit-argument action, before invoking the action. If the
+ user doesn't enter a number, then the count argument is set to 1. Nomi-
+ nally this argument is interpreted as a repeat count, meaning that the
+ action should be repeated that many times. In practice however, for
+ some actions a repeat count makes little sense. In such cases, actions
+ can either simply ignore the count argument, or use its value for a
+ different purpose.
+
+ A copy of the current input line is passed in the read-only line argu-
+ ment. The current cursor position within this string is given by the
+ index contained in the curpos argument. Note that direct manipulation
+ of the input line and the cursor position is not permitted. This is
+ because the rules dicated by various modes, such as vi mode versus
+ emacs mode, no-echo mode, and insert mode versus overstrike mode etc,
+ make it too complex for an application writer to write a conforming
+ editing action, as well as constrain future changes to the internals of
+ gl_get_line(). A potential solution to this dilema would be to allow
+ the action function to edit the line using the existing editing
+ actions. This is currently under consideration.
+
+ If the action function wishes to write text to the terminal, without
+ this getting mixed up with the displayed text of the input line, or
+ read from the terminal without having to handle raw terminal I/O, then
+ before doing either of these operations, it must temporarily suspend
+ line editing by calling the gl_normal_io() function. This function
+ flushes any pending output to the terminal, moves the cursor to the
+ start of the line that follows the last terminal line of the input
+ line, then restores the terminal to a state that is suitable for use
+ with the C stdio facilities. The latter includes such things as restor-
+ ing the normal mapping of \n to \r\n, and, when in server mode, restor-
+ ing the normal blocking form of terminal I/O. Having called this func-
+ tion, the action function can read from and write to the terminal with-
+ out the fear of creating a mess. It isn't necessary for the action
+ function to restore the original editing environment before it returns.
+ This is done automatically by gl_get_line() after the action function
+ returns. The following is a simple example of an action function which
+ writes the sentence "Hello world" on a new terminal line after the line
+ being edited. When this function returns, the input line is redrawn on
+ the line that follows the "Hello world" line, and line editing resumes.
+
+
+ static GL_ACTION_FN(say_hello_fn)
+ {
+ if(gl_normal_io(gl)) /* Temporarily suspend editing */
+ return GLA_ABORT;
+ printf("Hello world\n");
+ return GLA_CONTINUE;
+ }
+
+
+ Action functions must return one of the following values, to tell
+ gl_get_line() how to procede.
+
+
+ GLA_ABORT - Cause gl_get_line() to return NULL.
+ GLA_RETURN - Cause gl_get_line() to return the
+ completed input line.
+ GLA_CONTINUE - Resume command-line editing.
+
+
+ Note that the name argument of gl_register_action() specifies the name
+ by which a user can refer to the action in their configuration file.
+ This allows them to re-bind the action to an alternate key-seqeunce. In
+ order for this to work, it is necessary to call gl_register_action()
+ between calling new_GetLine() and the first call to gl_get_line().
+
+
+</pre><h2>HISTORY FILES</h2><pre>
+ To save the contents of the history buffer before quitting your appli-
+ cation, and subsequently restore them when you next start the applica-
+ tion, the following functions are provided.
+
+
+ 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 environment 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 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 pre-
+ fixes differ in different languages, the comment 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 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 his-
+ tory 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-exis-
+ tence of a file to be an error.
+
+
+</pre><h2>MULTIPLE HISTORY LISTS</h2><pre>
+ If your application uses a single GetLine object for entering many dif-
+ ferent 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. Initially this identi-
+ fier 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 identifiers and historical input lines between pro-
+ gram invokations, so you should choose fixed identifiers for the dif-
+ ferent types of input line used by your application.
+
+ Whenever gl_get_line() 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.
+
+
+</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 his-
+ tory 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 char-
+ acters which are written verbatim, interleaved with any of the follow-
+ ing 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 application 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 succes-
+ sively higher numbers. Note that the range of lines currently preserved
+ in the history 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-&gt;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 function that takes gl as its argument. There-
+ fore you should make a private copy of this string if you need to keep
+ it around.
+
+
+</pre><h2>MANUAL HISTORY ARCHIVAL</h2><pre>
+ By default, whenever a line is entered by the user, it is automatically
+ appended to the history list, just before gl_get_line() returns the
+ line to the caller. This is convenient for the majority of applica-
+ tions, but there are also applications that need finer grained control
+ over what gets added to the history list. In such cases, the automatic
+ addition of entered lines to the history list can be turned off by
+ calling the gl_automatic_history() function.
+
+
+ int gl_automatic_history(GetLine *gl, int enable);
+
+
+ If this function is called with its enable argument set to 0,
+ gl_get_line() won't automatically archive subsequently entered lines.
+ Automatic archiving can be reenabled at a later time, by calling this
+ function again, with its enable argument set to 1. While automatic
+ history archiving is disabled, the calling application can use the
+ gl_append_history() to append lines to the history list as needed.
+
+
+ int gl_append_history(GetLine *gl, const char *line);
+
+
+ The line argument specifies the line to be added to the history list.
+ This must be a normal ' ' terminated string. If this string contains
+ any newline characters, the line that gets archived in the history list
+ will be terminated by the first of these. Otherwise it will be termi-
+ nated by the ' ' terminator. If the line is longer than the maximum
+ input line length, that was specified when new_GetLine() was called,
+ when the line is recalled, it will get truncated to the actual
+ gl_get_line() line length.
+
+ If successful, gl_append_history() returns 0. Otherwise it returns non-
+ zero, and sets errno to one of the following values.
+
+
+ EINVAL - One of the arguments passed to
+ gl_append_history() was NULL.
+ ENOMEM - The specified line was longer than the allocated
+ size of the history buffer (as specified when
+ new_GetLine() was called), so it couldn't be
+ archived.
+
+
+ A textual description of the error can optionally be obtained by call-
+ ing gl_error_message(). Note that after such an error, the history list
+ remains in a valid state to receive new history lines, so there is lit-
+ tle harm in simply ignoring the return status of gl_append_history().
+
+
+</pre><h2>MISCELLANEOUS HISTORY CONFIGURATION</h2><pre>
+ If you wish to change the size of the history buffer that was origi-
+ nally 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 spec-
+ ify 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 &gt;= 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 discarded.
+
+ 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_his-
+ tory()), or all historical lines in the buffer.
+
+ The gl_toggle_history() function allows you to toggle history 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 history is turned off, no new
+ lines will be added to the history list, and history lookup key-bind-
+ ings 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 variable 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 written 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
+ database (terminfo or termcap), in order to determine which special
+ control sequences are needed to control various aspects of the termi-
+ nal. 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 terminal 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>
+ By default, gl_get_line() doesn't return until either a complete input
+ line has been entered by the user, or an error occurs. In programs that
+ need to watch for I/O from other sources than the terminal, there are
+ two options.
+
+
+ 1. Use the functions described in the
+ <a href="gl_io_mode.html"><b>gl_io_mode</b></a> man page to switch
+ gl_get_line() into non-blocking server mode. In this mode,
+ gl_get_line() becomes a non-blocking, incremental
+ line-editing function that can safely be called from
+ an external event loop. Although this is a very
+ versatile method, it involves taking on some
+ responsibilities that are normally performed behind
+ the scenes by gl_get_line().
+
+ 2. 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 argu-
+ ment 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 call-
+ back function for its own use, and can point to anything 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
+ function should be one of the following values.
+
+
+ GLFD_ABORT - Tell gl_get_line() to abort. When this
+ happens, gl_get_line() returns
+ NULL, and a following call to
+ gl_return_status() will return
+ GLR_FDABORT. Note that if the
+ application needs errno always to
+ have a meaningful value when
+ gl_get_line() returns NULL,
+ the callback function should set
+ errno appropriately.
+ 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 sig-
+ nals, 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.
+
+
+
+ If the callback function needs to read or write to the terminal, it
+ should ideally first call gl_normal_io(gl) to temporarily suspend line
+ editing. This will restore the terminal to canonical, blocking-I/O,
+ mode, and move the cursor to the start of a new terminal line. Later,
+ when the callback returns, gl_get_line() will notice that gl_nor-
+ mal_io() was called, redisplay the input line and resume editing. Note
+ that in this case the return values, GLFD_REFRESH and GLFD_CONTINUE are
+ equivalent.
+
+
+
+ To support cases where the callback function calls a third-party func-
+ tion which occasionally and u0prisicre-enabledesbeforee themicallback
+ automatic conversion of "0 to "
+ function is called. If the callack knows that the third-party function
+ wrote to the terminal, it should then return the GLFD_REFRESH return
+ value, to tell gl_get_line() to redisplay the input line.
+
+
+
+ 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 arguments, but with a callback argument
+ of 0. The data argument is ignored in this case.
+
+
+</pre><h2>SETTING AN INACTIVITY TIMEOUT</h2><pre>
+ On systems with the select() system call, the gl_inactivity_timeout()
+ function can be used to set or cancel an inactivity timeout. Inactivity
+ in this case refers both to keyboard input, and to I/O on any file
+ descriptors registered by prior and subsequent calls to gl_watch_fd().
+ On oddball systems that don't have select(), this call has no effect.
+
+
+ int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *callback,
+ void *data, unsigned long sec,
+ unsigned long nsec);
+
+
+ The timeout is specified in the form of an integral number of seconds
+ and an integral number of nanoseconds, via the sec and nsec arguments
+ respectively. Subsequently, whenever no activity is seen for this time
+ period, the function specified via the callback argument is called. The
+ data argument of gl_inactivity_timeout() is passed verbatim to this
+ callback function whenever it is invoked, and can thus be used to pass
+ arbitrary application-specific information to the callback. The follow-
+ ing macro is provided in libtecla.h for applications to use to declare
+ and prototype timeout callback functions.
+
+
+ #define GL_TIMEOUT_FN(fn) \
+ GlAfterTimeout (fn)(GetLine *gl, void *data)
+
+
+ On returning, the application's callback is expected to return one of
+ the following enumerators to tell gl_get_line() how to procede after
+ the timeout has been handled by the callback.
+
+
+ GLTO_ABORT - Tell gl_get_line() to abort. When
+ this happens, gl_get_line() will
+ return NULL, and a following call
+ to gl_return_status() will return
+ GLR_TIMEOUT. Note that if the
+ application needs errno always to
+ have a meaningful value when
+ gl_get_line() returns NULL,
+ the callback function should set
+ errno appropriately.
+ GLTO_REFRESH - Redraw the input line, then continue
+ waiting for input. You should return
+ this value if your callback wrote to the
+ terminal without having first called
+ gl_normal_io(gl).
+ GLTO_CONTINUE - In normal blocking-I/O mode, continue to
+ wait for input, without redrawing the
+ user's input line.
+ In non-blocking server I/O mode (see
+ <a href="gl_io_mode.html"><b>gl_io_mode</b></a>), cause gl_get_line()
+ to act as though I/O blocked. This means
+ that gl_get_line() will immediately
+ return NULL, and a following call
+ to gl_return_status() will return
+ GLR_BLOCKED.
+
+
+ Note that before calling the callback, gl_get_line() blocks most sig-
+ nals, 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.
+
+
+
+ If the callback function needs to read or write to the terminal, it
+ should ideally first call gl_normal_io(gl) to temporarily suspend line
+ editing. This will restore the terminal to canonical, blocking-I/O,
+ mode, and move the cursor to the start of a new terminal line. Later,
+ when the callback returns, gl_get_line() will notice that gl_nor-
+ mal_io() was called, redisplay the input line and resume editing. Note
+ that in this case the return values, GLTO_REFRESH and GLTO_CONTINUE are
+ equivalent.
+
+
+
+ To support cases where the callback function calls a third-party func-
+ tion which occasionally and u0prisicre-enabledesbeforee themicallback
+ automatic conversion of "0 to "
+ function is called. If the callack knows that the third-party function
+ wrote to the terminal, it should then return the GLTO_REFRESH return
+ value, to tell gl_get_line() to redisplay the input line.
+
+
+
+ Note that although the timeout argument includes a nano-second compo-
+ nent, few computer clocks presently have resolutions that are finer
+ than a few milliseconds, so asking for less than a few milliseconds is
+ equivalent to requesting zero seconds on a lot of systems. If this
+ would be a problem, you should base your timeout selection on the
+ actual resolution of the host clock (eg. by calling
+ sysconf(_SC_CLK_TCK)).
+
+
+
+ To turn off timeouts, simply call gl_inactivity_timeout() with a call-
+ back 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 ter-
+ minate 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 sec-
+ tion.
+
+ When the following subset of signals are caught, gl_get_line() first
+ restores the terminal settings and signal handling to how they were
+ before gl_get_line() was called, resends the signal, to allow the call-
+ ing application's signal handlers to handle it, then if the process
+ 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 following function.
+
+ int gl_last_signal(const GetLine *gl);
+
+ This returns the numeric code (eg. SIGINT) of the last signal that was
+ received during the most recent call to gl_get_line(), or -1 if no sig-
+ nals 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 keyboard 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.
+
+ SIGPOLL - On SVR4 systems, this signal notifies the
+ process of an asynchronous I/O event. Note
+ that under 4.3+BSD, SIGIO and SIGPOLL are
+ the same. On other systems, SIGIO is ignored
+ by default, so gl_get_line() doesn't
+ trap it by default.
+
+ 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.
+
+ SIGXFSZ - This signal is generated when a process
+ exceeds its soft file-size 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 or SIGPOLL, 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-con-
+ trol shells usually reset the terminal settings when a process relin-
+ quishes the controlling 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 sig-
+ nal 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 envi-
+ ronment 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 overridden it, never either writes to the termi-
+ nal, nor suspends or terminates the calling 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 argu-
+ ment 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 sig-
+ nal 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. 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 GL_SUSPEND_INPUT
+ combination is better if you know that you are always going to be writ-
+ ting 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 abort. When
+ this happens, gl_get_line() returns
+ NULL, and a following call to
+ gl_return_status() will return
+ GLR_SIGNAL. Note that if the
+ application needs errno always to
+ have a meaningful value when
+ gl_get_line() returns NULL,
+ the callback function should set
+ errno appropriately.
+ 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 calling program. It can also, however,
+ be used with the GL_RETURN 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.
+
+
+</pre><h2>RELIABLE SIGNAL HANDLING</h2><pre>
+ Signal handling is suprisingly hard to do reliably without race condi-
+ tions. In gl_get_line() a lot of care has been taken to allow applica-
+ tions to perform reliable signal handling around gl_get_line(). This
+ section explains how to make use of this.
+
+ As an example of the problems that can arise if the application isn't
+ written correctly, imagine that one's application has a SIGINT signal
+ handler that sets a global flag. Now suppose that the application tests
+ this flag just before invoking gl_get_line(). If a SIGINT signal hap-
+ pens to be received in the small window of time between the statement
+ that tests the value of this flag, and the statement that calls
+ gl_get_line(), then gl_get_line() will not see the signal, and will not
+ be interrupted. As a result, the application won't be able to respond
+ to the signal until the user gets around to finishing entering the
+ input line and gl_get_line() returns. Depending on the application,
+ this might or might not be a disaster, but at the very least it would
+ puzzle the user.
+
+ The way to avoid such problems is to do the following.
+
+ 1. If needed, use the gl_trap_signal() function to
+ configure gl_get_line() to abort when important
+ signals are caught.
+
+ 2. Configure gl_get_line() such that if any of the
+ signals that it catches are blocked when
+ gl_get_line() is called, they will be unblocked
+ automatically during times when gl_get_line() is
+ waiting for I/O. This can be done either
+ on a per signal basis, by calling the
+ gl_trap_signal() function, and specifying the
+ GLS_UNBLOCK attribute of the signal, or globally by
+ calling the gl_catch_blocked() function.
+
+
+ void gl_catch_blocked(GetLine *gl);
+
+
+ This function simply adds the GLS_UNBLOCK attribute
+ to all of the signals that it is currently configured to
+ trap.
+
+ 3. Just before calling gl_get_line(), block delivery
+ of all of the signals that gl_get_line() is
+ configured to trap. This can be done using the POSIX
+ sigprocmask() function in conjunction with the
+ gl_list_signals() function.
+
+
+ int gl_list_signals(GetLine *gl, sigset_t *set);
+
+
+ This function returns the set of signals that it is
+ currently configured to catch in the set argument,
+ which is in the form required by sigprocmask().
+
+ 4. In the example, one would now test the global flag that
+ the signal handler sets, knowing that there is now no
+ danger of this flag being set again until
+ gl_get_line() unblocks its signals while performing
+ I/O.
+
+ 5. Eventually gl_get_line() returns, either because
+ a signal was caught, an error occurred, or the user
+ finished entering their input line.
+
+ 6. Now one would check the global signal flag again, and if
+ it is set, respond to it, and zero the flag.
+
+ 7. Use sigprocmask() to unblock the signals that were
+ blocked in step 3.
+
+ The same technique can be used around certain POSIX signal-aware func-
+ tions, such as sigsetjmp() and sigsuspend(), and in particular, the
+ former of these two functions can be used in conjunction with sig-
+ longjmp() to implement race-condition free signal handling around other
+ long-running system calls. The way to do this, is explained next, by
+ showing how gl_get_line() manages to reliably trap signals around calls
+ to functions like read() and select() without race conditions.
+
+ The first thing that gl_get_line() does, whenever it is called, is to
+ use the POSIX sigprocmask() function to block the delivery of all of
+ the signals that it is currently configured to catch. This is redundant
+ if the application has already blocked them, but it does no harm. It
+ undoes this step just before returning.
+
+ Whenever gl_get_line() needs to call read() or select() to wait for
+ input from the user, it first calls the POSIX sigsetjmp() function,
+ being sure to specify a non-zero value for its savesigs argument. The
+ reason for the latter argument will become clear shortly.
+
+ If sigsetjmp() returns zero, gl_get_line() then does the following.
+
+
+ a. It uses the POSIX sigaction() function to register
+ a temporary signal handler to all of the signals that it
+ is configured to catch. This signal handler does two
+ things.
+
+ 1. It records the number of the signal that was received
+ in a file-scope variable.
+
+ 2. It then calls the POSIX siglongjmp()
+ function using the buffer that was passed to
+ sigsetjmp() for its first argument, and
+ a non-zero value for its second argument.
+
+ When this signal handler is registered, the sa_mask
+ member of the struct sigaction act argument of the
+ call to sigaction() is configured to contain all of
+ the signals that gl_get_line() is catching. This
+ ensures that only one signal will be caught at once by
+ our signal handler, which in turn ensures that multiple
+ instances of our signal handler don't tread on each
+ other's toes.
+
+ b. Now that the signal handler has been set up,
+ gl_get_line() unblocks all of the signals that it
+ is configured to catch.
+
+ c. It then calls the read() or select() system
+ calls to wait for keyboard input.
+
+ d. If this system call returns (ie. no signal is received),
+ gl_get_line() blocks delivery of the signals of
+ interest again.
+
+ e. It then reinstates the signal handlers that were
+ displaced by the one that was just installed.
+
+
+ Alternatively, if sigsetjmp() returns non-zero, this means that one of
+ the signals being trapped was caught while the above steps were execut-
+ ing. When this happens, gl_get_line() does the following.
+
+ First, note that when a call to siglongjmp() causes sigsetjmp() to
+ return, provided that the savesigs argument of sigsetjmp() was non-
+ zero, as specified above, the signal process mask is restored to how it
+ was when sigsetjmp() was called. This is the important difference
+ between sigsetjmp() and the older problematic setjmp(), and is the
+ essential ingredient that makes it possible to avoid signal handling
+ race conditions. Because of this we are guaranteed that all of the
+ signals that we blocked before calling sigsetjmp() are blocked again as
+ soon as any signal is caught. The following statements, which are then
+ executed, are thus guaranteed to be executed without any further sig-
+ nals being caught.
+
+ 1. If so instructed by the gl_get_line() configuration
+ attributes of the signal that was caught,
+ gl_get_line() restores the terminal attributes to
+ the state that they had when gl_get_line() was
+ called. This is particularly important for signals that
+ suspend or terminate the process, since otherwise the
+ terminal would be left in an unusable state.
+
+ 2. It then reinstates the application's signal handlers.
+
+ 3. Then it uses the C standard-library raise()
+ function to re-send the application the signal that
+ was caught.
+
+ 3. Next it unblocks delivery of the signal that we just
+ sent. This results in the signal that was just sent
+ via raise(), being caught by the application's
+ original signal handler, which can now handle it as it
+ sees fit.
+
+ 4. If the signal handler returns (ie. it doesn't terminate
+ the process), gl_get_line() blocks delivery of the
+ above signal again.
+
+ 5. It then undoes any actions performed in the first of the
+ above steps, and redisplays the line, if the signal
+ configuration calls for this.
+
+ 6. gl_get_line() then either resumes trying to
+ read a character, or aborts, depending on the
+ configuration of the signal that was caught.
+
+ What the above steps do in essence is to take asynchronously delivered
+ signals and handle them synchronously, one at a time, at a point in the
+ code where gl_get_line() has complete control over its environment.
+
+
+</pre><h2>THE TERMINAL SIZE</h2><pre>
+ On most systems the combination of the TIOCGWINSZ ioctl and the SIG-
+ WINCH 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 vari-
+ ables. 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.
+
+ Even on systems that do support ioctl(TIOCGWINSZ), if the terminal is
+ on the other end of a serial line, the terminal driver generally has no
+ way of detecting when a resize occurs or of querying what the current
+ size is. In such cases no SIGWINCH is sent to the process, and the
+ dimensions returned by ioctl(TIOCGWINSZ) aren't correct. The only way
+ to handle such instances is to provide a way for the user to enter a
+ command that tells the remote system what the new size is. This command
+ would then call the gl_set_term_size() function to tell gl_get_line()
+ about the change in size.
+
+
+ int gl_set_term_size(GetLine *gl, int ncolumn, int nline);
+
+
+ The ncolumn and nline arguments are used to specify the new dimensions
+ of the terminal, and must not be less than 1. On systems that do sup-
+ port ioctl(TIOCGWINSZ), this function first calls ioctl(TIOCSWINSZ) to
+ tell the terminal driver about the change in size. In non-blocking
+ server-I/O mode, if a line is currently being input, the input line is
+ then redrawn to accomodate the changed size. Finally the new values are
+ recorded in gl for future use by gl_get_line().
+
+ The gl_terminal_size() 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.
+
+ 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 fallback terminal dimen-
+ sions, 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 via
+ ioctl(TIOCGWINSZ) or environment variables.
+
+
+</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. Fur-
+ thermore, 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 tog-
+ gle on and off the display and archival of any text that is subse-
+ quently 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
+ provided that history hasn't been turned off via a call to gl_tog-
+ gle_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 set-
+ ting via the return value. In all cases, the return value of the func-
+ tion 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 completion will
+ invisibly complete your prefix as far as possible, ambiguous comple-
+ tions will not be displayed.
+
+
+</pre><h2>SINGLE CHARACTER QUERIES</h2><pre>
+ Using gl_get_line() to query the user for a single character reply, is
+ inconvenient for the user, since they must hit the enter or return key
+ before the character that they typed is returned to the program. Thus
+ the gl_query_char() function has been provided for single character
+ queries like this.
+
+
+ int gl_query_char(GetLine *gl, const char *prompt,
+ char defchar);
+
+
+ This function displays the specified prompt at the start of a new line,
+ and waits for the user to type a character. When the user types a char-
+ acter, gl_query_char() displays it to the right of the prompt, starts a
+ newline, then returns the character to the calling program. The return
+ value of the function is the character that was typed. If the read had
+ to be aborted for some reason, EOF is returned instead. In the latter
+ case, the application can call the previously documented gl_return_sta-
+ tus(), to find out what went wrong. This could, for example, have been
+ the reception of a signal, or the optional inactivity timer going off.
+
+ If the user simply hits enter, the value of the defchar argument is
+ substituted. This means that when the user hits either newline or
+ return, the character specified in defchar, is displayed after the
+ prompt, as though the user had typed it, as well as being returned to
+ the calling application. If such a replacement is not important, simply
+ pass '0 as the value of defchar.
+
+ If the entered character is an unprintable character, it is displayed
+ symbolically. For example, control-A is displayed as ^A, and characters
+ beyond 127 are displayed in octal, preceded by a backslash.
+
+ As with gl_get_line(), echoing of the entered character can be disabled
+ using the gl_echo_mode() function.
+
+ If the calling process is suspended while waiting for the user to type
+ their response, the cursor is moved to the line following the prompt
+ line, then when the process resumes, the prompt is redisplayed, and
+ gl_query_char() resumes waiting for the user to type a character.
+
+ Note that in non-blocking server mode, (see <a href="gl_io_mode.html"><b>gl_io_mode</b></a>),
+ if an incomplete input line is in the process of being read when
+ gl_query_char() is called, the partial input line is discarded, and
+ erased from the terminal, before the new prompt is displayed. The next
+ call to gl_get_line() will thus start editing a new line.
+
+
+</pre><h2>READING RAW CHARACTERS</h2><pre>
+ Whereas the gl_query_char() function visibly prompts the user for a
+ character, and displays what they typed, the gl_read_char() function
+ reads a signal character from the user, without writing anything to the
+ terminal, or perturbing any incompletely entered input line. This means
+ that it can be called not only from between calls to gl_get_line(), but
+ also from callback functions that the application has registered to be
+ called by gl_get_line().
+
+
+ int gl_read_char(GetLine *gl);
+
+
+ On success, the return value of gl_read_char() is the character that
+ was read. On failure, EOF is returned, and the gl_return_status() func-
+ tion can be called to find out what went wrong. Possibilities include
+ the optional inactivity timer going off, the receipt of a signal that
+ is configured to abort gl_get_line(), or terminal I/O blocking, when in
+ non-blocking server-I/O mode.
+
+ Beware that certain keyboard keys, such as function keys, and cursor
+ keys, usually generate at least 3 characters each, so a single call to
+ gl_read_char() won't be enough to identify such keystrokes.
+
+
+</pre><h2>CLEARING THE TERMINAL</h2><pre>
+ The calling program can clear the terminal by calling gl_erase_termi-
+ nal(). In non-blocking server-I/O mode, this function also arranges for
+ the current input line to be redrawn from scratch when gl_get_line() is
+ next called.
+
+
+ int gl_erase_terminal(GetLine *gl);
+
+
+
+</pre><h2>DISPLAYING TEXT DYNAMICALLY</h2><pre>
+ Between calls to gl_get_line(), the gl_display_text() function provides
+ a convenient way to display paragraphs of text, left-justified and
+ split over one or more terminal lines according to the constraints of
+ the current width of the terminal. Examples of the use of this function
+ may be found in the demo programs, where it is used to display intro-
+ ductions. In those examples the advanced use of optional prefixes, suf-
+ fixes and filled lines to draw a box around the text is also illus-
+ trated.
+
+
+ int gl_display_text(GetLine *gl, int indentation,
+ const char *prefix,
+ const char *suffix, int fill_char,
+ int def_width, int start,
+ const char *string);
+
+ If gl isn't currently connected to a terminal, for example if the out-
+ put of a program that uses gl_get_line() is being piped to another pro-
+ gram or redirected to a file, then the value of the def_width parameter
+ is used as the terminal width.
+
+ The indentation argument specifies the number of characters to use to
+ indent each line of ouput. The fill_char argument specifies the charac-
+ ter that will be used to perform this indentation.
+
+ The prefix argument can either be NULL, or be a string to place at the
+ beginning of each new line (after any indentation). Similarly, the
+ suffix argument can either be NULL, or be a string to place at the end
+ of each line. The suffix is placed flush against the right edge of the
+ terminal, and any space between its first character and the last word
+ on that line is filled with the character specified via the fill_char
+ argument. Normally the fill-character is a space.
+
+ The start argument tells gl_display_text() how many characters have
+ already been written to the current terminal line, and thus tells it
+ the starting column index of the cursor. Since the return value of
+ gl_display_text() is the ending column index of the cursor, by passing
+ the return value of one call to the start argument of the next call, a
+ paragraph that is broken between more than one string can be composed
+ by calling gl_display_text() for each successive portion of the para-
+ graph. Note that literal newline characters are necessary at the end of
+ each paragraph to force a new line to be started.
+
+ On error, gl_display_text() returns -1.
+
+
+</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.
+ Except in non-blocking server mode, it has no effect if used between
+ calls to gl_get_line(). In non-blocking server mode (see the
+ <a href="gl_io_mode.html"><b>gl_io_mode</b></a> man page, when used between two calls to
+ gl_get_line() that are operating on the same input line, the current
+ input line will be re-drawn with the new prompt on the following call
+ to gl_get_line().
+
+
+ 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 printable in the user's cur-
+ rent locale are now displayed verbatim and included in the returned
+ input line. Assuming that the calling program correctly contains a
+ call like the following,
+
+ 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 variables are defined, or the program
+ neglects to call setlocale, 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. Further documentation on how the user can make use
+ of this to enter international characters can be found in the
+ <a href="tecla.html"><b>tecla</b></a> man page.
+
+
+</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 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 mod-
+ ule 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.
+
+
+</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"><b>libtecla</b></a>, <a href="gl_io_mode.html"><b>gl_io_mode</b></a>, <a href="tecla.html"><b>tecla</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>, <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="gl_get_line.html"><b>gl_get_line</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/gl_io_mode.html b/libtecla-1.6.1/html/gl_io_mode.html
new file mode 100644
index 0000000..98c15a7
--- /dev/null
+++ b/libtecla-1.6.1/html/gl_io_mode.html
@@ -0,0 +1,509 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="gl_io_mode.html"><b>gl_io_mode</b></a> <a href="gl_io_mode.html"><b>gl_io_mode</b></a>
+
+
+
+</pre><h2>NAME</h2><pre>
+ gl_io_mode, gl_raw_io, gl_normal_io, gl_tty_signals, gl_abandon_line,
+ gl_handle_signal, gl_pending_io - How to use gl_get_line() from an
+ external event loop.
+
+</pre><h2>SYNOPSIS</h2><pre>
+ #include &lt;libtecla.h&gt;
+
+ int gl_io_mode(GetLine *gl, GlIOMode mode);
+
+ int gl_raw_io(GetLine *gl);
+
+ int gl_normal_io(GetLine *gl);
+
+ int gl_tty_signals(void (*term_handler)(int),
+ void (*susp_handler)(int),
+ void (*cont_handler)(int),
+ void (*size_handler)(int));
+
+ void gl_abandon_line(GetLine *gl);
+
+ void gl_handle_signal(int signo, GetLine *gl, int ngl);
+
+ GlPendingIO gl_pending_io(GetLine *gl);
+
+
+
+</pre><h2>DESCRIPTION</h2><pre>
+ The gl_get_line() function, which is documented separately in the
+ <a href="gl_get_line.html"><b>gl_get_line</b></a> man page, supports two different I/O modes.
+ These are selected by calling the gl_io_mode() function.
+
+
+ int gl_io_mode(GetLine *gl, GlIOMode mode);
+
+
+ The mode argument of this function specifies the new I/O mode, and must
+ be one of the following.
+
+
+ GL_NORMAL_MODE - Select the normal blocking-I/O mode.
+ In this mode gl_get_line()
+ doesn't return until either an error
+ occurs of the user finishes entering a
+ new line. This mode is the focus of
+ the <a href="gl_get_line.html"><b>gl_get_line</b></a> man page.
+
+ GL_SERVER_MODE - Select non-blocking server I/O mode.
+ In this mode, since non-blocking
+ terminal I/O is used, the entry of
+ each new input line typically requires
+ many calls to gl_get_line() from
+ an external I/O-driven event loop.
+ This mode is the focus of this man
+ page.
+
+
+ Newly created GetLine objects start in normal I/O mode, so to switch to
+ non-blocking server mode requires an initial call to gl_io_mode().
+
+
+</pre><h2>SERVER I/O MODE</h2><pre>
+ In non-blocking server I/O mode, the application is required to have an
+ event loop which calls gl_get_line() whenever the terminal file
+ descriptor can do the type I/O that gl_get_line() is waiting for. To
+ determine which type of I/O gl_get_line() is waiting for, the applica-
+ tion calls the gl_pending_io() function.
+
+
+ GlPendingIO gl_pending_io(GetLine *gl);
+
+
+ The return value of this function is one of the following two enumer-
+ ated values.
+
+
+ GLP_READ - gl_get_line() is waiting to write a
+ character to the terminal.
+
+ GLP_WRITE - gl_get_line() is waiting to read a
+ character from the keyboad.
+
+
+ If the application is using either the select() or poll() system calls
+ to watch for I/O on a group of file descriptors, then it should call
+ the gl_pending_io() function before each call to these functions to see
+ which direction of I/O it should tell them to watch for, and configure
+ their arguments accordingly. In the case of the select() system call,
+ this means using the FD_SET() macro to add the terminal file descriptor
+ either to the set of file descriptors to be watched for readability, or
+ the set to be watched for writability.
+
+ As in normal I/O mode, the return value of gl_get_line() is either a
+ pointer to a completed input line, or NULL. However, whereas in normal
+ I/O mode a NULL return value always means that an error occurred, in
+ non-blocking server mode, NULL is also returned when gl_get_line()
+ can't read or write to the terminal without blocking. Thus in non-
+ blocking server mode, in order to determine when a NULL return value
+ signifies that an error occurred or not, it is necessary to call the
+ gl_return_status() function. If this function returns the enumerated
+ value, GLR_BLOCKED, as documented in the <a href="gl_get_line.html"><b>gl_get_line</b></a> man
+ page, this means that gl_get_line() is waiting for I/O, and no error
+ has occurred.
+
+ When gl_get_line() returns NULL and gl_return_status() indicates that
+ this is due to blocked terminal I/O, the application should call
+ gl_get_line() again when the type of I/O reported by gl_pending_io()
+ becomes possible. The prompt, start_line and start_pos arguments of
+ gl_get_line() will be ignored on these calls. If you need to change
+ the prompt of the line that is currently being edited, then you can
+ call the gl_replace_prompt() function (documented in the
+ <a href="gl_get_line.html"><b>gl_get_line</b></a> man page) between calls to gl_get_line().
+
+
+</pre><h2>GIVING UP THE TERMINAL</h2><pre>
+ A complication that is unique to non-blocking server mode is that it
+ requires that the terminal be left in raw mode between calls to
+ gl_get_line(). If this weren't the case, the external event loop
+ wouldn't be able to detect individual key-presses, and the basic line
+ editing implemented by the terminal driver would clash with the editing
+ provided by gl_get_line(). What this means is that any time that the
+ terminal needs to be used for other things than entering a new input
+ line with gl_get_line(), it needs to be restored to a usable state. In
+ particular, whenever the process is suspended or terminated, the termi-
+ nal must be returned to a normal state. If this isn't done, then
+ depending on the characteristics of the shell that was used to invoke
+ the program, the user may end up with a hung terminal. To this end, the
+ gl_normal_io() function is provided for switching the terminal back to
+ the state that it was in when raw mode was last established.
+
+
+ int gl_normal_io(GetLine *gl);
+
+
+ What this function does is first flush any pending output to the termi-
+ nal, then move the cursor to the start of the terminal line which fol-
+ lows the end of the incompletely entered input line. At this point it
+ is safe to suspend or terminate the process, and it is safe for the
+ application to read and write to the terminal. To resume entry of the
+ input line, the application should call the gl_raw_io() function.
+
+
+ int gl_raw_io(GetLine *gl);
+
+
+ This function starts a new line, redisplays the partially completed
+ input line (if any), restores the cursor position within this line to
+ where it was when gl_normal_io() was called, then switches back to raw,
+ non-blocking terminal mode ready to continue entry of the input line
+ when gl_get_line() is next called.
+
+ Note that in non-blocking server mode, if gl_get_line() is called after
+ a call to gl_normal_io(), without an intervening call to gl_raw_io(),
+ gl_get_line() will call gl_raw_mode() itself, and the terminal will
+ remain in this mode when gl_get_line() returns.
+
+
+</pre><h2>SIGNAL HANDLING</h2><pre>
+ In the previous section it was pointed out that in non-blocking server
+ mode, the terminal must be restored to a sane state whenever a signal
+ is received that either suspends or terminates the process. In normal
+ I/O mode, this is done for you by gl_get_line(), but in non-blocking
+ server mode, since the terminal is left in raw mode between calls to
+ gl_get_line(), this signal handling has to be done by the application.
+ Since there are many signals that can suspend or terminate a process,
+ as well as other signals that are important to gl_get_line(), such as
+ the SIGWINCH signal, which tells it when the terminal size has changed,
+ the gl_tty_signals() function is provided for installing signal han-
+ dlers for all pertinent signals.
+
+
+ int gl_tty_signals(void (*term_handler)(int),
+ void (*susp_handler)(int),
+ void (*cont_handler)(int),
+ void (*size_handler)(int));
+
+
+ What this does is use gl_get_line()'s internal list of signals to
+ assign specified signal handlers to groups of signals. The arguments of
+ this function are as follows.
+
+
+ term_handler - This is the signal handler that is to be
+ used to trap signals that by default
+ terminate any process that receives
+ them (eg. SIGINT or SIGTERM).
+
+ susp_handler - This is the signal handler that is to be
+ used to trap signals that by default
+ suspend any process that receives them,
+ (eg. SIGTSTP or SIGTTOU).
+
+ cont_handler - This is the signal handler that is to be
+ used to trap signals that are usually
+ sent when a process resumes after being
+ suspended (usually SIGCONT). Beware that there is
+ nothing to stop a user from sending one of these
+ signals at other times.
+
+ size_handler - This signal handler is used to trap
+ signals that are sent to processes when
+ their controlling terminals are resized
+ by the user (eg. SIGWINCH).
+
+
+ These arguments can all be the same, if so desired, and you can specify
+ SIG_IGN (ignore this signal) or SIG_DFL (use the system-provided
+ default signal handler) instead of a function where pertinent. In par-
+ ticular, it is rarely useful to trap SIGCONT, so the cont_handler argu-
+ ment will usually be SIG_DFL or SIG_IGN.
+
+ The gl_tty_signals() function uses the POSIX sigaction() function to
+ install these signal handlers, and it is careful to use the sa_mask
+ member of each sigaction structure to ensure that only one of these
+ signals is ever delivered at a time. This guards against different
+ instances of these signal handlers from simultaneously trying to write
+ to common global data, such as a shared sigsetjmp() buffer or a signal-
+ received flag.
+
+ The signal handlers that are installed by this function, should call
+ the gl_handle_signal().
+
+
+ void gl_handle_signal(int signo, GetLine *gl, int ngl);
+
+
+ The signo argument tells this function which signal it is being asked
+ to respond to, and the gl argument should be a pointer to the first
+ element of an array of ngl GetLine objects. If your application only
+ has one of these objects, just pass its pointer as the gl argument and
+ specify ngl as 1.
+
+ Depending on the signal that is being handled, this function does dif-
+ ferent things.
+
+
+ Terminal resize signals (SIGWINCH)
+ If the signal indicates that the terminal was resized, then it arranges
+ for the next call to gl_get_line() to ask the terminal for its new size
+ and redraw the input line accordingly. In order that gl_get_line() be
+ called as soon as possible to do this, gl_handle_signal() also arranges
+ that the next call to gl_pending_io() will return GLP_WRITE. Thus if
+ the application waits for I/O in select() or poll(), then the applica-
+ tion needs to ensure that these functions will be reliably aborted when
+ a signal is caught and handled by the application. More on this below.
+
+
+</pre><h2>Process termination signals.</h2><pre>
+ If the signal that was caught is one of those that by default termi-
+ nates any process that receives it, then gl_handle_signal() does the
+ following steps.
+
+ 1. First it blocks the delivery of all signals that can be
+ blocked (ie. SIGKILL and SIGSTOP can't be blocked)
+
+ 2. Next it calls gl_normal_io() for each of the ngl
+ GetLine objects. Note that this does nothing to any of the
+ GetLine objects that aren't currently in raw mode.
+
+ 3. Next it sets the signal handler of the signal to its default,
+ process-termination disposition.
+
+ 4. Next it re-sends the process the signal that was caught.
+
+ 5. Finally it unblocks delivery of this signal, which
+ results in the process being terminated.
+
+
+</pre><h2>Process suspension signals.</h2><pre>
+ If the default disposition of the signal is to suspend the process, the
+ same steps are executed as for process termination signals, except that
+ when the process is later resumed, gl_handle_signal() continues, and
+ does the following steps.
+
+ 6. It re-blocks delivery of the signal.
+
+ 7. It reinstates the signal handler of the signal to the one
+ that was displaced when its default disposition was substituted.
+
+ 8. For any of the GetLine objects that were in raw mode when
+ gl_handle_signal() was called, gl_handle_signal() then
+ calls gl_raw_io(), to resume entry of the input lines on
+ those terminals.
+
+ 9. Finally, it restores the signal process mask to how it
+ was when gl_handle_signal() was called.
+
+ Note that the process is suspended or terminated using the original
+ signal that was caught, rather than using the uncatchable SIGSTOP and
+ SIGKILL signals. This is important, because when a process is suspended
+ or terminated, the parent of the process may wish to use the status
+ value returned by the wait() system call to figure out which signal was
+ responsible. In particular, most shells use this information to print a
+ corresponding message to the terminal. Users would be rightly confused
+ if when their process received a SIGPIPE signal, the program responded
+ by sending itself a SIGKILL signal, and the shell then printed out the
+ provocative statement, "Killed!".
+
+
+</pre><h2>INTERRUPTING THE EVENT LOOP</h2><pre>
+ If a signal is caught and handled when the application's event loop is
+ waiting in select() or poll(), these functions will be aborted with
+ errno set to EINTR. When this happens the event loop should call
+ gl_pending_io(), before calling select() or poll() again. It should
+ then arrange for select() or poll() to wait for the type of I/O that
+ this reports. This is necessary, because any signal handler which calls
+ gl_handle_signal(), will frequently change the type of I/O that
+ gl_get_line() is waiting for.
+
+ Unfortunately, if a signal arrives between the statements which config-
+ ure the arguments of select() or poll() and the calls to these func-
+ tions, then the signal will not be seen by these functions, which will
+ then not be aborted. If these functions are waiting for keyboard input
+ from the user when the signal is received, and the signal handler
+ arranges to redraw the input line to accomodate a terminal resize or
+ the resumption of the process, then this redisplay will be end up being
+ delayed until the user hits the next key. Apart from puzzling the user,
+ this clearly isn't a serious problem. However there is a way, albeit
+ complicated, to completely avoid this race condition. The following
+ steps illustrate this.
+
+ 1. Block all of the signals that gl_get_line() catches,
+ by passing the signal set returned by gl_list_signals() to
+ sigprocmask().
+
+ 2. Call gl_pending_io() and set up the arguments of
+ select() or poll() accordingly.
+
+ 3. Call sigsetjmp() with a non-zero savesigs argument.
+
+ 4. Initially this sigsetjmp() statement will return zero,
+ indicating that control isn't resuming there after a matching
+ call to siglongjmp().
+
+ 5. Replace all of the handlers of the signals that gl_get_line()
+ is configured to catch, with a signal handler that first records
+ the number of the signal that was caught, in a file-scope variable,
+ then calls siglongjmp() with a non-zero value argument, to
+ return execution to the above sigsetjmp()
+ statement. Registering these signal handlers can conveniently be
+ done using the gl_tty_signals() function.
+
+ 6. Set the file-scope variable that the above signal handler uses to
+ record any signal that is caught to -1, so that we can check
+ whether a signal was caught by seeing if it contains a valid signal
+ number.
+
+ 7. Now unblock the signals that were blocked in step 1. Any signal
+ that was received by the process in between step 1 and now will
+ now be delivered, and trigger our signal handler, as will any
+ signal that is received until we block these signals again.
+
+ 8. Now call select() or poll().
+
+ 9. When select() returns, again block the signals that were
+ unblocked in step 7.
+
+ If a signal is arrived any time during the above steps, our signal han-
+ dler will be triggered and cause control to return to the sigsetjmp()
+ statement, where this time, sigsetjmp() will return non-zero, indicat-
+ ing that a signal was caught. When this happens we simply skip the
+ above block of statements, and continue with the following statements,
+ which are executed regardless of whether or not a signal is caught.
+ Note that when sigsetjmp() returns, regardless of why it returned, the
+ process signal mask is returned to how it was when sigsetjmp() was
+ called. Thus the following statements are always executed with all of
+ our signals blocked.
+
+ 9. Reinstate the signal handlers that were displaced in step 5.
+
+ 10. Check wether a signal was caught, by checking the file-scope
+ variable that the signal handler records signal numbers in.
+
+ 11. If a signal was caught, send this signal to the application
+ again, and unblock just this signal, so that it invokes the
+ signal handler which we just reinstated in step 10.
+
+ 12. Unblock all of the signals that were blocked in step 7.
+
+ Since this is complicated, note that demo3.c includes a working example
+ of how to do this. The method used there however, is more general than
+ the above. What it provides is a wrapper function around select() which
+ encompasses steps 3 to 11. In this wrapper, rather than use
+ gl_list_signals() to figure out the signals to block, and and
+ gl_tty_signals() to assign and revert signal handlers, one of its argu-
+ ments is a sigset_t which specifies which signals to block and assign
+ signal handlers to. This function thus doesn't depend on gl_get_line()
+ and can thus be used in other situations where race-condition-free sig-
+ nal handling is required.
+
+
+</pre><h2>SIGNALS CAUGHT BY GL_GET_LINE</h2><pre>
+ Since the application is expected to handle signals in non-blocking
+ server mode, gl_get_line() doesn't attempt to duplicate this when it is
+ being called. If one of the signals that it is configured to catch is
+ sent to the application while gl_get_line() is being called,
+ gl_get_line() reinstates the caller's signal handlers, then just before
+ returning, re-sends the signal to the process to let the application's
+ signal handler handle it. If the process isn't terminated by this sig-
+ nal, gl_get_line() returns NULL, and a following call to gl_return_sta-
+ tus() returns the enumerated value GLR_SIGNAL.
+
+
+</pre><h2>ABORTING LINE INPUT</h2><pre>
+ Often, rather than letting it terminate the process, applications
+ respond to the SIGINT user-interrupt signal by aborting the current
+ input line. The way to do this in non-blocking server-I/O mode is to
+ not call gl_handle_signal() when this signal is caught, but instead to
+ call the gl_abandon_line().
+
+
+ void gl_abandon_line(GetLine *gl);
+
+
+ This function arranges that when gl_get_line() is next called, it first
+ flushes any pending output to the terminal, then discardes the current
+ input line, outputs a new prompt on the next line, and finally starts
+ accepting input of a new input line from the user.
+
+
+</pre><h2>SIGNAL SAFE FUNCTIONS</h2><pre>
+ Provided that certain rules are followed, the following functions can
+ have been written to be safely callable from signal handlers. Other
+ functions in this library should not be called from signal handlers.
+
+
+ gl_normal_io()
+ gl_raw_io()
+ gl_handle_signal()
+ gl_abandon_line()
+
+
+ In order for this to be true, all signal handlers that call these func-
+ tions must be registered in such a way that only one instance of any
+ one of them can be running at one time. The way to do this is to use
+ the POSIX sigaction() function to register all signal handlers, and
+ when doing this, use the sa_mask member of the corresponding sigaction
+ structure, to indicate that all of the signals who's handlers invoke
+ the above functions, should be blocked when the current signal is being
+ handled. This prevents two signal handlers from operating on a GetLine
+ object at the same time.
+
+ To prevent signal handlers from accessing a GetLine object while
+ gl_get_line() or any of its associated public functions are operating
+ on it, all public functions associated with gl_get_line(), including
+ gl_get_line() itself, temporarily block the delivery of signals when
+ they are accessing GetLine objects. Beware that the only signals that
+ they block are the signals that gl_get_line() is currently configured
+ to catch, so be sure that if you call any of the above functions from
+ signal handlers, that the signals that these handlers are assigned to
+ are configured to be caught by gl_get_line() (see gl_trap_signal()).
+
+
+</pre><h2>USING TIMEOUTS TO POLL</h2><pre>
+ If instead of using select() or poll() to wait for I/O, your applica-
+ tion just needs to get out of gl_get_line() periodically to briefly do
+ something else before returning to accept input from the user, this can
+ be done in non-blocking server mode by using the gl_inactivity_time-
+ out() function (see <a href="gl_get_line.html"><b>gl_get_line</b></a>), to specify that a
+ callback function that returns GLTO_CONTINUE should be called whenever
+ gl_get_line() has been waiting for I/O for more than a specified amount
+ of time.
+
+ When this callback is triggered, gl_get_line() will return NULL, and a
+ following call to gl_return_status() will return GLR_BLOCKED.
+
+ Beware that gl_get_line() won't return until the user hasn't typed a
+ key for the specified interval, so if the interval is long, and the
+ user keeps typing, gl_get_line() may not return for a while. In other
+ words there is no guarantee that it will return in the time specified.
+
+
+</pre><h2>THE SERVER DEMO PROGRAM</h2><pre>
+ The demo3 program that is distributed with the library, provides a
+ working example of how to use non-blocking server I/O mode in a real
+ program. As far as the user is concerned, this program operates
+ identically to the main demo program (called demo), except that whereas
+ the main demo program uses the normal blocking I/O mode, demo3 using
+ non-blocking I/O and an external event loop. The source code can be
+ found in demo3.c, and the comments therein explain the various steps.
+
+
+</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"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="tecla.html"><b>tecla</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>, <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="gl_io_mode.html"><b>gl_io_mode</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/index.html b/libtecla-1.6.1/html/index.html
new file mode 100644
index 0000000..29889da
--- /dev/null
+++ b/libtecla-1.6.1/html/index.html
@@ -0,0 +1,122 @@
+<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.6.1. This may be obtained from:
+<P>
+ <a href="libtecla-1.6.1.tar.gz">http://www.astro.caltech.edu/~mcs/tecla/libtecla-1.6.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="tecla.html">tecla</a> - Documentation for users of programs which use gl_get_line().
+<LI> <a href="libtecla.html">libtecla</a> - A programmers introduction to the tecla library.
+<LI> <a href="gl_get_line.html">gl_get_line</a> - The interactive line-input function.
+<LI> <a href="gl_io_mode.html">gl_io_mode</a> - Using gl_get_line() in a non-blocking fashion.
+<LI> <a href="cpl_complete_word.html">cpl_complete_word</a> - The word (eg. filename) completion function.
+<LI> <a href="ef_expand_file.html">ef_expand_file</a> - The filename expansion function.
+<LI> <a href="pca_lookup_file.html">pca_lookup_file</a> - A directory-list based filename lookup and completion module.
+<LI> <a href="enhance.html">enhance</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,9 with any of gcc, Sun C, or g++.
+ Mandrake Linux 7.1 etc.., gcc
+ Red Hat Linux 7 etc.., gcc
+ Fedora Core 1, gcc
+ Suse Linux 6.4, gcc
+ IBM AIX 4.3.3, gcc
+ HP-UX 10.20, HP-UX 11, gcc, c89
+ FreeBSD, gcc
+ Alpha OSF1, cc, gcc
+ Mac OS X
+ Cygwin (running under Windows)
+ QNX
+ NetBSD 1.6, 386, gcc
+ SGI IRIX 6.5
+</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,9 with any of gcc, Sun C, or g++.
+ Mandrake Linux, gcc
+ RedHat Linux, gcc
+ Fedora Core, gcc
+ SuSE Linux, gcc
+ HP-UX 11, gcc
+ IBM AIX 4.3.3, gcc
+ Alpha OSF1, cc
+ SGI IRIX 6.5
+</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 (31-Oct-2004)
+</BODY>
diff --git a/libtecla-1.6.1/html/libtecla.html b/libtecla-1.6.1/html/libtecla.html
new file mode 100644
index 0000000..2b85d7a
--- /dev/null
+++ b/libtecla-1.6.1/html/libtecla.html
@@ -0,0 +1,138 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="libtecla.html"><b>libtecla</b></a> <a href="libtecla.html"><b>libtecla</b></a>
+
+
+
+</pre><h2>NAME</h2><pre>
+ libtecla - An interactive command-line input library.
+
+</pre><h2>SYNOPSIS</h2><pre>
+ @CC@ ... -ltecla -lcurses
+
+
+</pre><h2>DESCRIPTION</h2><pre>
+ The tecla library provides programs with interactive command line edit-
+ ing 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 the calling program.
+
+ The various parts of the library are documented in the following man
+ pages:
+
+ <a href="tecla.html"><b>tecla</b></a> - Use level documentation of the
+ command-line editing facilities
+ provided by gl_get_line().
+ <a href="gl_get_line.html"><b>gl_get_line</b></a> - The interactive line-input module.
+ <a href="gl_io_mode.html"><b>gl_io_mode</b></a> - How to use gl_get_line() in an
+ incremental, non-blocking fashion.
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a> - The word completion module.
+ <a href="ef_expand_file.html"><b>ef_expand_file</b></a> - The filename expansion module.
+ <a href="pca_lookup_file.html"><b>pca_lookup_file</b></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"><b>enhance</b></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 read-
+ ing directory entries when doing filename completion. The reentrant
+ version of the library is usually called libtecla_r.a instead of libte-
+ cla.a, so if only the latter is available, it probably isn't the cor-
+ rect 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 comple-
+ tion of incomplete usernames in ~username/ expressions is disabled.
+ This doesn't disable expansion 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 formal 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 cen-
+ ters 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"><b>gl_get_line</b></a>, <a href="tecla.html"><b>tecla</b></a>, <a href="gl_io_mode.html"><b>gl_io_mode</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>, <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>, <a href="enhance.html"><b>enhance</b></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.
+
+
+
+ <a href="libtecla.html"><b>libtecla</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/pca_lookup_file.html b/libtecla-1.6.1/html/pca_lookup_file.html
new file mode 100644
index 0000000..d5e1e7b
--- /dev/null
+++ b/libtecla-1.6.1/html/pca_lookup_file.html
@@ -0,0 +1,312 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="pca_lookup_file.html"><b>pca_lookup_file</b></a> <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+
+
+
+</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 &lt;libtecla.h&gt;
+
+ 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 libte-
+ cla(@LIBR_MANEXT@) man page).
+
+ PathCache objects allow an application to search for files in any colon
+ separated list of directories, such as the unix execution PATH environ-
+ ment variable. Files in absolute directories are cached in a PathCache
+ object, whereas relative directories are scanned as needed. Using a
+ PathCache object, you can look up the full pathname of a simple file-
+ name, 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 pro-
+ vided for only selecting specific types of files. The obvious applica-
+ tion of this facility is to provide Tab-completion and lookup of exe-
+ cutable 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 &lt;stdio.h&gt;
+ #include &lt;stdlib.h&gt;
+ #include &lt;libtecla.h&gt;
+
+ 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&lt;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 directories, such as
+ "/usr/bin:/home/mcs/bin:.". This can include directories specified by
+ absolute pathnames such as "/usr/bin", as well as sub-directories spec-
+ ified by relative pathnames such as "." or "bin". Files in the absolute
+ directories 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. Otherwise, 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 file-
+ name cache, is achieved by passing the provided pca_path_completions()
+ callback function to the cpl_complete_word() function (see the cpl_com-
+ plete_word(@FUNC_MANEXT@) man page).
+
+ CPL_MATCH_FN(pca_path_completions);
+
+ This callback requires that its data argument be a pointer to a PcaP-
+ athConf 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 functions which allow you to individually change
+ these parameters are discussed below.
+
+ By default, the pca_path_completions() callback function searches back-
+ wards 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 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 completion and lookup functions to
+ be selective in the filenames that they return. This is done by regis-
+ tering 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 per-
+ missions of the file and the permissions of its parent directories, and
+ only returns 1 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 PATH environment vari-
+ able. The example program given earlier in this man page provides a
+ demonstration of this.
+
+ Beware that if somebody tries to complete an empty string, your call-
+ back will get called once for every file in the cache, which could num-
+ ber 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.
+
+ 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 pca_scan_path()
+ is called, and whenever pca_set_check_fn() is called with changed call-
+ back function or data arguments.
+
+
+</pre><h2>ERROR HANDLING</h2><pre>
+ If pca_scan_path() reports that an error occurred by returning 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 completion in ~username/ expressions, in cpl_path_comple-
+ tions().
+
+ Using the libtecla_r.a 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 PathCache object. In other words, if
+ two threads want to do path searching, they should each call new_Path-
+ Cache() 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"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+</pre>
+</body>
diff --git a/libtecla-1.6.1/html/release.html b/libtecla-1.6.1/html/release.html
new file mode 100644
index 0000000..b048f4f
--- /dev/null
+++ b/libtecla-1.6.1/html/release.html
@@ -0,0 +1,590 @@
+<html><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.6.1:
+
+ This is primarily a minor bug-fix release.
+
+ One added feature is the ability to call gl_normal_io() from
+ callbacks registered by gl_watch_fd() and
+ gl_inactivity_timeout(). This allows these callbacks to cleanly
+ suspend line editing before either reading from the terminal, or
+ writing to the terminal; and then subsequently causes the input line
+ to be automatically redisplayed, and line-editing to be resumed by
+ gl_get_line(), as soon as the callback returns.
+
+ Another minor change is that if the terminal type specified in the
+ TERM environment variable is set to "dumb", gl_get_line() now treats
+ the terminal as though it were a non-interactive stream, rather than
+ treating it as a VT100-compatible terminal. This means that it
+ doesn't either prompt for input, or perform any command-line
+ editing, even when it really is interacting with a terminal. This is
+ aimed at the rare situation where a third-pary program that connects
+ to libtecla through an embedded pseudo-terminal, needs to be forced
+ to behave as though it weren't talking to a terminal, in order that
+ it be useable in non-interactive scripts.
+
+ Note that in the previous release, the optional configuration
+ function, gl_tty_signals(), was incorrectly swapping the suspend and
+ terminal signal handlers before installing them.
+
+ A configuration problem that prevented select() from being used
+ under MacOS X, has been fixed.
+
+ Although not documented in the man page, it was meant to be possible
+ to take the input line that one call to gl_get_line() returned, and
+ ask the next call to gl_get_line() to present it back to the user
+ for re-editing, simply by passing the pointer returned by one call
+ to gl_get_line() as the start_line argument of the next call to
+ gl_get_line(). This feature unfortunately stopped working in 1.6.0,
+ so this release restores it, and officially documents it in the man
+ page documentation of gl_get_line().
+
+ In the previous version of the library, calling gl_terminal_size()
+ on a system without SIGWINCH support, would crash the
+ application. This has been fixed.
+
+ Libtecla now apparently compiles cleanly under IRIX.
+
+Version 1.6.0:
+
+ This release is primarily a bug-fix release. However there are also
+ four new functions, so the minor version number has been
+ incremented to reflect this.
+
+ Two of the new functions are gl_automatic_history() and
+ gl_append_history(). The former of these functions allows the
+ application to tell gl_get_line() not to automatically archive
+ entered lines in the history list. The second of these functions
+ allows the application to explicitly append a line to the history
+ list. Thus together, these two functions allow the calling
+ application to take over control of what is placed in the history
+ list.
+
+ The third new function is gl_query_char(), which prompts the user
+ for a single character reply, which the user can then type without
+ having to hit return to enter it. Unless echoing is disabled, the
+ character that is entered is then displayed after the prompt,
+ and a newline is started.
+
+ Finally, the 4th new function is gl_read_char(), which also reads
+ a single character from the user, but doesn't prompt the user, write
+ anything to the terminal, or disturb any partially entered input
+ line. It is thus safe to call this function not only from between
+ calls to gl_get_line(), but also from application callback
+ functions, even if gl_normal_io() hasn't been called.
+
+ When using the history-search-backwards or history-search-forwards
+ actions, if the search prefix that the user typed, contains any of
+ the *,? or [ globbing characters, it is now treated as a glob
+ pattern to be matched against historical lines, instead of a simple
+ prefix.
+
+ I have added a --without-file-system option to the configure
+ script. This is intended for use in embedded systems that either
+ don't have filesystems, or where the file-system code in libtecla is
+ seen as unwanted bloat. See the INSTALL document for details.
+
+ Similarly, I also added a --without-file-actions option to the
+ configure script. This allows the application author/installer to
+ prevent users of gl_get_line() from accessing the filesystem with
+ the builtin actions of gl_get_line(). It does this by removing a
+ number of action functions, such as expand-filename, and list-glob,
+ and by changing the default behavior of other actions, such as
+ complete-word and list-or-eof, to show no completions.
+
+ Now to the bugs that have been fixed. Version 1.5.0 had a lot of big
+ internal changes, so there are a number of bugs that needed to be
+ fixed. There was a bug which caused a crash if gl_load_history()
+ was called multiple times. There was another bug which caused a
+ prompt not to be displayed on the next line after switching from
+ reading input from a file to reading from the terminal. Also, in
+ tecla configuration files, backslash escaped characters within
+ key-binding key-sequences weren't being escaped. Thus ^\\ got
+ interpretted as a control-\ followed by a \ character instead of as
+ a control-\. There was a bug in the history recall mechanism which
+ caused the search prefix to be forgotten in certain complicated
+ usage scenarios. There was a minor memory leak in the
+ gl_configure_getline() function. Finally, if gl_get_line() was
+ aborted by a signal, or any other abnormal event, the value of errno
+ which originally indicated what had happened, got zeroed by the
+ code that restored the terminal to a usable state. Thus the
+ application couldn't figure out what had caused the error, apart
+ from by looking at gl_return_status(). All of these bugs have been
+ fixed.
+
+ In the Makefile, there were a number of places where install-sh was
+ invoked without a path prefix. This has now been remedied.
+
+ A fully functional workaround for a bug in Solaris' terminal I/O
+ code has also been implemented. This bug, which only manifested
+ itself in libtecla's uncommonly used non-blocking server I/O mode,
+ caused characters entered while in normal I/O mode, between calls to
+ gl_get_line() to be invisible to the next call to gl_get_line(),
+ until the user typed at least one more key after raw terminal mode
+ was restored.
+
+ The Gnu autoconf config.guess and config.sub scripts have been
+ updated to their latest versions. Apparently the old versions that I
+ was previously using were too old to know about certain BSD ports.
+
+Version 1.5.0:
+
+ This release includes several major new features for those using
+ gl_get_line(), shared library support in Darwin, better cross
+ compilation support, and various minor bug fixes.
+
+ The biggest new feature is the option of a non-blocking I/O mode, in
+ which gl_get_line() can safely be called from an application's
+ external event-loop to incrementally read input lines from the user.
+ This feature is documented in the gl_io_mode(3) man page.
+
+ In addition, there is now support for the definition of additional
+ word-completion action functions, which can then be bound to
+ different keys. See the documentation of the gl_completion_action()
+ function in the gl_get_line(3) man page.
+
+ Externally defined action functions can also be defined, although
+ presently they don't have write access to the input line, so they
+ are restricted to operations that display information text to the
+ terminal, or modify the environment of the calling application in
+ some way. See the documentation of the gl_register_action() function
+ in the gl_get_line(3) man page.
+
+ Some of the non-blocking I/O support functions can also be used for
+ improved signal handling in the normal blocking mode. In particular,
+ the gl_list_signals() and gl_catch_blocked() functions make it
+ easier to write reliable signal handling around gl_get_line(). The
+ new "RELIABLE SIGNAL HANDLING" section of the gl_get_line(3) man
+ page is intended as an introduction to this subject.
+
+ Programs can now clear the terminal between calls to gl_get_line(),
+ by calling the new gl_erase_terminal() function.
+
+ The gl_display_text() function, now used in the demos to display
+ introductory banners, is provided for formatting text according to
+ the width of the terminal.
+
+ It is now possible to install inactivity timeout callbacks in
+ gl_get_line(), using the new gl_inactivity_timeout() function.
+
+ The new gl_set_term_size() function allows the application to
+ explicitly set the terminal size, for cases, such as when one is
+ using a terminal at the end of a serial lineq, where the terminal
+ driver doesn't send the process a SIGWINCH when the terminal size
+ changes.
+
+ The new gl_bind_keyseq() function provides a convenient
+ alternative to gl_configure_getline(), for binding or unbinding
+ one key-sequence at a time.
+
+ gl_get_line()s signal handling, file-descriptor event-handling,
+ inactivity-timeout handling and server-mode non-blocking I/O
+ features now not only work when input is coming from a terminal, but
+ now also work when input is coming from non-interactive streams,
+ such as files and pipes.
+
+ The history implementation has been re-written to make it more
+ efficient and easier to modify. The biggest user-level change is
+ that when recalling history lines using a search prefix, the same
+ line is no longer returned more than once in a row. Previously this
+ duplicate elimination only worked when one was recalling a line
+ without specifying a search prefix, and this was naively performed
+ by preventing neighboring duplicates from existing in the history
+ list, rather than by skipping duplicates at search time.
+
+ In previous versions of the library, when gl_get_line() and its
+ associated public functions detected invalid arguments, or couldn't
+ allocate memory, etc, error messages were written to stderr. This
+ isn't appropriate for library functions, so instead of writing such
+ messages to stderr, these messages are now recorded in buffers
+ within the affected GetLine object. The latest error message can
+ then subsequently be queried by calling gl_error_message(). The use
+ of errno has also been expanded, and a new function called
+ gl_return_status() has been provided to expand on the cause of the
+ last return from gl_get_line().
+
+ User level usage and configuration information has now been split
+ out of the gl_get_line(3) man page into a separate tecla(7) man
+ page. The enhance(3) man page has also been renamed to enhance(1).
+
+ When expanding "~/", gl_get_line() now checks for, and returns the
+ value of the HOME environment variable, if it exists, in preference
+ to looking up the directory of the current user in the password
+ file.
+
+ When the terminal was resized to a narrower width, previous versions
+ of gl_get_line() would redraw the line higher up the terminal. This
+ bug has been fixed. A bug in history recall has also been fixed, in
+ which an error message was being generated if one attempted to
+ recall a line while the cursor was at the end of the longest
+ possible input line. A more serious bug, in which callbacks
+ registered by gl_watch_fd() weren't being called for write-events,
+ has also been fixed. Finally, a few minor fixes have been made to
+ improve support under QNX and Mac OS X.
+
+ Beware that in this release, much of the underlying code has
+ undergone some radical re-work, so although backwards compatibility
+ of all documented features has been preserved, there may be some
+ lingering bugs that could break existing programs. So, if you plan
+ to use this version in production code, please test it as far as
+ possible within your application before releasing it to your
+ clients, and as always, please report any unexpected behavior.
+
+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></html>
diff --git a/libtecla-1.6.1/html/tecla.html b/libtecla-1.6.1/html/tecla.html
new file mode 100644
index 0000000..6f270c1
--- /dev/null
+++ b/libtecla-1.6.1/html/tecla.html
@@ -0,0 +1,1120 @@
+<head>
+<title>Manual Page</title>
+</head>
+<body>
+<pre>
+<a href="tecla.html"><b>tecla</b></a> <a href="tecla.html"><b>tecla</b></a>
+
+
+
+</pre><h2>NAME</h2><pre>
+ tecla, teclarc - The user interface provided by the Tecla library.
+
+</pre><h2>DESCRIPTION</h2><pre>
+ This man page describes the command-line editing features that are
+ available to users of programs that read keyboard input via the Tecla
+ library. Users of the tcsh shell will find the default key-bindings
+ very familiar. Users of the bash shell will also find it quite famil-
+ iar, but with a few minor differences, most notably in how forward and
+ backward searches through the list of historical commands are per-
+ formed. There are two major editing modes, one with emacs-like key-
+ bindings and another with vi-like key-bindings. By default emacs mode
+ is enabled, but vi mode can alternatively be selected via the user's
+ configuration file. This file can also be used to change the bindings
+ of individual keys to suit the user's preferences. By default, tab com-
+ pletion is provided. If the application hasn't reconfigured this to
+ complete other types of symbols, then tab completion completes file-
+ names.
+
+
+</pre><h2>KEY SEQUENCE NOTATION</h2><pre>
+ In the rest of this man page, and also in all Tecla configuration
+ files, key-sequences are expressed as follows.
+
+
+ ^A or C-a
+ This is a control-A, entered by pressing the control key at
+ the same time as the A key.
+
+ \E or M-
+ In key-sequences, both of these notations can be entered
+ either by pressing the escape key, then the following key, or by
+ pressing the Meta key at the same time as the following 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.
+
+ up
+ This refers to the up-arrow key.
+
+ down
+ This refers to the down-arrow key.
+
+ left
+ This refers to the left-arrow key.
+
+ right
+ This refers to the right-arrow key.
+
+ a
+ This is just a normal A key.
+
+
+
+</pre><h2>THE TECLA CONFIGURATION FILE</h2><pre>
+ By default, Tecla looks for a file called .teclarc in your home direc-
+ tory (ie. ~/.teclarc). If it finds this file, it reads it, interpret-
+ ing 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 unrecog-
+ nized control-sequence is typed, place the following line in the con-
+ figuration file:
+
+ nobeep
+
+ An example of a key binding line in the configuration file is the fol-
+ lowing.
+
+ 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 fol-
+ lowing 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 printable 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 following 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 exam-
+ ple, by not specifying an action function, the following command
+ unbinds the default beginning-of-line action from the ^A key sequence:
+
+ bind ^A
+
+ If you create a ~/.teclarc configuration file, but it appears to have
+ no effect on the program, check the documentation of the program to see
+ if the author chose a different name for this file.
+
+
+</pre><h2>FILENAME AND TILDE COMPLETION</h2><pre>
+ With the default key bindings, pressing the TAB key (aka. ^I) results
+ in Tecla attempting to complete the incomplete filename that precedes
+ the cursor. Tecla 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, then
+ Tecla 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, Tecla 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, Tecla 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(@LIBR_MANEXT@) man page for more details.
+
+
+</pre><h2>FILENAME EXPANSION</h2><pre>
+ With the default key bindings, pressing ^X* causes Tecla to expand the
+ filename that precedes the cursor, replacing ~/ and ~user/ expressions
+ with the corresponding home directories, and replacing $envvar expres-
+ sions 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() func-
+ tion. See the <a href="ef_expand_file.html"><b>ef_expand_file</b></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. Alternatively, you can do the same with the ^P, and ^N
+ 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.
+
+ 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 pre-
+ cedes 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", Tecla would recall the "ls -l get-
+ line.c" line. Pressing M-p again would recall the "ls ~/tecla/" line.
+
+ Note that if the string that you are searching for, contains any of the
+ special characters, *, ?, or '[', then it is interpretted as a pattern
+ to be matched. Thus, cotinuing with the above example, after typing in
+ the list of commands shown, if you then typed:
+
+ *tecla*
+
+ and hit M-p, then the "emacs ~/tecla/getline.c" line would be recalled
+ first, since it contains the word tecla somewhere in the line, Simi-
+ larly, hitting M-p again, would recall the "ls ~/tecla/" line, and hit-
+ ting it once more would recall the "ls ~/tecla/" line. The pattern syn-
+ tax is the same as that described for filename expansion, in the
+ ef_expand_file(@LIBR_MANEXT@ man page.
+
+
+</pre><h2>HISTORY FILES</h2><pre>
+ Authors of programs that use the Tecla library have the option of sav-
+ ing historical command-lines in a file before exiting, and subsequently
+ reading them back in from this file when the program is next started.
+ There is no standard name for this file, since it makes sense for each
+ application to use its own history file, so that commands from differ-
+ ent applications don't get mixed up.
+
+
+</pre><h2>INTERNATIONAL CHARACTER SETS</h2><pre>
+ Since libtecla version 1.4.0, Tecla 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,
+
+ 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 variables are defined, or the program
+ neglects to call setlocale, 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.
+
+
+ Meta keys and locales
+ Beware that in most locales other than the default C locale, meta char-
+ acters 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 compose key without unexpectedly triggering meta
+ key bindings. You can still invoke meta bindings, since there are actu-
+ ally two ways to do this. For example the binding M-c can also be
+ invoked by pressing the escape key momentarily, then pressing 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 generate 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 continue 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 dis-
+ played 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.
+
+
+ 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 laptop the xev program reports that pressing this key gen-
+ erates 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, fol-
+ lowed by ", followed by i.
+
+
+</pre><h2>THE AVAILABLE KEY BINDING FUNCTIONS</h2><pre>
+ The following is a list of the editing functions provided by the Tecla
+ library. The names in the leftmost column of the list can be used in
+ configuration files to specify which function a given key or combina-
+ tion of keys should invoke. They are also used in the next two sections
+ to list the default key-bindings in emacs and vi modes.
+
+ 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 &gt; 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 Tecla 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.
+
+ Under UNIX the terminal driver sets a number of special keys for cer-
+ tain 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 -&gt; user-interrupt
+ ^\ -&gt; abort
+ ^Z -&gt; suspend
+ ^Q -&gt; start-output
+ ^S -&gt; stop-output
+ ^V -&gt; literal-next
+
+ 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 -&gt; cursor-right
+ left -&gt; cursor-left
+ up -&gt; up-history
+ down -&gt; down-history
+
+ The remaining bindings don't depend on the terminal setttings.
+
+ ^F -&gt; cursor-right
+ ^B -&gt; cursor-left
+ M-i -&gt; insert-mode
+ ^A -&gt; beginning-of-line
+ ^E -&gt; end-of-line
+ ^U -&gt; delete-line
+ ^K -&gt; kill-line
+ M-f -&gt; forward-word
+ M-b -&gt; backward-word
+ ^D -&gt; del-char-or-list-or-eof
+ ^H -&gt; backward-delete-char
+ ^? -&gt; backward-delete-char
+ M-d -&gt; forward-delete-word
+ M-^H -&gt; backward-delete-word
+ M-^? -&gt; backward-delete-word
+ M-u -&gt; upcase-word
+ M-l -&gt; downcase-word
+ M-c -&gt; capitalize-word
+ ^R -&gt; redisplay
+ ^L -&gt; clear-screen
+ ^T -&gt; transpose-chars
+ ^@ -&gt; set-mark
+ ^X^X -&gt; exchange-point-and-mark
+ ^W -&gt; kill-region
+ M-w -&gt; copy-region-as-kill
+ ^Y -&gt; yank
+ ^P -&gt; up-history
+ ^N -&gt; down-history
+ M-p -&gt; history-search-backward
+ M-n -&gt; history-search-forward
+ ^I -&gt; complete-word
+ ^X* -&gt; expand-filename
+ ^X^F -&gt; read-from-file
+ ^X^R -&gt; read-init-files
+ ^Xg -&gt; list-glob
+ ^Xh -&gt; list-history
+ M-&lt; -&gt; beginning-of-history
+ M-&gt; -&gt; end-of-history
+ \n -&gt; newline
+ \r -&gt; newline
+ M-o -&gt; repeat-history
+ M-^V -&gt; vi-mode
+
+ M-0, M-1, ... M-9 -&gt; digit-argument (see below)
+
+ Note that ^I is what the TAB key generates, and that ^@ can be gener-
+ ated 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 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.
+
+ To learn how to tell the Tecla library to use vi mode instead of the
+ default emacs editing mode, see the earlier section entitled THE TECLA
+ CONFIGURATION FILE.
+
+ Under UNIX the terminal driver sets a number of special keys for cer-
+ tain 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 command to change these keys, then the default bindings should
+ match.
+
+ ^C -&gt; user-interrupt
+ ^\ -&gt; abort
+ ^Z -&gt; suspend
+ ^Q -&gt; start-output
+ ^S -&gt; stop-output
+ ^V -&gt; literal-next
+ M-^C -&gt; user-interrupt
+ M-^\ -&gt; abort
+ M-^Z -&gt; suspend
+ M-^Q -&gt; start-output
+ M-^S -&gt; 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 ta-
+ ble. Thus, once in command mode, when you type the letter i, for exam-
+ ple, 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 different key sequences
+ when their cursor keys are pressed.
+
+ right -&gt; cursor-right
+ left -&gt; cursor-left
+ up -&gt; up-history
+ down -&gt; 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 -&gt; list-or-eof
+ ^G -&gt; list-glob
+ ^H -&gt; backward-delete-char
+ ^I -&gt; complete-word
+ \r -&gt; newline
+ \n -&gt; newline
+ ^L -&gt; clear-screen
+ ^N -&gt; down-history
+ ^P -&gt; up-history
+ ^R -&gt; redisplay
+ ^U -&gt; backward-kill-line
+ ^W -&gt; backward-delete-word
+ ^X* -&gt; expand-filename
+ ^X^F -&gt; read-from-file
+ ^X^R -&gt; read-init-files
+ ^? -&gt; 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 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.
+
+ M-\ -&gt; cursor-right (Meta-space)
+ M-$ -&gt; end-of-line
+ M-* -&gt; expand-filename
+ M-+ -&gt; down-history
+ M-- -&gt; up-history
+ M-&lt; -&gt; beginning-of-history
+ M-&gt; -&gt; end-of-history
+ M-^ -&gt; beginning-of-line
+ M-; -&gt; repeat-find-char
+ M-, -&gt; invert-refind-char
+ M-| -&gt; goto-column
+ M-~ -&gt; change-case
+ M-. -&gt; vi-repeat-change
+ M-% -&gt; find-parenthesis
+ M-a -&gt; vi-append
+ M-A -&gt; vi-append-at-eol
+ M-b -&gt; backward-word
+ M-B -&gt; backward-word
+ M-C -&gt; vi-change-rest-of-line
+ M-cb -&gt; vi-backward-change-word
+ M-cB -&gt; vi-backward-change-word
+ M-cc -&gt; vi-change-line
+ M-ce -&gt; vi-forward-change-word
+ M-cE -&gt; vi-forward-change-word
+ M-cw -&gt; vi-forward-change-word
+ M-cW -&gt; vi-forward-change-word
+ M-cF -&gt; vi-backward-change-find
+ M-cf -&gt; vi-forward-change-find
+ M-cT -&gt; vi-backward-change-to
+ M-ct -&gt; vi-forward-change-to
+ M-c; -&gt; vi-change-refind
+ M-c, -&gt; vi-change-invert-refind
+ M-ch -&gt; vi-backward-change-char
+ M-c^H -&gt; vi-backward-change-char
+ M-c^? -&gt; vi-backward-change-char
+ M-cl -&gt; vi-forward-change-char
+ M-c\ -&gt; vi-forward-change-char (Meta-c-space)
+ M-c^ -&gt; vi-change-to-bol
+ M-c0 -&gt; vi-change-to-bol
+ M-c$ -&gt; vi-change-rest-of-line
+ M-c| -&gt; vi-change-to-column
+ M-c% -&gt; vi-change-to-parenthesis
+ M-dh -&gt; backward-delete-char
+ M-d^H -&gt; backward-delete-char
+ M-d^? -&gt; backward-delete-char
+ M-dl -&gt; forward-delete-char
+ M-d -&gt; forward-delete-char (Meta-d-space)
+ M-dd -&gt; delete-line
+ M-db -&gt; backward-delete-word
+ M-dB -&gt; backward-delete-word
+ M-de -&gt; forward-delete-word
+ M-dE -&gt; forward-delete-word
+ M-dw -&gt; forward-delete-word
+ M-dW -&gt; forward-delete-word
+ M-dF -&gt; backward-delete-find
+ M-df -&gt; forward-delete-find
+ M-dT -&gt; backward-delete-to
+ M-dt -&gt; forward-delete-to
+ M-d; -&gt; delete-refind
+ M-d, -&gt; delete-invert-refind
+ M-d^ -&gt; backward-kill-line
+ M-d0 -&gt; backward-kill-line
+ M-d$ -&gt; kill-line
+ M-D -&gt; kill-line
+ M-d| -&gt; delete-to-column
+ M-d% -&gt; delete-to-parenthesis
+ M-e -&gt; forward-word
+ M-E -&gt; forward-word
+ M-f -&gt; forward-find-char
+ M-F -&gt; backward-find-char
+ M-- -&gt; up-history
+ M-h -&gt; cursor-left
+ M-H -&gt; beginning-of-history
+ M-i -&gt; vi-insert
+ M-I -&gt; vi-insert-at-bol
+ M-j -&gt; down-history
+ M-J -&gt; history-search-forward
+ M-k -&gt; up-history
+ M-K -&gt; history-search-backward
+ M-l -&gt; cursor-right
+ M-L -&gt; end-of-history
+ M-n -&gt; history-re-search-forward
+ M-N -&gt; history-re-search-backward
+ M-p -&gt; append-yank
+ M-P -&gt; yank
+ M-r -&gt; vi-replace-char
+ M-R -&gt; vi-overwrite
+ M-s -&gt; vi-forward-change-char
+ M-S -&gt; vi-change-line
+ M-t -&gt; forward-to-char
+ M-T -&gt; backward-to-char
+ M-u -&gt; vi-undo
+ M-w -&gt; forward-to-word
+ M-W -&gt; forward-to-word
+ M-x -&gt; forward-delete-char
+ M-X -&gt; backward-delete-char
+ M-yh -&gt; backward-copy-char
+ M-y^H -&gt; backward-copy-char
+ M-y^? -&gt; backward-copy-char
+ M-yl -&gt; forward-copy-char
+ M-y\ -&gt; forward-copy-char (Meta-y-space)
+ M-ye -&gt; forward-copy-word
+ M-yE -&gt; forward-copy-word
+ M-yw -&gt; forward-copy-word
+ M-yW -&gt; forward-copy-word
+ M-yb -&gt; backward-copy-word
+ M-yB -&gt; backward-copy-word
+ M-yf -&gt; forward-copy-find
+ M-yF -&gt; backward-copy-find
+ M-yt -&gt; forward-copy-to
+ M-yT -&gt; backward-copy-to
+ M-y; -&gt; copy-refind
+ M-y, -&gt; copy-invert-refind
+ M-y^ -&gt; copy-to-bol
+ M-y0 -&gt; copy-to-bol
+ M-y$ -&gt; copy-rest-of-line
+ M-yy -&gt; copy-line
+ M-Y -&gt; copy-line
+ M-y| -&gt; copy-to-column
+ M-y% -&gt; copy-to-parenthesis
+ M-^E -&gt; emacs-mode
+ M-^H -&gt; cursor-left
+ M-^? -&gt; cursor-left
+ M-^L -&gt; clear-screen
+ M-^N -&gt; down-history
+ M-^P -&gt; up-history
+ M-^R -&gt; redisplay
+ M-^D -&gt; list-or-eof
+ M-^I -&gt; complete-word
+ M-\r -&gt; newline
+ M-\n -&gt; newline
+ M-^X^R -&gt; read-init-files
+ M-^Xh -&gt; list-history
+
+ M-0, M-1, ... M-9 -&gt; 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 inter-
+ preted as a repeat count by most bindings. A notable exception is the
+ goto-column binding, which interprets 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 bind-
+ ings 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 function 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 it does in the vi editor itself.
+ So for example, in vi command 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>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"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="gl_io_mode.html"><b>gl_io_mode</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
+ <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>, <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>
+
+
+</pre><h2>AUTHOR</h2><pre>
+ Martin Shepherd (mcs@astro.caltech.edu)
+
+
+
+ <a href="tecla.html"><b>tecla</b></a>
+</pre>
+</body>