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