diff options
Diffstat (limited to 'libtecla-1.6.3/html')
| -rw-r--r-- | libtecla-1.6.3/html/changes.html | 2826 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/cpl_complete_word.html | 477 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/ef_expand_file.html | 273 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/enhance.html | 105 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/gl_get_line.html | 2407 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/gl_io_mode.html | 634 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/index.html | 73 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/libtecla.html | 199 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/pca_lookup_file.html | 420 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/release.html | 604 | ||||
| -rw-r--r-- | libtecla-1.6.3/html/tecla.html | 1276 |
11 files changed, 9294 insertions, 0 deletions
diff --git a/libtecla-1.6.3/html/changes.html b/libtecla-1.6.3/html/changes.html new file mode 100644 index 0000000..ed34d3b --- /dev/null +++ b/libtecla-1.6.3/html/changes.html @@ -0,0 +1,2826 @@ +<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. + +09/11/2014 mcs@astro.caltech.edu + configure.in configure + Dominyk Tiller reported that libtecla didn't compile on + Mac OS X, due to libgcc.a being cited in the makefile + without any path. This turned out to be because Gnu + autoconf claims that the clang compiler is gcc, and clang + has a -print-libgcc-file-name, but this only prints + libgcc.a. I have modified the configure script to check + whether the path returned by -print-libgcc-file-name + actually exists and only use it if it does. + +27/10/2014 Jon Szymaniak (documented here by mcs@astro.caltech.edu) + Makefile.rules + Use $(AR) instead of plain ar, so that cross-compilation + uses the correct ar program when cross-compiling. + + Add $(TARGETS) dependency to building the demo programs + and the enhance program. When using parallel compilation + this is needed to ensure that the library is compiled + before the demos. + +10/04/2013 mcs@astro.caltech.edu + Makefile.in + Jonathan Niehof reported that libtecla wouldn't compile if + there were spaces in LDFLAGS and pointed out that there should + be quotes around $(LDFLAGS) in Makefile.in. This also applied + to a few other variables cited in the same way. + +10/06/2012 mcs@astro.caltech.edu + enhance.c configure.in + I had incorrectly assumed that system-V pseudo-terminal + allocation and system-V streams terminals always went + together. However system-V pseudo terminal allocation is + now part of UNIX98, and this has been adopted into many BSD + style operating systems, without the use of system-V + streams. On such systems the lack of system-V streams IOCTL + opcodes prevented system-V pseudo-terminal allocation being + used. This was hidden under Linux until recently, because + it had a stropts.h file, which made it appear as though + Linux supported system-V streams terminals. + + I have now created separate configuration tests and options + in the configure script for system-V terminal allocation + and system-V streams. On systems that only have the former, + the latter won't be used. + +16/05/2005 mcs@astro.caltech.edu + getline.c + When an initial input line was presented to gl_get_line() + for editing, the new input line was incorrectly appended to + the previous input line, instead of replacing it. + +10/01/2004 Derek Jones (documented here by mcs@astro.caltech.edu) + getline.c + Derek discovered that the function that computes the + width of the prompt, was not correctly skipping over 3 of + the 6 possible prompt-formatting directives. Thus, when + the %f,%p or %v prompt-formatting directives were used, + the width of the prompt was incorrectly calculated. The + fix was to copy the list of directives from + gl_display_prompt(). I have also added a comment to + gl_display_prompt(), to warn anybody who adds or removes + formatting directives there, to also do the same to + gl_displayed_prompt_width(). + +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->line[] + and gl->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->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->endline flag in conflicting ways in + two places. To fix this I have created a gl->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->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->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->term_curpos and + gl->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->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->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 > 127 were only printed if preceded by the + literal-next action. Alternatively, by placing the + command literal_if_printable in the tecla configuration + file, all printable characters are treated as literal + characters, even if they are bound to action functions. + + For international users of programs written by + programmers that weren't aware of the need to call + setlocale() to support alternate character sets, the + configuration file can now also contain the single-word + command "setlocale", which tells gl_get_line() to remedy + this. + +27/11/2001 mcs@astro.caltech.edu + demo.c demo2.c enhance man3/gl_get_line.3 + All demos and programs now call setlocale(LC_CTYPE,""). + This makes them support character sets of different + locales, where specified with the LC_CTYPE, LC_ALL, or + LANG environment variables. I also added this to the demo + in the man page, and documented its effect. + +27/11/2001 mcs@astro.caltech.edu + getline.c + When displaying unsigned characters with values over + 127 literally, previously it was assumed that they would + all be displayable. Now isprint() is consulted, and if it + says that a character isn't printable, the character code + is displayed in octal like \307. In non-C locales, some + characters with values > 127 are displayable, and + isprint() tells gl_get_line() which are and which aren't. + +27/11/2001 mcs@astro.caltech.edu + getline.c pathutil.c history.c enhance.c demo2.c + All arguments of the ctype.h character class functions + are now cast to (int)(unsigned char). Previously they + were cast to (int), which doesn't correctly conform to + the requirements of the C standard, and could cause + problems for characters with values > 127 on systems + with signed char's. + +26/11/2001 mcs@astro.caltech.edu + man3/enhance.3 man3/libtecla.3 + I started writing a man page for the enhance program. + +26/11/2001 mcs@astro.caltech.edu + Makefile.in Makefile.rules INSTALL + It is now possible to specify whether the demos and other + programs are to be built, by overriding the default + values of the DEMOS, PROGRAMS and PROGRAMS_R variables. + I have also documented the BINDIR variable and the + install_bin makefile target. + +22/11/2001 mcs@astro.caltech.edu + getline.c libtecla.h libtecla.map man3/gl_get_line.3 + man3/gl_ignore_signal.3 man3/gl_trap_signal.3 + Signal handling has now been modified to be customizable. + Signals that are trapped by default can be removed from + the list of trapped signals, and signals that aren't + currently trapped, can be added to the list. Applications + can also specify the signal and terminal environments in + which an application's signal handler is invoked, and + what gl_get_line() does after the signal handler returns. + +13/11/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + Added half-bright, reverse-video and blinking text to the + available prompt formatting options. + getline.c + Removed ^O from the default VT100 sgr0 capability + string. Apparently it can cause problems with some + terminal emulators, and we don't need it, since it turns + off the alternative character set mode, which we don't + use. + getline.c + gl_tigetstr() and gl_tgetstr() didn't guard against the + error returns of tigetstr() and tgetstr() respectively. + They now do. + +11/11/2001 mcs@astro.caltech.edu + getline.c libtecla.h libtecla.map man3/gl_get_line.3 + man3/gl_prompt_style.3 + Although the default remains to display the prompt string + literally, the new gl_prompt_style() function can be used + to enable text attribute formatting directives in prompt + strings, such as underlining, bold font, and highlighting + directives. + +09/11/2001 mcs@astro.caltech.edu + enhance.c Makefile.rules configure.in configure + I added a new program to the distribution that allows one + to run most third party programs with the tecla library + providing command-line editing. + +08/11/2001 mcs@astro.caltech.edu + libtecla.h getline.c man3/gl_get_line.3 history.c history.h + I added a max_lines argument to gl_show_history() and + _glh_show_history(). This can optionally be used to + set a limit on the number of history lines displayed. + libtecla.h getline.c man3/gl_get_line.3 + I added a new function called gl_replace_prompt(). This + can be used by gl_get_line() callback functions to + request that a new prompt be use when they return. + +06/11/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + I implemented, bound and documented the list-history + action, used for listing historical lines of the current + history group. + getline.c man3/gl_get_line.3 man3/gl_echo_mode.3 + I wrote functions to specify and query whether subsequent + lines will be visible as they are being typed. + +28/10/2001 mcs@astro.caltech.edu + getline.c man3/gl_get_line.3 + For those cases where a terminal provides its own + high-level terminal editing facilities, you can now + specify an edit-mode argument of 'none'. This disables + all tecla key bindings, and by using canonical terminal + input mode instead of raw input mode, editing is left up + to the terminal driver. + +21/10/2001 mcs@astro.caltech.edu + libtecla.h getline.c history.c history.h + man3/gl_get_line.3 man3/gl_history_info.3 + I added the new gl_state_of_history(), + gl_range_of_history() and gl_size_of_history() + functions for querying information about the + history list. + history.c + While testing the new gl_size_of_history() + function, I noticed that when the history buffer + wrapped, any location nodes of old lines between + the most recent line and the end of the buffer + weren't being removed. This could result in bogus + entries appearing at the start of the history list. + Now fixed. + +20/10/2001 mcs@astro.caltech.edu + + libtecla.h getline.c history.c history.h + man3/gl_get_line.3 man3/gl_lookup_history.3 + I added a function called gl_lookup_history(), that + the application can use to lookup lines in the history + list. + libtecla.h getline.c history.c history.h man3/gl_get_line.3 + gl_show_history() now takes a format string argument + to control how the line is displayed, and with what + information. It also now provides the option of either + displaying all history lines or just those of the + current history group. + getline.c man3/gl_get_line.3 + gl_get_line() only archives lines in the history buffer + if the newline action was invoked by a newline or + carriage return character. + +16/10/2001 mcs@astro.caltech.edu + + history.c history.h getline.c libtecla.h libtecla.map + man3/gl_get_line.3 man3/gl_resize_history.3 + man3/gl_limit_history.3 man3/gl_clear_history.3 + man3/gl_toggle_history.3 + I added a number of miscellaneous history configuration + functions. You can now resize or delete the history + buffer, limit the number of lines that are allowed in the + buffer, clear either all history or just the history of + the current history group, and temporarily enable and + disable the history mechanism. + +13/10/2001 mcs@astro.caltech.edu + + getline.c + tputs_fp is now only declared if using termcap or + terminfo. + getline.c libtecla.map man3/gl_get_line.3 + man3/gl_terminal_size.3 + I added a public gl_terminal_size() function for + updating and querying the current size of the terminal. + update_version configure.in libtecla.h + A user noted that on systems where the configure script + couldn't be used, it was inconvenient to have the version + number macros set by the configure script, so they are + now specified in libtecla.h. To reduce the likelihood + that the various files where the version number now + appears might get out of sync, I have written the + update_version script, which changes the version number + in all of these files to a given value. + +01/10/2001 mcs@astro.caltech.edu + + getline.c history.c history.h man3/gl_get_line.3 + I added a max_lines argument to gl_save_history(), to + allow people to optionally place a ceiling on the number + of history lines saved. Specifying this as -1 sets the + ceiling to infinity. + +01/10/2001 mcs@astro.caltech.edu + + configure.in configure + Under digital unix, getline wouldn't compile with + _POSIX_C_SOURCE set, due to type definitions needed by + select being excluded by this flag. Defining the + _OSF_SOURCE macro as well on this system, resolved this. + +30/09/2001 mcs@astro.caltech.edu + + getline.c libtecla.h history.c history.h man3/gl_get_line.3 + man3/gl_group_history.3 + I implemented history streams. History streams + effectively allow multiple history lists to be stored in + a single history buffer. Lines in the buffer are tagged + with the current stream identification number, and + lookups only consider lines that are marked with the + current stream identifier. + getline.c libtecla.h history.c history.h man3/gl_get_line.3 + man3/gl_show_history.3 + The new gl_show_history function displays the current + history to a given stdio output stream. + +29/09/2001 mcs@astro.caltech.edu + + getline.c + Previously new_GetLine() installed a persistent signal + handler to be sure to catch the SIGWINCH (terminal size + change) signal between calls to gl_get_line(). This had + the drawback that if multiple GetLine objects were + created, only the first GetLine object used after the + signal was received, would see the signal and adapt to + the new terminal size. Instead of this, a signal handler + for sigwinch is only installed while gl_get_line() is + running, and just after installing this handler, + gl_get_line() checks for terminal size changes that + might have occurred while the signal handler wasn't + installed. + getline.c + Dynamically allocated copies of capability strings looked + up in the terminfo or termcap databases are now made, so + that calls to setupterm() etc for one GetLine object + don't get trashed when another GetLine object calls + setupterm() etc. It is now safe to allocate and use + multiple GetLine objects, albeit only within a single + thread. + +28/09/2001 mcs@astro.caltech.edu + + version.c Makefile.rules + I added a function for querying the version number of + the library. + +26/09/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + I added the new gl_watch_fd() function, which allows + applications to register callback functions to be invoked + when activity is seen on arbitrary file descriptors while + gl_get_line() is awaiting keyboard input from the user. + + keytab.c + If a request is received to delete a non-existent + binding, which happens to be an ambiguous prefix of other + bindings no complaint is now generated about it being + ambiguous. + +23/09/2001 mcs@astro.caltech.edu + + getline.c history.c history.h man3/gl_get_line.3 + libtecla.map demo.c + I added new public functions for saving and restoring the + contents of the history list. The demo program now uses + these functions to load and save history in ~/.demo_history. + +23/09/2001 mcs@astro.caltech.edu + + getline.c + On trying the demo for the first time on a KDE konsole + terminal, I discovered that the default M-O binding + to repeat history was hiding the arrow keys, which are + M-OA etc. I have removed this binding. The M-o (ie the + lower case version of this), is still bound. + +18/09/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 libtecla.map + Automatic reading of ~/.teclarc is now postponed until + the first call to gl_get_line(), to give the application + the chance to specify alternative configuration sources + with the new function gl_configure_getline(). The latter + function allows configuration to be done with a string, a + specified application-specific file, and/or a specified + user-specific file. I also added a read-init-files action + function, for re-reading the configuration files, if any. + This is by default bound to ^X^R. This is all documented + in gl_get_line.3. + +08/09/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + It is now possible to bind actions to key-sequences + that start with printable characters. Previously + keysequences were required to start with meta or control + characters. This is documented in gl_get_line.3. + + getline.c man3/gl_get_line.3 + A customized completion function can now arrange for + gl_get_line() to return the current input line whenever a + successful completion has been made. This is signalled by + setting the last character of the optional continuation + suffix to a newline character. This is documented in + gl_get_line.3. + +05/07/2001 Bug reported by Mike MacFaden, fixed by mcs + + configure.in + There was a bug in the configure script that only + revealed itself on systems without termcap but not + terminfo (eg. NetBSD). I traced the bug back to a lack of + sufficient quoting of multi-line m4 macro arguments in + configure.in, and have now fixed this and recreated the + configure script. + +05/07/2001 Bug reported and patched by Mike MacFaden (patch modified + by mcs to match original intentions). + + getline.c + getline.c wouldn't compile when termcap was selected as + the terminal information database. setupterm() was being + passed a non-existent variable, in place of the term[] + argument of gl_control_strings(). Also if + gl_change_terminal() is called with term==NULL, "ansi" + is now substituted. + +02/07/2001 Version 1.3.3 released. + +27/06/2001 mcs@astro.caltech.edu + + getline.c expand.c cplmatch.c + Added checks to fprintf() statements that write to the + terminal. + getline.c + Move the cursor to the end of the line before suspending, + so that the cursor doesn't get left in the middle of the + input line. + Makefile.in + On systems that don't support shared libraries, the + distclean target of make deleted libtecla.h. This has + now been fixed. + getline.c + gl_change_terminal() was being called by gl_change_editor(), + with the unwanted side effect that raw terminal modes were + stored as those to be restored later, if called by an + action function. gl_change_terminal() was being called in + this case to re-establish terminal-specific key bindings, + so I have just split this part of the function out into + a separate function for both gl_change_editor() and + gl_change_terminal() to call. + +12/06/2001 mcs@astro.caltech.edu + + getline.c + Signal handling has been improved. Many more signals are + now trapped, and instead of using a simple flag set by a + signal handler, race conditions are avoided by blocking + signals during most of the gl_get_line() code, and + unblocking them via calls to sigsetjmp(), just before + attempting to read each new character from the user. + The matching use of siglongjmp() in the signal + handlers ensures that signals are reblocked correctly + before they are handled. In most cases, signals cause + gl_get_line() to restore the terminal modes and signal + handlers of the calling application, then resend the + signal to the application. In the case of SIGINT, SIGHUP, + SIGPIPE, and SIGQUIT, if the process still exists after + the signals are resent, gl_get_line() immediately returns + with appropriate values assigned to errno. If SIGTSTP, + SIGTTIN or SIGTTOU signals are received, the process is + suspended. If any other signal is received, and the + process continues to exist after the signal is resent to + the calling application, line input is resumed after the + terminal is put back into raw mode, the gl_get_line() + signal handling is restored, and the input line redrawn. + man/gl_get_line(3) + I added a SIGNAL HANDLING section to the gl_get_line() + man page, describing the new signal handling features. + +21/05/2001 Version 1.3.2 released. + +21/05/2001 mcs@astro.caltech.edu + + getline.c + When vi-replace-char was used to replace the character at + the end of the line, it left the cursor one character to + its right instead of on top of it. Now rememdied. + getline.c + When undoing, to properly emulate vi, the cursor is now + left at the leftmost of the saved and current cursor + positions. + getline.c man3/gl_get_line.3 + Implemented find-parenthesis (%), delete-to-paren (M-d%), + vi-change-to-paren (M-c%), copy-to-paren (M-y%). + cplfile.c pcache.c + In three places I was comparing the last argument of + strncmp() to zero instead of the return value of + strncmp(). + +20/05/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + Implemented and documented the vi-repeat-change action, + bound to the period key. This repeats the last action + that modified the input line. + +19/05/2001 mcs@astro.caltech.edu + + man3/gl_get_line.3 + I documented the new action functions and bindings + provided by Tim Eliseo, plus the ring-bell action and + the new "nobeep" configuration option. + getline.c + I modified gl_change_editor() to remove and reinstate the + terminal settings as well as the default bindings, since + these have editor-specific differences. I also modified + it to not abort if a key-sequence can't be bound for some + reason. This allows the new vi-mode and emacs-mode + bindings to be used safely. + getline.c + When the line was re-displayed on receipt of a SIGWINCH + signal, the result wasn't visible until the next + character was typed, since a call to fflush() was needed. + gl_redisplay_line() now calls gl_flush_output() to remedy + this. + +17/05/2001 mcs@astro.catlech.edu + + getline.c + Under Linux, calling fflush(gl->output_fd) hangs if + terminal output has been suspended with ^S. With the + tecla library taking responsability for reading the stop + and start characters this was a problem, because once + hung in fflush(), the keyboard input loop wasn't entered, + so the user couldn't type the start character to resume + output. To remedy this, I now have the terminal process + these characters, rather than the library. + +12/05/2001 mcs@astro.caltech.edu + + getline.c + The literal-next action is now implemented as a single + function which reads the next character itself. + Previously it just set a flag which effected the + interpretation of the next character read by the input + loop. + getline.c + Added a ring-bell action function. This is currently + unbound to any key by default, but it is used internally, + and can be used by users that want to disable any of the + default key-bindings. + +12/05/2001 Tim Eliseo (logged here by mcs) + + getline.c + Don't reset gl->number until after calling an action + function. By looking at whether gl->number is <0 or + not, action functions can then tell whether the count + that they were passed was explicitly specified by the + user, as opposed to being defaulted to 1. + getline.c + In vi, the position at which input mode is entered + acts as a barrier to backward motion for the few + backward moving actions that are enabled in input mode. + Tim added this barrier to getline. + getline.c + In gl_get_line() after reading an input line, or + having the read aborted by a signal, the sig_atomic_t + gl_pending_signal was being compared to zero instead + of -1 to see if no signals had been received. + gl_get_line() will thus have been calling raise(-1), + which luckily didn't seem to do anything. Tim also + arranged for errno to be set to EINTR when a signal + aborts gl_get_line(). + getline.c + The test in gl_add_char_to_line() for detecting + when overwriting a character with a wider character, + had a < where it needed a >. Overwriting with a wider + character thus overwrote trailing characters. Tim also + removed a redundant copy of the character into the + line buffer. + getline.c + gl_cursor_left() and gl->cursor_right() were executing + a lot of redundant code, when the existing call to the + recently added gl_place_cursor() function, does all that + is necessary. + getline.c + Remove redundant code from backward_kill_line() by + re-implimenting in terms of gl_place_cursor() and + gl_delete_chars(). + getline.c + gl_forward_delete_char() now records characters in cut + buffer when in vi command mode. + getline.c + In vi mode gl_backward_delete_char() now only deletes + up to the point at which input mode was entered. Also + gl_delete_chars() restores from the undo buffer when + deleting in vi insert mode. + getline.c + Added action functions, vi-delete-goto-column, + vi-change-to-bol, vi-change-line, emacs-mode, vi-mode, + vi-forward-change-find, vi-backward-change-find, + vi-forward-change-to, vi-backward-change-to, + vi-change-goto-col, forward-delete-find, backward-delete-find, + forward-delete-to, backward-delete-to, + delete-refind, delete-invert-refind, forward-copy-find, + backward-copy-find, forward-copy-to, backward-copy-to + copy-goto-column, copy-rest-of-line, copy-to-bol, copy-line, + history-re-search-forward, history-re-search-backward. + +06/05/2001 Version 1.3.1 released. + +03/05/2001 mcs@astro.caltech.edu + + configure.in + Old versions of GNU ld don't accept version scripts. + Under Linux I thus added a test to try out ld with + the --version-script argument to see if it works. + If not, version scripts aren't used. + configure.in + My test for versions of Solaris earlier than 7 + failed when confronted by a three figure version + number (2.5.1). Fixed. + +30/04/2001 mcs@astro.caltech.edu + + getline.c + In vi mode, history-search-backward and + history-search-forward weren't doing anything when + invoked at the start of an empty line, whereas + they should have acted like up-history and down-history. + Makefile.in Makefile.rules + When shared libraries are being created, the build + procedure now arranges for any alternate library + links to be created as well, before linking the + demos. Without this the demos always linked to the + static libraries (which was perfectly ok, but wasn't a + good example). + Makefile.in Makefile.rules + On systems on which shared libraries were being created, + if there were no alternate list of names, make would + abort due to a Bourne shell 'for' statement that didn't + have any arguments. Currently there are no systems who's + shared library configurations would trigger this + problem. + Makefile.rules + The demos now relink to take account of changes to the + library. + configure.in configure + When determining whether the reentrant version of the + library should be compiled by default, the configure + script now attempts to compile a dummy program that + includes all of the appropriate system headers and + defines _POSIX_C_SOURCE. This should now be a robust test + on systems which use C macros to alias these function + names to other internal functions. + configure.in + Under Solaris 2.6 and earlier, the curses library is in + /usr/ccs/lib. Gcc wasn't finding this. In addition to + remedying this, I had to remove "-z text" from + LINK_SHARED under Solaris to get it to successfully + compile the shared library against the static curses + library. + configure.in + Under Linux the -soname directive was being used + incorrectly, citing the fully qualified name of the + library instead of its major version alias. This will + unfortunately mean that binaries linked with the 1.2.3 + and 1.2.4 versions of the shared library won't use + later versions of the library unless relinked. + +30/04/2001 mcs@astro.caltech.edu + + getline.c + In gl_get_input_line(), don't redundantly copy the + start_line if start_line == gl->line. + +30/04/2001 Version 1.3.0 released. + +28/04/2001 mcs@astro.caltech.edu + + configure.in + I removed the --no-undefined directive from the Linux + LINK_SHARED command. After recent patches to our RedHat + 7.0 systems ld started reporting some internal symbols of + libc as being undefined. Using nm on libc indicated that + the offending symbols are indeed defined, albeit as + "common" symbols, so there appears to be a bug in + RedHat's ld. Removing this flag allows the tecla shared + library to compile, and programs appear to function fine. + man3/gl_get_line.3 + The default key-sequence used to invoke the + read-from-file action was incorrectly cited as ^Xi + instead of ^X^F. + +26/04/2001 mcs@astro.caltech.edu + + getline.c man3/gl_get_line.3 + A new vi-style editing mode was added. This involved + adding many new action functions, adding support for + specifying editing modes in users' ~/.teclarc files, + writing a higher level cursor motion function to support + the different line-end bounds required in vi command + mode, and a few small changes to support the fact that vi + has two modes, input mode and command mode with different + bindings. + + When vi editing mode is enabled, any binding that starts + with an escape or a meta character, is interpreted as a + command-mode binding, and switches the library to vi + command mode if not already in that mode. Once in command + mode the first character of all keysequences entered + until input mode is re-enabled, are quietly coerced to + meta characters before being looked up in the key-binding + table. So, for example, in the key-binding table, the + standard vi command-mode 'w' key, which moves the cursor + one word to the right, is represented by M-w. This + emulates vi's dual sets of bindings in a natural way + without needing large changes to the library, or new + binding syntaxes. Since cursor keys normally emit + keysequences which start with escape, it also does + something sensible when a cursor key is pressed during + input mode (unlike true vi, which gets upset). + + I also added a ^Xg binding for the new list-glob action + to both the emacs and vi key-binding tables. This lists + the files that match the wild-card expression that + precedes it on the command line. + + The function that reads in ~/.teclarc used to tell + new_GetLine() to abort if it encountered anything that it + didn't understand in this file. It now just reports an + error and continues onto the next line. + Makefile.in: + When passing LIBS=$(LIBS) to recursive invokations of + make, quotes weren't included around the $(LIBS) part. + This would cause problems if LIBS ever contained more + than one word (with the supplied configure script this + doesn't happen currently). I added these quotes. + expand.c man3/ef_expand_file.3: + I wrote a new public function called ef_list_expansions(), + to list the matching filenames returned by + ef_expand_file(). + + I also fixed the example in the man page, which cited + exp->file instead of exp->files, and changed the + dangerous name 'exp' with 'expn'. + keytab.c: + Key-binding tables start with 100 elements, and are + supposedly incremented in size by 100 elements whenever + the a table runs out of space. The realloc arguments to + do this were wrong. This would have caused problems if + anybody added a lot of personal bindings in their + ~/.teclarc file. I only noticed it because the number of + key bindings needed by the new vi mode exceeded this + number. + libtecla.map + ef_expand_file() is now reported as having been added in + the upcoming 1.3.0 release. + +25/03/2001 Markus Gyger (logged here by mcs) + + Makefile.in: + Make symbolic links to alternative shared library names + relative instead of absolute. + Makefile.rules: + The HP-UX libtecla.map.opt file should be made in the + compilation directory, to allow the source code directory + to be on a readonly filesystem. + cplmatch.c demo2.c history.c pcache.c + To allow the library to be compiled with a C++ compiler, + without generating warnings, a few casts were added where + void* return values were being assigned directly to + none void* pointer variables. + +25/03/2001 mcs@astro.caltech.edu + + libtecla.map: + Added comment header to explain the purpose of the file. + Also added cpl_init_FileArgs to the list of exported + symbols. This symbol is deprecated, and no longer + documented, but for backwards compatibility, it should + still be exported. + configure: + I had forgotten to run autoconf before releasing version + 1.2.4, so I have just belatedly done so. This enables + Markus' changes to "configure.in" documented previously, + (see 17/03/2001). + +20/03/2001 John Levon (logged here by mcs) + + libtecla.h + A couple of the function prototypes in libtecla.h have + (FILE *) argument declarations, which means that stdio.h + needs to be included. The header file should be self + contained, so libtecla.h now includes stdio.h. + +18/03/2001 Version 1.2.4 released. + + README html/index.html configure.in + Incremented minor version from 3 to 4. + +18/03/2001 mcs@astro.caltech.edu + + getline.c + The fix for the end-of-line problem that I released a + couple of weeks ago, only worked for the first line, + because I was handling this case when the cursor position + was equal to the last column, rather than when the cursor + position modulo ncolumn was zero. + Makefile.in Makefile.rules + The demos are now made by default, their rules now being + int Makefile.rules instead of Makefile.in. + INSTALL + I documented how to compile the library in a different + directory than the distribution directory. + I also documented features designed to facilitate + configuring and building the library as part of another + package. + +17/03/2001 Markus Gyger (logged here by mcs) + + getline.c + Until now cursor motions were done one at a time. Markus + has added code to make use the of the terminfo capability + that moves the cursor by more than one position at a + time. This greatly improves performance when editing near + the start of long lines. + getline.c + To further improve performance, Markus switched from + writing one character at a time to the terminal, using + the write() system call, to using C buffered output + streams. The output buffer is only flushed when + necessary. + Makefile.rules Makefile.in configure.in + Added support for compiling for different architectures + in different directories. Simply create another directory + and run the configure script located in the original + directory. + Makefile.in configure.in libtecla.map + Under Solaris, Linux and HP-UX, symbols that are to be + exported by tecla shared libraries are explicitly specified + via symbol map files. Only publicly documented functions + are thus visible to applications. + configure.in + When linking shared libraries under Solaris SPARC, + registers that are reserved for applications are marked + as off limits to the library, using -xregs=no%appl when + compiling with Sun cc, or -mno-app-regs when compiling + with gcc. Also removed -z redlocsym for Solaris, which + caused problems under some releases of ld. + homedir.c (after minor changes by mcs) + Under ksh, ~+ expands to the current value of the ksh + PWD environment variable, which contains the path of + the current working directory, including any symbolic + links that were traversed to get there. The special + username "+" is now treated equally by tecla, except + that it substitutes the return value of getcwd() if PWD + either isn't set, or if it points at a different + directory than that reported by getcwd(). + +08/03/2001 Version 1.2.3 released. + +08/03/2001 mcs@astro.caltech.edu + + getline.c + On compiling the library under HP-UX for the first time + I encountered and fixed a couple of bugs: + + 1. On all systems except Solaris, the callback function + required by tputs() takes an int argument for the + character that is to be printed. Under Solaris it + takes a char argument. The callback function was + passing this argument, regardless of type, to write(), + which wrote the first byte of the argument. This was + fine under Solaris and under little-endian systems, + because the first byte contained the character to be + written, but on big-endian systems, it always wrote + the zero byte at the other end of the word. As a + result, no control characters were being written to + the terminal. + 2. While attempting to start a newline after the user hit + enter, the library was outputting the control sequence + for moving the cursor down, instead of the newline + character. On many systems the control sequence for + moving the cursor down happends to be a newline + character, but under HP-UX it isn't. The result was + that no new line was being started under HP-UX. + +04/03/2001 mcs@astro.caltech.edu + + configure.in Makefile.in Makefile.stub configure config.guess + config.sub Makefile.rules install-sh PORTING README INSTALL + Configuration and compilation of the library is now + performed with the help of an autoconf configure + script. In addition to relieving the user of the need to + edit the Makefile, this also allows automatic compilation + of the reentrant version of the library on platforms that + can handle it, along with the creation of shared + libraries where configured. On systems that aren't known + to the configure script, just the static tecla library is + compiled. This is currently the case on all systems + except Linux, Solaris and HP-UX. In the hope that + installers will provide specific conigurations for other + systems, the configure.in script is heavily commented, + and instructions on how to use are included in a new + PORTING file. + +24/02/2001 Version 1.2b released. + +22/02/2001 mcs@astro.caltech.edu + + getline.c + It turns out that most terminals, but not all, on writing + a character in the rightmost column, don't wrap the + cursor onto the next line until the next character is + output. This library wasn't aware of this and thus if one + tried to reposition the cursor from the last column, + gl_get_line() thought that it was moving relative to a + point on the next line, and thus moved the cursor up a + line. The fix was to write one extra character when in + the last column to force the cursor onto the next line, + then backup the cursor to the start of the new line. + getline.c + On terminal initialization, the dynamic LINES and COLUMNS + environment variables were ignored unless + terminfo/termcap didn't return sensible dimensions. In + practice, when present they should override the static + versions in the terminfo/termcap databases. This is the + new behavior. In reality this probably won't have caused + many problems, because a SIGWINCH signal which informs of + terminal size changes is sent when the terminal is + opened, so the dimensions established during + initialization quickly get updated on most systems. + +18/02/2001 Version 1.2a released. + +18/02/2001 mcs@astro.caltech.edu + + getline.c + Three months ago I moved the point at which termios.h + was included in getline.c. Unfortunately, I didn't notice + that this moved it to after the test for TIOCGWINSZ being + defined. This resulted in SIGWINCH signals not being + trapped for, and thus terminal size changes went + unnoticed. I have now moved the test to after the + inclusion of termios.h. + +12/02/2001 Markus Gyger (described here by mcs) + + man3/pca_lookup_file.3 man3/gl_get_line.3 + man3/ef_expand_file.3 man3/cpl_complete_word.3 + In the 1.2 release of the library, all functions in the + library were given man pages. Most of these simply + include one of the above 4 man pages, which describe the + functions while describing the modules that they are in. + Markus added all of these function names to the lists in + the "NAME" headers of the respective man pages. + Previously only the primary function of each module was + named there. + +11/02/2001 mcs@astro.caltech.edu + + getline.c + On entering a line that wrapped over two or more + terminal, if the user pressed enter when the cursor + wasn't on the last of the wrapped lines, the text of the + wrapped lines that followed it got mixed up with the next + line written by the application, or the next input + line. Somehow this slipped through the cracks and wasn't + noticed until now. Anyway, it is fixed now. + +09/02/2001 Version 1.2 released. + +04/02/2001 mcs@astro.caltech.edu + + pcache.c libtecla.h + With all filesystems local, demo2 was very fast to start + up, but on a Sun system with one of the target + directories being on a remote nfs mounted filesystem, the + startup time was many seconds. This was due to the + executable selection callback being applied to all files + in the path at startup. To avoid this, all files are now + included in the cache, and the application specified + file-selection callback is only called on files as they + are matched. Whether the callback rejected or accepted + them is then cached so that the next time an already + checked file is looked at, the callback doesn't have to + be called. As a result, startup is now fast on all + systems, and since usually there are only a few matching + file completions at a time, the delay during completion + is also usually small. The only exception is if the user + tries to complete an empty string, at which point all + files have to be checked. Having done this once, however, + doing it again is fast. + man3/pca_lookup_file.3 + I added a man page documenting the new PathCache module. + man3/<many-new-files>.3 + I have added man pages for all of the functions in each + of the modules. These 1-line pages use the .so directive + to redirect nroff to the man page of the parent module. + man Makefile update_html + I renamed man to man3 to make it easier to test man page + rediction, and updated Makefile and update_html + accordingly. I also instructed update_html to ignore + 1-line man pages when making html equivalents of the man + pages. + cplmatch.c + In cpl_list_completions() the size_t return value of + strlen() was being used as the length argument of a "%*s" + printf directive. This ought to be an int, so the return + value of strlen() is now cast to int. This would have + caused problems on architectures where the size of a + size_t is not equal to the size of an int. + +02/02/2001 mcs@astro.caltech.edu + + getline.c + Under UNIX, certain terminal bindings are set using the + stty command. This, for example, specifies which control + key generates a user-interrupt (usually ^C or ^Y). What I + hadn't realized was that ASCII NUL is used as the way to + specify that one of these bindings is unset. I have now + modified the code to skip unset bindings, leaving the + corresponding action bound to the built-in default, or a + user provided binding. + +28/01/2001 mcs@astro.caltech.edu + + pcache.c libtecla.h + A new module was added which supports searching for files + in any colon separated list of directories, such as the + unix execution PATH environment variable. Files in these + directories, after being individually okayed for + inclusion via an application provided callback, are + cached in a PathCache object. You can then look up the + full pathname of a given filename, or you can use the + provided completion callback to list possible completions + in the path-list. The contents of relative directories, + such as ".", obviously can't be cached, so these + directories are read on the fly during lookups and + completions. The obvious application of this facility is + to provide Tab-completion of commands, and thus a + callback to place executable files in the cache, is + provided. + demo2.c + This new program demonstrates the new PathCache + module. It reads and processes lines of input until the + word 'exit' is entered, or C-d is pressed. The default + tab-completion callback is replaced with one which at the + start of a line, looks up completions of commands in the + user's execution path, and when invoked in other parts of + the line, reverts to normal filename completion. Whenever + a new line is entered, it extracts the first word on the + line, looks it up in the user's execution path to see if + it corresponds to a known command file, and if so, + displays the full pathname of the file, along with the + remaining arguments. + cplfile.c + I added an optional pair of callback function/data + members to the new cpl_file_completions() configuration + structure. Where provided, this callback is asked + on a file-by-file basis, which files should be included + in the list of file completions. For example, a callback + is provided for listing only completions of executable + files. + cplmatch.c + When listing completions, the length of the type suffix + of each completion wasn't being taken into account + correctly when computing the column widths. Thus the + listing appeared ragged sometimes. This is now fixed. + pathutil.c + I added a function for prepending a string to a path, + and another for testing whether a pathname referred to + an executable file. + +28/01/2001 mcs@astro.caltech.edu + + libtecla.h cplmatch.c man/cpl_complete_word.3 + The use of a publically defined structure to configure + the cpl_file_completions() callback was flawed, so a new + approach has been designed, and the old method, albeit + still supported, is no longer documented in the man + pages. The definition of the CplFileArgs structure in + libtecla.h is now accompanied by comments warning people + not to modify it, since modifications could break + applications linked to shared versions of the tecla + library. The new method involves an opaque CplFileConf + object, instances of which are returned by a provided + constructor function, configured with provided accessor + functions, and when no longer needed, deleted with a + provided destructor function. This is documented in the + cpl_complete_word man page. The cpl_file_completions() + callback distinguishes what type of configuration + structure it has been sent by virtue of a code placed at + the beginning of the CplFileConf argument by its + constructor. + +04/01/2001 mcs@astro.caltech.edu (Release of version 1.1j) + + getline.c + I added upper-case bindings for the default meta-letter + keysequences such as M-b. They thus continue to work + when the user has caps-lock on. + Makefile + I re-implemented the "install" target in terms of new + install_lib, install_inc and install_man targets. When + distributing the library with other packages, these new + targets allows for finer grained control of the + installation process. + +30/12/2000 mcs@astro.caltech.edu + + getline.c man/gl_get_line.3 + I realized that the recall-history action that I + implemented wasn't what Markus had asked me for. What he + actually wanted was for down-history to continue going + forwards through a previous history recall session if no + history recall session had been started while entering + the current line. I have thus removed the recall-history + action and modified the down-history action function + accordingly. + +24/12/2000 mcs@astro.caltech.edu + + getline.c + I modified gl_get_line() to allow the previously returned + line to be passed in the start_line argument. + getline.c man/gl_get_line.3 + I added a recall-history action function, bound to M^P. + This recalls the last recalled history line, regardless + of whether it was from the current or previous line. + +13/12/2000 mcs@astro.caltech.edu (Release of version 1.1i) + + getline.c history.h history.c man/gl_get_line.3 + I implemented the equivalent of the ksh Operate action. I + have named the tecla equivalent "repeat-history". This + causes the line that is to be edited to returned, and + arranges for the next most recent history line to be + preloaded on the next call to gl_get_line(). Repeated + invocations of this action thus result in successive + history lines being repeated - hence the + name. Implementing the ksh Operate action was suggested + by Markus Gyger. In ksh it is bound to ^O, but since ^O + is traditionally bound by the default terminal settings, + to stop-output, I have bound the tecla equivalent to M-o. + +01/12/2000 mcs@astro.caltech.edu (Release of version 1.1h) + + getline.c keytab.c keytab.h man/gl_get_line.3 + I added a digit-argument action, to allow repeat + counts for actions to be entered. As in both tcsh + and readline, this is bound by default to each of + M-0, M-1 through to M-9, the number being appended + to the current repeat count. Once one of these has been + pressed, the subsequent digits of the repeat count can be + typed with or without the meta key pressed. It is also + possible to bind digit-argument to other keys, with or + without a numeric final keystroke. See man page for + details. + + getline.c man/gl_get_line.3 + Markus noted that my choice of M-< for the default + binding of read-from-file, could be confusing, since + readline binds this to beginning-of-history. I have + thus rebound it to ^X^F (ie. like find-file in emacs). + + getline.c history.c history.h man/gl_get_line.3 + I have now implemented equivalents of the readline + beginning-of-history and end-of-history actions. + These are bound to M-< and M-> respectively. + + history.c history.h + I Moved the definition of the GlHistory type, and + its subordinate types from history.h to history.c. + There is no good reason for any other module to + have access to the innards of this structure. + +27/11/2000 mcs@astro.caltech.edu (Release of version 1.1g) + + getline.c man/gl_get_line.3 + I added a "read-from-file" action function and bound it + by default to M-<. This causes gl_get_line() to + temporarily return input from the file who's name + precedes the cursor. + +26/11/2000 mcs@astro.caltech.edu + + getline.c keytab.c keytab.h man/gl_get_line.3 + I have reworked some of the keybinding code again. + + Now, within key binding strings, in addition to the + previously existing notation, you can now use M-a to + denote meta-a, and C-a to denote control-a. For example, + a key binding which triggers when the user presses the + meta key, the control key and the letter [ + simultaneously, can now be denoted by M-C-[, or M-^[ or + \EC-[ or \E^[. + + I also updated the man page to use M- instead of \E in + the list of default bindings, since this looks cleaner. + + getline.c man/gl_get_line.3 + I added a copy-region-as-kill action function and + gave it a default binding to M-w. + +22/11/2000 mcs@astro.caltech.edu + + *.c + Markus Gyger sent me a copy of a previous version of + the library, with const qualifiers added in appropriate + places. I have done the same for the latest version. + Among other things, this gets rid of the warnings + that are generated if one tells the compiler to + const qualify literal strings. + + getline.c getline.h glconf.c + I have moved the contents of glconf.c and the declaration + of the GetLine structure into getline.c. This is cleaner, + since now only functions in getline.c can mess with the + innards of GetLine objects. It also clears up some problems + with system header inclusion order under Solaris, and also + the possibility that this might result in inconsistent + system macro definitions, which in turn could cause different + declarations of the structure to be seen in different files. + + hash.c + I wrote a wrapper function to go around strcmp(), such that + when hash.c is compiled with a C++ compiler, the pointer + to the wrapper function is a C++ function pointer. + This makes it compatible with comparison function pointer + recorded in the hash table. + + cplmatch.c getline.c libtecla.h + Markus noted that the Sun C++ compiler wasn't able to + match up the declaration of cpl_complete_word() in + libtecla.h, where it is surrounded by a extern "C" {} + wrapper, with the definition of this function in + cplmatch.c. My suspicion is that the compiler looks not + only at the function name, but also at the function + arguments to see if two functions match, and that the + match_fn() argument, being a fully blown function pointer + declaration, got interpetted as that of a C function in + one case, and a C++ function in the other, thus + preventing a match. + + To fix this I now define a CplMatchFn typedef in libtecla.h, + and use this to declare the match_fn callback. + +20/11/2000 (Changes suggested by Markus Gyger to support C++ compilers): + expand.c + Renamed a variable called "explicit" to "xplicit", to + avoid conflicts when compiling with C++ compilers. + *.c + Added explicit casts when converting from (void *) to + other pointer types. This isn't needed in C but it is + in C++. + getline.c + tputs() has a strange declaration under Solaris. I was + enabling this declaration when the SPARC feature-test + macro was set. Markus changed the test to hinge on the + __sun and __SVR4 macros. + direader.c glconf.c stringrp.c + I had omitted to include string.h in these two files. + + Markus also suggested some other changes, which are still + under discussion. With the just above changes however, the + library compiles without complaint using g++. + +19/11/2000 mcs@astro.caltech.edu + getline.h getline.c keytab.c keytab.h glconf.c + man/gl_get_line.3 + I added support for backslash escapes (include \e + for the keyboard escape key) and literal binary + characters to the characters allowed within key sequences + of key bindings. + + getline.h getline.c keytab.c keytab.h glconf.c + man/gl_get_line.3 + I introduced symbolic names for the arrow keys, and + modified the library to use the cursor key sequences + reported by terminfo/termcap in addition to the default + ANSI ones. Anything bound to the symbolically named arrow + keys also gets bound to the default and terminfo/termcap + cursor key sequences. Note that under Solaris + terminfo/termcap report the properties of hardware X + terminals when TERM is xterm instead of the terminal + emulator properties, and the cursor keys on these two + systems generate different key sequences. This is an + example of why extra default sequences are needed. + + getline.h getline.c keytab.c + For some reason I was using \e to represent the escape + character. This is supported by gcc, which thus doesn't + emit a warning except with the -pedantic flag, but isn't + part of standard C. I now use a macro to define escape + as \033 in getline.h, and this is now used wherever the + escape character is needed. + +17/11/2000 mcs@astro.caltech.edu (Release of version 1.1d) + + getline.c, man/gl_get_line(3), html/gl_get_line.html + In tcsh ^D is bound to a function which does different + things depending on where the cursor is within the input + line. I have implemented its equivalent in the tecla + library. When invoked at the end of the line this action + function displays possible completions. When invoked on + an empty line it causes gl_get_line() to return NULL, + thus signalling end of input. When invoked within a line + it invokes forward-delete-char, as before. The new action + function is called del-char-or-list-or-eof. + + getline.c, man/gl_get_line(3), html/gl_get_line.html + I found that the complete-word and expand-file actions + had underscores in their names instead of hyphens. This + made them different from all other action functions, so I + have changed the underscores to hyphens. + + homedir.c + On SCO UnixWare while getpwuid_r() is available, the + associated _SC_GETPW_R_SIZE_MAX macro used by sysconf() + to find out how big to make the buffer to pass to this + function to cater for any password entry, doesn't + exist. I also hadn't catered for the case where sysconf() + reports that this limit is indeterminate. I have thus + change the code to substitute a default limit of 1024 if + either the above macro isn't defined or if sysconf() says + that the associated limit is indeterminate. + +17/11/2000 mcs@astro.caltech.edu (Release of version 1.1c) + + getline.c, getline.h, history.c, history.h + I have modified the way that the history recall functions + operate, to make them better emulate the behavior of + tcsh. Previously the history search bindings always + searched for the prefix that preceded the cursor, then + left the cursor at the same point in the line, so that a + following search would search using the same prefix. This + isn't how tcsh operates. On finding a matching line, tcsh + puts the cursor at the end of the line, but arranges for + the followup search to continue with the same prefix, + unless the user does any cursor motion or character + insertion operations in between, in which case it changes + the search prefix to the new set of characters that are + before the cursor. There are other complications as well, + which I have attempted to emulate. As far as I can + tell, the tecla history recall facilities now fully + emulate those of tcsh. + +16/11/2000 mcs@astro.caltech.edu (Release of version 1.1b) + + demo.c: + One can now quit from the demo by typing exit. + + keytab.c: + The first entry of the table was getting deleted + by _kt_clear_bindings() regardless of the source + of the binding. This deleted the up-arrow binding. + Symptoms noted by gazelle@yin.interaccess.com. + + getline.h: + Depending on which system include files were include + before the inclusion of getline.h, SIGWINCH and + TIOCGWINSZ might or might not be defined. This resulted + in different definitions of the GetLine object in + different files, and thus some very strange bugs! I have + now added #includes for the necessary system header files + in getline.h itself. The symptom was that on creating a + ~/.teclarc file, the demo program complained of a NULL + argument to kt_set_keybinding() for the first line of the + file. + +15/11/2000 mcs@astro.caltech.edu (Release of version 1.1a) + + demo.c: + I had neglected to check the return value of + new_GetLine() in the demo program. Oops. + + getline.c libtecla.h: + I wrote gl_change_terminal(). This allows one to change to + a different terminal or I/O stream, by specifying the + stdio streams to use for input and output, along with the + type of terminal that they are connected to. + + getline.c libtecla.h: + Renamed GetLine::isterm to GetLine::is_term. Standard + C reserves names that start with "is" followed by + alphanumeric characters, so this avoids potential + clashes in the future. + + keytab.c keytab.h + Each key-sequence can now have different binding + functions from different sources, with the user provided + binding having the highest precedence, followed by the + default binding, followed by any terminal specific + binding. This allows gl_change_terminal() to redefine the + terminal-specific bindings each time that + gl_change_terminal() is called, without overwriting the + user specified or default bindings. In the future, it will + also allow for reconfiguration of user specified + bindings after the call to new_GetLine(). Ie. deleting a + user specified binding should reinstate any default or + terminal specific binding. + + man/cpl_complete_word.3 html/cpl_complete_word.html + man/ef_expand_file.3 html/ef_expand_file.html + man/gl_get_line.3 html/gl_get_line.html + I added sections on thread safety to the man pages of the + individual modules. + + man/gl_get_line.3 html/gl_get_line.html + I documented the new gl_change_terminal() function. + + man/gl_get_line.3 html/gl_get_line.html + In the description of the ~/.teclarc configuration file, + I had omitted the 'bind' command word in the example + entry. I have now remedied this. +</pre></body></html> diff --git a/libtecla-1.6.3/html/cpl_complete_word.html b/libtecla-1.6.3/html/cpl_complete_word.html new file mode 100644 index 0000000..e69c8c0 --- /dev/null +++ b/libtecla-1.6.3/html/cpl_complete_word.html @@ -0,0 +1,477 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of cpl_complete_word</TITLE> +</HEAD><BODY> +<H1>cpl_complete_word</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +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 +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> +#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + +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> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>cpl_complete_word()</B> function is part of the tecla library +(see the <A HREF="libtecla.html">libtecla</A>(3) man page). It is usually called behind the scenes +by <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>, but can also be called separately. +<P> +Given an input line containing an incomplete word to be completed, it +calls a user-provided callback function (or the provided +file-completion callback function) to look up all possible completion +suffixes for that word. The callback function is expected to look +backward in the line, starting from the specified cursor position, to +find the start of the word to be completed, then to look up all +possible completions of that word and record them, one at a time by +calling <B>cpl_add_completion()</B>. +<P> +<P> +Descriptions of the functions of this module are as follows: +<P> +<PRE> + WordCompletion *new_WordCompletion(void) +</PRE> + +<P> +This function creates the resources used by the <B>cpl_complete_word()</B> +function. In particular, it maintains the memory that is used to +return the results of calling <B>cpl_complete_word()</B>. +<P> +<PRE> + WordCompletion *del_WordCompletion(WordCompletion *cpl) +</PRE> + +<P> +This function deletes the resources that were returned by a previous +call to <B>new_WordCompletion()</B>. It always returns <B>NULL</B> (ie. a +deleted object). It does nothing if the <B>cpl</B> argument is +<B>NULL</B>. +<P> +The callback functions which lookup possible completions should be +defined with the following macro (which is defined in libtecla.h). +<P> +<PRE> + #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \ + void *data, \ + const char *line, \ + int word_end) +</PRE> + +<P> +Functions of this type are called by <B>cpl_complete_word()</B>, and +all of the arguments of the callback are those that were passed to +said function. In particular, the <B>line</B> argument contains the +input line containing the word to be completed, and <B>word_end</B> is +the index of the character that follows the last character of the +incomplete word within this string. The callback is expected to look +backwards from <B>word_end</B> for the start of the incomplete +word. What constitutes the start of a word clearly depends on the +application, so it makes sense for the callback to take on this +responsibility. For example, the builtin filename completion function +looks backwards until it hits an unescaped space, or the start of the +line. Having found the start of the word, the callback should then +lookup all possible completions of this word, and record each +completion via separate calls to <B>cpl_add_completion()</B>. If the +callback needs access to an application-specific symbol table, it can +pass it and any other data that it needs, via the <B>data</B> +argument. This removes any need for globals. +<P> +The callback function should return 0 if no errors occur. On failure +it should return 1, and register a terse description of the error by +calling <B>cpl_record_error()</B>. +<P> +<PRE> + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); +</PRE> + +<P> +The last error message recorded by calling <B>cpl_record_error()</B>, +can subsequently be queried by calling <B>cpl_last_error()</B>, as +described later. +<P> +<PRE> + 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); +</PRE> + +<P> +The <B>cpl_add_completion()</B> function is called zero or more times +by the completion callback function to record each possible completion +in the specified <B>WordCompletion</B> object. These completions are +subsequently returned by <B>cpl_complete_word()</B>, as described +later. The <B>cpl</B>, <B>line</B>, and <B>word_end</B> arguments should +be those that were passed to the callback function. The +<B>word_start</B> argument should be the index within the input line +string of the start of the word that is being completed. This should +equal <B>word_end</B> if a zero-length string is being completed. The +<B>suffix</B> 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 <B>cpl_add_completion()</B> +returns. +<P> +Note that in the array of possible completions which the +<B>cpl_complete_word()</B> function returns, the suffix recorded by +<B>cpl_add_completion()</B> is listed along with the concatentation of +this suffix with the word that lies between <B>word_start</B> and +<B>word_end</B> in the input line. +<P> +The <B>type_suffix</B> argument specifies an optional string to be +appended to the completion if it is displayed as part of a list of +completions by <B>cpl_list_completions()</B>. 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 <B>type_suffix</B> to "()". Note that the +<B>type_suffix</B> 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 <B>cpl_complete_word()</B> +are needed. +<P> +The <B>cont_suffix</B> is a continuation suffix to append to the +completed word in the input line if this is the only completion. This +is something that isn't part of the completion itself, but that gives +the user an indication about how they might continue to extend the +token. For example, the file-completion callback function adds a +directory separator if the completed word is a directory. If the +completed word were a function name, you could similarly aid the user +by arranging for an open parenthesis to be appended. +<P> +<PRE> + CplMatches *cpl_complete_word(WordCompletion *cpl, + const char *line, + int word_end, void *data, + CplMatchFn *match_fn); +</PRE> + +<P> +The <B>cpl_complete_word()</B> is normally called behind the scenes by +<B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>, but can also be called separately if you +separately allocate a <B>WordCompletion</B> object. It performs word +completion, as described at the beginning of this section. Its first +argument is a resource object previously returned by +<B>new_WordCompletion()</B>. The <B>line</B> argument is the input line +string, containing the word to be completed. The <B>word_end</B> +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 <B>gl_get_line()</B>, this is the character over which the +user pressed <B>TAB</B>. The <B>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</B> +argument provides a way for the application to pass arbitrary data to +the callback function. +<P> +If no errors occur, the <B>cpl_complete_word()</B> function returns a +pointer to a <B>CplMatches</B> container, as defined below. This +container is allocated as part of the <B>cpl</B> object that was passed +to <B>cpl_complete_word()</B>, and will thus change on each call which +uses the same <B>cpl</B> argument. +<P> +<PRE> + 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; +</PRE> + +<P> +If an error occurs during completion, <B>cpl_complete_word()</B> +returns NULL. A description of the error can be acquired by calling +the <B>cpl_last_error() function. +<P> +</B><PRE> + const char *cpl_last_error(WordCompletion *cpl); +</PRE> + +<P> +The <B>cpl_last_error() function returns a terse description of the +error which occurred on the last call to cpl_complete_word()</B> or +<B>cpl_add_completion()</B>. +<P> +<PRE> + CplMatches *cpl_recall_matches(WordCompletion *cpl); +</PRE> + +<P> +As a convenience, the return value of the last call to +<B>cpl_complete_word()</B> can be recalled at a later time by calling +<B>cpl_recall_matches()</B>. If <B>cpl_complete_word()</B> returned +<B>NULL</B>, so will <B>cpl_recall_matches()</B>. +<P> +<PRE> + int cpl_list_completions(CplMatches *result, FILE *fp, + int terminal_width); +</PRE> + +<P> +When the <B>cpl_complete_word()</B> function returns multiple possible +completions, the <B>cpl_list_completions()</B> 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 <B>type_suffix</B> strings that were recorded with each completion, +thus indicating their types to the user. +<P> +<A NAME="lbAE"> </A> +<H2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</H2> + +<P> +By default the <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B> function, passes the following +completion callback function to <B>cpl_complete_word()</B>. This +function can also be used separately, either by sending it to +<B>cpl_complete_word()</B>, or by calling it directly from your +own completion callback function. +<P> +<PRE> + CPL_MATCH_FN(cpl_file_completions); +</PRE> + +<P> +Certain aspects of the behavior of this callback can be changed via +its <B>data</B> argument. If you are happy with its default behavior +you can pass <B>NULL</B> in this argument. Otherwise it should be a +pointer to a <B>CplFileConf</B> object, previously allocated by calling +<B>new_CplFileConf()</B>. +<P> +<PRE> + CplFileConf *new_CplFileConf(void); +</PRE> + +<P> +<B>CplFileConf</B> objects encapsulate the configuration parameters of +<B>cpl_file_completions()</B>. These parameters, which start out with +default values, can be changed by calling the accessor functions +described below. +<P> +By default, the <B>cpl_file_completions() callback function +searches backwards for the start of the filename being completed, +looking for the first un-escaped space or the start of the input +line. If you wish to specify a different location, call +cfc_file_start()</B> with the index at which the filename starts in +the input line. Passing start_index=-1 re-enables the default +behavior. +<P> +<PRE> + void cfc_file_start(CplFileConf *cfc, int start_index); +</PRE> + +<P> +By default, when <B>cpl_file_completions()</B> 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 <B>cfc_literal_escapes()</B> with a +non-zero value in its <B>literal</B> argument. +<P> +<PRE> + void cfc_literal_escapes(CplFileConf *cfc, int literal); +</PRE> + +<P> +By default, <B>cpl_file_completions()</B> 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 <B>0</B> if the +file should be ignored, or <B>1</B> if the file should be included in +the list of completions. To register such a function for use by +<B>cpl_file_completions()</B>, call <B>cfc_set_check_fn()</B>, 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. +<P> +<PRE> + #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); +</PRE> + +<P> +The <B>cpl_check_exe()</B> function is a provided callback of the above +type, for use with <B>cpl_file_completions()</B>. It returns non-zero +if the filename that it is given represents a normal file that the +user has execute permission to. You could use this to have +<B>cpl_file_completions()</B> only list completions of executable +files. +<P> +When you have finished with a <B>CplFileConf</B> variable, you can pass +it to the <B>del_CplFileConf()</B> destructor function to reclaim its +memory. +<P> +<PRE> + CplFileConf *del_CplFileConf(CplFileConf *cfc); +</PRE> + +<P> +<P> +<A NAME="lbAF"> </A> +<H2>THREAD SAFETY</H2> + +<P> +In multi-threaded programs, you should use the <B>libtecla_r.a</B> +version of the library. This uses POSIX reentrant functions where +available (hence the <B>_r</B> 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 <B>~username/</B> +expressions, in <B>cpl_file_completions()</B>. +<P> +Using the <B>libtecla_r.a</B> 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 <B>WordCompletion</B> object. In +other words, if two threads want to do word completion, they should +each call <B>new_WordCompletion()</B> to allocate their own completion +objects. +<P> +<A NAME="lbAG"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library +libtecla.h - The tecla header file. +</PRE> + +<P> +<A NAME="lbAH"> </A> +<H2>SEE ALSO</H2> + +<P> +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) +</PRE> + +<P> +<A NAME="lbAI"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">THE BUILT-IN FILENAME-COMPLETION CALLBACK</A><DD> +<DT><A HREF="#lbAF">THREAD SAFETY</A><DD> +<DT><A HREF="#lbAG">FILES</A><DD> +<DT><A HREF="#lbAH">SEE ALSO</A><DD> +<DT><A HREF="#lbAI">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/ef_expand_file.html b/libtecla-1.6.3/html/ef_expand_file.html new file mode 100644 index 0000000..13db3b5 --- /dev/null +++ b/libtecla-1.6.3/html/ef_expand_file.html @@ -0,0 +1,273 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of ef_expand_file</TITLE> +</HEAD><BODY> +<H1>ef_expand_file</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile - expand filenames containing ~user/$envvar and wildcard expressions +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + +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> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>ef_expand_file()</B> function is part of the tecla library +(see the <A HREF="libtecla.html">libtecla</A>(3) man page). It expands a specified filename, +converting <B>~user/</B> and <B>~/</B> expressions at the start of the +filename to the corresponding home directories, replacing +<B>$envvar</B> 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. +<P> +In the presence of wildcards, the returned list of filenames only +includes the names of existing files which match the +wildcards. Otherwise, the original filename is returned after +expansion of tilde and dollar expressions, and the result is not +checked against existing files. This mimics the file-globbing behavior +of the unix <B>tcsh</B> shell. +<P> +The supported wildcards and their meanings are: +<PRE> + * - 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'. +</PRE> + +<P> +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. +<P> +The following is a complete example of how to use the file expansion +function. +<P> +<PRE> + #include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> + #include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + + int main(int argc, char *argv[]) + { + ExpandFile *ef; /* The expansion resource object */ + char *filename; /* The filename being expanded */ + FileExpansion *expn; /* The results of the expansion */ + int i; + + ef = new_ExpandFile(); + if(!ef) + return 1; + + for(arg = *(argv++); arg; arg = *(argv++)) { + if((expn = ef_expand_file(ef, arg, -1)) == NULL) { + fprintf(stderr, "Error expanding %s (%s).\n", arg, + ef_last_error(ef)); + } else { + printf("%s matches the following files:\n", arg); + for(i=0; i<expn->nfile; i++) + printf(" %s\n", expn->files[i]); + } + } + + ef = del_ExpandFile(ef); + return 0; + } +</PRE> + +<P> +Descriptions of the functions used above are as follows: +<P> +<PRE> + ExpandFile *new_ExpandFile(void) +</PRE> + +<P> +This function creates the resources used by the <B>ef_expand_file()</B> +function. In particular, it maintains the memory that is used to record the +array of matching filenames that is returned by <B>ef_expand_file()</B>. This +array is expanded as needed, so there is no built in limit to the number of +files that can be matched. +<P> +<PRE> + ExpandFile *del_ExpandFile(ExpandFile *ef) +</PRE> + +<P> +This function deletes the resources that were returned by a previous call to +<B>new_ExpandFile()</B>. It always returns <B>NULL</B> (ie a deleted object). It +does nothing if the <B>ef</B> argument is <B>NULL</B>. +<P> +A container of the following type is returned by <B>ef_expand_file()</B>. +<P> +<PRE> + 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; +</PRE> + +<P> +<PRE> + FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen) +</PRE> + +<P> +The <B>ef_expand_file()</B> function performs filename expansion, as documented +at the start of this section. Its first argument is a resource object returned +by <B>new_ExpandFile()</B>. A pointer to the start of the filename to be matched +is passed via the <B>path</B> argument. This must be a normal <B>NUL</B> +terminated string, but unless a length of -1 is passed in <B>pathlen</B>, only +the first <B>pathlen</B> characters will be used in the filename expansion. If +the length is specified as -1, the whole of the string will be +expanded. +<P> +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 <B>nfile</B> member will be 1, and the <B>exists</B> 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 +<B>files[]</B> array will contain the names of the <B>nfile</B> existing +files that matched the wildcarded filename, and the <B>exists</B> +member will have the value 1. Note that the returned container belongs +to the specified <B>ef</B> object, and its contents will change on each +call, so if you need to retain the results of more than one call to +<B>ef_expand_file()</B>, you should either make a private copy of the +returned results, or create multiple file-expansion resource objects +via multiple calls to <B>new_ExpandFile()</B>. +<P> +On error, <B>NULL</B> is returned, and an explanation of the error can +be determined by calling <B>ef_last_error(ef)</B>. +<P> +<PRE> + const char *ef_last_error(ExpandFile *ef) +</PRE> + +<P> +This function returns the message which describes the error that +occurred on the last call to <B>ef_expand_file()</B>, for the given +<B>(ExpandFile *ef)</B> resource object. +<P> +<PRE> + int ef_list_expansions(FileExpansion *result, FILE *fp, + int terminal_width); +</PRE> + +<P> +The <B>ef_list_expansions()</B> function provides a convenient way to +list the filename expansions returned by <B>ef_expand_file()</B>. Like +the unix <B>ls</B> command, it arranges the filenames into equal width +columns, each column having the width of the largest file. The number +of columns used is thus determined by the length of the longest +filename, and the specified terminal width. Beware that filenames that +are longer than the specified terminal width are printed without being +truncated, so output longer than the specified terminal width can +occur. The list is written to the stdio stream specified by the +<B>fp</B> argument. +<P> +<A NAME="lbAE"> </A> +<H2>THREAD SAFETY</H2> + +<P> +In multi-threaded programs, you should use the <B>libtecla_r.a</B> +version of the library. This uses POSIX reentrant functions where +available (hence the <B>_r</B> suffix), and disables features that rely +on non-reentrant system functions. Currently there are no features +disabled in this module. +<P> +Using the <B>libtecla_r.a</B> 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 <B>ExpandFile</B> object. In other +words, if two threads want to do file expansion, they should each call +<B>new_ExpandFile()</B> to allocate their own file-expansion objects. +<P> +<A NAME="lbAF"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library +libtecla.h - The tecla header file. +</PRE> + +<P> +<A NAME="lbAG"> </A> +<H2>SEE ALSO</H2> + +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="cpl_complete_word.html">cpl_complete_word</A>(3), +<A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) +</PRE> + +<P> +<A NAME="lbAH"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">THREAD SAFETY</A><DD> +<DT><A HREF="#lbAF">FILES</A><DD> +<DT><A HREF="#lbAG">SEE ALSO</A><DD> +<DT><A HREF="#lbAH">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/enhance.html b/libtecla-1.6.3/html/enhance.html new file mode 100644 index 0000000..f048a81 --- /dev/null +++ b/libtecla-1.6.3/html/enhance.html @@ -0,0 +1,105 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of enhance</TITLE> +</HEAD><BODY> +<H1>enhance</H1> +Section: User Commands (1)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +enhance - A program that adds command-line editing to third party programs. +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +enhance command [ argument ... ] +</PRE> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>enhance</B> program provides enhanced command-line editing +facilities to users of third party applications, to which one doesn't +have any source code. It does this by placing a pseudo-terminal +between the application and the real terminal. It uses the tecla +command-line editing library to read input from the real terminal, +then forwards each just completed input line to the application via +the pseudo-terminal. All output from the application is forwarded +back unchanged to the real terminal. +<P> +Whenever the application stops generating output for more than a tenth +of a second, the <B>enhance</B> program treats the latest incomplete +output line as the prompt, and redisplays any incompleted input line +that the user has typed after it. Note that the small delay, which is +imperceptible to the user, isn't necessary for correct operation of +the program. It is just an optimization, designed to stop the input +line from being redisplayed so often that it slows down output. +<P> +Note that the user-level command-line editing facilities provided by +the Tecla library are documented in the <B><A HREF="tecla.html">tecla</A>(7)</B> man page +<P> +<A NAME="lbAE"> </A> +<H2>DEFICIENCIES</H2> + +<P> +The one major problem that hasn't been solved yet, is how to deal with +applications that change whether typed input is echo'd by their +controlling terminal. For example, programs that ask for a password, +such as ftp and telnet, temporarily tell their controlling terminal +not to echo what the user types. Since this request goes to the +application side of the psuedo terminal, the <B>enhance</B> program has +no way of knowing that this has happened, and continues to echo typed +input to its controlling terminal, while the user types their +password. +<P> +Furthermore, before executing the host application, the <B>enhance</B> +program initially sets the pseudo terminal to noecho mode, so that +everything that it sends to the program doesn't get redundantly +echoed. If a program that switches to noecho mode explicitly restores +echoing afterwards, rather than restoring the terminal modes that were +previously in force, then subsequently, every time that you enter a +new input line, a duplicate copy will be displayed on the next line. +<P> +<A NAME="lbAF"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library. +~/.teclarc - The tecla personal customization file. +</PRE> + +<P> +<A NAME="lbAG"> </A> +<H2>SEE ALSO</H2> + +<A HREF="tecla.html">tecla</A>(7), <A HREF="libtecla.html">libtecla</A>(3) +<BR> +<A NAME="lbAH"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">DEFICIENCIES</A><DD> +<DT><A HREF="#lbAF">FILES</A><DD> +<DT><A HREF="#lbAG">SEE ALSO</A><DD> +<DT><A HREF="#lbAH">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/gl_get_line.html b/libtecla-1.6.3/html/gl_get_line.html new file mode 100644 index 0000000..7f922fe --- /dev/null +++ b/libtecla-1.6.3/html/gl_get_line.html @@ -0,0 +1,2407 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of gl_get_line</TITLE> +</HEAD><BODY> +<H1>gl_get_line</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +gl_get_line, new_GetLine, del_GetLine, gl_customize_completion, +gl_change_terminal, gl_configure_getline, gl_load_history, +gl_save_history, gl_group_history, gl_show_history, gl_watch_fd, +gl_inactivity_timeout, gl_terminal_size, gl_set_term_size, +gl_resize_history, gl_limit_history, gl_clear_history, +gl_toggle_history, gl_lookup_history, gl_state_of_history, +gl_range_of_history, gl_size_of_history, gl_echo_mode, +gl_replace_prompt, gl_prompt_style, gl_ignore_signal, gl_trap_signal, +gl_last_signal, 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_history, +gl_query_char, gl_read_char - allow the user to compose an input line +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> +#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + +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> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>gl_get_line()</B> function is part of the tecla library (see the +<B><A HREF="libtecla.html">libtecla</A>(3)</B> man page). If the user is typing at a terminal, each +call prompts them for an line of input, then provides interactive +editing facilities, similar to those of the unix <B>tcsh</B> 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 <B><A HREF="tecla.html">tecla</A>(7)</B> man page. This man page +concerns itself with documentation for programmers interested in using +this library in their application. +<P> +<A NAME="lbAE"> </A> +<H2>AN EXAMPLE</H2> + +<P> +The following shows a complete example of how to use the +<B>gl_get_line()</B> function to get input from the user: +<P> +<PRE> + #include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> + #include <<A HREF="file:///usr/include/locale.h">locale.h</A>> + #include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + + int main(int argc, char *argv[]) + { + char *line; /* The line that the user typed */ + GetLine *gl; /* The gl_get_line() resource object */ + + setlocale(LC_CTYPE, ""); /* Adopt the user's choice */ + /* of character set. */ + + gl = new_GetLine(1024, 2048); + if(!gl) + return 1; + + while((line=gl_get_line(gl, "$ ", NULL, -1)) != NULL && + strcmp(line, "exit\n") != 0) + printf("You typed: %s\n", line); + + gl = del_GetLine(gl); + return 0; + } +</PRE> + +<P> +In the example, first the resources needed by the <B>gl_get_line()</B> function +are created by calling <B>new_GetLine()</B>. This allocates the memory used in +subsequent calls to the <B>gl_get_line()</B> 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 <B>exit</B>. Then +finally the resources that were allocated by <B>new_GetLine()</B>, are returned +to the system by calling <B>del_GetLine()</B>. Note the use of the <B>NULL</B> +return value of <B>del_GetLine()</B> to make <B>gl</B> <B>NULL</B>. This is a +safety precaution. If the program subsequently attempts to pass <B>gl</B> to +<B>gl_get_line()</B>, said function will complain, and return an error, instead of +attempting to use the deleted resource object. +<P> +<P> +<A NAME="lbAF"> </A> +<H2>THE FUNCTIONS USED IN THE EXAMPLE</H2> + +The descriptions of the functions used in the example are as follows: +<P> +<PRE> + GetLine *new_GetLine(size_t linelen, size_t histlen) +</PRE> + +<P> +This function creates the resources used by the <B>gl_get_line()</B> +function and returns an opaque pointer to the object that contains +them. The maximum length of an input line is specified via the +<B>linelen</B> argument, and the number of bytes to allocate for +storing history lines is set by the <B>histlen</B> argument. History +lines are stored back-to-back in a single buffer of this size. Note +that this means that the number of history lines that can be stored at +any given time, depends on the lengths of the individual lines. If +you want to place an upper limit on the number of lines that can be +stored, see the <B>gl_limit_history()</B> function described later. If +you don't want history at all, specify <B>histlen</B> as zero, and no +history buffer will be allocated. +<P> +On error, a message is printed to <B>stderr</B> and <B>NULL</B> is returned. +<P> +<PRE> + GetLine *del_GetLine(GetLine *gl) +</PRE> + +<P> +This function deletes the resources that were returned by a previous +call to <B>new_GetLine()</B>. It always returns <B>NULL</B> (ie a +deleted object). It does nothing if the <B>gl</B> argument is +<B>NULL</B>. +<P> +<PRE> + char *gl_get_line(GetLine *gl, const char *prompt, + const char *start_line, int start_pos); +</PRE> + +<P> +The <B>gl_get_line()</B> function can be called any number of +times to read input from the user. The <B>gl</B> argument +must have been previously returned by a call to +<B>new_GetLine()</B>. The <B>prompt</B> argument should be a +normal <B>NUL</B> terminated string, specifying the prompt to +present the user with. By default prompts are displayed +literally, but if enabled with the <B>gl_prompt_style()</B> +function (see later), prompts can contain directives to do +underlining, switch to and from bold fonts, or turn +highlighting on and off. +<P> +If you want to specify the initial contents of the line, for the user +to edit, pass the desired string via the <B>start_line</B> +argument. You can then specify which character of this line the cursor +is initially positioned over, using the <B>start_pos</B> 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 <B>start_line</B> as <B>NULL</B>, and set <B>start_pos</B> to +-1. Note that the line pointer returned by one call to +<B>gl_get_line()</B> can be passed back to the next call to +<B>gl_get_line()</B> via the <B>start_line</B>. 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. +<P> +The <B>gl_get_line()</B> function returns a pointer to the line entered +by the user, or <B>NULL</B> on error or at the end of the input. The +returned pointer is part of the specified <B>gl</B> 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 <B>gl_get_line()</B> again to read the rest of the line. Note that +this behavior makes <B>gl_get_line()</B> similar to <B>fgets()</B>. In +fact when <B>stdin</B> isn't connected to a terminal,<B>gl_get_line()</B> +just calls <B>fgets()</B>. +<P> +<A NAME="lbAG"> </A> +<H2>THE RETURN STATUS OF GL_GET_LINE</H2> + +<P> +As described above, the <B>gl_get_line()</B> function has two possible +return values; a pointer to the completed input line, or +<B>NULL</B>. Extra information about what caused <B>gl_get_line()</B> to +return is available both by inspecting <B>errno</B>, and by calling the +<B>gl_return_status()</B> function. +<P> +<P> +<PRE> + GlReturnStatus gl_return_status(GetLine *gl); +</PRE> + +<P> +<P> +The following are the possible enumerated values that this +function returns. +<P> +<P> +<PRE> + GLR_NEWLINE - The last call to <B>gl_get_line()</B> + successfully returned a completed + input line. + + GLR_BLOCKED - <B>gl_get_line()</B> was in non-blocking + server mode, and returned early to + avoid blocking the process while + waiting for terminal I/O. The + <B>gl_pending_io()</B> function can be + used to see what type of I/O + <B>gl_get_line()</B> was waiting for. + (see the <B><A HREF="gl_io_mode.html">gl_io_mode</A>(3)</B> man page + for details). + + GLR_SIGNAL - A signal was caught by + <B>gl_get_line()</B> that had an + after-signal disposition of + <B>GLS_ABORT</B> (See <B>gl_trap_signal()</B>). + + GLR_TIMEOUT - The inactivity timer expired while + <B>gl_get_line()</B> was waiting for + input, and the timeout callback + function returned <B>GLTO_ABORT</B>. + See <B>gl_inactivity_timeout()</B> for + information about timeouts. + + GLR_FDABORT - An application I/O callack returned + <B>GLFD_ABORT</B> (see <B>gl_watch_fd()</B>). + + 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 + <B>list-or-eof</B> or <B>del-char-or-list-or-eof</B> + actions at the start of a new line. + + GLR_ERROR - An unexpected error caused + <B>gl_get_line()</B> to abort (consult + <B>errno</B> and/or + <B>gl_error_message()</B> for details. +</PRE> + +<P> +<P> +When <B>gl_return_status()</B> returns <B>GLR_ERROR</B>, and the +value of <B>errno</B> isn't sufficient to explain what +happened, you can use the <B>gl_error_message()</B> function +to request a description of the last error that occurred. +<P> +<P> +<PRE> + const char *gl_error_message(GetLine *gl, char *buff, + size_t n); +</PRE> + +<P> +<P> +The return value is a pointer to the message that +occurred. If the <B>buff</B> argument is <B>NULL</B>, this +will be a pointer to a buffer within <B>gl</B>, who's value +will probably change on the next call to any function +associated with <B>gl_get_line()</B>. Otherwise, if a +non-<B>NULL</B> <B>buff</B> argument is provided, the error +message, including a <B>'\0'</B> terminator, will be written +within the first <B>n</B> 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. +<P> +<A NAME="lbAH"> </A> +<H2>OPTIONAL PROMPT FORMATTING</H2> + +<P> +Whereas by default the prompt string that you specify is +displayed literally, without any special interpretation of +the characters within it, the <B>gl_prompt_style()</B> +function can be used to enable optional formatting +directives within the prompt. +<P> +<PRE> + void gl_prompt_style(GetLine *gl, GlPromptStyle style); +</PRE> + +<P> +The <B>style</B> argument, which specifies the formatting +style, can take any of the following values: +<P> +<PRE> + 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 <B>"%UOK%u$ "</B> would + display the prompt <B>"OK$ "</B>, + but with the <B>OK</B> 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> + +<P> +<A NAME="lbAI"> </A> +<H2>ALTERNATE CONFIGURATION SOURCES</H2> + +<P> +As mentioned above, by default users have the option of configuring +the behavior of <B>gl_get_line()</B> via a configuration file called +<B>.teclarc</B> in their home directories. The fact that all +applications share this same configuration file is both an advantage +and a disadvantage. In most cases it is an advantage, since it +encourages uniformity, and frees the user from having to configure +each application separately. In some applications, however, this +single means of configuration is a problem. This is particularly true +of embedded software, where there's no filesystem to read a +configuration file from, and also in applications where a radically +different choice of keybindings is needed to emulate a legacy keyboard +interface. To cater for such cases, the following function allows the +application to control where configuration information is read from. +<P> +<P> +<PRE> + int gl_configure_getline(GetLine *gl, + const char *app_string, + const char *app_file, + const char *user_file); +</PRE> + +<P> +<P> +It allows the configuration commands that would normally be read from +a user's <B>~/.teclarc</B> file, to be read from any or none of, a +string, an application specific configuration file, and/or a +user-specific configuration file. If this function is called before +the first call to <B>gl_get_line()</B>, the default behavior of +reading <B>~/.teclarc</B> on the first call to <B>gl_get_line()</B> is +disabled, so all configuration must be achieved using the +configuration sources specified with this function. +<P> +If <B>app_string != NULL</B>, 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 <B>app_file != +NULL</B> then it is interpreted as the full pathname of an +application-specific configuration file. If <B>user_file != NULL</B> +then it is interpreted as the full pathname of a user-specific +configuration file, such as <B>~/.teclarc</B>. For example, in the +following call, +<P> +<P> +<PRE> + gl_configure_getline(gl, "edit-mode vi \n nobeep", + "/usr/share/myapp/teclarc", + "~/.teclarc"); +</PRE> + +<P> +<P> +the <B>app_string</B> 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 +<B>/usr/share/myapp/teclarc</B>, then finally reads user-specific +configuration commands from an optional <B>.teclarc</B> file in the +user's home directory. Note that the arguments are listed in ascending +order of priority, with the contents of <B>app_string</B> being +potentially overriden by commands in <B>app_file</B>, and commands in +<B>app_file</B> potentially being overriden by commands in +<B>user_file</B>. +<P> +You can call this function as many times as needed, the results being +cumulative, but note that copies of any filenames specified via the +<B>app_file</B> and <B>user_file</B> arguments are recorded internally +for subsequent use by the <B>read-init-files</B> key-binding function, +so if you plan to call this function multiple times, be sure that the +last call specifies the filenames that you want re-read when the user +requests that the configuration files be re-read. +<P> +Individual key sequences can also be bound and unbound using the +<B>gl_bind_keyseq()</B> function. +<P> +<P> +<PRE> + int gl_bind_keyseq(GetLine *gl, GlKeyOrigin origin, + const char *keyseq, + const char *action); +</PRE> + +<P> +<P> +The <B>origin</B> argument specifies the priority of the binding, +according to who it is being established for, and must be one of +the following two values. +<P> +<PRE> + GL_USER_KEY - The user requested this key-binding. + GL_APP_KEY - This is a default binding set by the + application. +</PRE> + +<P> +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 +<B>gl_configure_getline()</B>. +<P> +The <B>keyseq</B> argument specifies the key-sequence to be bound or +unbound, and is expressed in the same way as in a <B>~/.teclarc</B> +configuration file. The <B>action</B> argument must either be a string +containing the name of the action to bind the key-sequence to, or it +must be <B>NULL</B> or "" to unbind the key-sequence. +<P> +<A NAME="lbAJ"> </A> +<H2>CUSTOMIZED WORD COMPLETION</H2> + +<P> +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 <B>gl_customize_completion()</B> function. +<P> +<PRE> + int gl_customize_completion(GetLine *gl, void *data, + CplMatchFn *match_fn); +</PRE> + +<P> +The <B>data</B> argument provides a way for your application to pass +arbitrary, application-specific information to the callback +function. This is passed to the callback every time that it is +called. It might for example, point to the symbol table from which +possible completions are to be sought. The <B>match_fn</B> argument +specifies the callback function to be called. The <B>CplMatchFn</B> +function type is defined in <B>libtecla.h</B>, as is a +<B>CPL_MATCH_FN()</B> macro that you can use to declare and prototype +callback functions. The declaration and responsibilities of callback +functions are described in depth in the <A HREF="cpl_complete_word.html">cpl_complete_word</A>(3) man +page. +<P> +In brief, the callback function is responsible for looking backwards +in the input line, back from the point at which the user pressed TAB, +to find the start of the word being completed. It then must lookup +possible completions of this word, and record them one by one in the +<B>WordCompletion</B> object that is passed to it as an argument, by +calling the <B>cpl_add_completion()</B> function. If the callback +function wishes to provide filename completion in addition to its own +specific completions, it has the option of itself calling the builtin +file-name completion callback. This also, is documented in the +<B><A HREF="cpl_complete_word.html">cpl_complete_word</A>(3)</B> man page. +<P> +Note that if you would like <B>gl_get_line()</B> to return the current +input line when a successful completion is been made, you can arrange +this when you call <B>cpl_add_completion()</B>, 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 +<B>gl_get_line()</B> will return this input line. +<P> +<P> +If, for some reason, your callback function needs to write something +to the terminal, it must call <B>gl_normal_io()</B> 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 +<B>gl_get_line()</B> that the input line will need to be redrawn when +the callback returns. +<P> +<A NAME="lbAK"> </A> +<H2>ADDING COMPLETION ACTIONS</H2> + +<P> +In the previous section the ability to customize the behavior of the +only default completion action, <B>complete-word</B>, 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 +<B>gl_completion_action()</B> function. +<P> +<P> +<PRE> + int gl_completion_action(GetLine *gl, + void *data, CplMatchFn *match_fn, + int list_only, const char *name, + const char *keyseq); +</PRE> + +<P> +<P> +The <B>data</B> and <B>match_fn</B> arguments are as described +in the <B>cpl_complete_word</B> man page, and specify the +callback function that should be invoked to identify +possible completions. The <B>list_only</B> argument +determines whether the action that is being defined should +attempt to complete the word as far as possible in the input +line before displaying 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 <B>0</B>, and the +latter by specifying a value of <B>1</B>. The <B>name</B> +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 <B>keyseq</B> argument specifies +the default key-sequence to bind the action to. If this is +<B>NULL</B>, no new keysequence will be bound to the action. +<P> +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 <B>gl_completion_action()</B> to +install a given action for the first time, you should do +this between calling <B>new_GetLine()</B> and the first call +to <B>gl_get_line()</B>. Otherwise, when the user's +configuration file is read on the first call to +<B>gl_get_line()</B>, the name of the your additional action +won't be known, and any reference to it in the configuration +file will generate an error. +<P> +As discussed for <B>gl_customize_completion()</B>, if your callback +function, for some reason, needs to write anything to the terminal, it +must call <B>gl_normal_io()</B> before doing so. +<P> +<A NAME="lbAL"> </A> +<H2>DEFINING CUSTOM ACTIONS</H2> + +<P> +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 +having 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 <B>gl_register_action()</B> function is provided. +<P> +<P> +<PRE> + int gl_register_action(GetLine *gl, void *data, + GlActionFn *fn, const char *name, + const char *keyseq); +</PRE> + +<P> +<P> +This function lets the application register an external function, +<B>fn</B>, that will thereafter be called whenever either the specified +key-sequence, <B>keyseq</B>, is entered by the user, or the user enters +any other key-sequence that the user subsequently binds to the +specified action name, <B>name</B>, in their configuration file. The +<B>data</B> argument can be a pointer to anything that the application +wishes to have passed to the action function, <B>fn</B>, whenever that +function is invoked. +<P> +The action function, <B>fn</B>, should be declared using the following +macro, which is defined in <B>libtecla.h</B>. +<P> +<P> +<PRE> + #define GL_ACTION_FN(fn) GlAfterAction (fn)(GetLine *gl, \ + void *data, int count, size_t curpos, \ + const char *line) +</PRE> + +<P> +<P> +The <B>gl</B> and <B>data</B> arguments are those that were previously +passed to <B>gl_register_action()</B> when the action function was +registered. The <B>count</B> argument is a numeric argument which the +user has the option of entering using the <B>digit-argument</B> action, +before invoking the action. If the user doesn't enter a number, then +the <B>count</B> argument is set to 1. Nominally 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 <B>count</B> argument, or use its value for a +different purpose. +<P> +A copy of the current input line is passed in the read-only <B>line</B> +argument. The current cursor position within this string is given by +the index contained in the <B>curpos</B> 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 <B>gl_get_line()</B>. 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. +<P> +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 <B>gl_normal_io()</B> 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 +restoring the normal mapping of <B>\n</B> to <B>\r\n</B>, and, when +in server mode, restoring the normal blocking form of terminal +I/O. Having called this function, the action function can read from +and write to the terminal without 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 +<B>gl_get_line()</B> 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. +<P> +<P> +<PRE> + 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; + } +</PRE> + +<P> +<P> +Action functions must return one of the following values, to tell +<B>gl_get_line()</B> how to procede. +<P> +<P> +<PRE> + 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. +</PRE> + +<P> +<P> +Note that the <B>name</B> argument of <B>gl_register_action()</B> +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 <B>gl_register_action()</B> between calling <B>new_GetLine()</B> +and the first call to <B>gl_get_line()</B>. +<P> +<A NAME="lbAM"> </A> +<H2>HISTORY FILES</H2> + +<P> +To save the contents of the history buffer before quitting your +application, and subsequently restore them when you next start the +application, the following functions are provided. +<P> +<P> +<PRE> + 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); +</PRE> + +<P> +<P> +The <B>filename</B> 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". +<P> +Along with each history line, extra information about it, such as when +it was entered by the user, and what its nesting level is, is recorded +as a comment preceding the line in the history file. Writing this as a +comment allows the history file to double as a command file, just in +case you wish to replay a whole session using it. Since comment +prefixes differ in different languages, the <B>comment</B> 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 <B>gl_load_history()</B> that you used +when you called <B>gl_save_history()</B> to write the history file. +<P> +The <B>max_lines</B> must be either -1 to specify that all lines in the +history list be saved, or a positive number specifying a ceiling on +how many of the most recent lines should be saved. +<P> +Both fuctions return non-zero on error, after writing an error message +to stderr. Note that <B>gl_load_history()</B> does not consider the +non-existence of a file to be an error. +<P> +<A NAME="lbAN"> </A> +<H2>MULTIPLE HISTORY LISTS</H2> + +<P> +If your application uses a single <B>GetLine</B> object for entering +many different types of input lines, you may wish <B>gl_get_line()</B> +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, <B>gl_get_line()</B> marks lines being recorded in the +history list with an integer identifier chosen by the application. +Initially this identifier is set to 0<B> by new_GetLine()</B>, +but it can be changed subsequently by calling +<B>gl_group_history()</B>. +<P> +<P> +<PRE> + int gl_group_history(GetLine *gl, unsigned id); +</PRE> + +<P> +<P> +The integer identifier <B>id</B> can be any number chosen by the +application, but note that <B>gl_save_history()</B> and +<B>gl_load_history()</B> preserve the association between identifiers +and historical input lines between program invokations, so you should +choose fixed identifiers for the different types of input line used by +your application. +<P> +Whenever <B>gl_get_line()</B> 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. +<P> +<A NAME="lbAO"> </A> +<H2>DISPLAYING HISTORY</H2> + +<P> +The history list can be displayed by calling <B>gl_show_history()</B>. +<P> +<P> +<PRE> + int gl_show_history(GetLine *gl, FILE *fp, + const char *fmt, + int all_groups, + int max_lines); +</PRE> + +<P> +<P> +This displays the current contents of the history list to the stdio +output stream <B>fp</B>. If the <B>max_lines</B> argument is greater +than or equal to zero, then no more than this number of the most +recent lines will be displayed. If the <B>all_groups</B> argument is +non-zero, lines from all history groups are displayed. Otherwise just +those of the currently selected history group are displayed. The +format string argument, <B>fmt</B>, determines how the line is +displayed. This can contain arbitrary characters which are written +verbatim, interleaved with any of the following format directives: +<P> +<PRE> + %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. +</PRE> + +<P> +Thus a format string like <B>"%D %T %H</B> would output something like: +<P> +<PRE> + 2001-11-20 10:23:34 Hello world +</PRE> + +<P> +Note the inclusion of an explicit newline character in the format +string. +<P> +<A NAME="lbAP"> </A> +<H2>LOOKING UP HISTORY</H2> + +<P> +The <B>gl_lookup_history()</B> function allows the calling application +to look up lines in the history list. +<P> +<P> +<PRE> + 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); +</PRE> + +<P> +<P> +The <B>id</B> argument indicates which line to look up, where the first +line that was entered in the history list after <B>new_GetLine()</B> +was called, is denoted by 0, and subsequently entered lines are +denoted with successively higher numbers. Note that the range of lines +currently preserved in the history list can be queried by calling the +<B>gl_range_of_history()</B> 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 <B>hline</B> argument, and +<B>1</B> is returned. Otherwise <B>0</B> is returned, and the variable +pointed to by <B>hline</B> is left unchanged. +<P> +Beware that the string returned in <B>hline->line</B> 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 <B>gl</B> as its +argument. Therefore you should make a private copy of this string if +you need to keep it around. +<P> +<A NAME="lbAQ"> </A> +<H2>MANUAL HISTORY ARCHIVAL</H2> + +<P> +By default, whenever a line is entered by the user, it is +automatically appended to the history list, just before +<B>gl_get_line()</B> returns the line to the caller. This is convenient +for the majority of applications, 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 +<B>gl_automatic_history()</B> function. +<P> +<P> +<PRE> + int gl_automatic_history(GetLine *gl, int enable); +</PRE> + +<P> +<P> +If this function is called with its <B>enable</B> argument set to +<B>0</B>, <B>gl_get_line()</B> won't automatically archive subsequently +entered lines. Automatic archiving can be reenabled at a later time, +by calling this function again, with its <B>enable</B> argument set to +1. While automatic history archiving is disabled, the calling +application can use the <B>gl_append_history()</B> to append lines to +the history list as needed. +<P> +<P> +<PRE> + int gl_append_history(GetLine *gl, const char *line); +</PRE> + +<P> +<P> +The <B>line</B> argument specifies the line to be added to the history +list. This must be a normal <B>' '</B> 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 terminated by the <B>' '</B> terminator. If the line is +longer than the maximum input line length, that was specified when +<B>new_GetLine()</B> was called, when the line is recalled, it will get +truncated to the actual <B>gl_get_line()</B> line length. +<P> +If successful, <B>gl_append_history()</B> returns 0. Otherwise it +returns non-zero, and sets <B>errno</B> to one of the following values. +<P> +<P> +<PRE> + 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. +</PRE> + +<P> +<P> +A textual description of the error can optionally be obtained by +calling <B>gl_error_message()</B>. Note that after such an error, the +history list remains in a valid state to receive new history lines, so +there is little harm in simply ignoring the return status of +<B>gl_append_history()</B>. +<P> +<A NAME="lbAR"> </A> +<H2>MISCELLANEOUS HISTORY CONFIGURATION</H2> + +<P> +If you wish to change the size of the history buffer that was +originally specified in the call to <B>new_GetLine()</B>, you can do so +with the <B>gl_resize_history()</B> function. +<P> +<P> +<PRE> + int gl_resize_history(GetLine *gl, size_t histlen); +</PRE> + +<P> +<P> +The <B>histlen</B> argument specifies the new size in bytes, and if you +specify this as 0, the buffer will be deleted. +<P> +As mentioned in the discussion of <B>new_GetLine()</B>, 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 <B>gl_limit_history()</B> function. +<P> +<P> +<PRE> + void gl_limit_history(GetLine *gl, int max_lines); +</PRE> + +<P> +<P> +The <B>max_lines</B> should either be a positive number <B>>= 0</B>, +specifying an upper limit on the number of lines in the buffer, or be +<B>-1</B> to cancel any previously specified limit. When a limit is in +effect, only the <B>max_lines</B> most recently appended lines are kept +in the buffer. Older lines are discarded. +<P> +To discard lines from the history buffer, use the +<B>gl_clear_history()</B> function. +<P> +<PRE> + void gl_clear_history(GetLine *gl, int all_groups); +</PRE> + +<P> +The <B>all_groups</B> argument tells the function whether to delete +just the lines associated with the current history group (see +<B>gl_group_history()</B>), or all historical lines in the buffer. +<P> +The <B>gl_toggle_history()</B> function allows you to toggle history on +and off without losing the current contents of the history list. +<P> +<P> +<PRE> + void gl_toggle_history(GetLine *gl, int enable); +</PRE> + +<P> +<P> +Setting the <B>enable</B> argument to 0 turns off the history +mechanism, and setting it to 1 turns it back on. When history is +turned off, no new lines will be added to the history list, and +history lookup key-bindings will act as though there is nothing in the +history buffer. +<P> +<A NAME="lbAS"> </A> +<H2>QUERYING HISTORY INFORMATION</H2> + +<P> +The configured state of the history list can be queried with the +<B>gl_history_state()</B> function. +<P> +<P> +<PRE> + 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); +</PRE> + +<P> +On return, the status information is recorded in the variable pointed +to by the <B>state</B> argument. +<P> +The <B>gl_range_of_history()</B> function returns the number and +range of lines in the history list. +<P> +<P> +<PRE> +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); +</PRE> + +<P> +The return values are recorded in the variable pointed to by the +<B>range</B> argument. If the <B>nlines</B> member of this structure is +greater than zero, then the <B>oldest</B> and <B>newest</B> members +report the range of lines in the list, and <B>newest=oldest+nlines-1</B>. +Otherwise they are both zero. +<P> +The <B>gl_size_of_history()</B> function returns the total size of the +history buffer and the amount of the buffer that is currently +occupied. +<P> +<PRE> + 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); +</PRE> + +<P> +On return, the size information is recorded in the variable pointed to +by the <B>size</B> argument. +<P> +<A NAME="lbAT"> </A> +<H2>CHANGING TERMINALS</H2> + +<P> +The <B>new_GetLine()</B> constructor function assumes that input is to +be read from <B>stdin</B>, and output written to <B>stdout</B>. The +following function allows you to switch to different input and output +streams. +<P> +<PRE> + int gl_change_terminal(GetLine *gl, FILE *input_fp, + FILE *output_fp, const char *term); +</PRE> + +<P> +The <B>gl</B> argument is the object that was returned by +<B>new_GetLine()</B>. The <B>input_fp</B> argument specifies the stream +to read from, and <B>output_fp</B> specifies the stream to be written +to. Only if both of these refer to a terminal, will interactive +terminal input be enabled. Otherwise <B>gl_get_line()</B> will simply +call <B>fgets()</B> 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 <B>term</B> argument. The value +of the <B>term</B> argument is looked up in the terminal information +database (terminfo or termcap), in order to determine which special +control sequences are needed to control various aspects of the +terminal. <B>new_GetLine()</B> for example, passes the return value of +<B>getenv("TERM")</B> in this argument. Note that if one or both of +<B>input_fp</B> and <B>output_fp</B> don't refer to a terminal, then it +is legal to pass <B>NULL</B> instead of a terminal type. +<P> +Note that if you want to pass file descriptors to +<B>gl_change_terminal()</B>, you can do this by creating stdio stream +wrappers using the POSIX <B>fdopen()</B> function. +<P> +<A NAME="lbAU"> </A> +<H2>EXTERNAL EVENT HANDLING</H2> + +<P> +By default, <B>gl_get_line()</B> 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. +<P> +<P> +<PRE> + 1. Use the functions described in the + <B><A HREF="gl_io_mode.html">gl_io_mode</A>(3)</B> man page to switch + <B>gl_get_line()</B> into non-blocking server mode. In this mode, + <B>gl_get_line()</B> 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 <B>gl_get_line()</B>. + + 2. While <B>gl_get_line()</B> 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 <B>select()</B> system call, + which is most, if not all flavors of unix. +</PRE> + +<P> +<P> +Registering a file descriptor to be watched by +<B>gl_get_line()</B> involves calling the <B>gl_watch_fd()</B> function. +<P> +<P> +<PRE> + int gl_watch_fd(GetLine *gl, int fd, GlFdEvent event, + GlFdEventFn *callback, void *data); +</PRE> + +<P> +<P> +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. +<P> +The <B>fd</B> argument is the file descriptor to be watched. The +<B>event</B> argument specifies what type of activity is of interest, +chosen from the following enumerated values: +<P> +<P> +<PRE> + 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. +</PRE> + +<P> +<P> +The <B>callback</B> 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. +<P> +<P> +<PRE> + #define GL_FD_EVENT_FN(fn) GlFdStatus (fn)(GetLine *gl, \ + void *data, int fd, \ + GlFdEvent event) +</PRE> + +<P> +The <B>data</B> argument of the <B>gl_watch_fd()</B> function is passed +to the callback function for its own use, and can point to anything +you like, including <B>NULL</B>. 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. +<P> +<P> +<PRE> + GLFD_ABORT - Tell gl_get_line() to abort. When this + happens, <B>gl_get_line()</B> returns + <B>NULL</B>, and a following call to + <B>gl_return_status()</B> will return + <B>GLR_FDABORT</B>. Note that if the + application needs <B>errno</B> always to + have a meaningful value when + <B>gl_get_line()</B> returns <B>NULL</B>, + the callback function should set + <B>errno</B> 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. +</PRE> + +<P> +Note that before calling the callback, <B>gl_get_line()</B> blocks most +signals, and leaves its own signal handlers installed, so if you need +to catch a particular signal you will need to both temporarily install +your own signal handler, and unblock the signal. Be sure to re-block +the signal (if it was originally blocked) and reinstate the original +signal handler, if any, before returning. +<P> +<P> +<P> +If the callback function needs to read or write to the terminal, it +should ideally first call <B>gl_normal_io(gl)</B> 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, <B>gl_get_line()</B> will +notice that <B>gl_normal_io()</B> was called, redisplay the input line +and resume editing. Note that in this case the return values, +<B>GLFD_REFRESH</B> and <B>GLFD_CONTINUE</B> are equivalent. +<P> +<P> +<P> +To support cases where the callback function calls a third-party +function which occasionally and unpredictably writes to the terminal, +the automatic conversion of <B>"</B> to <B>"</B> is re-enabled +before the callback function is called. If the callack knows that the +third-party function wrote to the terminal, it should then return the +<B>GLFD_REFRESH</B> return value, to tell <B>gl_get_line()</B> to +redisplay the input line. +<P> +<P> +<P> +To remove a callback function that you previously registered for a +given file descriptor and event, simply call <B>gl_watch_fd()</B> with +the same file descriptor and <B>event</B> arguments, but with a +<B>callback</B> argument of <B>0</B>. The <B>data</B> argument is ignored +in this case. +<P> +<A NAME="lbAV"> </A> +<H2>SETTING AN INACTIVITY TIMEOUT</H2> + +<P> +On systems with the <B>select()</B> system call, the +<B>gl_inactivity_timeout()</B> 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 <B>gl_watch_fd()</B>. On oddball systems that don't +have <B>select()</B>, this call has no effect. +<P> +<P> +<PRE> + int gl_inactivity_timeout(GetLine *gl, GlTimeoutFn *callback, + void *data, unsigned long sec, + unsigned long nsec); +</PRE> + +<P> +<P> +The timeout is specified in the form of an integral number of seconds +and an integral number of nanoseconds, via the <B>sec</B> and +<B>nsec</B> arguments respectively. Subsequently, whenever no activity +is seen for this time period, the function specified via the +<B>callback</B> argument is called. The <B>data</B> argument of +<B>gl_inactivity_timeout()</B> 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 following macro +is provided in <B>libtecla.h</B> for applications to use to declare and +prototype timeout callback functions. +<P> +<P> +<PRE> + #define GL_TIMEOUT_FN(fn) \ + GlAfterTimeout (fn)(GetLine *gl, void *data) +</PRE> + +<P> +<P> +On returning, the application's callback is expected to return one of +the following enumerators to tell <B>gl_get_line()</B> how to procede +after the timeout has been handled by the callback. +<P> +<P> +<PRE> + GLTO_ABORT - Tell gl_get_line() to abort. When + this happens, <B>gl_get_line()</B> will + return <B>NULL</B>, and a following call + to <B>gl_return_status()</B> will return + <B>GLR_TIMEOUT</B>. Note that if the + application needs <B>errno</B> always to + have a meaningful value when + <B>gl_get_line()</B> returns <B>NULL</B>, + the callback function should set + <B>errno</B> 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 + <B>gl_normal_io(gl)</B>. + 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">gl_io_mode</A>(3)), cause <B>gl_get_line()</B> + to act as though I/O blocked. This means + that <B>gl_get_line()</B> will immediately + return <B>NULL</B>, and a following call + to <B>gl_return_status()</B> will return + <B>GLR_BLOCKED</B>. +</PRE> + +<P> +<P> +Note that before calling the callback, <B>gl_get_line()</B> blocks most +signals, and leaves its own signal handlers installed, so if you need +to catch a particular signal you will need to both temporarily install +your own signal handler, and unblock the signal. Be sure to re-block +the signal (if it was originally blocked) and reinstate the original +signal handler, if any, before returning. +<P> +<P> +<P> +If the callback function needs to read or write to the terminal, it +should ideally first call <B>gl_normal_io(gl)</B> 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, <B>gl_get_line()</B> will +notice that <B>gl_normal_io()</B> was called, redisplay the input line +and resume editing. Note that in this case the return values, +<B>GLTO_REFRESH</B> and <B>GLTO_CONTINUE</B> are equivalent. +<P> +<P> +<P> +To support cases where the callback function calls a third-party +function which occasionally and unpredictably writes to the terminal, +the automatic conversion of <B>"</B> to <B>"</B> is re-enabled +before the callback function is called. If the callack knows that the +third-party function wrote to the terminal, it should then return the +<B>GLTO_REFRESH</B> return value, to tell <B>gl_get_line()</B> to +redisplay the input line. +<P> +<P> +<P> +Note that although the timeout argument includes a nano-second +component, 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 +<B>sysconf(_SC_CLK_TCK)</B>). +<P> +<P> +<P> +To turn off timeouts, simply call <B>gl_inactivity_timeout()</B> with a +<B>callback</B> argument of <B>0</B>. The <B>data</B> argument is ignored +in this case. +<P> +<A NAME="lbAW"> </A> +<H2>SIGNAL HANDLING DEFAULTS</H2> + +<P> +By default, the <B>gl_get_line()</B> function intercepts a +number of signals. This is particularly important for +signals which would by default terminate the process, since +the terminal needs to be restored to a usable state before +this happens. In this section, the signals that are trapped +by default, and how <B>gl_get_line()</B> responds to them, is +described. Changing these defaults is the topic of the +following section. +<P> +When the following subset of signals are caught, <B>gl_get_line()</B> +first restores the terminal settings and signal handling to how they +were before <B>gl_get_line()</B> was called, resends the signal, to +allow the calling application's signal handlers to handle it, then if +the process still exists, <B>gl_get_line()</B> returns <B>NULL</B> and +sets <B>errno</B> as specified below. +<P> +<P> +<PRE> + 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 <B>gl_change_terminal()</B> 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 +</PRE> + +<P> +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 <B>SIGQUIT</B> 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 <B>gl_get_line()</B> returns. +<P> +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. +<P> +<PRE> + int gl_last_signal(const GetLine *gl); +</PRE> + +<P> +This returns the numeric code (eg. <B>SIGINT</B>) of the last signal +that was received during the most recent call to <B>gl_get_line()</B>, +or <B>-1</B> if no signals were received. +<P> +On systems that support it, when a SIGWINCH (window change) signal is +received, <B>gl_get_line()</B> 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. +<P> +Finally, the following signals cause <B>gl_get_line()</B> to first +restore the terminal and signal environment to that which prevailed +before <B>gl_get_line()</B> was called, then resend the signal to the +application. If the process still exists after the signal has been +delivered, then <B>gl_get_line()</B> 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. +<P> +<PRE> + 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 <B>gl_get_line()</B> 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 <A HREF="setitimer.html">setitimer</A>(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. +</PRE> + +<P> +<P> +Obviously not all of the above signals are supported on all systems, +so code to support them is conditionally compiled into the tecla +library. +<P> +Note that if <B>SIGKILL</B> or <B>SIGPOLL</B>, which by definition can't +be caught, or any of the hardware generated exception signals, such as +<B>SIGSEGV</B>, <B>SIGBUS</B> and <B>SIGFPE</B>, are received and +unhandled while <B>gl_get_line()</B> has the terminal in raw mode, the +program will be terminated without the terminal having been restored +to a usable state. In practice, job-control shells usually reset the +terminal settings when a process relinquishes the controlling +terminal, so this is only a problem with older shells. +<P> +<A NAME="lbAX"> </A> +<H2>CUSTOMIZED SIGNAL HANDLING</H2> + +<P> +The previous section listed the signals that +<B>gl_get_line()</B> 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 <B>gl_get_line()</B> should respond to a given +signal. +<P> +If you don't need <B>gl_get_line()</B> to do anything in +response to a signal that it normally traps, you can tell to +<B>gl_get_line()</B> to ignore that signal by calling +<B>gl_ignore_signal()</B>. +<P> +<PRE> + int gl_ignore_signal(GetLine *gl, int signo); +</PRE> + +<P> +The <B>signo</B> argument is the number of the signal +(eg. <B>SIGINT</B>) that you want to have ignored. If the +specified signal isn't currently one of those being trapped, +this function does nothing. +<P> +The <B>gl_trap_signal()</B> function allows you to either add +a new signal to the list that <B>gl_get_line()</B> traps, or +modify how it responds to a signal that it already traps. +<P> +<PRE> + int gl_trap_signal(GetLine *gl, int signo, unsigned flags, + GlAfterSignal after, int errno_value); +</PRE> + +<P> +The <B>signo</B> argument is the number of the signal that +you wish to have trapped. The <B>flags</B> argument is a set +of flags which determine the environment in which the +application's signal handler is invoked, the <B>after</B> +argument tells <B>gl_get_line()</B> what to do after the +application's signal handler returns, and <B>errno_value</B> +tells <B>gl_get_line()</B> what to set <B>errno</B> to if told +to abort. +<P> +The <B>flags</B> argument is a bitwise OR of zero or more of +the following enumerators: +<P> +<PRE> + 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. +</PRE> + +<P> +Two commonly useful flag combinations are also enumerated as +follows: +<P> +<PRE> + GLS_RESTORE_ENV = GLS_RESTORE_SIG | GLS_RESTORE_TTY | + GLS_REDRAW_LINE + + GLS_SUSPEND_INPUT = GLS_RESTORE_ENV | GLS_RESTORE_LINE +</PRE> + +<P> +<P> +If your signal handler, or the default system signal +handler for this signal, if you haven't overridden it, never +either writes to the terminal, nor suspends or terminates +the calling program, then you can safely set the <B>flags</B> +argument to <B>0</B>. +<P> +If your signal handler always writes to the terminal, reads +from it, or suspends or terminates the program, you should +specify the <B>flags</B> argument as <B>GL_SUSPEND_INPUT</B>, +so that: +<P> +<PRE> +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 + <B>\r\n</B>, instead of just <B>\n</B>. +</PRE> + +<P> +The <B>GL_RESTORE_ENV</B> combination is the same as +<B>GL_SUSPEND_INPUT</B>, 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 <B>GL_SUSPEND_LINE</B> would cause +the input line to be unnecessarily duplicated when nothing +had been written to the terminal. Such a signal handler, +when it does write to the terminal, should be sure to start +a new line at the start of its first write, by writing a +\ +n' character, and should be sure to leave the cursor on a +new line before returning. If the signal arrives while the +user is entering a line that only occupies a signal terminal +line, or if the cursor is on the last terminal line of a +longer input line, this will have the same effect as +<B>GL_SUSPEND_INPUT</B>. 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 <B>GL_SUSPEND_INPUT</B> combination is better if you +know that you are always going to be writting to the +terminal. +<P> +The <B>after</B> argument, which determines what +<B>gl_get_line()</B> does after the application's signal +handler returns (if it returns), can take any one of the +following values: +<P> +<PRE> + GLS_RETURN - Return the completed input line, just as + though the user had pressed the return + key. + + GLS_ABORT - Cause <B>gl_get_line()</B> to abort. When + this happens, <B>gl_get_line()</B> returns + <B>NULL</B>, and a following call to + <B>gl_return_status()</B> will return + <B>GLR_SIGNAL</B>. Note that if the + application needs <B>errno</B> always to + have a meaningful value when + <B>gl_get_line()</B> returns <B>NULL</B>, + the callback function should set + <B>errno</B> appropriately. + GLS_CONTINUE - Resume command line editing. +</PRE> + +<P> +The <B>errno_value</B> argument is intended to be combined +with the <B>GLS_ABORT</B> option, telling <B>gl_get_line()</B> +what to set the standard <B>errno</B> variable to before +returning <B>NULL</B> to the calling program. It can also, +however, be used with the <B>GL_RETURN</B> 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. +<P> +<A NAME="lbAY"> </A> +<H2>RELIABLE SIGNAL HANDLING</H2> + +<P> +Signal handling is suprisingly hard to do reliably without race +conditions. In <B>gl_get_line()</B> a lot of care has been taken to +allow applications to perform reliable signal handling around +<B>gl_get_line()</B>. This section explains how to make use of this. +<P> +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 <B>gl_get_line()</B>. If a SIGINT +signal happens to be received in the small window of time between the +statement that tests the value of this flag, and the statement that +calls <B>gl_get_line()</B>, then <B>gl_get_line()</B> 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 <B>gl_get_line()</B> +returns. Depending on the application, this might or might not be a +disaster, but at the very least it would puzzle the user. +<P> +The way to avoid such problems is to do the following. +<P> +1. If needed, use the <B>gl_trap_signal()</B> function to +<BR> configure <B>gl_get_line()</B> to abort when important +<BR> signals are caught. +<P> +2. Configure <B>gl_get_line()</B> such that if any of the +<BR> signals that it catches are blocked when +<BR> <B>gl_get_line()</B> is called, they will be unblocked +<BR> automatically during times when <B>gl_get_line()</B> is +<BR> waiting for I/O. This can be done either +<BR> on a per signal basis, by calling the +<BR> <B>gl_trap_signal()</B> function, and specifying the +<BR> <B>GLS_UNBLOCK</B> attribute of the signal, or globally by +<BR> calling the <B>gl_catch_blocked()</B> function. +<P> +<P> +<PRE> + void gl_catch_blocked(GetLine *gl); +</PRE> + +<P> +<P> +<BR> This function simply adds the <B>GLS_UNBLOCK</B> attribute +<BR> to all of the signals that it is currently configured to +<BR> trap. +<P> +3. Just before calling <B>gl_get_line()</B>, block delivery +<BR> of all of the signals that <B>gl_get_line()</B> is +<BR> configured to trap. This can be done using the POSIX +<BR> <B>sigprocmask()</B> function in conjunction with the +<BR> <B>gl_list_signals()</B> function. +<P> +<P> +<PRE> + int gl_list_signals(GetLine *gl, sigset_t *set); +</PRE> + +<P> +<P> +<BR> This function returns the set of signals that it is +<BR> currently configured to catch in the <B>set</B> argument, +<BR> which is in the form required by <B>sigprocmask()</B>. +<P> +4. In the example, one would now test the global flag that +<BR> the signal handler sets, knowing that there is now no +<BR> danger of this flag being set again until +<BR> <B>gl_get_line()</B> unblocks its signals while performing +<BR> I/O. +<P> +5. Eventually <B>gl_get_line()</B> returns, either because +<BR> a signal was caught, an error occurred, or the user +<BR> finished entering their input line. +<P> +6. Now one would check the global signal flag again, and if +<BR> it is set, respond to it, and zero the flag. +<P> +7. Use <B>sigprocmask()</B> to unblock the signals that were +<BR> blocked in step 3. +<P> +The same technique can be used around certain POSIX +signal-aware functions, such as <B>sigsetjmp()</B> and +<B>sigsuspend()</B>, and in particular, the former of these +two functions can be used in conjunction with +<B>siglongjmp()</B> to implement race-condition free signal +handling around other long-running system calls. The way to +do this, is explained next, by showing how +<B>gl_get_line()</B> manages to reliably trap signals around +calls to functions like <B>read()</B> and <B>select()</B> +without race conditions. +<P> +The first thing that <B>gl_get_line()</B> does, whenever it +is called, is to use the POSIX <B>sigprocmask()</B> 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. +<P> +Whenever <B>gl_get_line()</B> needs to call <B>read()</B> or +<B>select()</B> to wait for input from the user, it first +calls the POSIX <B>sigsetjmp()</B> function, being sure to +specify a non-zero value for its <B>savesigs</B> argument. +The reason for the latter argument will become clear +shortly. +<P> +If <B>sigsetjmp()</B> returns zero, <B>gl_get_line()</B> then +does the following. +<P> +<P> +<PRE> +a. It uses the POSIX <B>sigaction()</B> 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 <B>siglongjmp()</B> + function using the buffer that was passed to + <B>sigsetjmp()</B> for its first argument, and + a non-zero value for its second argument. + + When this signal handler is registered, the <B>sa_mask</B> + member of the <B>struct sigaction act</B> argument of the + call to <B>sigaction()</B> is configured to contain all of + the signals that <B>gl_get_line()</B> 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, + <B>gl_get_line()</B> unblocks all of the signals that it + is configured to catch. + +c. It then calls the <B>read()</B> or <B>select()</B> system + calls to wait for keyboard input. + +d. If this system call returns (ie. no signal is received), + <B>gl_get_line()</B> 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. +</PRE> + +<P> +<P> +Alternatively, if <B>sigsetjmp()</B> returns non-zero, this +means that one of the signals being trapped was caught while +the above steps were executing. When this happens, +<B>gl_get_line()</B> does the following. +<P> +First, note that when a call to <B>siglongjmp()</B> causes +<B>sigsetjmp()</B> to return, provided that the +<B>savesigs</B> argument of <B>sigsetjmp()</B> was non-zero, +as specified above, the signal process mask is restored to +how it was when <B>sigsetjmp()</B> was called. This is the +important difference between <B>sigsetjmp()</B> and the older +problematic <B>setjmp()</B>, 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 <B>sigsetjmp()</B> +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 signals being +caught. +<P> +1. If so instructed by the <B>gl_get_line()</B> configuration +<BR> attributes of the signal that was caught, +<BR> <B>gl_get_line()</B> restores the terminal attributes to +<BR> the state that they had when <B>gl_get_line()</B> was +<BR> called. This is particularly important for signals that +<BR> suspend or terminate the process, since otherwise the +<BR> terminal would be left in an unusable state. +<P> +2. It then reinstates the application's signal handlers. +<P> +3. Then it uses the C standard-library <B>raise()</B> +<BR> function to re-send the application the signal that +<BR> was caught. +<P> +3. Next it unblocks delivery of the signal that we just +<BR> sent. This results in the signal that was just sent +<BR> via <B>raise()</B>, being caught by the application's +<BR> original signal handler, which can now handle it as it +<BR> sees fit. +<P> +4. If the signal handler returns (ie. it doesn't terminate +<BR> the process), <B>gl_get_line()</B> blocks delivery of the +<BR> above signal again. +<P> +5. It then undoes any actions performed in the first of the +<BR> above steps, and redisplays the line, if the signal +<BR> configuration calls for this. +<P> +6. <B>gl_get_line()</B> then either resumes trying to +<BR> read a character, or aborts, depending on the +<BR> configuration of the signal that was caught. +<P> +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 <B>gl_get_line()</B> has +complete control over its environment. +<P> +<A NAME="lbAZ"> </A> +<H2>THE TERMINAL SIZE</H2> + +<P> +On most systems the combination of the <B>TIOCGWINSZ</B> ioctl and the +<B>SIGWINCH</B> signal is used to maintain an accurate idea of the +terminal size. The terminal size is newly queried every time that +<B>gl_get_line()</B> is called and whenever a <B>SIGWINCH</B> signal is +received. +<P> +On the few systems where this mechanism isn't available, at +startup <B>new_GetLine()</B> first looks for the <B>LINES</B> +and <B>COLUMNS</B> environment variables. If these aren't +found, or they contain unusable values, then if a terminal +information database like terminfo or termcap is available, +the default size of the terminal is looked up in this +database. If this too fails to provide the terminal size, a +default size of 80 columns by 24 lines is used. +<P> +Even on systems that do support <B>ioctl(TIOCGWINSZ)</B>, 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 <B>SIGWINCH</B> is sent to +the process, and the dimensions returned by <B>ioctl(TIOCGWINSZ)</B> +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 +<B>gl_set_term_size()</B> function to tell <B>gl_get_line()</B> about +the change in size. +<P> +<P> +<PRE> + int gl_set_term_size(GetLine *gl, int ncolumn, int nline); +</PRE> + +<P> +<P> +The <B>ncolumn</B> and <B>nline</B> arguments are used to specify the +new dimensions of the terminal, and must not be less than 1. On +systems that do support <B>ioctl(TIOCGWINSZ)</B>, this function first +calls <B>ioctl(TIOCSWINSZ)</B> 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 <B>gl</B> for +future use by <B>gl_get_line()</B>. +<P> +The <B>gl_terminal_size()</B> 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. +<P> +<PRE> + 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); +</PRE> + +<P> +This function first updates <B>gl_get_line()</B>'s fallback terminal +dimensions, then records its findings in the return value. +<P> +The <B>def_ncolumn</B> and <B>def_nline</B> specify the +default number of terminal columns and lines to use if the +terminal size can't be determined via <B>ioctl(TIOCGWINSZ)</B> or +environment variables. +<P> +<A NAME="lbBA"> </A> +<H2>HIDING WHAT YOU TYPE</H2> + +<P> +When entering sensitive information, such as passwords, it is best not +to have the text that you are entering echoed on the terminal. +Furthermore, such text should not be recorded in the history list, +since somebody finding your terminal unattended could then recall it, +or somebody snooping through your directories could see it in your +history file. With this in mind, the <B>gl_echo_mode()</B> +function allows you to toggle on and off the display and archival of +any text that is subsequently entered in calls to <B>gl_get_line()</B>. +<P> +<P> +<PRE> + int gl_echo_mode(GetLine *gl, int enable); +</PRE> + +<P> +<P> +The <B>enable</B> argument specifies whether entered text +should be visible or not. If it is <B>0</B>, then +subsequently entered lines will not be visible on the +terminal, and will not be recorded in the history list. If +it is <B>1</B>, then subsequent input lines will be displayed +as they are entered, and provided that history hasn't been +turned off via a call to <B>gl_toggle_history()</B>, then +they will also be archived in the history list. Finally, if +the <B>enable</B> argument is <B>-1</B>, then the echoing mode +is left unchanged, which allows you to non-destructively +query the current setting via the return value. In all +cases, the return value of the function is <B>0</B> if +echoing was disabled before the function was called, and +<B>1</B> if it was enabled. +<P> +When echoing is turned off, note that although tab +completion will invisibly complete your prefix as far as +possible, ambiguous completions will not be displayed. +<P> +<A NAME="lbBB"> </A> +<H2>SINGLE CHARACTER QUERIES</H2> + +<P> +Using <B>gl_get_line()</B> 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 <B>gl_query_char()</B> function has been provided for +single character queries like this. +<P> +<P> +<PRE> + int gl_query_char(GetLine *gl, const char *prompt, + char defchar); +</PRE> + +<P> +<P> +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 character, <B>gl_query_char()</B> 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, <B>EOF</B> is +returned instead. In the latter case, the application can call the +previously documented <B>gl_return_status()</B>, to find out what went +wrong. This could, for example, have been the reception of a signal, +or the optional inactivity timer going off. +<P> +If the user simply hits enter, the value of the <B>defchar</B> argument +is substituted. This means that when the user hits either newline or +return, the character specified in <B>defchar</B>, 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 <B>'</B> as the value of <B>defchar</B>. +<P> +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. +<P> +As with <B>gl_get_line()</B>, echoing of the entered character can be +disabled using the <B>gl_echo_mode()</B> function. +<P> +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 +<B>gl_query_char()</B> resumes waiting for the user to type a +character. +<P> +Note that in non-blocking server mode, (see +<A HREF="gl_io_mode.html">gl_io_mode</A>(3)), if an incomplete input line is in the +process of being read when <B>gl_query_char()</B> is called, the +partial input line is discarded, and erased from the terminal, before +the new prompt is displayed. The next call to <B>gl_get_line()</B> will +thus start editing a new line. +<P> +<A NAME="lbBC"> </A> +<H2>READING RAW CHARACTERS</H2> + +<P> +Whereas the <B>gl_query_char()</B> function visibly prompts the user +for a character, and displays what they typed, the +<B>gl_read_char()</B> 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 <B>gl_get_line()</B>, but also from callback +functions that the application has registered to be called by +<B>gl_get_line()</B>. +<P> +<P> +<PRE> + int gl_read_char(GetLine *gl); +</PRE> + +<P> +<P> +On success, the return value of <B>gl_read_char()</B> is the character +that was read. On failure, <B>EOF</B> is returned, and the +<B>gl_return_status()</B> function 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. +<P> +Beware that certain keyboard keys, such as function keys, and cursor +keys, usually generate at least 3 characters each, so a single call to +<B>gl_read_char()</B> won't be enough to identify such keystrokes. +<P> +<A NAME="lbBD"> </A> +<H2>CLEARING THE TERMINAL</H2> + +<P> +The calling program can clear the terminal by calling +<B>gl_erase_terminal()</B>. In non-blocking server-I/O mode, this +function also arranges for the current input line to be redrawn from +scratch when <B>gl_get_line()</B> is next called. +<P> +<P> +<PRE> + int gl_erase_terminal(GetLine *gl); +</PRE> + +<P> +<P> +<A NAME="lbBE"> </A> +<H2>DISPLAYING TEXT DYNAMICALLY</H2> + +<P> +Between calls to <B>gl_get_line()</B>, the <B>gl_display_text()</B> +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 introductions. In those examples the advanced use of +optional prefixes, suffixes and filled lines to draw a box around the +text is also illustrated. +<P> +<P> +<PRE> + 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); +</PRE> + +<P> +If <B>gl</B> isn't currently connected to a terminal, for example if +the output of a program that uses <B>gl_get_line()</B> is being piped +to another program or redirected to a file, then the value of the +<B>def_width</B> parameter is used as the terminal width. +<P> +The <B>indentation</B> argument specifies the number of characters to +use to indent each line of ouput. The <B>fill_char</B> argument +specifies the character that will be used to perform this indentation. +<P> +The <B>prefix</B> argument can either be <B>NULL</B>, or be a string to +place at the beginning of each new line (after any indentation). +Similarly, the <B>suffix</B> argument can either be <B>NULL</B>, 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 <B>fill_char</B> argument. Normally the +fill-character is a space. +<P> +The <B>start</B> argument tells <B>gl_display_text()</B> 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 <B>gl_display_text()</B> is the ending column index of +the cursor, by passing the return value of one call to the <B>start</B> +argument of the next call, a paragraph that is broken between more +than one string can be composed by calling <B>gl_display_text()</B> for +each successive portion of the paragraph. Note that literal newline +characters are necessary at the end of each paragraph to force a new +line to be started. +<P> +On error, <B>gl_display_text()</B> returns -1. +<P> +<A NAME="lbBF"> </A> +<H2>CALLBACK FUNCTION FACILITIES</H2> + +<P> +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. +<P> +Calling the <B>gl_replace_prompt()</B> function from a +callback tells <B>gl_get_line()</B> to display a different +prompt when the callback returns. Except in non-blocking +server mode, it has no effect if used between calls to +<B>gl_get_line()</B>. In non-blocking server mode (see the +<B><A HREF="gl_io_mode.html">gl_io_mode</A>(3)</B> man page, when used between two calls to +<B>gl_get_line()</B> 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 <B>gl_get_line()</B>. +<P> +<P> +<PRE> + void gl_replace_prompt(GetLine *gl, const char *prompt); +</PRE> + +<P> +<P> +<A NAME="lbBG"> </A> +<H2>INTERNATIONAL CHARACTER SETS</H2> + +<P> +Since libtecla version 1.4.0, <B>gl_get_line()</B> 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, +<P> +<PRE> + setlocale(LC_CTYPE, ""); +</PRE> + +<P> +then the current locale is determined by the first of the environment +variables <B>LC_CTYPE</B>, <B>LC_ALL</B>, and <B>LANG</B>, 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 +<B>C</B> 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: +<P> +<PRE> + locale -a +</PRE> + +<P> +at the shell prompt. Further documentation on how the user can make use +of this to enter international characters can be found in the +<B><A HREF="tecla.html">tecla</A>(7)</B> man page. +<P> +<A NAME="lbBH"> </A> +<H2>THREAD SAFETY</H2> + +<P> +In a multi-threaded program, you should use the libtecla_r.a version +of the library. This uses reentrant versions of system functions, +where available. Unfortunately neither terminfo nor termcap were +designed to be reentrant, so you can't safely use the functions of the +getline module in multiple threads (you can use the separate +file-expansion and word-completion modules in multiple threads, see +the corresponding man pages for details). However due to the use of +POSIX reentrant functions for looking up home directories etc, it is +safe to use this module from a single thread of a multi-threaded +program, provided that your other threads don't use any termcap or +terminfo functions. +<P> +<A NAME="lbBI"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library +libtecla.h - The tecla header file. +~/.teclarc - The personal tecla customization file. +</PRE> + +<P> +<A NAME="lbBJ"> </A> +<H2>SEE ALSO</H2> + +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_io_mode.html">gl_io_mode</A>(3), <A HREF="tecla.html">tecla</A>(7), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="cpl_complete_word.html">cpl_complete_word</A>(3), <A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) +</PRE> + +<P> +<A NAME="lbBK"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">AN EXAMPLE</A><DD> +<DT><A HREF="#lbAF">THE FUNCTIONS USED IN THE EXAMPLE</A><DD> +<DT><A HREF="#lbAG">THE RETURN STATUS OF GL_GET_LINE</A><DD> +<DT><A HREF="#lbAH">OPTIONAL PROMPT FORMATTING</A><DD> +<DT><A HREF="#lbAI">ALTERNATE CONFIGURATION SOURCES</A><DD> +<DT><A HREF="#lbAJ">CUSTOMIZED WORD COMPLETION</A><DD> +<DT><A HREF="#lbAK">ADDING COMPLETION ACTIONS</A><DD> +<DT><A HREF="#lbAL">DEFINING CUSTOM ACTIONS</A><DD> +<DT><A HREF="#lbAM">HISTORY FILES</A><DD> +<DT><A HREF="#lbAN">MULTIPLE HISTORY LISTS</A><DD> +<DT><A HREF="#lbAO">DISPLAYING HISTORY</A><DD> +<DT><A HREF="#lbAP">LOOKING UP HISTORY</A><DD> +<DT><A HREF="#lbAQ">MANUAL HISTORY ARCHIVAL</A><DD> +<DT><A HREF="#lbAR">MISCELLANEOUS HISTORY CONFIGURATION</A><DD> +<DT><A HREF="#lbAS">QUERYING HISTORY INFORMATION</A><DD> +<DT><A HREF="#lbAT">CHANGING TERMINALS</A><DD> +<DT><A HREF="#lbAU">EXTERNAL EVENT HANDLING</A><DD> +<DT><A HREF="#lbAV">SETTING AN INACTIVITY TIMEOUT</A><DD> +<DT><A HREF="#lbAW">SIGNAL HANDLING DEFAULTS</A><DD> +<DT><A HREF="#lbAX">CUSTOMIZED SIGNAL HANDLING</A><DD> +<DT><A HREF="#lbAY">RELIABLE SIGNAL HANDLING</A><DD> +<DT><A HREF="#lbAZ">THE TERMINAL SIZE</A><DD> +<DT><A HREF="#lbBA">HIDING WHAT YOU TYPE</A><DD> +<DT><A HREF="#lbBB">SINGLE CHARACTER QUERIES</A><DD> +<DT><A HREF="#lbBC">READING RAW CHARACTERS</A><DD> +<DT><A HREF="#lbBD">CLEARING THE TERMINAL</A><DD> +<DT><A HREF="#lbBE">DISPLAYING TEXT DYNAMICALLY</A><DD> +<DT><A HREF="#lbBF">CALLBACK FUNCTION FACILITIES</A><DD> +<DT><A HREF="#lbBG">INTERNATIONAL CHARACTER SETS</A><DD> +<DT><A HREF="#lbBH">THREAD SAFETY</A><DD> +<DT><A HREF="#lbBI">FILES</A><DD> +<DT><A HREF="#lbBJ">SEE ALSO</A><DD> +<DT><A HREF="#lbBK">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/gl_io_mode.html b/libtecla-1.6.3/html/gl_io_mode.html new file mode 100644 index 0000000..42d27dc --- /dev/null +++ b/libtecla-1.6.3/html/gl_io_mode.html @@ -0,0 +1,634 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of gl_io_mode</TITLE> +</HEAD><BODY> +<H1>gl_io_mode</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +<BR> gl_io_mode, gl_raw_io, gl_normal_io, gl_tty_signals, gl_abandon_line, +<BR> gl_handle_signal, gl_pending_io - How to use gl_get_line() from an external event loop. +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + +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> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>gl_get_line()</B> function, which is documented separately in +the <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B> man page, supports two different I/O modes. +These are selected by calling the <B>gl_io_mode()</B> function. +<P> +<P> +<PRE> + int gl_io_mode(GetLine *gl, GlIOMode mode); +</PRE> + +<P> +<P> +The <B>mode</B> argument of this function specifies the new I/O mode, +and must be one of the following. +<P> +<P> +<PRE> + GL_NORMAL_MODE - Select the normal blocking-I/O mode. + In this mode <B>gl_get_line()</B> + doesn't return until either an error + occurs of the user finishes entering a + new line. This mode is the focus of + the <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B> 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 <B>gl_get_line()</B> from + an external I/O-driven event loop. + This mode is the focus of this man + page. +</PRE> + +<P> +<P> +Newly created <B>GetLine</B> objects start in normal I/O +mode, so to switch to non-blocking server mode requires an +initial call to <B>gl_io_mode()</B>. +<P> +<A NAME="lbAE"> </A> +<H2>SERVER I/O MODE</H2> + +<P> +In non-blocking server I/O mode, the application is required +to have an event loop which calls <B>gl_get_line()</B> +whenever the terminal file descriptor can do the type I/O +that <B>gl_get_line()</B> is waiting for. To determine which +type of I/O <B>gl_get_line()</B> is waiting for, the +application calls the <B>gl_pending_io()</B> function. +<P> +<P> +<PRE> + GlPendingIO gl_pending_io(GetLine *gl); +</PRE> + +<P> +<P> +The return value of this function is one of the following two +enumerated values. +<P> +<P> +<PRE> + 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. +</PRE> + +<P> +<P> +If the application is using either the <B>select()</B> or <B>poll()</B> +system calls to watch for I/O on a group of file descriptors, then it +should call the <B>gl_pending_io()</B> 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 <B>select()</B> system call, this means using the <B>FD_SET()</B> +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. +<P> +As in normal I/O mode, the return value of <B>gl_get_line()</B> is +either a pointer to a completed input line, or <B>NULL</B>. However, +whereas in normal I/O mode a <B>NULL</B> return value always means that +an error occurred, in non-blocking server mode, <B>NULL</B> is also +returned when <B>gl_get_line()</B> can't read or write to the terminal +without blocking. Thus in non-blocking server mode, in order to +determine when a <B>NULL</B> return value signifies that an error +occurred or not, it is necessary to call the <B>gl_return_status()</B> +function. If this function returns the enumerated value, +<B>GLR_BLOCKED</B>, as documented in the <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B> man page, +this means that <B>gl_get_line()</B> is waiting for I/O, and no error +has occurred. +<P> +When <B>gl_get_line()</B> returns <B>NULL</B> and +<B>gl_return_status()</B> indicates that this is due to blocked +terminal I/O, the application should call <B>gl_get_line()</B> again +when the type of I/O reported by <B>gl_pending_io()</B> becomes +possible. The <B>prompt</B>, <B>start_line</B> and <B>start_pos</B> +arguments of <B>gl_get_line()</B> 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 <B>gl_replace_prompt()</B> function +(documented in the <B><A HREF="gl_get_line.html">gl_get_line</A>(3) man page) between calls to +gl_get_line()</B>. +<P> +<A NAME="lbAF"> </A> +<H2>GIVING UP THE TERMINAL</H2> + +<P> +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 +<B>gl_get_line()</B>. 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 <B>gl_get_line()</B>. What this means is that any +time that the terminal needs to be used for other things than entering +a new input line with <B>gl_get_line()</B>, it needs to be restored to +a usable state. In particular, whenever the process is suspended or +terminated, the terminal 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 <B>gl_normal_io()</B> function is provided +for switching the terminal back to the state that it was in when raw +mode was last established. +<P> +<P> +<PRE> + int gl_normal_io(GetLine *gl); +</PRE> + +<P> +<P> +What this function does is first flush any pending output to the +terminal, then move the cursor to the start of the terminal line which +follows 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 <B>gl_raw_io()</B> +function. +<P> +<P> +<PRE> + int gl_raw_io(GetLine *gl); +</PRE> + +<P> +<P> +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 <B>gl_normal_io()</B> was called, then switches back +to raw, non-blocking terminal mode ready to continue entry of the +input line when <B>gl_get_line()</B> is next called. +<P> +Note that in non-blocking server mode, if <B>gl_get_line()</B> is +called after a call to <B>gl_normal_io()</B>, without an intervening +call to <B>gl_raw_io()</B>, <B>gl_get_line()</B> will call +<B>gl_raw_mode()</B> itself, and the terminal will remain in this mode +when <B>gl_get_line()</B> returns. +<P> +<A NAME="lbAG"> </A> +<H2>SIGNAL HANDLING</H2> + +<P> +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 <B>gl_get_line()</B>, but in +non-blocking server mode, since the terminal is left in raw mode +between calls to <B>gl_get_line()</B>, 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 +<B>gl_get_line()</B>, such as the <B>SIGWINCH</B> signal, which tells it +when the terminal size has changed, the <B>gl_tty_signals()</B> +function is provided for installing signal handlers for all pertinent +signals. +<P> +<P> +<PRE> + int gl_tty_signals(void (*term_handler)(int), + void (*susp_handler)(int), + void (*cont_handler)(int), + void (*size_handler)(int)); +</PRE> + +<P> +<P> +What this does is use <B>gl_get_line()</B>'s internal list of signals +to assign specified signal handlers to groups of signals. The +arguments of this function are as follows. +<P> +<P> +<PRE> + 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). +</PRE> + +<P> +<P> +These arguments can all be the same, if so desired, and you can +specify <B>SIG_IGN</B> (ignore this signal) or <B>SIG_DFL</B> (use the +system-provided default signal handler) instead of a function where +pertinent. In particular, it is rarely useful to trap <B>SIGCONT</B>, +so the <B>cont_handler</B> argument will usually be <B>SIG_DFL</B> or +<B>SIG_IGN</B>. +<P> +The <B>gl_tty_signals()</B> function uses the POSIX <B>sigaction()</B> +function to install these signal handlers, and it is careful to use +the <B>sa_mask</B> 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 +<B>sigsetjmp()</B> buffer or a signal-received flag. +<P> +The signal handlers that are installed by this function, should call +the <B>gl_handle_signal(). +<P> +<P> +</B><PRE> + void gl_handle_signal(int signo, GetLine *gl, int ngl); +</PRE> + +<P> +<P> +The <B>signo</B> argument tells this function which signal it is being +asked to respond to, and the <B>gl</B> argument should be a pointer to +the first element of an array of <B>ngl</B> <B>GetLine</B> objects. If +your application only has one of these objects, just pass its pointer +as the <B>gl</B> argument and specify <B>ngl</B> as <B>1</B>. +<P> +Depending on the signal that is being handled, this function does +different things. +<P> +<A NAME="lbAH"> </A> +<H3>Terminal resize signals (SIGWINCH)</H3> + +<P> +If the signal indicates that the terminal was resized, then it +arranges for the next call to <B>gl_get_line()</B> to ask the terminal +for its new size and redraw the input line accordingly. In order that +<B>gl_get_line()</B> be called as soon as possible to do this, +<B>gl_handle_signal()</B> also arranges that the next call to +<B>gl_pending_io()</B> will return <B>GLP_WRITE</B>. Thus if the +application waits for I/O in <B>select()</B> or <B>poll()</B>, then the +application needs to ensure that these functions will be reliably +aborted when a signal is caught and handled by the application. More +on this below. +<P> +<A NAME="lbAI"> </A> +<H2>Process termination signals.</H2> + +<P> +If the signal that was caught is one of those that by default +terminates any process that receives it, then <B>gl_handle_signal()</B> +does the following steps. +<P> +1. First it blocks the delivery of all signals that can be +<BR> blocked (ie. <B>SIGKILL</B> and <B>SIGSTOP</B> can't be blocked) +<P> +2. Next it calls <B>gl_normal_io()</B> for each of the <B>ngl</B> +<BR> <B>GetLine</B> objects. Note that this does nothing to any of the +<BR> <B>GetLine</B> objects that aren't currently in raw mode. +<P> +3. Next it sets the signal handler of the signal to its default, +<BR> process-termination disposition. +<P> +4. Next it re-sends the process the signal that was caught. +<P> +5. Finally it unblocks delivery of this signal, which +<BR> results in the process being terminated. +<P> +<A NAME="lbAJ"> </A> +<H2>Process suspension signals.</H2> + +<P> +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, <B>gl_handle_signal()</B> +continues, and does the following steps. +<P> +6. It re-blocks delivery of the signal. +<P> +7. It reinstates the signal handler of the signal to the one +<BR> that was displaced when its default disposition was substituted. +<P> +8. For any of the <B>GetLine</B> objects that were in raw mode when +<BR> <B>gl_handle_signal()</B> was called, <B>gl_handle_signal()</B> then +<BR> calls <B>gl_raw_io()</B>, to resume entry of the input lines on +<BR> those terminals. +<P> +9. Finally, it restores the signal process mask to how it +<BR> was when <B>gl_handle_signal()</B> was called. +<P> +Note that the process is suspended or terminated using the original +signal that was caught, rather than using the uncatchable +<B>SIGSTOP</B> and <B>SIGKILL</B> 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 <B>wait()</B> 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 <B>SIGPIPE</B> signal, the program responded by sending +itself a <B>SIGKILL</B> signal, and the shell then printed out the +provocative statement, "Killed!". +<P> +<A NAME="lbAK"> </A> +<H2>INTERRUPTING THE EVENT LOOP</H2> + +<P> +If a signal is caught and handled when the application's event loop is +waiting in <B>select()</B> or <B>poll()</B>, these functions will be +aborted with <B>errno</B> set to <B>EINTR</B>. When this happens the +event loop should call <B>gl_pending_io()</B>, before calling +<B>select()</B> or <B>poll()</B> again. It should then arrange for +<B>select()</B> or <B>poll()</B> to wait for the type of I/O that this +reports. This is necessary, because any signal handler which calls +<B>gl_handle_signal()</B>, will frequently change the type of I/O that +<B>gl_get_line()</B> is waiting for. +<P> +Unfortunately, if a signal arrives between the statements which +configure the arguments of <B>select()</B> or <B>poll()</B> and the +calls to these functions, 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. +<P> +1. Block all of the signals that <B>gl_get_line()</B> catches, +<BR> by passing the signal set returned by <B>gl_list_signals()</B> to +<BR> <B>sigprocmask()</B>. +<P> +2. Call <B>gl_pending_io()</B> and set up the arguments of +<BR> <B>select()</B> or <B>poll()</B> accordingly. +<P> +3. Call <B>sigsetjmp()</B> with a non-zero <B>savesigs</B> argument. +<P> +4. Initially this <B>sigsetjmp()</B> statement will return zero, +<BR> indicating that control isn't resuming there after a matching +<BR> call to <B>siglongjmp()</B>. +<P> +5. Replace all of the handlers of the signals that <B>gl_get_line()</B> +<BR> is configured to catch, with a signal handler that first records +<BR> the number of the signal that was caught, in a file-scope variable, +<BR> then calls <B>siglongjmp()</B> with a non-zero value argument, to +<BR> return execution to the above <B>sigsetjmp()</B> +<BR> statement. Registering these signal handlers can conveniently be +<BR> done using the <B>gl_tty_signals()</B> function. +<P> +6. Set the file-scope variable that the above signal handler uses to +<BR> record any signal that is caught to -1, so that we can check +<BR> whether a signal was caught by seeing if it contains a valid signal +<BR> number. +<P> +7. Now unblock the signals that were blocked in step 1. Any signal +<BR> that was received by the process in between step 1 and now will +<BR> now be delivered, and trigger our signal handler, as will any +<BR> signal that is received until we block these signals again. +<P> +8. Now call <B>select()</B> or <B>poll()</B>. +<P> +9. When <B>select()</B> returns, again block the signals that were +<BR> unblocked in step 7. +<P> +If a signal is arrived any time during the above steps, our signal +handler will be triggered and cause control to return to the +<B>sigsetjmp()</B> statement, where this time, <B>sigsetjmp()</B> will +return non-zero, indicating 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 <B>sigsetjmp()</B> +returns, regardless of why it returned, the process signal mask is +returned to how it was when <B>sigsetjmp()</B> was called. Thus the +following statements are always executed with all of our signals +blocked. +<P> +9. Reinstate the signal handlers that were displaced in step 5. +<P> +10. Check wether a signal was caught, by checking the file-scope +<BR> variable that the signal handler records signal numbers in. +<P> +11. If a signal was caught, send this signal to the application +<BR> again, and unblock just this signal, so that it invokes the +<BR> signal handler which we just reinstated in step 10. +<P> +12. Unblock all of the signals that were blocked in step 7. +<P> +Since this is complicated, note that <B>demo3.c</B> 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 +<B>select()</B> which encompasses steps 3 to 11. In this wrapper, +rather than use <B>gl_list_signals()</B> to figure out the signals to +block, and and <B>gl_tty_signals()</B> to assign and revert signal +handlers, one of its arguments is a <B>sigset_t</B> which specifies +which signals to block and assign signal handlers to. This function +thus doesn't depend on <B>gl_get_line()</B> and can thus be used in +other situations where race-condition-free signal handling is +required. +<P> +<A NAME="lbAL"> </A> +<H2>SIGNALS CAUGHT BY GL_GET_LINE</H2> + +<P> +Since the application is expected to handle signals in non-blocking +server mode, <B>gl_get_line()</B> 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 <B>gl_get_line()</B> is being +called, <B>gl_get_line()</B> 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 signal, <B>gl_get_line()</B> returns <B>NULL</B>, and +a following call to <B>gl_return_status()</B> returns the enumerated +value <B>GLR_SIGNAL</B>. +<P> +<A NAME="lbAM"> </A> +<H2>ABORTING LINE INPUT</H2> + +<P> +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 <B>gl_handle_signal()</B> when this signal is caught, but +instead to call the <B>gl_abandon_line()</B>. +<P> +<P> +<PRE> + void gl_abandon_line(GetLine *gl); +</PRE> + +<P> +<P> +This function arranges that when <B>gl_get_line()</B> 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. +<P> +<A NAME="lbAN"> </A> +<H2>SIGNAL SAFE FUNCTIONS</H2> + +<P> +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. +<P> +<P> +<PRE> + gl_normal_io() + gl_raw_io() + gl_handle_signal() + gl_abandon_line() +</PRE> + +<P> +<P> +In order for this to be true, all signal handlers that call these +functions 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 <B>sigaction()</B> function to register all signal +handlers, and when doing this, use the <B>sa_mask</B> 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 <B>GetLine</B> object at the same time. +<P> +To prevent signal handlers from accessing a <B>GetLine</B> object while +<B>gl_get_line()</B> or any of its associated public functions are +operating on it, all public functions associated with +<B>gl_get_line()</B>, including <B>gl_get_line()</B> itself, temporarily +block the delivery of signals when they are accessing <B>GetLine</B> +objects. Beware that the only signals that they block are the signals +that <B>gl_get_line()</B> 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 <B>gl_get_line()</B> (see <B>gl_trap_signal()</B>). +<P> +<A NAME="lbAO"> </A> +<H2>USING TIMEOUTS TO POLL</H2> + +<P> +If instead of using <B>select()</B> or <B>poll()</B> to wait for I/O, +your application just needs to get out of <B>gl_get_line()</B> +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 <B>gl_inactivity_timeout()</B> function (see +<B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>), to specify that a callback function that +returns <B>GLTO_CONTINUE</B> should be called whenever +<B>gl_get_line()</B> has been waiting for I/O for more than a specified +amount of time. +<P> +When this callback is triggered, <B>gl_get_line()</B> will return +<B>NULL</B>, and a following call to <B>gl_return_status()</B> will +return <B>GLR_BLOCKED</B>. +<P> +Beware that <B>gl_get_line()</B> 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, +<B>gl_get_line()</B> may not return for a while. In other +words there is no guarantee that it will return in the time +specified. +<P> +<A NAME="lbAP"> </A> +<H2>THE SERVER DEMO PROGRAM</H2> + +<P> +The <B>demo3</B> 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 <B>demo</B>), except that +whereas the main demo program uses the normal blocking I/O mode, +<B>demo3</B> using non-blocking I/O and an external event loop. The +source code can be found in <B>demo3.c</B>, and the comments therein +explain the various steps. +<P> +<A NAME="lbAQ"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library +libtecla.h - The tecla header file. +</PRE> + +<P> +<A NAME="lbAR"> </A> +<H2>SEE ALSO</H2> + +<P> +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="tecla.html">tecla</A>(7), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="cpl_complete_word.html">cpl_complete_word</A>(3), <A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) +</PRE> + +<P> +<A NAME="lbAS"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">SERVER I/O MODE</A><DD> +<DT><A HREF="#lbAF">GIVING UP THE TERMINAL</A><DD> +<DT><A HREF="#lbAG">SIGNAL HANDLING</A><DD> +<DL> +<DT><A HREF="#lbAH">Terminal resize signals (SIGWINCH)</A><DD> +</DL> +<DT><A HREF="#lbAI">Process termination signals.</A><DD> +<DT><A HREF="#lbAJ">Process suspension signals.</A><DD> +<DT><A HREF="#lbAK">INTERRUPTING THE EVENT LOOP</A><DD> +<DT><A HREF="#lbAL">SIGNALS CAUGHT BY GL_GET_LINE</A><DD> +<DT><A HREF="#lbAM">ABORTING LINE INPUT</A><DD> +<DT><A HREF="#lbAN">SIGNAL SAFE FUNCTIONS</A><DD> +<DT><A HREF="#lbAO">USING TIMEOUTS TO POLL</A><DD> +<DT><A HREF="#lbAP">THE SERVER DEMO PROGRAM</A><DD> +<DT><A HREF="#lbAQ">FILES</A><DD> +<DT><A HREF="#lbAR">SEE ALSO</A><DD> +<DT><A HREF="#lbAS">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/index.html b/libtecla-1.6.3/html/index.html new file mode 100644 index 0000000..fb34147 --- /dev/null +++ b/libtecla-1.6.3/html/index.html @@ -0,0 +1,73 @@ +<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.3. This may be obtained from: +<P> + <a href="libtecla-1.6.3.tar.gz">http://www.astro.caltech.edu/~mcs/tecla/libtecla-1.6.3.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> + +<HR> +Martin Shepherd (09-Nov-2014) +</BODY> diff --git a/libtecla-1.6.3/html/libtecla.html b/libtecla-1.6.3/html/libtecla.html new file mode 100644 index 0000000..b155918 --- /dev/null +++ b/libtecla-1.6.3/html/libtecla.html @@ -0,0 +1,199 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of libtecla</TITLE> +</HEAD><BODY> +<H1>libtecla</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +libtecla - An interactive command-line input library. +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +gcc ... -ltecla -lcurses +</PRE> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>tecla</B> library provides programs with interactive command +line editing facilities, similar to those of the unix <B>tcsh</B> +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. +<P> +The various parts of the library are documented in the following man +pages: +<P> +<PRE> + <A HREF="tecla.html">tecla</A>(7) - Use level documentation of the + command-line editing facilities + provided by <B>gl_get_line()</B>. + <A HREF="gl_get_line.html">gl_get_line</A>(3) - The interactive line-input module. + <A HREF="gl_io_mode.html">gl_io_mode</A>(3) - How to use <B>gl_get_line()</B> in an + incremental, non-blocking fashion. + <A HREF="cpl_complete_word.html">cpl_complete_word</A>(3) - The word completion module. + <A HREF="ef_expand_file.html">ef_expand_file</A>(3) - The filename expansion module. + <A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) - A directory-list based filename + lookup and completion module. +</PRE> + +<P> +In addition there is one optional application distributed +with the library: +<P> +<PRE> + <A HREF="enhance.html">enhance</A>(1) - Add command-line editing to third + party applications. +</PRE> + +<P> +<A NAME="lbAE"> </A> +<H2>THREAD SAFETY</H2> + +<P> +If the library is compiled with -D_POSIX_C_SOURCE=199506L, reentrant +versions of as many functions as possible are used. This includes +using getpwuid_r() and getpwnam_r() instead of getpwuid() and +getpwnam() when looking up the home directories of specific users in +the password file (for ~user/ expansion), and readdir_r() instead of +readdir() for reading directory entries when doing filename +completion. The reentrant version of the library is usually called +libtecla_r.a instead of libtecla.a, so if only the latter is +available, it probably isn't the correct version to link with +threaded programs. +<P> +Reentrant functions for iterating through the password file aren't +available, so when the library is compiled to be reentrant, TAB +completion of incomplete usernames in <B>~username/</B> expressions is +disabled. This doesn't disable expansion of complete <B>~username</B> +expressions, which can be done reentrantly, or expansion of the parts +of filenames that follow them, so this doesn't remove much +functionality. +<P> +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. +<P> +<A NAME="lbAF"> </A> +<H2>LIBRARY VERSION NUMBER</H2> + +<P> +The version number of the library can be queried using the following +function. +<P> +<PRE> + void libtecla_version(int *major, int *minor, int *micro); +</PRE> + +<P> +<P> +On return, this function records the three components of the libtecla +version number in <B>*major</B>, <B>*minor</B>, <B>*micro</B>. The formal +meaning of the three components is as follows. +<P> +<P> +<PRE> + 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> + +<P> +<P> +<A NAME="lbAG"> </A> +<H2>TRIVIA</H2> + +<P> +In Spanish, a "tecla" is the key of a keyboard. Since this library +centers on keyboard input, and given that I wrote much of the library +while working in Chile, this seemed like a suitable name. +<P> +<A NAME="lbAH"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library. +libtecla.h - The tecla header file. +~/.teclarc - The tecla personal customization file. +</PRE> + +<P> +<A NAME="lbAI"> </A> +<H2>SEE ALSO</H2> + +<P> +<PRE> +<A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="tecla.html">tecla</A>(7), <A HREF="gl_io_mode.html">gl_io_mode</A>(3), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="cpl_complete_word.html">cpl_complete_word</A>(3), <A HREF="pca_lookup_file.html">pca_lookup_file</A>(3), <A HREF="enhance.html">enhance</A>(1) +</PRE> + +<P> +<A NAME="lbAJ"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> +<A NAME="lbAK"> </A> +<H2>ACKNOWLEDGMENTS</H2> + +<P> +<PRE> +Markus Gyger - Lots of assistance, including help with + shared libraries, configuration information, + particularly for Solaris; modifications to + support C++ compilers, improvements for ksh + users, faster cursor motion, output + buffering, and changes to make gl_get_line() + 8-bit clean. +Mike MacFaden - Suggestions, feedback and testing that led + to many of the major new functions that were + added in version 1.4.0. +Tim Eliseo - Many vi-mode bindings and fixes. +</PRE> + +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">THREAD SAFETY</A><DD> +<DT><A HREF="#lbAF">LIBRARY VERSION NUMBER</A><DD> +<DT><A HREF="#lbAG">TRIVIA</A><DD> +<DT><A HREF="#lbAH">FILES</A><DD> +<DT><A HREF="#lbAI">SEE ALSO</A><DD> +<DT><A HREF="#lbAJ">AUTHOR</A><DD> +<DT><A HREF="#lbAK">ACKNOWLEDGMENTS</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/pca_lookup_file.html b/libtecla-1.6.3/html/pca_lookup_file.html new file mode 100644 index 0000000..44b0cb2 --- /dev/null +++ b/libtecla-1.6.3/html/pca_lookup_file.html @@ -0,0 +1,420 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of pca_lookup_file</TITLE> +</HEAD><BODY> +<H1>pca_lookup_file</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +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 +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + +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> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>PathCache</B> object is part of the tecla library (see the +<A HREF="libtecla.html">libtecla</A>(3) man page). +<P> +<B>PathCache</B> objects allow an application to search for files in +any colon separated list of directories, such as the unix execution +PATH environment variable. Files in absolute directories are cached in +a <B>PathCache</B> object, whereas relative directories are scanned as +needed. Using a <B>PathCache</B> object, you can look up the full +pathname of a simple filename, or you can obtain a list of the +possible completions of a given filename prefix. By default all files +in the list of directories are targets for lookup and completion, but +a versatile mechanism is provided for only selecting specific types of +files. The obvious application of this facility is to provide +Tab-completion and lookup of executable commands in the unix PATH, so +an optional callback which rejects all but executable files, is +provided. +<P> +<A NAME="lbAE"> </A> +<H2>AN EXAMPLE</H2> + +<P> +Under UNIX, the following example program looks up and displays the +full pathnames of each of the command names on the command line. +<P> +<PRE> + #include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> + #include <<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>> + #include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + + int main(int argc, char *argv[]) + { + int i; + /* + * Create a cache for executable files. + */ + PathCache *pc = new_PathCache(); + if(!pc) + <A HREF="exit.html">exit</A>(1); + /* + * Scan the user's PATH for executables. + */ + if(pca_scan_path(pc, getenv("PATH"))) { + fprintf(stderr, "%s\n", pca_last_error(pc)); + <A HREF="exit.html">exit</A>(1); + } + /* + * Arrange to only report executable files. + */ + pca_set_check_fn(pc, cpl_check_exe, NULL); + /* + * Lookup and display the full pathname of each of the + * commands listed on the command line. + */ + for(i=1; i<argc; i++) { + char *cmd = pca_lookup_file(pc, argv[i], -1, 0); + printf("The full pathname of '%s' is %s\n", argv[i], + cmd ? cmd : "unknown"); + } + pc = del_PathCache(pc); /* Clean up */ + return 0; + } +</PRE> + +<P> +The following is an example of what this does on my laptop under +linux: +<P> +<PRE> + $ ./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> + +<P> +<A NAME="lbAF"> </A> +<H2>FUNCTION DESCRIPTIONS</H2> + +<P> +In order to use the facilities of this module, you must first allocate +a <B>PathCache</B> object by calling the <B>new_PathCache()</B> +constructor function. +<P> +<PRE> + PathCache *new_PathCache(void) +</PRE> + +<P> +This function creates the resources needed to cache and lookup files +in a list of directories. It returns <B>NULL</B> on error. +<P> +<A NAME="lbAG"> </A> +<H2>POPULATING THE CACHE</H2> + +Once you have created a cache, it needs to be populated with files. +To do this, call the <B>pca_scan_path()</B> function. +<P> +<PRE> + int pca_scan_path(PathCache *pc, const char *path); +</PRE> + +<P> +Whenever this function is called, it discards the current contents of +the cache, then scans the list of directories specified in its +<B>path</B> argument for files. The <B>path</B> argument must be a +string containing a colon-separated list of directories, such as +<B>"/usr/bin:/home/mcs/bin:."</B>. This can include directories +specified by absolute pathnames such as <B>"/usr/bin"</B>, as well as +sub-directories specified by relative pathnames such as <B>"."</B> or +<B>"bin"</B>. Files in the absolute directories are immediately cached +in the specified <B>PathCache</B> 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. +<P> +On success this function return <B>0</B>. On error it returns <B>1</B>, +and a description of the error can be obtained by calling +<B>pca_last_error(pc)</B>. +<P> +<A NAME="lbAH"> </A> +<H2>LOOKING UP FILES</H2> + +<P> +Once the cache has been populated with files, you can look up the full +pathname of a file, simply by specifying its filename to +<B>pca_lookup_file()</B>. +<P> +<PRE> + char *pca_lookup_file(PathCache *pc, const char *name, + int name_len, int literal); +</PRE> + +<P> +To make it possible to pass this function a filename which is actually +part of a longer string, the <B>name_len</B> argument can be used to +specify the length of the filename at the start of the <B>name[]</B> +argument. If you pass <B>-1</B> for this length, the length of the +string will be determined with <B>strlen()</B>. If the <B>name[]</B> +string might contain backslashes that escape the special meanings of +spaces and tabs within the filename, give the <B>literal</B> argument, +the value <B>0</B>. Otherwise, if backslashes should be treated as +normal characters, pass <B>1</B> for the value of the <B>literal</B> +argument. +<P> +<A NAME="lbAI"> </A> +<H2>FILENAME COMPLETION</H2> + +<P> +Looking up the potential completions of a filename-prefix in the +filename cache, is achieved by passing the provided +<B>pca_path_completions()</B> callback function to the +<B>cpl_complete_word()</B> function (see the <B><A HREF="cpl_complete_word.html">cpl_complete_word</A>(3)</B> +man page). +<P> +<PRE> + CPL_MATCH_FN(pca_path_completions); +</PRE> + +<P> +This callback requires that its <B>data</B> argument be a pointer to a +<B>PcaPathConf</B> object. Configuration objects of this type are +allocated by calling <B>new_PcaPathConf()</B>. +<P> +<PRE> + PcaPathConf *new_PcaPathConf(PathCache *pc); +</PRE> + +<P> +This function returns an object initialized with default configuration +parameters, which determine how the <B>cpl_path_completions()</B> +callback function behaves. The functions which allow you to +individually change these parameters are discussed below. +<P> +By default, the <B>pca_path_completions()</B> callback function +searches backwards for the start of the filename being completed, +looking for the first un-escaped space or the start of the input +line. If you wish to specify a different location, call +<B>ppc_file_start()</B> with the index at which the filename starts in +the input line. Passing <B>start_index=-1</B> re-enables the default +behavior. +<P> +<PRE> + void ppc_file_start(PcaPathConf *ppc, int start_index); +</PRE> + +<P> +By default, when <B>pca_path_completions()</B> 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 <B>ppc_literal_escapes()</B> with a +non-zero value in its <B>literal</B> argument. +<P> +<PRE> + void ppc_literal_escapes(PcaPathConf *ppc, int literal); +</PRE> + +<P> +When you have finished with a <B>PcaPathConf</B> variable, you can pass +it to the <B>del_PcaPathConf()</B> destructor function to reclaim its +memory. +<P> +<PRE> + PcaPathConf *del_PcaPathConf(PcaPathConf *ppc); +</PRE> + +<P> +<P> +<A NAME="lbAJ"> </A> +<H2>BEING SELECTIVE</H2> + +If you are only interested in certain types or files, such as, for +example, executable files, or files whose names end in a particular +suffix, you can arrange for the file completion and lookup functions +to be selective in the filenames that they return. This is done by +registering a callback function with your <B>PathCache</B> +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 <B>1</B> the filename will be +reported as a match, and if it returns <B>0</B>, it will be ignored. +Suitable callback functions and their prototypes should be declared +with the following macro. The <B>CplCheckFn</B> <B>typedef</B> is also +provided in case you wish to declare pointers to such functions. +<P> +<PRE> + #define CPL_CHECK_FN(fn) int (fn)(void *data, \ + const char *pathname) + typedef CPL_CHECK_FN(CplCheckFn); +</PRE> + +<P> +Registering one of these functions involves calling the +<B>pca_set_check_fn()</B> function. In addition to the callback +function, passed via the <B>check_fn</B> argument, you can pass a +pointer to anything via the <B>data</B> argument. This pointer will be +passed on to your callback function, via its own <B>data</B> argument, +whenever it is called, so this provides a way to pass appplication +specific data to your callback. +<P> +<PRE> + void pca_set_check_fn(PathCache *pc, CplCheckFn *check_fn, + void *data); +</PRE> + +<P> +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 <B>cpl_check_exe()</B> callback function looks at +the executable permissions of the file and the permissions of its +parent directories, and only returns <B>1</B> 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 <B>PATH</B> environment variable. The example program given +earlier in this man page provides a demonstration of this. +<P> +Beware that if somebody tries to complete an empty string, your +callback will get called once for every file in the cache, which could +number in the thousands. If your callback does anything time +consuming, this could result in an unacceptable delay for the user, so +callbacks should be kept short. +<P> +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 <B>pca_scan_path()</B> is called, and whenever +<B>pca_set_check_fn()</B> is called with changed callback function or +data arguments. +<P> +<A NAME="lbAK"> </A> +<H2>ERROR HANDLING</H2> + +<P> +If <B>pca_scan_path()</B> reports that an error occurred by returning +<B>1</B>, you can obtain a terse description of the error by calling +<B>pca_last_error(pc)</B>. This returns an internal string containing +an error message. +<P> +<PRE> + const char *pca_last_error(PathCache *pc); +</PRE> + +<P> +<P> +<A NAME="lbAL"> </A> +<H2>CLEANING UP</H2> + +<P> +Once you have finished using a <B>PathCache</B> object, you can reclaim +its resources by passing it to the <B>del_PathCache()</B> destructor +function. This takes a pointer to one of these objects, and always +returns <B>NULL</B>. +<P> +<PRE> + PathCache *del_PathCache(PathCache *pc); +</PRE> + +<P> +<A NAME="lbAM"> </A> +<H2>THREAD SAFETY</H2> + +<P> +In multi-threaded programs, you should use the <B>libtecla_r.a</B> +version of the library. This uses POSIX reentrant functions where +available (hence the <B>_r</B> 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 <B>~username/</B> +expressions, in <B>cpl_path_completions()</B>. +<P> +Using the <B>libtecla_r.a</B> 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 <B>PathCache</B> object. In other +words, if two threads want to do path searching, they should each call +<B>new_PathCache()</B> to allocate their own caches. +<P> +<A NAME="lbAN"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library +libtecla.h - The tecla header file. +</PRE> + +<P> +<A NAME="lbAO"> </A> +<H2>SEE ALSO</H2> + +<P> +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="cpl_complete_word.html">cpl_complete_word</A>(3) +</PRE> + +<P> +<A NAME="lbAP"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">AN EXAMPLE</A><DD> +<DT><A HREF="#lbAF">FUNCTION DESCRIPTIONS</A><DD> +<DT><A HREF="#lbAG">POPULATING THE CACHE</A><DD> +<DT><A HREF="#lbAH">LOOKING UP FILES</A><DD> +<DT><A HREF="#lbAI">FILENAME COMPLETION</A><DD> +<DT><A HREF="#lbAJ">BEING SELECTIVE</A><DD> +<DT><A HREF="#lbAK">ERROR HANDLING</A><DD> +<DT><A HREF="#lbAL">CLEANING UP</A><DD> +<DT><A HREF="#lbAM">THREAD SAFETY</A><DD> +<DT><A HREF="#lbAN">FILES</A><DD> +<DT><A HREF="#lbAO">SEE ALSO</A><DD> +<DT><A HREF="#lbAP">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> diff --git a/libtecla-1.6.3/html/release.html b/libtecla-1.6.3/html/release.html new file mode 100644 index 0000000..22729cf --- /dev/null +++ b/libtecla-1.6.3/html/release.html @@ -0,0 +1,604 @@ +<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.3: + + This release corrects some problems in the build process, + including one that was preventing libtecla from being compiled + on Mac OS X. + +Version 1.6.2: + + This release updates the configuration script to ensure that the + enhance utility program is compiled correctly on systems that have + system V psuedo-terminal allocation but not system V streams. + + There are no new features. + +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.3/html/tecla.html b/libtecla-1.6.3/html/tecla.html new file mode 100644 index 0000000..3031a48 --- /dev/null +++ b/libtecla-1.6.3/html/tecla.html @@ -0,0 +1,1276 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of tecla</TITLE> +</HEAD><BODY> +<H1>tecla</H1> +Section: Environments, Tables, and Troff Macros (7)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +tecla, teclarc - The user interface provided by the Tecla library. +<A NAME="lbAC"> </A> +<H2>DESCRIPTION</H2> + +<P> +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 +familiar, but with a few minor differences, most notably in how +forward and backward searches through the list of historical commands +are performed. 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 completion is provided. If the application hasn't +reconfigured this to complete other types of symbols, then tab +completion completes file-names. +<P> +<A NAME="lbAD"> </A> +<H2>KEY SEQUENCE NOTATION</H2> + +<P> +In the rest of this man page, and also in all Tecla configuration +files, key-sequences are expressed as follows. +<P> +<P> +<PRE> +<B>^A</B> or <B>C-a</B> + This is a control-A, entered by pressing the control key at + the same time as the <B>A</B> key. + +<B>\E</B> or <B>M-</B> + 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 <B>M-p</B> can be typed in two ways, by pressing + the escape key, followed by pressing <B>p</B>, or by pressing the + Meta key at the same time as <B>p</B>. + +<B>up</B> + This refers to the up-arrow key. + +<B>down</B> + This refers to the down-arrow key. + +<B>left</B> + This refers to the left-arrow key. + +<B>right</B> + This refers to the right-arrow key. + +<B>a</B> + This is just a normal A key. +</PRE> + +<P> +<P> +<A NAME="lbAE"> </A> +<H2>THE TECLA CONFIGURATION FILE</H2> + +<P> +By default, Tecla looks for a file called <B>.teclarc</B> in your +home directory (ie. <B>~/.teclarc</B>). If it finds this file, it +reads it, interpreting each line as defining a new key binding or an +editing configuration option. Since the emacs keybindings are +installed by default, if you want to use the non-default vi editing +mode, the most important item to go in this file is the following +line: +<P> +<PRE> + edit-mode vi +</PRE> + +<P> +This will re-configure the default bindings for vi-mode. The +complete set of arguments that this command accepts are: +<P> +<PRE> + 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. +</PRE> + +<P> +To prevent the terminal bell from being rung, such as when +an unrecognized control-sequence is typed, place the +following line in the configuration file: +<P> +<PRE> + nobeep +</PRE> + +<P> +An example of a key binding line in the configuration file is +the following. +<P> +<PRE> + bind M-[2~ insert-mode +</PRE> + +<P> +On many keyboards, the above key sequence is generated when one +presses the <B>insert</B> 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 <B>M-</B> part of this +sequence can be typed either by pressing the escape key before the +following key, or by pressing the Meta key at the same time as the +following key. Thus if you had set the above key binding, and the +insert key on your keyboard didn't generate the above key sequence, +you could still type it in either of the following 2 ways. +<P> +<PRE> + 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 '~'. +</PRE> + +<P> +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. +<P> +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. +<P> +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: +<P> +<PRE> + bind up history-search-backwards + bind down history-search-backwards +</PRE> + +<P> +To unbind an existing binding, you can do this with the bind command +by omitting to name any action to rebind the key sequence to. For +example, by not specifying an action function, the following command +unbinds the default beginning-of-line action from the ^A key sequence: +<P> +<PRE> + bind ^A +</PRE> + +<P> +If you create a <B>~/.teclarc</B> 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. +<P> +<A NAME="lbAF"> </A> +<H2>FILENAME AND TILDE COMPLETION</H2> + +<P> +With the default key bindings, pressing the TAB key (aka. <B>^I</B>) +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. +<P> +In addition to literally written filenames, Tecla can +complete files that start with <B>~/</B> and <B>~user/</B> expressions +and that contain <B>$envvar</B> expressions. In particular, if you hit +TAB within an incomplete <B>~user</B>, expression, Tecla +will attempt to complete the username, listing any ambiguous matches. +<P> +The completion binding is implemented using the +<B>cpl_word_completions()</B> function, which is also available +separately to users of this library. See the +<B><A HREF="cpl_complete_word.html">cpl_complete_word</A>(3)</B> man page for more details. +<P> +<A NAME="lbAG"> </A> +<H2>FILENAME EXPANSION</H2> + +<P> +With the default key bindings, pressing <B>^X*</B> causes Tecla to +expand the filename that precedes the cursor, replacing <B>~/</B> and +<B>~user/</B> expressions with the corresponding home directories, and +replacing <B>$envvar</B> expressions with the value of the specified +environment variable, then if there are any wildcards, replacing the +so far expanded filename with a space-separated list of the files +which match the wild cards. +<P> +The expansion binding is implemented using the <B>ef_expand_file()</B> function. +See the <B><A HREF="ef_expand_file.html">ef_expand_file</A>(3)</B> man page for more details. +<P> +<A NAME="lbAH"> </A> +<H2>RECALLING PREVIOUSLY TYPED LINES</H2> + +<P> +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 <B>^P</B>, and +<B>^N</B> 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. +<P> +Note that in vi mode, all of the history recall functions switch the +library into command mode. +<P> +In emacs mode the <B>M-p</B> and <B>M-n</B> keys work just like the +<B>^P</B> and <B>^N</B> 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 <B>K</B> and <B>J</B> characters do the +same thing, except that the string that they search for includes the +character under the cursor as well as what precedes it. +<P> +Thus for example, suppose that you were in emacs mode, and you had +just entered the following list of commands in the order shown: +<P> +<PRE> + ls ~/tecla/ + cd ~/tecla + ls -l getline.c + emacs ~/tecla/getline.c +</PRE> + +<P> +If you next typed: +<P> +<PRE> + ls +</PRE> + +<P> +and then hit <B>M-p</B>, then rather than returning the previously +typed emacs line, which doesn't start with "ls", Tecla +would recall the "ls -l getline.c" line. Pressing <B>M-p</B> again +would recall the "ls ~/tecla/" line. +<P> +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: +<P> +<PRE> + *tecla* +</PRE> + +<P> +and hit <B>M-p</B>, then the "emacs ~/tecla/getline.c" line would be +recalled first, since it contains the word tecla somewhere in the +line, Similarly, hitting <B>M-p</B> again, would recall the "ls +~/tecla/" line, and hitting it once more would recall the "ls +~/tecla/" line. The pattern syntax is the same as that described for +filename expansion, in the <B>ef_expand_file(3</B> man +page. +<P> +<A NAME="lbAI"> </A> +<H2>HISTORY FILES</H2> + +<P> +Authors of programs that use the Tecla library have the option of +saving 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 different applications don't get mixed up. +<P> +<A NAME="lbAJ"> </A> +<H2>INTERNATIONAL CHARACTER SETS</H2> + +<P> +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, +<P> +<PRE> + setlocale(LC_CTYPE, ""); +</PRE> + +<P> +then the current locale is determined by the first of the environment +variables <B>LC_CTYPE</B>, <B>LC_ALL</B>, and <B>LANG</B>, 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 +<B>C</B> 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: +<P> +<PRE> + locale -a +</PRE> + +<P> +at the shell prompt. +<P> +<A NAME="lbAK"> </A> +<H3>Meta keys and locales</H3> + +<P> +Beware that in most locales other than the default C locale, meta +characters become printable, and they are then no longer considered to +match <B>M-c</B> style key bindings. This allows international +characters to be entered with the compose key without unexpectedly +triggering meta key bindings. You can still invoke meta bindings, +since there are actually two ways to do this. For example the binding +<B>M-c</B> can also be invoked by pressing the escape key momentarily, +then pressing the <B>c</B> key, and this will work regardless of +locale. Moreover, many modern terminal emulators, such as gnome's +gnome-terminal's and KDE's konsole terminals, already generate escape +pairs like this when you use the meta key, rather than a real meta +character, and other emulators usually have a way to request this +behavior, so you can continue to use the meta key on most systems. +<P> +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 +<B>EightBitInput</B> X resource to <B>False</B>. You can either do this +by placing a line like the following in your <B>~/.Xdefaults</B> file, +<P> +<PRE> + XTerm*EightBitInput: False + +</PRE> + +or by starting an xterm with an <B>-xrm '*EightBitInput: False'</B> +command-line argument. In recent versions of xterm you can toggle this +feature on and off with the <B>"Meta Sends Escape"</B> option in the +menu that is displayed when you press the left mouse button and the +control key within an xterm window. In CDE, dtterms can be similarly +coerced to generate escape pairs in place of meta characters, by +setting the <B>Dtterm*KshMode</B> resource to <B>True</B>. +<P> +<A NAME="lbAL"> </A> +<H3>Entering international characters</H3> + +<P> +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 <B>xev</B> program reports that +pressing this key generates keycode 115, so to turn this key +into a compose key, I do the following: +<P> +<PRE> + xmodmap -e 'keycode 115 = Multi_key' +</PRE> + +<P> +I can then enter an i with a umlaut over it by typing this key, +followed by <B>"</B>, followed by i. +<P> +<A NAME="lbAM"> </A> +<H2>THE AVAILABLE KEY BINDING FUNCTIONS</H2> + +<P> +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 +combination of keys should invoke. They are also used in the next two +sections to list the default key-bindings in emacs and vi modes. +<P> +<PRE> + user-interrupt - Send a SIGINT signal to the + parent process. + abort - Send a SIGABRT signal to the + parent process. + suspend - Suspend the parent process. + stop-output - Pause terminal output. + start-output - Resume paused terminal output. + literal-next - Arrange for the next character + to be treated as a normal + character. This allows control + characters to be entered. + cursor-right - Move the cursor one character + right. + cursor-left - Move the cursor one character + left. + insert-mode - Toggle between insert mode and + overwrite mode. + beginning-of-line - Move the cursor to the + beginning of the line. + end-of-line - Move the cursor to the end of + the line. + delete-line - Delete the contents of the + current line. + kill-line - Delete everything that follows + the cursor. + backward-kill-line - Delete all characters between + the cursor and the start of the + line. + forward-word - Move to the end of the word + which follows the cursor. + forward-to-word - Move the cursor to the start of + the word that follows the + cursor. + backward-word - Move to the start of the word + which precedes the cursor. + goto-column - Move the cursor to the + 1-relative column in the line + specified by any preceding + digit-argument sequences (see + ENTERING REPEAT COUNTS below). + find-parenthesis - If the cursor is currently + over a parenthesis character, + move it to the matching + parenthesis character. If not + over a parenthesis character + move right to the next close + parenthesis. + forward-delete-char - Delete the character under the + cursor. + backward-delete-char - Delete the character which + precedes the cursor. + list-or-eof - This is intended for binding + to ^D. When invoked when the + cursor is within the line it + displays all possible + completions then redisplays + the line unchanged. When + invoked on an empty line, it + signals end-of-input (EOF) to + the caller of gl_get_line(). + del-char-or-list-or-eof - This is intended for binding + to ^D. When invoked when the + cursor is within the line it + invokes forward-delete-char. + When invoked at the end of the + line it displays all possible + completions then redisplays + the line unchanged. When + invoked on an empty line, it + signals end-of-input (EOF) to + the caller of gl_get_line(). + forward-delete-word - Delete the word which follows + the cursor. + backward-delete-word - Delete the word which precedes + the cursor. + upcase-word - Convert all of the characters + of the word which follows the + cursor, to upper case. + downcase-word - Convert all of the characters + of the word which follows the + cursor, to lower case. + capitalize-word - Capitalize the word which + follows the cursor. + change-case - If the next character is upper + case, toggle it to lower case + and vice versa. + redisplay - Redisplay the line. + clear-screen - Clear the terminal, then + redisplay the current line. + transpose-chars - Swap the character under the + cursor with the character just + before the cursor. + set-mark - Set a mark at the position of + the cursor. + exchange-point-and-mark - Move the cursor to the last + mark that was set, and move + the mark to where the cursor + used to be. + kill-region - Delete the characters that lie + between the last mark that was + set, and the cursor. + copy-region-as-kill - Copy the text between the mark + and the cursor to the cut + buffer, without deleting the + original text. + yank - Insert the text that was last + deleted, just before the + current position of the cursor. + append-yank - Paste the current contents of + the cut buffer, after the + cursor. + up-history - Recall the next oldest line + that was entered. Note that + in vi mode you are left in + command mode. + down-history - Recall the next most recent + line that was entered. If no + history recall session is + currently active, the next + line from a previous recall + session is recalled. Note that + in vi mode you are left in + command mode. + history-search-backward - Recall the next oldest line + who's prefix matches the string + which currently precedes the + cursor (in vi command-mode the + character under the cursor is + also included in the search + string). Note that in vi mode + you are left in command mode. + history-search-forward - Recall the next newest line + who's prefix matches the string + which currently precedes the + cursor (in vi command-mode the + character under the cursor is + also included in the search + string). Note that in vi mode + you are left in command mode. + history-re-search-backward -Recall the next oldest line + who's prefix matches that + established by the last + invocation of either + history-search-forward or + history-search-backward. + history-re-search-forward - Recall the next newest line + who's prefix matches that + established by the last + invocation of either + history-search-forward or + history-search-backward. + complete-word - Attempt to complete the + incomplete word which + precedes the cursor. Unless + the host program has customized + word completion, filename + completion is attempted. In vi + commmand mode the character + under the cursor is also + included in the word being + completed, and you are left in + vi insert mode. + expand-filename - Within the command line, expand + wild cards, tilde expressions + and dollar expressions in the + filename which immediately + precedes the cursor. In vi + commmand mode the character + under the cursor is also + included in the filename being + expanded, and you are left in + vi insert mode. + list-glob - List any filenames which match + the wild-card, tilde and dollar + expressions in the filename + which immediately precedes the + cursor, then redraw the input + line unchanged. + list-history - Display the contents of the + history list for the current + history group. If a repeat + count of > 1 is specified, + only that many of the most + recent lines are displayed. + See the "ENTERING REPEAT + COUNTS" section. + read-from-file - Temporarily switch to reading + input from the file who's + name precedes the cursor. + read-init-files - Re-read teclarc configuration + files. + beginning-of-history - Move to the oldest line in the + history list. Note that in vi + mode you are left in command + mode. + end-of-history - Move to the newest line in the + history list (ie. the current + line). Note that in vi mode + this leaves you in command + mode. + digit-argument - Enter a repeat count for the + next key-binding function. + For details, see the ENTERING + REPEAT COUNTS section. + newline - Terminate and return the + current contents of the + line, after appending a + newline character. The newline + character is normally '\n', + but will be the first + character of the key-sequence + that invoked the newline + action, if this happens to be + a printable character. If the + action was invoked by the + '\n' newline character or the + '\r' carriage return + character, the line is + appended to the history + buffer. + repeat-history - Return the line that is being + edited, then arrange for the + next most recent entry in the + history buffer to be recalled + when 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 <B>nobeep</B> 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> + +<P> +<A NAME="lbAN"> </A> +<H2>DEFAULT KEY BINDINGS IN EMACS MODE</H2> + +<P> +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 <B>tcsh</B> shell, when it is in +emacs editing mode. +<P> +This is the default editing mode of the Tecla library. +<P> +Under UNIX the terminal driver sets a number of special keys for certain +functions. The tecla library attempts to use the same keybindings to maintain +consistency. The key sequences shown for the following 6 bindings are thus just +examples of what they will probably be set to. If you have used the <B>stty</B> +command to change these keys, then the default bindings should match. +<P> +<PRE> + ^C -> user-interrupt + ^\ -> abort + ^Z -> suspend + ^Q -> start-output + ^S -> stop-output + ^V -> literal-next +</PRE> + +<P> +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. +<P> +<BR> right -> cursor-right +<BR> left -> cursor-left +<BR> up -> up-history +<BR> down -> down-history +<P> +The remaining bindings don't depend on the terminal setttings. +<P> +<PRE> + ^F -> cursor-right + ^B -> cursor-left + M-i -> insert-mode + ^A -> beginning-of-line + ^E -> end-of-line + ^U -> delete-line + ^K -> kill-line + M-f -> forward-word + M-b -> backward-word + ^D -> del-char-or-list-or-eof + ^H -> backward-delete-char + ^? -> backward-delete-char + M-d -> forward-delete-word + M-^H -> backward-delete-word + M-^? -> backward-delete-word + M-u -> upcase-word + M-l -> downcase-word + M-c -> capitalize-word + ^R -> redisplay + ^L -> clear-screen + ^T -> transpose-chars + ^@ -> set-mark + ^X^X -> exchange-point-and-mark + ^W -> kill-region + M-w -> copy-region-as-kill + ^Y -> yank + ^P -> up-history + ^N -> down-history + M-p -> history-search-backward + M-n -> history-search-forward + ^I -> complete-word + ^X* -> expand-filename + ^X^F -> read-from-file + ^X^R -> read-init-files + ^Xg -> list-glob + ^Xh -> list-history + M-< -> beginning-of-history + M-> -> end-of-history + \n -> newline + \r -> newline + M-o -> repeat-history + M-^V -> vi-mode + + M-0, M-1, ... M-9 -> digit-argument (see below) +</PRE> + +<P> +Note that <B>^I</B> is what the TAB key generates, and that <B>^@</B> +can be generated not only by pressing the control key and the <B>@</B> +key simultaneously, but also by pressing the control key and the space +bar at the same time. +<P> +<A NAME="lbAO"> </A> +<H2>DEFAULT KEY BINDINGS IN VI MODE</H2> + +<P> +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. +<P> +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. +<P> +Under UNIX the terminal driver sets a number of special keys +for certain functions. The Tecla library attempts to use the +same keybindings to maintain consistency, binding them both +in input mode and in command mode. The key sequences shown +for the following 6 bindings are thus just examples of what +they will probably be set to. If you have used the <B>stty</B> +command to change these keys, then the default bindings +should match. +<P> +<PRE> + ^C -> user-interrupt + ^\ -> abort + ^Z -> suspend + ^Q -> start-output + ^S -> stop-output + ^V -> literal-next + M-^C -> user-interrupt + M-^\ -> abort + M-^Z -> suspend + M-^Q -> start-output + M-^S -> stop-output +</PRE> + +<P> +Note that above, most of the bindings are defined twice, once +as a raw control code like <B>^C</B> and then a second time as +a meta character like <B>M-^C</B>. The former is the binding +for vi input mode, whereas the latter is the binding for vi +command mode. Once in command mode all key-sequences that the +user types that they don't explicitly start with an escape or +a meta key, have their first key secretly converted to a meta +character before the key sequence is looked up in the key +binding table. Thus, once in command mode, when you type the +letter <B>i</B>, for example, the Tecla library actually looks +up the binding for <B>M-i</B>. +<P> +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. +<P> +<BR> right -> cursor-right +<BR> left -> cursor-left +<BR> up -> up-history +<BR> down -> down-history +<P> +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). +<P> +The following are the terminal-independent key bindings for vi input +mode. +<P> +<PRE> + ^D -> list-or-eof + ^G -> list-glob + ^H -> backward-delete-char + ^I -> complete-word + \r -> newline + \n -> newline + ^L -> clear-screen + ^N -> down-history + ^P -> up-history + ^R -> redisplay + ^U -> backward-kill-line + ^W -> backward-delete-word + ^X* -> expand-filename + ^X^F -> read-from-file + ^X^R -> read-init-files + ^? -> backward-delete-char +</PRE> + +<P> +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. +<P> +<PRE> + M-\ -> cursor-right (Meta-space) + M-$ -> end-of-line + M-* -> expand-filename + M-+ -> down-history + M-- -> up-history + M-< -> beginning-of-history + M-> -> end-of-history + M-^ -> beginning-of-line + M-; -> repeat-find-char + M-, -> invert-refind-char + M-| -> goto-column + M-~ -> change-case + M-. -> vi-repeat-change + M-% -> find-parenthesis + M-a -> vi-append + M-A -> vi-append-at-eol + M-b -> backward-word + M-B -> backward-word + M-C -> vi-change-rest-of-line + M-cb -> vi-backward-change-word + M-cB -> vi-backward-change-word + M-cc -> vi-change-line + M-ce -> vi-forward-change-word + M-cE -> vi-forward-change-word + M-cw -> vi-forward-change-word + M-cW -> vi-forward-change-word + M-cF -> vi-backward-change-find + M-cf -> vi-forward-change-find + M-cT -> vi-backward-change-to + M-ct -> vi-forward-change-to + M-c; -> vi-change-refind + M-c, -> vi-change-invert-refind + M-ch -> vi-backward-change-char + M-c^H -> vi-backward-change-char + M-c^? -> vi-backward-change-char + M-cl -> vi-forward-change-char + M-c\ -> vi-forward-change-char (Meta-c-space) + M-c^ -> vi-change-to-bol + M-c0 -> vi-change-to-bol + M-c$ -> vi-change-rest-of-line + M-c| -> vi-change-to-column + M-c% -> vi-change-to-parenthesis + M-dh -> backward-delete-char + M-d^H -> backward-delete-char + M-d^? -> backward-delete-char + M-dl -> forward-delete-char + M-d -> forward-delete-char (Meta-d-space) + M-dd -> delete-line + M-db -> backward-delete-word + M-dB -> backward-delete-word + M-de -> forward-delete-word + M-dE -> forward-delete-word + M-dw -> forward-delete-word + M-dW -> forward-delete-word + M-dF -> backward-delete-find + M-df -> forward-delete-find + M-dT -> backward-delete-to + M-dt -> forward-delete-to + M-d; -> delete-refind + M-d, -> delete-invert-refind + M-d^ -> backward-kill-line + M-d0 -> backward-kill-line + M-d$ -> kill-line + M-D -> kill-line + M-d| -> delete-to-column + M-d% -> delete-to-parenthesis + M-e -> forward-word + M-E -> forward-word + M-f -> forward-find-char + M-F -> backward-find-char + M-- -> up-history + M-h -> cursor-left + M-H -> beginning-of-history + M-i -> vi-insert + M-I -> vi-insert-at-bol + M-j -> down-history + M-J -> history-search-forward + M-k -> up-history + M-K -> history-search-backward + M-l -> cursor-right + M-L -> end-of-history + M-n -> history-re-search-forward + M-N -> history-re-search-backward + M-p -> append-yank + M-P -> yank + M-r -> vi-replace-char + M-R -> vi-overwrite + M-s -> vi-forward-change-char + M-S -> vi-change-line + M-t -> forward-to-char + M-T -> backward-to-char + M-u -> vi-undo + M-w -> forward-to-word + M-W -> forward-to-word + M-x -> forward-delete-char + M-X -> backward-delete-char + M-yh -> backward-copy-char + M-y^H -> backward-copy-char + M-y^? -> backward-copy-char + M-yl -> forward-copy-char + M-y\ -> forward-copy-char (Meta-y-space) + M-ye -> forward-copy-word + M-yE -> forward-copy-word + M-yw -> forward-copy-word + M-yW -> forward-copy-word + M-yb -> backward-copy-word + M-yB -> backward-copy-word + M-yf -> forward-copy-find + M-yF -> backward-copy-find + M-yt -> forward-copy-to + M-yT -> backward-copy-to + M-y; -> copy-refind + M-y, -> copy-invert-refind + M-y^ -> copy-to-bol + M-y0 -> copy-to-bol + M-y$ -> copy-rest-of-line + M-yy -> copy-line + M-Y -> copy-line + M-y| -> copy-to-column + M-y% -> copy-to-parenthesis + M-^E -> emacs-mode + M-^H -> cursor-left + M-^? -> cursor-left + M-^L -> clear-screen + M-^N -> down-history + M-^P -> up-history + M-^R -> redisplay + M-^D -> list-or-eof + M-^I -> complete-word + M-\r -> newline + M-\n -> newline + M-^X^R -> read-init-files + M-^Xh -> list-history + + M-0, M-1, ... M-9 -> digit-argument (see below) +</PRE> + +<P> +Note that <B>^I</B> is what the TAB key generates. +<P> +<A NAME="lbAP"> </A> +<H2>ENTERING REPEAT COUNTS</H2> + +<P> +Many of the key binding functions described previously, take an +optional count, typed in before the target keysequence. This is +interpreted as a repeat count by most bindings. A notable exception is +the goto-column binding, which interprets the count as a column +number. +<P> +By default you can specify this count argument by pressing the meta +key while typing in the numeric count. This relies on the +<B>digit-argument</B> action being bound to Meta-0, Meta-1 etc. Once +any one of these bindings has been activated, you can optionally take +your finger off the meta key to type in the rest of the number, since +every numeric digit thereafter is treated as part of the number, +unless it is preceded by the <B>literal-next</B> 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. +<P> +For example, in emacs mode, typing: +<P> +<PRE> + M-12a +</PRE> + +<P> +causes the letter 'a' to be added to the line 12 times, +whereas +<P> +<PRE> + M-4M-c +</PRE> + +<P> +Capitalizes the next 4 words. +<P> +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: +<P> +<PRE> + 4w2x +</PRE> + +<P> +moves the cursor four words to the right, then deletes two characters. +<P> +You can also bind <B>digit-argument</B> 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. +<P> +<A NAME="lbAQ"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The Tecla library +libtecla.h - The Tecla header file. +~/.teclarc - The personal Tecla customization file. +</PRE> + +<P> +<A NAME="lbAR"> </A> +<H2>SEE ALSO</H2> + +<P> +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="gl_io_mode.html">gl_io_mode</A>(3), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="cpl_complete_word.html">cpl_complete_word</A>(3), <A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) +</PRE> + +<BR> +<A NAME="lbAS"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">DESCRIPTION</A><DD> +<DT><A HREF="#lbAD">KEY SEQUENCE NOTATION</A><DD> +<DT><A HREF="#lbAE">THE TECLA CONFIGURATION FILE</A><DD> +<DT><A HREF="#lbAF">FILENAME AND TILDE COMPLETION</A><DD> +<DT><A HREF="#lbAG">FILENAME EXPANSION</A><DD> +<DT><A HREF="#lbAH">RECALLING PREVIOUSLY TYPED LINES</A><DD> +<DT><A HREF="#lbAI">HISTORY FILES</A><DD> +<DT><A HREF="#lbAJ">INTERNATIONAL CHARACTER SETS</A><DD> +<DL> +<DT><A HREF="#lbAK">Meta keys and locales</A><DD> +<DT><A HREF="#lbAL">Entering international characters</A><DD> +</DL> +<DT><A HREF="#lbAM">THE AVAILABLE KEY BINDING FUNCTIONS</A><DD> +<DT><A HREF="#lbAN">DEFAULT KEY BINDINGS IN EMACS MODE</A><DD> +<DT><A HREF="#lbAO">DEFAULT KEY BINDINGS IN VI MODE</A><DD> +<DT><A HREF="#lbAP">ENTERING REPEAT COUNTS</A><DD> +<DT><A HREF="#lbAQ">FILES</A><DD> +<DT><A HREF="#lbAR">SEE ALSO</A><DD> +<DT><A HREF="#lbAS">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> |