1\chapter{S-Lang 2 API NEWS and UPGRADE information} 2 3 The \slang API underwent a number of changes for version 2. In 4 particular, the following interfaces have been affected: 5#v+ 6 SLsmg 7 SLregexp 8 SLsearch 9 SLrline 10 SLprep 11 slang interpreter modules 12#v- 13 Detailed information about these changes is given below. Other 14 changes include: 15\begin{itemize} 16\item UTF-8 encoded strings are now supported at both the C library level 17 and the interpreter. 18\item Error handling by the interpreter has been rewritten to support 19 try/catch style exception. Applications may also define 20 application-specific error codes. 21\item The library may be compiled with large-file-support. 22\end{itemize} 23See the relevant chapters in this manual for more information. 24 25\sect{SLang_Error} 26 27 The \var{SLang_Error} variable is nolonger part of the API. Change code 28 such as 29#v+ 30 SLang_Error = foo; 31 if (SLang_Error == bar) ... 32#v- 33 to 34#v+ 35 SLang_set_error (foo); 36 if (bar == SLang_get_error ()) ... 37#v- 38 39\sect{SLsmg/SLtt Functions} 40 41 The changes to these functions were dictated by the new UTF-8 42 support. For the most part, the changes should be transparent but 43 some functions and variables have been changed. 44 45\begin{itemize} 46\item SLtt_Use_Blink_For_ACS is nolonger supported, nor necessary I think only 47 DOSEMU uses this. 48\item 49 Prototypes for \cfun{SLsmg_draw_object} and \cfun{SLsmg_write_char} 50 were changed to use wide characters (SLwchar_Type). 51\item 52 \var{SLsmg_Char_Type} was changed from an \exmp{unsigned short} to a 53 structure. This change was necessary in order to support combining 54 characters and double width unicode characters. This change may affect 55 the use of the following functions: 56#v+ 57 SLsmg_char_at 58 SLsmg_read_raw 59 SLsmg_write_raw 60 SLsmg_write_color_chars 61#v- 62\item The \exmp{SLSMG_BUILD_CHAR} macro has been removed. 63 The \exmp{SLSMG_EXTRACT_CHAR} macro will continue to work as long as 64 combining characters are not present. 65\item The prototype for \cfun{SLsmg_char_at} was changed to 66#v+ 67 int SLsmg_char_at (SLsmg_Char_Type *); 68#v- 69\end{itemize} 70 71\sect{SLsearch Functions} 72 73 \var{SLsearch_Type} is now an opaque type. Code such as 74#v+ 75 SLsearch_Type st; 76 SLsearch_init (string, 1, 0, &st); 77 . 78 . 79 s = SLsearch (buf, bufmax, &st); 80#v- 81 which searches forward in \exmp{buf} for \exmp{string} must be changed to 82#v+ 83 SLsearch_Type *st = SLsearch_open (string, SLSEARCH_CASELESS); 84 if (st == NULL) 85 return; 86 . 87 . 88 s = SLsearch_forward (st, buf, bufmax); 89 . 90 . 91 SLsearch_close (st); 92#v- 93 94\sect{Regular Expression Functions} 95 96 The slang v1 regular expression API has been redesigned in order to 97 facilitate the incorporation of third party regular expression 98 engines. 99 100 New functions include: 101#v+ 102 SLregexp_compile 103 SLregexp_free 104 SLregexp_match 105 SLregexp_nth_match 106 SLregexp_get_hints 107#v- 108 109 The plan is to migrate to the use of the PCRE regular expressions 110 for version 2.2. As such, you may find it convenient to adopt the 111 PCRE library now instead of updating to the changed \slang API. 112 113\sect{Readline Functions} 114 115 The readline interface has changed in order to make it easier to 116 use. Using it now is as simple as: 117#v+ 118 SLrline_Type *rli; 119 rli = SLrline_open (SLtt_Screen_Cols, flags); 120 buf = SLrline_read_line (rli, prompt, &len); 121 /* Use buf */ 122 . 123 . 124 SLfree (buf); 125 SLrline_close (rli); 126#v- 127 See how it is used in \file{slsh/readline.c}. 128 129\sect{Preprocessor Interface} 130 131 SLPreprocess_Type was renamed to SLprep_Type and made opaque. 132 New functions include: 133#v+ 134 SLprep_new 135 SLprep_delete 136 SLprep_set_flags 137 SLprep_set_comment 138 SLprep_set_prefix 139 SLprep_set_exists_hook 140 SLprep_set_eval_hook 141#v- 142 If you currently use: 143#v+ 144 SLPreprocess_Type pt; 145 SLprep_open_prep (&pt); 146 . 147 . 148 SLprep_close_prep (&pt); 149#v- 150 Then change it to: 151#v+ 152 SLprep_Type *pt; 153 pt = SLprep_new (); 154 . 155 . 156 SLprep_delete (pt); 157#v- 158 159\sect{Functions dealing with the interpreter C API} 160 161\begin{itemize} 162\item \cfun{SLang_pop_double} has been changed to be more like the other 163 \cfun{SLang_pop_*} functions. Now, it may be used as: 164#v+ 165 double x; 166 if (-1 == SLang_pop_double (&x)) 167 . 168 . 169#v- 170\item All the functions that previously took an "unsigned char" to 171 specify a slang data type have changed to require an \var{SLtype}. 172 Previously, \var{SLtype} was typedefed to be an \var{unsigned 173 char}, but now it is an \var{int}. 174 175\item The \var{SLang_Class_Type} object is now an opaque type. If you were 176 previously accessing its fields directly, then you will have to 177 change the code to use one of the accessor functions. 178\end{itemize} 179 180\sect{Modules} 181 182\begin{itemize} 183\item 184 In order to support the loading of a module into multiple 185 namespaces, a module's init function may be called more than once. 186 See modules/README for more information. 187\item 188 The \var{init_<module>_module} function is no longer supported 189 because it did not support namespaces. Use the 190 \var{init_<module>_module_ns} function instead. 191\end{itemize} 192