CodeText(3pm)

💖 CodeText(3pm) 💖 — Tk::CodeText bestie manual

okay so this is CodeText(3pm) from User Contributed Perl Documentation, and it's giving Tk::CodeText — the TextUndo widget with syntax highlighting capabilities. Part 1, bestie, so no cap, let's get into it. 🎀✨

---

✨ NAME ✨

Tk::CodeText — a TextUndo widget with syntax highlighting capabilities. that's the whole vibe. periodt. 💅

🌸 SYNOPSIS 🌸

bestie, here's the main-character setup fr fr:

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 🦋

okay so Tk::CodeText inherits Tk::TextUndo and all its options and methods. no cap. 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. it's giving very "editor that actually gets you" energy. 💅

Syntax highlighting is done through a plugin approach. 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. lowkey iconic.

Currently there is support for Bash, HTML, Perl, Pod, and Xresources. slay. 🌈

💅 OPTIONS 💅

• -autoindent — 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. so if you want your new lines to match the current line's indent, this is your girl. ✨
• -commentchar — Name: commentchar; Class: Commentchar; Switch: -commentchar. By default "#". that's the default, bestie. periodt.
• -disablemenu — 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. so if that right-click menu is not your vibe, set this. 💅
• -indentchar — Name: indentchar; Class: Indentchar; Switch: -indentchar. By default "\t". the tab character, iykyk.
• -match — 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 ''.

• -matchoptions — 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. fr fr.

"-background red -foreground yellow"

• -rules — 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. ngl, this one's a little meta.

• -rulesdir — 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. so if you want your rules on disk, set this. 🎀
• -syntax — 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. main character energy.

• -updatecall — 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. lowkey important warning.

There are some undocumented options. They are used internally. It is propably best to leave them alone. bestie, don't touch. 💀

👑 METHODS 👑

doAutoIndent

Checks the indention of the previous line and indents the line where the cursor is equally deep. so it matches the vibe of the line above. ✨

highlight($begin, $end);

Does syntax highlighting on the section of text indicated by $begin and $end. $begin and $end are linenumbers not indexes! not indexes, bestie, don't get it twisted.

highlightCheck>($begin, $end);

An insert or delete has taken place affecting the section of text between $begin and $end. highlightCheck is being called after and insert or delete operation. $begin and $end (again linenumbers, not indexes) indicate the section of text affected. highlightCheck checks what needs to be highlighted again and does the highlighting. it's giving cleanup crew. 🧚

highlightLine($line);

Does syntax highlighting on linenumber $line.

highlightPlug

Checks wether the appropriate highlight plugin has been loaded. If none or the wrong one is loaded, it loads the correct plugin. It returns a reference to the plugin loaded. It also checks wether the rules have changed. If so, it restarts highlighting from the beginning of the text. so it's the plugin manager, basically. 💅

highlightPlugInit

Loads and initalizes a highlighting plugin. First it checks the value of the -syntax option to see which plugin should be loaded. Then it checks wether a set of rules is defined to this plugin in the -rules option. If not, it tries to obtain a set of rules from disk using rulesFetch. If this fails as well it will use the hardcoded rules from the syntax plugin. iconic.

highlightPurge($line);

Tells the widget that the text from linenumber $line to the end of the text is not to be considered highlighted any more. so it's the "forget this" button. 🙈

highlightVisual

Calls visualEnd to see what part of the text is visible on the display, and adjusts highlighting accordingly. only highlights what you can see. efficient queen. 👑

linenumber($index);

Returns the linenumber part of an index. You may also specify indexes like 'end' or 'insert' etc.

matchCheck

Checks wether the character that is just before the 'insert'-mark should be matched, and if so should it match forwards or backwards. It then calls matchFind. vibe check for brackets. 🎀

matchFind($direction, $char, $match, $start, $stop);

Matches $char to $match, skipping nested $char/$match pairs, and displays the match found (if any).

rulesEdit

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

rulesFetch

Checks wether the file

$text->cget('-rulesdir') . '/' . $text->cget('-syntax') . '.rules'

exists, and if so attempts to load this as a set of rules.

rulesSave

Saves the currently loaded rules as

$text->cget('-rulesdir') . '/' . $text->cget('-syntax') . '.rules'

selectionComment

Comment currently selected text.

selectionIndent

Indent currently selected text.

selectionModify

Used by the other selection... methods to do the actual work. the backstage queen. 💅

selectionUnComment

Uncomment currently selected text.

selectionUnIndent

Unindent currently selected text.

🌟 SYNTAX HIGHLIGHTING 🌟

This section is a brief description of how the syntax highlighting process works. okay so, the lore. 📖

🧚 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. lazy loading, but make it fashion. 💅

highlightPlug checks wether a plugin is present. Next it will check whether the -rules option has been specified or wether 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. fr fr.

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

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

