CodeRush Templates – What makes them different?

The full version of CodeRush ships with several features not found in the Xpress version.

Simultaneously the most well known and least known about of these features is the CodeRush Template Engine.

So what can a Template do?

Well at it’s core, a template is nothing more than a bunch of text omitted on command.

Yup that’s it. :)

Type some characters hit <space> (the default template expansion key) and a whole slew of text is thrown into your editor as if you typed it yourself.

I know what you’re thinking….

You’re thinking … “but my clipboard can do that. What’s so special?”

Well you’re right… your clipboard can do that, but it has some comparative limitations.

For example:

• Your standard windows clipboard can carry, at most, 1 set of text for pasting.
• Visual studio has an enhanced clipboard which can carry about 20, but it does this in a way which forces you to have to cycle (Using that most painful of keycombos CTRL+Shift+V) through this ‘ring’ of clipped items until you’re, frankly, lucky enough to stumble upon the one you were looking for.  Your <deity of choice> help you if you happen to hit this key combo 1 time too many. (Round the cycle you go again)

So what does the template system do which makes it anything other than a glorified clipboard?

Well the Template system quite a few advantages.

• Context Sensitivity:
• You can learn a single template and use it in differing circumstances to produce subtly different effects.
• Templates expand differently or not at all based on the context at the time of expansion.
• Mnemonics Naming:
• The template names are designed to be easy to remember and/or calculate.
• Some Templates are Generic/Dynamic:
• Dynamic Templates are those whose trigger is not defined entirely by their name, but have some external component.
• The system of mnemonic naming, reduces the amount of learning to a bare minimum.
• Language Agnostic
• The vast majority of VB.Net and C# templates have counterparts in the opposing language which generates the equivalent code in that language. So once you are used to using CodeRush, switching languages is even less of an issue.
• The CodeRush Template library is vast:
• VB.Net has more than 920.
• C#has more than 940.
• Another 150+ dedicated to xaml, xml and html.
• These figures don’t take into account the multiplier effect caused by some of those being Dynamic/Generic. for example, each template referencing the ?Type? dynamic list, is some 70 times more useful, than if it did not.
• Templates have Links, Fields, Markers, Targets, Selection definitions and many other Text Commands and String Providers with which to augment the template they are embedded.
• The template system is extensible.
• You can create as many new templates as you like.
• You can customize your templates with Text Commands and String Providers.
• You can write your own custom Text Commands and String Providers in and .Net language.

Ok… So that’s something of a bulleted list… Let’s dig a little deeper…

Digging Deeper

Mnemonic Naming

A mnemonic is an aid to memory. Each character in the name (aka the trigger) of a CodeRush Template, represents a part of what it is going to generate. It represents what will happen when the template expands.

Lets take a simple example… ‘Variables’:

If you want to declare a variable of type ‘string’, you type vs<space>
If you want to declare a variable or type ‘double’, you type vd<space>
If you want to declare a variable of type ‘date’, you type vd8<space>

See the pattern? A similar logic works for properties:

If you want to declare a property of type ‘string’ you type ps<space>
If you want to declare a property of type ‘double’ you type pd<space>
If you want to declare a property of type ‘date’ you type pd8<space>

For readonly Properties…

If you want to declare a readonly property of type ‘string’ you type rs<space>
If you want to declare a readonly property of type ‘double’ you type rd<space>
If you want to declare a readonly property of type ‘date’ you type rd8<space>

A property of type string is ps<space>
A readonly property of type string is rs<space>
A method returning a string is ms<space>

Other mnemonic devices are at play all over the CodeRush Template library.

Context Sensitivity

As previously discussed, vs<space> expands to form a declaration of a variable of type ‘string’.

What hasn’t been show so far, is that, dependant on where this expansion occurs, several different expansions might occur.

