1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator"
content="HTML Tidy for Windows (vers 1st August 2002), see www.w3.org" />
<meta name="generator" content="SciTE" />
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Migration to Scintilla 5.x.</title>
<style type="text/css">
<!--
/*<![CDATA[*/
CODE { font-weight: bold; font-family: Menlo,Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
CODE.example { background: #EBFFF7;}
CODE.windows { background: #E7F0FF;}
CODE.unix { background: #FFFFD7;}
A:visited { color: blue; }
A:hover { text-decoration: underline ! important; }
A.message { text-decoration: none; font-weight: bold; font-family: Menlo,Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
A.seealso { text-decoration: none; font-weight: bold; font-family: Menlo,Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
A.toc { text-decoration: none; }
A.jump { text-decoration: none; }
LI.message { text-decoration: none; font-weight: bold; font-family: Menlo,Consolas,Bitstream Vera Sans Mono,Courier New,monospace; }
H2 { background: #E0EAFF; }
table {
border: 0px;
border-collapse: collapse;
}
div.console {
font-family: Menlo,Consolas,Bitstream Vera Sans Mono,Courier New,monospace;
color: #008000;
font-weight: bold;
background: #F7FCF7;
border: 1px solid #C0D7C0;
margin: 0.3em 3em;
padding: 0.3em 0.6em;
}
span.console {
font-family: Menlo,Consolas,Bitstream Vera Sans Mono,Courier New,monospace;
color: #008000;
font-weight: bold;
background: #F7FCF7;
border: 1px solid #C0D7C0;
margin: 0.1em 0em;
padding: 0.1em 0.3em;
}
.name {
color: #B08000;
}
/*]]>*/
-->
</style>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table bgcolor="#000000" width="100%" cellspacing="0" cellpadding="0" border="0"
summary="Banner">
<tr>
<td><img src="SciTEIco.png" border="3" height="64" width="64" alt="Lexilla icon" /></td>
<td><a href="index.html"
style="color:white;text-decoration:none;font-size:200%">Scintilla</a></td>
</tr>
</table>
<h1>Migrating Applications to Scintilla 5 with Lexilla.</h1>
<h2>Introduction</h2>
<p>With Scintilla 5.0, all lexers were moved from Scintilla into the Lexilla library
which is a <a href="https://www.scintilla.org/Lexilla.html">separate project</a>.
Lexilla may be either a static library
that is linked into an application or a shared library that is loaded at runtime.</p>
<p>Lexilla has its own <a href="LexillaDoc.html">documentation</a>.</p>
<h2>Basics</h2>
<p>With Scintilla 4.x, it was most common for applications to set a lexer either by lexer name or lexer ID (<span class="name">SCLEX_...</span>) by calling
<code>SCI_SETLEXERLANGUAGE("<name>")</code> or <code>SCI_SETLEXER(SCLEX_*)</code>.</p>
<p>With Scintilla 5, the normal technique is to call Lexilla's <span class="name">CreateLexer</span> function
with a lexer name, then apply the result with
Scintilla's <span class="name">SCI_SETILEXER</span> method:<br />
<code>ILexer5 *pLexer = CreateLexer("<name>")<br />
SCI_SETILEXER(pLexer)</code></p>
<p>Lexer names are now strongly preferred to lexer IDs and applications should switch where possible.
Some lexers will not have lexer IDs but all will have names.</p>
<p>Applications may be written in C++ or C; may contain a statically linked Lexilla library or load a Lexilla
shared library; and may use the raw Lexilla API or the LexillaAccess C++ helper module.</p>
<h2>From C++: LexillaAccess</h2>
<p>The easiest technique is to implement in C++ using LexillaAccess and load a Lexilla shared library.</p>
<p>LexillaAccess simplifies use of Lexilla, hides operating system differences, and allows loading
multiple libraries that support the Lexilla protocol.
It is defined in lexilla/access/LexillaAccess.h and the source code is in lexilla/access/LexillaAccess.cxx.
Add these to the build dependencies of the project or build file.</p>
<p>Both SciTE and TestLexers (used to test Lexilla) in lexilla/test use LexillaAccess.
TestLexers is much simpler than SciTE so can be a good example to examine.</p>
<h3>Building</h3>
<p>Header files for lexers and for using Lexilla will be included so build files will need to reference these new locations.
LexillaAccess.cxx should be added to the set of source files.
In make, for example, this may appear similar to:</p>
<code class="example">
LEXILLA_DIR ?= $(srcdir)/../../lexilla<br />
INCLUDES += -I $(LEXILLA_DIR)/include -I $(LEXILLA_DIR)/access<br />
SOURCES += $(LEXILLA_DIR)/access/LexillaAccess.cxx<br />
</code>
<h3>Steps in code</h3>
<p>Set the directory to search for Lexilla when full paths aren't provided.
This may be a known good system or user directory or the directory of the application
depending on the operating system conventions.</p>
<code class="example">
std::string homeDirectory = "/Users/Me/bin";<br />
Lexilla::SetDefaultDirectory(homeDirectory);<br />
</code>
<p>Load Lexilla or another library that implements the Lexilla protocol.
The name "." means the standard name and extension (liblexilla.so / liblexilla.dylib / lexilla.dll)
in the default directory so is often a good choice. Names without extensions have the operating system's preferred
shared library extension added.
A full path can also be used.
Multiple libraries can be loaded at once by listing them separated by ';'.
Something like one of these lines:</p>
<code class="example">
Lexilla::Load(".");<br />
Lexilla::Load("lexilla;lexpeg;XMLexers");<br />
Lexilla::Load("/usr/lib/liblexilla.so;/home/aardvark/bin/libpeg.so");<br />
</code>
<p>Choose the name of the lexer to use. This may be determined from the file extension or some other mechanism.</p>
<code class="example">
std::string lexerName = "cpp";<br />
</code>
<p>Create a lexer and apply it to a Scintilla instance.</p>
<code class="example">
Scintilla::ILexer5 *pLexer = Lexilla::MakeLexer(lexerName);<br />
CallScintilla(scintilla, SCI_SETILEXER, 0, pLexer);<br />
</code>
<p>Some applications may use integer lexer IDs from SciLexer.h with an "SCLEX_" prefix like
<span class="name">SCLEX_CPP</span>.
These can be converted to a name with NameFromID before passing to MakeLexer.</p>
<code class="example">
Scintilla::ILexer5 *pLexer = Lexilla::MakeLexer(Lexilla::NameFromID(SCLEX_CPP));<br />
</code>
<h2>From C: Lexilla.h and system APIs</h2>
<p>Applications written in C or C++ can use the raw Lexilla API which is defined in lexilla/include/Lexilla.h.
Since the ILexer interface is difficult to define for C, C applications should treat the result of CreateLexer as a
<code>void*</code> that is simply passed through to Scintilla.
If there is a need to call methods on the lexer
before passing it to Scintilla then it would be best to use some C++ code although it may be possible
for a sufficiently motivated developer to call methods on the lexer from C.</p>
<p>There is an example for using Lexilla from C in examples/CheckLexilla.</p>
<h3>Steps in code</h3>
<p>Include the system header for loading shared objects.
This depends on the operating system: <windows.h> for <code class="windows">Windows</code> or
<dlfcn.h> for <code class="unix">Unix</code>.</p>
<code class="windows">#include <windows.h><br /></code>
<code class="unix">#include <dlfcn.h><br /></code>
<p>Define a path to the Lexilla shared library.
This may be a known good system or user directory or the directory of the application
depending on the operating system conventions.</p>
<code class="example">
#include "Lexilla.h"<br />
char szLexillaPath[] = "../../bin/" LEXILLA_LIB LEXILLA_EXTENSION;<br />
</code>
<p>Load Lexilla using the appropriate operating system function: either LoadLibrary on Windows or
dlopen on Unix.</p>
<code class="windows">HMODULE lexillaLibrary = LoadLibrary(szLexillaPath);<br /></code>
<code class="unix">void *lexillaLibrary = dlopen(szLexillaPath, RTLD_LAZY);<br /></code>
<p>Find the CreateLexer function inside the shared library using either GetProcAddress on Windows or
dlsym on Unix.</p>
<code class="windows">FARPROC fun = GetProcAddress(lexillaLibrary, LEXILLA_CREATELEXER);<br /></code>
<code class="unix">void *fun = dlsym(lexillaLibrary, LEXILLA_CREATELEXER);<br /></code>
<p>Cast this to the correct type.</p>
<code class="example">CreateLexerFn lexerCreate = (CreateLexerFn)(fun);<br /></code>
<p>Choose the name of the lexer to use. This may be determined from the file extension or some other mechanism.</p>
<code class="example">char lexerName[] = "cpp";<br /></code>
<p>Create a lexer and apply it to a Scintilla instance.</p>
<code class="example">
void *pLexer = lexerCreate(lexerName);<br />
CallScintilla(scintilla, SCI_SETILEXER, 0, pLexer);<br />
</code>
<p>If the application uses integer lexer IDs then find the <span class="name">LEXILLA_LEXERNAMEFROMID</span>
function, cast to <span class="name">LexerNameFromIDFn</span> then call with the ID before using the result to call
<span class="name">CreateLexer</span>.</p>
<code class="windows">FARPROC funName = GetProcAddress(lexillaLibrary, LEXILLA_LEXERNAMEFROMID);<br /></code>
<code class="unix">void *funName = dlsym(lexillaLibrary, LEXILLA_LEXERNAMEFROMID);<br /></code>
<code class="example">LexerNameFromIDFn lexerNameFromID = (LexerNameFromIDFn)(funName);<br /></code>
<code class="example">const char *name = lexerNameFromID(lexerID);<br /></code>
<h2>Static linking</h2>
<p>Lexilla may be linked directly into an application or built into a static library that is then
linked into the application, then there is no need to load a shared library and
<span class="name">CreateLexer</span> can be directly called.</p>
<p>It is possible to link Lexilla into an application and then dynamically load other
shared libraries that implement the Lexilla protocol.
SciTE on Windows implements this as an option when built with STATIC_BUILD defined.</p>
</body>
</html>
|
