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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Tk::CodeText - a TextUndo widget with syntax highlighting capabilities</title>
<link rev="made" href="mailto:feedback@suse.de" />
</head>
<body style="background-color: white">
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#options">OPTIONS</a></li>
<li><a href="#methods">METHODS</a></li>
<li><a href="#syntax_highlighting">SYNTAX HIGHLIGHTING</a></li>
<li><a href="#writing_plugins">WRITING PLUGINS</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#todo">TODO</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Tk::CodeText - a TextUndo widget with syntax highlighting capabilities</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
use Tk;
require Tk::CodeText;</pre>
<pre>
my $m = new MainWindow;</pre>
<pre>
my $e = $m->Scrolled('CodeText',
-disablemenu => 1,
-syntax => 'Perl',
-scrollbars => 'se',
)->pack(-expand => 1, -fill => 'both');</pre>
<pre>
$m->configure(-menu => $e->menu);
$m->MainLoop;</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Tk::CodeText inherits Tk::TextUndo and all its options and methods. Besides
syntax highlighting, methods are provided for commenting and uncommenting
as well as indenting and unindenting a selected area, matching pairs of braces, brackets and
brackets and curlies and automatic indenting of new lines.</p>
<p>Syntax highlighting is done through a plugin approach. Currently there is
support for <strong>Perl</strong>, <strong>Pod</strong>, <strong>HTML</strong> and <strong>Xresources</strong>. Adding languages
is a matter of writing plugin modules. Theoretically this is not limited to programming languages.
The plugin approach could also provide the possibility for grammar or spell checking in spoken
languages.</p>
<p>
</p>
<hr />
<h1><a name="options">OPTIONS</a></h1>
<dl>
<dt><strong><a name="item_name%3a_autoindent">Name: <strong>autoindent</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_autoindent">Class: <strong>Autoindent</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dautoindent">Switch: <strong>-autoindent</strong></a></strong><br />
</dt>
<dd>
Boolean, when you press the enter button, should the next line begin at the
same position as the current line or not. By default <strong>false</strong>.
</dd>
<p></p>
<dt><strong><a name="item_name%3a_commentchar">Name: <strong>commentchar</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_commentchar">Class: <strong>Commentchar</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dcommentchar">Switch: <strong>-commentchar</strong></a></strong><br />
</dt>
<dd>
By default ``#''.
</dd>
<p></p>
<dt><strong><a name="item_name%3a_disablemenu">Name: <strong>disablemenu</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_disablemenu">Class: <strong>Disablemenu</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2ddisablemenu">Switch: <strong>-disablemenu</strong></a></strong><br />
</dt>
<dd>
Boolean, by default 0. In case you don't want the menu under the
right mouse button to pop up.
</dd>
<p></p>
<dt><strong><a name="item_name%3a_indentchar">Name: <strong>indentchar</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_indentchar">Class: <strong>Indentchar</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dindentchar">Switch: <strong>-indentchar</strong></a></strong><br />
</dt>
<dd>
By default ``\t''.
</dd>
<p></p>
<dt><strong><a name="item_name%3a_match">Name: <strong>match</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_match">Class: <strong>Match</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dmatch">Switch: <strong>-match</strong></a></strong><br />
</dt>
<dd>
string of pairs for brace/bracket/curlie etc matching. If this description
doesn't make anything clear, don't worry, the default setting will:
</dd>
<dd>
<pre>
'[]{}()'</pre>
</dd>
<dd>
<p>if you don't want matching to be available, simply set it to ''.</p>
</dd>
<p></p>
<dt><strong><a name="item_name%3a_matchoptions">Name: <strong>matchoptions</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_matchoptions">Class: <strong>Matchoptions</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dmatchoptions">Switch: <strong>-matchoptions</strong></a></strong><br />
</dt>
<dd>
Options list for the tag 'Match'. By default:
</dd>
<dd>
<pre>
[-background => 'red', -foreground => 'yellow']</pre>
</dd>
<dd>
<p>You can also specify this option as a space separated string. Might come in
handy for your Xresource files.</p>
</dd>
<dd>
<pre>
"-background red -foreground yellow"</pre>
</dd>
<p></p>
<dt><strong><a name="item_name%3a_not_available">Name: not available</a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_not_available">Class: not available</a></strong><br />
</dt>
<dt><strong><a name="item_switch_%2drules">Switch <strong>-rules</strong></a></strong><br />
</dt>
<dd>
Specify the color and font options for highlighting. You specify a list
looking a bit like this.
</dd>
<dd>
<pre>
[
['Tagname1', @options1],
['Tagname2', @options2],
]</pre>
</dd>
<dd>
<p>The names of the tags are depending on the syntax that is highlighted.
See the language modules for more information about this data structure.</p>
</dd>
<p></p>
<dt><strong><a name="item_name%3a_rulesdir">Name: rulesdir</a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_rulesdir">Class: Rulesdir</a></strong><br />
</dt>
<dt><strong><a name="item_switch_%2drulesdir">Switch <strong>-rulesdir</strong></a></strong><br />
</dt>
<dd>
Specify the directory where this widget stores its coloring defenitions.
Files in this directory are stored as ``HTML.rules'', ``Perl.rules'' etc.
By default it is set to '', which means that when you switch syntax
the highlighting rules are not loaded or stored. The hard coded defaults
in the language modules will be used.
</dd>
<p></p>
<dt><strong><a name="item_name%3a_syntax">Name: <strong>syntax</strong></a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_syntax">Class: <strong>Syntax</strong></a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dsyntax">Switch: <strong>-syntax</strong></a></strong><br />
</dt>
<dd>
Specifies the language for highlighting. At this moment the possible
values are <strong>None</strong>, <strong>HTML</strong>, <strong>Perl</strong>, <strong>Pod</strong> and <strong>Xresources</strong>.
By default <strong>None</strong>
</dd>
<dd>
<p>Alternatively it is possible to specify a reference to your independent plugin.</p>
</dd>
<p></p>
<dt><strong><a name="item_name%3a_not_available">Name: Not available</a></strong><br />
</dt>
<dt><strong><a name="item_class%3a_not_available">Class: Not available</a></strong><br />
</dt>
<dt><strong><a name="item_switch%3a_%2dupdatecall">Switch: <strong>-updatecall</strong></a></strong><br />
</dt>
<dd>
Here you can specify a callback that will be executed whenever the insert
cursor has moved or text has been modified, so your application can keep
track of position etc. Don't make this callback to heavy, the widget will
get sluggish quickly.
</dd>
<p></p></dl>
<p>There are some undocumented options. They are used internally.
It is propably best to leave them alone.</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<dl>
<dt><strong><a name="item_doautoindent"><strong>doAutoIndent</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlight"><strong>highlight</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlightcheck"><strong>highlightCheck</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlightline"><strong>highlightLine</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlightplug"><strong>highlightPlug</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlightpluginit"><strong>highlightPlugInit</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlightpurge"><strong>highlightPurge</strong></a></strong><br />
</dt>
<dt><strong><a name="item_highlightvisual"><strong>highlightVisual</strong></a></strong><br />
</dt>
<dt><strong><a name="item_linenumber"><strong>linenumber</strong></a></strong><br />
</dt>
<dt><strong><a name="item_matchcheck"><strong>matchCheck</strong></a></strong><br />
</dt>
<dt><strong><a name="item_matchfind"><strong>matchFind</strong></a></strong><br />
</dt>
<dt><strong><a name="item_rulesedit"><strong>rulesEdit</strong></a></strong><br />
</dt>
<dd>
Pops up a window that enables the user the set the color and font options
for the current syntax.
</dd>
<p></p>
<dt><strong><a name="item_rulesfetch"><strong>rulesFetch</strong></a></strong><br />
</dt>
<dt><strong><a name="item_rulessave"><strong>rulesSave</strong></a></strong><br />
</dt>
<dt><strong><a name="item_selectioncomment"><strong>selectionComment</strong></a></strong><br />
</dt>
<dt><strong><a name="item_selectionindent"><strong>selectionIndent</strong></a></strong><br />
</dt>
<dt><strong><a name="item_selectionmodify"><strong>selectionModify</strong></a></strong><br />
</dt>
<dt><strong><a name="item_selectionuncomment"><strong>selectionUnComment</strong></a></strong><br />
</dt>
<dt><strong><a name="item_selectionunindent"><strong>selectionUnIndent</strong></a></strong><br />
</dt>
</dl>
<p>
</p>
<hr />
<h1><a name="syntax_highlighting">SYNTAX HIGHLIGHTING</a></h1>
<p>This section is a brief description of how the syntax highlighting process
works.</p>
<p><strong>Initiating plugin</strong></p>
<p>The highlighting plugin is only then initiated when it is needed. When some
highlighting needs to be done, the widget calls <strong>highlightPlug</strong> to retrieve
a reference to the plugin.</p>
<p><strong>highlightPlug</strong> checks wether a plugin is present. Next it will check whether the <strong>-rules</strong> option has been
specified or whter the <strong>-rules</strong> option has changed. If no rules are specified in <strong>-rules</strong>, it will look for a pathname
in the <strong>-rulesdir</strong> option. If that is found it will try to load a file called '*.rules', where * is the value of <strong>-syntax</strong>.</p>
<p>If no plugin is present, or the <strong>-syntax</strong> option has changed value,
<strong>highlightPlug</strong> loads the plugin. and constructs optionally giving it
a reference to the found rules as parameter. if no rules
are specified, the plugin will use its internal hardcoded defaults.</p>
<p><strong>Changing the rules</strong></p>
<p>A set of rules is a list, containing lists of tagnames, followed by options.
If you want to see what they look like, you can have a look at the constructors
of each plugin module. Every plugin has a fixed set of tagnames it can handle.</p>
<p>There are two ways to change the rules.</p>
<p>You can invoke the <strong>rulesEdit</strong> method, which is also available through the
<strong>View</strong> menu. The result is a popup in which you can specify color and font
options for each tagname. After pressing 'Ok', the edited rules will be applied.
If <strong>-rulesdir</strong> is specified, the rules will be saved on disk as
<em>rulesdir/syntax.rules</em>.</p>
<p>You can also use <strong>configure</strong> to specify a new set of rules. In this you have
ofcause more freedom to use all available tag options. For more details about
those there is a nice section about tag options in the Tk::Text documentation.
After the call to <strong>configure</strong> it is wise to call <strong>highlightPlug</strong>.</p>
<p><strong>Highlighting text</strong></p>
<p>Syntax highlighting is done in a lazy manor. Only that piece of text is
highlighted that is needed to present the user a pretty picture. This is
done to minimize use of system resources. Highlighting is running on the
foreground. Jumping directly to the end of a long fresh loaded textfile may
very well take a couple of seconds.</p>
<p>Highlighting is done on a line to line basis. At the end of each line the
highlighting status is saved in the list in <strong>-colorinf</strong>, so when highlighting
the next line, the <strong>highlight</strong> method of <strong>CodeText</strong> will know how to begin.</p>
<p>The line that needs highlighting is offered to the <strong>highlight</strong> method of
the plugin. This method returns a list of offset and tagname pairs.
Take for example the following line of perl code.</p>
<pre>
my $mother = 'older than i am';</pre>
<p>The <strong>highlight</strong> method of the Perl plugin will return the following list;</p>
<pre>
(2 => 'Reserved', #'my' is a reserved word
1 => 'DEFAULT', #Space
7 => 'Variable', #$mother
1 => 'DEFAULT', #Space
1 => 'Operator', #'='
1 => 'DEFAULT', #Space
17 => 'String', #'older than i am'
1 => 'DEFAULT',) #;</pre>
<p>The <strong>highlight</strong> method of CodeText will then mark positions 0 to 2 as
'Reserved', positions 2 to 3 as 'DEFAULT', positions 3 to 10 as 'Variable',
etcetera.</p>
<p>
</p>
<hr />
<h1><a name="writing_plugins">WRITING PLUGINS</a></h1>
<p>After writing a couple of plugins myself i have come to a couple of guidelines
about how to set them up. If you are interested in adding support for your
own syntax highlighting problem or language this section is of interest to you.</p>
<p><strong>From scratch</strong></p>
<p>If you choose to build a plugin completely from scratch, your module needs
to meet the following requirements.</p>
<pre>
- If you want to write a formal addition to Tk::CodeText,
your plugin must be in the namespace
Tk::CodeText::YourSyntax.
- The constructor is called 'new', and it should accept
a reference a reference to a list of rules as parameters.
- The following methods will be called upon by Tk::CodeText:
highlight, stateCompare, rules, setSate,
getState, syntax.</pre>
<p>More information about those methods is available in the documentation of
Tk::CodeText::None and Tk::CodeText::Template. Good luck, you're on your own now.</p>
<p><strong>Inheriting Tk::CodeText::Template</strong></p>
<p>For many not too complicated highlighting problems Tk::CodeText::Template
provides a nice basis to start from. I have been able to write to
easily write support for HTML, Pod and Xresources files. Anyway, your code
should look like this:</p>
<pre>
package Tk::CodeText::MySyntax;
use strict;
use base('Tk::CodeText::Template');
sub new {
my ($proto, $wdg, $rules) = @_;
my $class = ref($proto) || $proto;</pre>
<p>Next, specify the set of hardcoded rules.</p>
<pre>
if (not defined($rules)) {
$rules = [
['Tagname1', -foreground => 'red'],
['Tagname1', -foreground => 'red'],
];
};</pre>
<p>Call the constructor of Tk::CodeText::Template and bless your
object.</p>
<pre>
my $self = $class->SUPER::new($wdg, $rules);
bless ($self, $class);</pre>
<p>Perhaps do a couple of other things</p>
<pre>
#$self->listAdd('listname', value1, value2 ....)</pre>
<pre>
return $self;
}</pre>
<p>Then you need a <strong>highlight</strong> method. This method will be given a line of text
as parameter by CodeText.</p>
<pre>
sub highlight {
my ($self $txt) = @_;</pre>
<p>Reset everything so that there is a clean beginning;</p>
<pre>
$cw->snippet('');
my $out = $self->out;
@$out = ();</pre>
<p>Here comes the difficult part, where you are on your own. Perhaps you can
draw some inspiration from existing highlighting plugins. The trick is to
repeatedly build a text snippet using the <strong>snippet</strong> and/or <strong>snippetAppend</strong>
methods of Tk::CodeText::Template. Whenever you have a snippet, you want to
assign a tag to, you call <strong>snippetParse</strong>. The methods <strong>stack</strong>, <strong>stackPush</strong>,
and <strong>stackPush</strong> are used to keep track of the current, possibly nested,
tag. <strong>snippetParse</strong> pushes the length of the snippet and the tagname that
is on top of the stack to the @$out array. For more information read the
documentation of Tk::CodeText::Template.</p>
<p>After you're done highlighting, you still have to return your result;</p>
<pre>
return @$out;
}</pre>
<p>And then, last but not least, you need a <strong>syntax</strong> method.</p>
<pre>
sub syntax {
my $self = shift;
return 'MySyntax'
}
1;</pre>
<p><strong>Using another module as basis</strong></p>
<p>An example of this approach is the Perl syntax module.</p>
<p>Also with this approach you will have to meet the minimum criteria
as set out in the <strong>From scratch</strong> section.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<dl>
<dt><strong><a name="item_jeuken">Hans Jeuken (<a href="mailto:haje@toneel.demon.nl">haje@toneel.demon.nl</a>)</a></strong><br />
</dt>
</dl>
<p>
</p>
<hr />
<h1><a name="bugs">BUGS</a></h1>
<p>Unknown.</p>
<p>
</p>
<hr />
<h1><a name="todo">TODO</a></h1>
<dl>
<dt><strong><a name="item_find_and_eliminate_bugs%2e">Find and eliminate bugs.</a></strong><br />
</dt>
<dt><strong><a name="item_improve_documentation%2e">Improve documentation.</a></strong><br />
</dt>
<dt><strong><a name="item_add_additional_language_modules%2e_i_am_going_to_n">Add additional language modules. I am going to need help on this one.</a></strong><br />
</dt>
<dt><strong><a name="item_optimize_highlighting_methods%2e">Optimize highlighting methods.</a></strong><br />
</dt>
<dd>
Syntax highlighting consumes a lot of system resources. Squeezing every bit
of performance out of it might make it less sluggish on slow systems, like
a pentium at 100Mhz.
</dd>
<dd>
<p>If you're interested in this module, please have a look at the code
and point out to me where I might have overlooked something. Of special
interest are the CodeText methods <strong>highlight</strong> and <strong>highlightLine</strong> as well as
the code of the language modules.</p>
</dd>
<p></p>
<dt><strong><a name="item_add_variable_options_for_linenumber%2c_position%2c">Add variable options for linenumber, position, filename etc.</a></strong><br />
</dt>
<dt><strong><a name="item_make_the_rules_editor_fail_safe%2e">Make the rules editor fail safe.</a></strong><br />
</dt>
</dl>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<dl>
<dt><strong><a name="item_tk%3a%3atext%2c_tk%3a%3atextundo%2c_tk%3a%3acodete"><strong>Tk::Text</strong>, <strong>Tk::TextUndo</strong>, <strong>Tk::CodeText::None</strong>, <strong>Tk::CodeText::Perl</strong>
<strong>Tk::CodeText::HTML</strong></a></strong><br />
</dt>
</dl>
</body>
</html>
|
