Jacob Thurman

Here’s another interesting tidbit about the upcoming new code templates.  Again, this is all pre-release, and is subject to change or withdrawal until it actually ships.  Comments and suggestions are, as always welcome.

Castalia’s code templates have always been context-sensitive, to a degree.  In the template editor, there have always been checkboxes that allow you to specify whether a template should fire in strings or in comments.  This is important because when you type “if” in a comment, you probably don’t mean to create an if..then statement.

This sensitivity is good, but it could be better.  Take, for example, the “r=” template, which expands to “Result :=”.  This is only really useful in a function, and wouldn’t be good to do in a procedure (in fact, if you typed this in a procedure, having it NOT fire would serve as a good reminder that you don’t have a return value for your procedure – catching the error before it gets out of control).  With Castalia’s current templates, there’s no way to specify that a template fire only in a function, not in a procedure.

With the new templates, this is easy.  In the template editor, the checkboxes are gone, and have been replaced with a simple “scope” edit control.  Each template has a scope string, which is sort of like a demented CSS selector.  Here’s what the scope string looks like for the “r=” template:

 function – string & function – comment

This is reasonably self explanatory, but let’s explore a bit.  This string is made of two individual scope selectors, joined with an &, meaning AND.  Each individual selector is in the form “positive – negative” and will match any location in code where the positive part is true, and the negative part is false.  So “function – string” means “in a function, but not in a string.”  “function – comment” means “in a function, but not in a comment.”  The & means that both of those selectors must be true in order for the template to fire.

The individual parts of a selector can contain nested words, for greater precision.  For example, if you wanted a template to fire only in a function that is a member of a class, you could do it:

class > function

The positive or negative part of a selector can be blank.  In the example above, the negative selector is blank (so there is no “-” sign).  If the positive selector is blank, the selector begins with the “-” operator.  This selector will fire everywhere except in a comment or a string:

 - comment & – string

Note that the “-” operator is always binary – it is part of the selector, not a modifier of a selector.  That is, this is invalid:

method – (comment & string)

What is being intended here should be written like this:

method – comment & method – string

Or like this:

method & – comment & – string

If you want to use an OR operator, you would use a comma.  For example, the following scope would match any class except in a comment, or any string:

class – comment, string

Operator precedence between & and , is simply left to right.  You can change that with parenthesis:

class – comment, (string & method)

This would fire in any class except in a comment, or in any string that’s in a method.  There are better ways to write that, but it demonstrates the concept.  One more example wouldn’t hurt, so here’s how I would write it better:

class – comment, method > string

Scope selectors in the new Castalia templates allow for powerful and completely flexible control over where templates fire, and are one of the major improvements over the old template system.  The more I work on this, more excited I am to get it finished and get it into your hands.

I don’t talk about upcoming features very often, but I want to get some feedback on some stuff that’s in the works for the next edition of Castalia.  Before I get started, I need to throw out the usual disclaimer that this is about future stuff that is still in the works, and may or may not actually appear in the finished product.  You know the drill…

So, here’s the deal:

Code templates in Castalia have remained more or less the same since the first version.  They are snippets of text with some special characters in them that do things like drop a bookmark or insert a multicursor point.  At first, the special characters were actual characters that just didn’t have any meaning in Delphi, like a | for an insertion point, and a ~ for an indent, etc….  Eventually, I wanted the editor to make a little more sense, so they were replaced with high-order characters that the editor would display as icons that gave some indication of what they would do.

This templating system is very useful, but it’s still limited to a basic idea of text snippets that are inserted into the editor… They’re just really powerful text snippets.

The time has come for more power and flexibility in Castalia’s code templates.  Over the last several weeks I have completely gutted the template system from Castalia and begun what has turned into a complete rewrite.

The new code template system is actually a scripting system.  Borrowing from web programming systems like PHP or ASP, the new templates are a combination of text to be inserted directly into the editor and of scripting code, contained between {% and %} markers.

The scripting language is Delphi-based, so there’s no syntax to learn as you write really powerful code templates.  It also takes the mystery out of the special icons that are currently used to indicate features.  Here’s an example of what the ifb template looks like (ifb inserts an if statement with a begin..end block):

if {% InsertCursor(0) %} then
begin
{%= Indent %}{% InsertCursor (1) %}
end;

Everything not between {% %} markers is inserted directly into the editor.  Code between the {% %} markers is executed.  This example shows the InsertCursor(AOrder: Integer) procedure, which drops a bookmark at that point in the text. The bookmark with AOrder = 0 will be the location of the cursor after the template is done executing.  The bookmarks are then picked up in the order indicated by the AOrder parameter.

Also notice the {%= marker, which means “insert the result of this code into the editor.”  Indent returns a string of spaces matching your indent size.

Here’s an example of a template to insert the current method name as a string:

{% if ClassName <> ” then
begin
%}{%= ClassName %}.{% end %}{%= ProcedureName %}

Notice the Delphi code right in the template to check whether there is a current class and insert the “ClassName.” before the method name.

The built-in functions and variables will be  able to do everything the old template system could, and more.  The scripting code will make it even more capable.  I have lots of ideas as to what I’d like to make possible, but I want this to be as flexible and powerful as possible, and that’s where you come in:

What do you envision yourself wanting to do with this new template system?  With the ability to embed Delphi code right into the template, what functions and variables would you like Castalia to provide that will make the templates work for you?  How can this be made to work best for you?