7. Readline Interface

The S-Lang library includes simple but capable readline functionality in its SLrline layer. The SLrline routines provide a simple mechanism for an application to get prompted input from a user with command line editing, completions, and history recall.

The use of the SLrline routines will be illustrated with a few simple examples. All of the examples given in this section may be found in the file demo/rline.c in the S-Lang source code distribution. For clarity, the code shown below omits most error checking.

7.1 Introduction

The first example simply reads input from the user until the user enters quit:

   SLrline_Type *rl;
   SLang_init_tty (-1, 0, 1);
   rl = SLrline_open (80, SL_RLINE_BLINK_MATCH);
   while (1)
     {
       char *line;
       unsigned int len;

       line = SLrline_read_line (rl, "prompt>", &len);
       if (line == NULL) break;
       if (0 == strcmp (line, "quit"))
         {
            SLfree (line);
            break;
         }
       (void) fprintf (stdout, "\nRead %d bytes: %s\n", strlen(line), line);
       SLfree (line);
     }
   SLrline_close (rl);
   SLang_reset_tty ();

The SLrline_open function was used to create an instance of an SLrline_Type object. The function takes two arguments: and edit window display width (80 above), and a set of flags. In this case, the SL_RLINE_BLINK_MATCH flags has been used to turn on parenthesis blinking. Once finished, the SLrline_Type object must be freed using the SLrline_close function.

The actual reading of the line occurs in the SLrline_read_line function, which takes an SLrline_Type instance and a string representing the prompt to be used. The line itself is returned as a malloced char * and must be freed using the SLfree function after used. The length (in bytes) of the line is returned via the parameter list.

If an end-of-file character (^D on Unix) was entered at the beginning of a line, the SLrline_read_line function will return NULL. However, it also return NULL if an error of some sort was encountered. The only way to tell the difference between these two conditions is to call SLang_get_error.

The above code fragment did not provide for any sort of SIGINT handling. Without such a provision, pressing ^C at the prompt could be enough to kill the application. This is especially undesirable if one wants to press ^C to abort the call to SLrline_read_line. The function example_2 in demo/rline.c shows code to handle this situation as well as distinguish between EOF and other errors.

7.2 Interpreter Interface

SLrline features such as command-line completion, vi-emulation, and so on are implemented through callbacks or hooks from the SLrline functions to the S-Lang interpreter. Hence, this functionality is only available to applications that make use of the interpreter.

TBD...