11. S-Lang 2 API NEWS and UPGRADE information

The S-Lang API underwent a number of changes for version 2. In particular, the following interfaces have been affected:

    SLsmg
    SLregexp
    SLsearch
    SLrline
    SLprep
    slang interpreter modules

• UTF-8 encoded strings are now supported at both the C library level and the interpreter.
• Error handling by the interpreter has been rewritten to support try/catch style exception. Applications may also define application-specific error codes.
• The library may be compiled with large-file-support.

11.1 SLang_Error

The SLang_Error variable is nolonger part of the API. Change code such as

      SLang_Error = foo;
      if (SLang_Error == bar) ...

      SLang_set_error (foo);
      if (bar == SLang_get_error ()) ...

11.2 SLsmg/SLtt Functions

The changes to these functions were dictated by the new UTF-8 support. For the most part, the changes should be transparent but some functions and variables have been changed.

• SLtt_Use_Blink_For_ACS is nolonger supported, nor necessary I think only DOSEMU uses this.
• Prototypes for SLsmg_draw_object and SLsmg_write_char were changed to use wide characters (SLwchar_Type).
• SLsmg_Char_Type was changed from an unsigned short to a structure. This change was necessary in order to support combining characters and double width unicode characters. This change may affect the use of the following functions:

       SLsmg_char_at
       SLsmg_read_raw
       SLsmg_write_raw
       SLsmg_write_color_chars
  

• The SLSMG_BUILD_CHAR macro has been removed. The SLSMG_EXTRACT_CHAR macro will continue to work as long as combining characters are not present.
• The prototype for SLsmg_char_at was changed to

       int SLsmg_char_at (SLsmg_Char_Type *);
  

11.3 SLsearch Functions

SLsearch_Type is now an opaque type. Code such as

      SLsearch_Type st;
      SLsearch_init (string, 1, 0, &st);
         .
         .
      s = SLsearch (buf, bufmax, &st);

      SLsearch_Type *st = SLsearch_open (string, SLSEARCH_CASELESS);
      if (st == NULL)
        return;
         .
         .
      s = SLsearch_forward (st, buf, bufmax);
         .
         .
      SLsearch_close (st);

11.4 Regular Expression Functions

The slang v1 regular expression API has been redesigned in order to facilitate the incorporation of third party regular expression engines.

New functions include:

     SLregexp_compile
     SLregexp_free
     SLregexp_match
     SLregexp_nth_match
     SLregexp_get_hints

The plan is to migrate to the use of the PCRE regular expressions for version 2.2. As such, you may find it convenient to adopt the PCRE library now instead of updating to the changed S-Lang API.

11.5 Readline Functions

The readline interface has changed in order to make it easier to use. Using it now is as simple as:

      SLrline_Type *rli;
      rli = SLrline_open (SLtt_Screen_Cols, flags);
      buf = SLrline_read_line (rli, prompt, &len);
      /* Use buf */
         .
         .
      SLfree (buf);
      SLrline_close (rli);

11.6 Preprocessor Interface

SLPreprocess_Type was renamed to SLprep_Type and made opaque. New functions include:

      SLprep_new
      SLprep_delete
      SLprep_set_flags
      SLprep_set_comment
      SLprep_set_prefix
      SLprep_set_exists_hook
      SLprep_set_eval_hook

      SLPreprocess_Type pt;
      SLprep_open_prep (&pt);
         .
         .
      SLprep_close_prep (&pt);

      SLprep_Type *pt;
      pt = SLprep_new ();
         .
         .
      SLprep_delete (pt);

11.7 Functions dealing with the interpreter C API

• SLang_pop_double has been changed to be more like the other SLang_pop_* functions. Now, it may be used as:

         double x;
         if (-1 == SLang_pop_double (&x))
           .
           .
  

• All the functions that previously took an "unsigned char" to specify a slang data type have changed to require an SLtype. Previously, SLtype was typedefed to be an unsigned char, but now it is an int.
• The SLang_Class_Type object is now an opaque type. If you were previously accessing its fields directly, then you will have to change the code to use one of the accessor functions.

11.8 Modules

• In order to support the loading of a module into multiple namespaces, a module's init function may be called more than once. See modules/README for more information.
• The init_<module>_module function is no longer supported because it did not support namespaces. Use the init_<module>_module_ns function instead.