• If the caret (flashy vertical bar indicating where text is inserted) is positioned inside a class or structure, the expansion should declare a private field of type string.
• If the caret is instead within a method, the declaration will be a local (changing structure and keywords, where appropriate in the case of say… VB.Net).
• If the caret is within the brackets representing the signature of a method, then the expansion is appropriate to declare a parameter.

Similarly r<space> will create a readonly property with backing store of type Object, if expanded within a class.
However, if expanded within a method, it will yield the return keyword.

There are roughly 190 contexts shipping with CodeRush which can potentially be true or false. This allows it to have a pretty good idea of whether or not a given template is appropriate for your current situation.

CodeRush uses this information to streamline it’s operation, eliminating vast swaths of templates from consideration when they are simply not appropriate. Because of this, we *could* arrange to use a valid keyword, such as ‘switch’ or ‘select’, outside of it’s normal context allowing it to trigger a template expansion whilst leaving it inert, in it’s natural context so as not to disturb the natural flow of the developer.

Text Commands and String Providers

As you will no doubt have realised whilst expanding some of those previous examples, templates are not just static text.

Text Commands and String Providers are another example of how CodeRush Templates are a step above the available alternatives.

String Providers are akin to functions which return strings, in that they generate string values based upon some logic, which are then injected into the templates at the point from which they are called.

You can have a template which inserts the current date, time or username into a header string. They can also be used to inject the name of the current method, class, project etc.

One interesting use of a String Provider is to inject a value previously saved to a location in memory by another String Provider or Text Command. This has the effect of allowing 1 template to pass parameters to another. Also it means that a useful part of 1 template can be extracted and made available to be called by several other templates. This makes the library as a whole more efficient.

Text Commands are subtly different, they are closer to void procs (or Subs for those who use VB.Net like myself). They emit no text into the template they are placed within, but they can perform other tasks. Text Commands are used to Add References to your project, position the caret, indicate a selection, turn text into a field or link and many more things besides.

Links, Fields, Markers, Targets, BlockAnchors and Caret

These are some of the more common Text Commands you might find in CodeRush Templates.

• Fields are used to wrap discrete sections of the output for further customization after expansion.
• Links and TypeLinks are used to link sections of output together so that post-expansion customizations affect each linked area in the same way.
• Markers (both hard and soft) can be added to the code to allow you to revisit a section of output and at a later time.
• A caret (with an optional BlockAnchor) can be used to set the initial position (and selection) post-expansion.
• …and a target can be used to set the final destination of the caret once all fields are filled.

Generic/Dynamic Templates

Some templates are defined a little differently to others. Dynamic (Sometimes called Generic) templates are defined such that their name (or trigger) is not hard coded as a single sequence. In fact it may surprise you to know that the templates we have been using up until now are just such templates.

The template vs<space> is not actually named vs. Instead it is named v?Type?. This is an indication to the template system, that it may use any mnemonic from a Dynamic List called Type (stored else where in the CodeRush settings) in place of the ?Type?. This particular list is provided by CodeRush and happens to contain approximately 70 different .Net types.

What this effectively means is that any template that happens to allow the use of the ?Type? list, can have it’s effective usages multiplied by 70. That’s quite the effect for a couple of lines of template.

Some Templates use dynamic lists more than once in their name, which causes their potential combination of uses to skyrocket. you may never use many of these, but it’s good to know the flexibility is there if you need it.

Extensibility

All templates that come with CodeRush are editable. You can customize them to your liking, or you can create entirely new templates using the same techniques as those who created this extensive library.

Further you can create entirely new Text Commands and String Providers for use in your templates as well as other features. Each is simply a component dropped on the design surface of a plugin and given appropriate code in it’s Execute or GetString methods. additionally you can create your own Dynamic Lists to hook your own templates up to.

What next…?

In a future post I will give some examples of Templates to be found in this vast library and show you how to use them to good effect. Additionally I’ll show you how to use some of the techniques described here to formulate your own templates.

----------------------------------------------------------------------------------------
Blatant Advert: Why not swing by the DevExpress Facebook page. You know you want to :)
----------------------------------------------------------------------------------------