S-Lang Library C Programmer's Guide, V2.0.4: S-Lang 2 API NEWS and UPGRADE information

Next Previous Contents

## 10. S-Lang 2 API NEWS and UPGRADE information

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

> `

>         SLsmg
>         SLregexp
>         SLsearch
>         SLrline
>         SLprep
>         slang interpreter modules

> `

More detail of the changes is presented below. Other changes include:

- UTF-8 encoded strings are now supported at both the C library level and the interpreter.
- Error handling by the interpreter has been rewritten. Now applications may define application-specific error codes.
- The library may be compiled with large-file-support.

See the relevant chapters in this manual for more information.

## 10.1 SLang_Error

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

> `

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

> `

to

> `

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

> `

## 10.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. 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 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` changed to

  > `

  >          int SLsmg_char_at (SLsmg_Char_Type *);

  > `

## 10.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);

> `

which searches forward in `buf` for `string` must be changed to

> `

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

> `

## 10.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.

## 10.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);

> `

See how it is used in `slsh/readline.c`.

## 10.6 Preprocessor Interface

SLPreprocess_Type has been 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

> `

If you currently use:

> `

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

> `

Then change it to:

> `

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

> `

## 10.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.

## 10.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.

Next Previous Contents