xref: /dports/devel/libtecla/libtecla/RELEASE.NOTES

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.