There are two ways to change the rules. two options, bestie. 💖

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

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

💜 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. so don't be dramatic if it takes a sec. 😭

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. line by line, like a true main character. ✨

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 🛠️

ok so after writing a couple of these plugins myself, i've lowkey collected a whole set of guidelines for how to set them up. if you're tryna add support for your own syntax highlighting problem or language, this section is literally for you bestie 💖

---

🧚 From scratch

if you decide to build a plugin completely from scratch, your module needs to meet these requirements, no cap:

• if you want to write a formal addition to Tk::CodeText, your plugin has to live in the namespace Tk::CodeText::YourSyntax. yes that's the whole vibe, that's the address 👑
• the constructor is called new, and it should accept a reference a reference to a list of rules as parameters. (that's not a typo, that's the manpage, i'm just the messenger 😭)
• Tk::CodeText is gonna call these methods on you: highlight, stateCompare, rules, setSate, getState, syntax. (yes, setSate. iconic spelling, we respect it 💅)

more info about those methods lives in the documentation of Tk::CodeText::None and Tk::CodeText::Template. good luck, you're on your own now 🫶

---

🌸 Inheriting Tk::CodeText::Template

for a lot of highlighting problems, Tk::CodeText::Template gives you a genuinely nice basis to start from. your code could 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 up, you specify your set of hardcoded rules ✨

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

then you call the constructor of Tk::CodeText::Template and bless your object:

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

so now we've got the SUPER class available and we can start defining a couple of things. obsessed honestly 💜

you could add a couple of lists, super useful for keywords and stuff:

   $self->lists({
       'Keywords' => ['foo', 'bar'],
       'Operators' => ['and', 'or'],
   });

for every tag you have to define a corresponding callback like this:

   $self->callbacks({
       'Tagname1' => \&Callback1,
       'Tagname2' => \&Callback2,
   });

and you have to define a default tagname like this:

   $self->stackPush('Tagname1');

maybe do a couple of other things, but in the end you gotta wrap up the new method:

   bless ($self, $class);
   return $self;
}

then you need to define the callbacks that are mentioned in the callbacks hash. when you're just starting to write your plugin, i suggest making them look like this:

sub callback1 {
   my ($self $txt) = @_;
   return $self->parserError($txt); #for debugging your later additions
}

later you add matching statements inside these callback methods. for instance, if you want callback1 to parse spaces, it's gonna look like this:

sub callback1 {
   my ($self $txt) = @_;
   if ($text =~ s/^(\s+)//) { #spaces
       $self->snippetParse($1, 'Tagname1'); #the tagname here is optional
       return $text;
   }
   return $self->parserError($txt); #for debugging your later additions
}

if callback1 is the callback that's called by default, you have to add the mechanism for checking lists to it. hence, the code is gonna look like this:

sub callback1 {
   my ($self $txt) = @_;
   if ($text =~ s/^(\s+)//) { #spaces
       $self->snippetParse($1, 'Tagname1'); #the tagname here is optional
       return $text;
   }
   if ($text =~ s/^([^$separators]+)//) {      #fetching a bare part
       if ($self->tokenTest($1, 'Reserved')) {
           $self->snippetParse($1, 'Reserved');
       } elsif ($self->tokenTest($1, 'Keyword')) {
           $self->snippetParse($1, 'Keyword');
       } else { #unrecognized text
           $self->snippetParse($1);
       }
       return $text
   }
   return $self->parserError($txt); #for debugging your later additions
}

go have a look at the code of Tk::CodeText::Bash. things should clear up, fr fr. and then, last but not least, you need a syntax method ⭐

---

🦋 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. no skipping, bestie 🙈

---

💌 CONTRIBUTIONS 💌

if you've written a plugin, i will be happy to include it in the next release of Tk::CodeText. if you send it to me, please have it accompanied with the sample of code that you used for testing. receipts, basically. we love receipts 🎀

👑 AUTHOR 👑

Hans Jeuken (haje@toneel.demon.nl) — the main character, periodt.

💀 BUGS 💀

Unknown. if you find any, please contact the author.

📝 TODO 📝

• add additional language modules. i am going to need help on this one 😭
• HTML and Xresources plugins need rewriting.
• the sample files in the test suite should be set up so that conformity with the language specification can actually be verified.

🔭 SEE ALSO 🔭

• Tk::Text
• Tk::TextUndo
• Tk::CodeText::None
• Tk::CodeText::Perl
• Tk::CodeText::HTML
• Tk::CodeText::Template
• Tk::CodeText::Bash

---

and that's the whole page, bestie 🫶 this one shipped as CodeText(3pm) under perl v5.40.1, dated 2025-05-04 — go forth and highlight some syntax, you've got this 💅✨🌈