NAME

Tk::CodeText - a TextUndo widget with syntax highlighting capabilities

SYNOPSIS

use Tk;
require Tk::CodeText;

my $m = new MainWindow;

my $e = $m->Scrolled('CodeText',
	-disablemenu => 1,
	-syntax => 'Perl',
	-scrollbars => 'se',
)->pack(-expand => 1, -fill => 'both');

$m->configure(-menu => $e->menu);
$m->MainLoop;

DESCRIPTION

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.

Syntax highlighting is done through a plugin approach. Currently there is support for Perl, Pod, HTML and Xresources. 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.

OPTIONS

Name: autoindent

Class: Autoindent

Switch: -autoindent

Boolean, when you press the enter button, should the next line begin at the same position as the current line or not. By default false.

Name: commentchar

Class: Commentchar

Switch: -commentchar

By default "#".

Name: disablemenu

Class: Disablemenu

Switch: -disablemenu

Boolean, by default 0. In case you don't want the menu under the right mouse button to pop up.

Name: indentchar

Class: Indentchar

Switch: -indentchar

By default "\t".

Name: match

Class: Match

Switch: -match

string of pairs for brace/bracket/curlie etc matching. If this description doesn't make anything clear, don't worry, the default setting will:

'[]{}()'

if you don't want matching to be available, simply set it to ''.

Name: matchoptions

Class: Matchoptions

Switch: -matchoptions

Options list for the tag 'Match'. By default:

[-background => 'red', -foreground => 'yellow']

You can also specify this option as a space separated string. Might come in handy for your Xresource files.

"-background red -foreground yellow"

Name: not available

Class: not available

Switch -rules

Specify the color and font options for highlighting. You specify a list looking a bit like this.

[
    ['Tagname1', @options1],
    ['Tagname2', @options2],
]

The names of the tags are depending on the syntax that is highlighted. See the language modules for more information about this data structure.

Name: rulesdir

Class: Rulesdir

Switch -rulesdir

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.

Name: syntax

Class: Syntax

Switch: -syntax

Specifies the language for highlighting. At this moment the possible values are None, HTML, Perl, Pod and Xresources. By default None

Alternatively it is possible to specify a reference to your independent plugin.

Name: Not available

Class: Not available

Switch: -updatecall

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.

There are some undocumented options. They are used internally. It is propably best to leave them alone.

METHODS

doAutoIndent

highlight

highlightCheck

highlightLine

highlightPlug

highlightPlugInit

highlightPurge

highlightVisual

linenumber

matchCheck

matchFind

rulesEdit

Pops up a window that enables the user the set the color and font options for the current syntax.

rulesFetch

rulesSave

selectionComment

selectionIndent

selectionModify

selectionUnComment

selectionUnIndent

SYNTAX HIGHLIGHTING

This section is a brief description of how the syntax highlighting process works.

Initiating plugin

The highlighting plugin is only then initiated when it is needed. When some highlighting needs to be done, the widget calls highlightPlug to retrieve a reference to the plugin.

highlightPlug checks wether a plugin is present. Next it will check whether the -rules option has been specified or whter the -rules option has changed. If no rules are specified in -rules, it will look for a pathname in the -rulesdir option. If that is found it will try to load a file called '*.rules', where * is the value of -syntax.

If no plugin is present, or the -syntax option has changed value, highlightPlug 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.

Changing the rules

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.

There are two ways to change the rules.

You can invoke the rulesEdit method, which is also available through the View 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 -rulesdir is specified, the rules will be saved on disk as rulesdir/syntax.rules.

You can also use configure 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 configure it is wise to call highlightPlug.

Highlighting text

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.

Highlighting is done on a line to line basis. At the end of each line the highlighting status is saved in the list in -colorinf, so when highlighting the next line, the highlight method of CodeText will know how to begin.

The line that needs highlighting is offered to the highlight method of the plugin. This method returns a list of offset and tagname pairs. Take for example the following line of perl code.

my $mother = 'older than i am';

The highlight method of the Perl plugin will return the following list;

(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',)    #;

The highlight 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.

WRITING PLUGINS

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.

From scratch

If you choose to build a plugin completely from scratch, your module needs to meet the following requirements.

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

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.

Inheriting Tk::CodeText::Template

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:

package Tk::CodeText::MySyntax;

use strict;
use base('Tk::CodeText::Template');

sub new {
   my ($proto, $wdg, $rules) = @_;
   my $class = ref($proto) || $proto;

Next, specify the set of hardcoded rules.

if (not defined($rules)) {
   $rules =  [
      ['Tagname1', -foreground => 'red'],
      ['Tagname1', -foreground => 'red'],
   ];
};

Call the constructor of Tk::CodeText::Template and bless your object.

my $self = $class->SUPER::new($wdg, $rules);
bless ($self, $class);

Perhaps do a couple of other things

   #$self->listAdd('listname', value1, value2 ....)

   return $self;
}

Then you need a highlight method. This method will be given a line of text as parameter by CodeText.

sub highlight {
   my ($self $txt) = @_;

Reset everything so that there is a clean beginning;

$cw->snippet('');
my $out = $self->out;
@$out = ();

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 snippet and/or snippetAppend methods of Tk::CodeText::Template. Whenever you have a snippet, you want to assign a tag to, you call snippetParse. The methods stack, stackPush, and stackPush are used to keep track of the current, possibly nested, tag. snippetParse 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.

After you're done highlighting, you still have to return your result;

   return @$out;
}

And then, last but not least, you need a syntax method.

sub syntax {
   my $self = shift;
   return 'MySyntax'
}
1;

Using another module as basis

An example of this approach is the Perl syntax module.

Also with this approach you will have to meet the minimum criteria as set out in the From scratch section.

AUTHOR

Hans Jeuken (haje@toneel.demon.nl)

BUGS

Unknown.

TODO

Find and eliminate bugs.

Improve documentation.

Add additional language modules. I am going to need help on this one.

Optimize highlighting methods.

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.

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 highlight and highlightLine as well as the code of the language modules.

Add variable options for linenumber, position, filename etc.

Make the rules editor fail safe.

SEE ALSO

Tk::Text, Tk::TextUndo, Tk::CodeText::None, Tk::CodeText::Perl Tk::CodeText::HTML

cpanm Tk::CodeText

perl -MCPAN -e shell
install Tk::CodeText