CodeRush – Common TextCommands

TextCommands

Compared to StringProviders, TextCommands are rather more complicated to explain. This is because they are used for a more diverse set of tasks.

To this end I will explain several of the more commonly used TextCommands and show you exactly how they are used.

They don’t inject text in the location they occupy. Instead their location is typically used as a reference for some other sort of operation.

As always, we’ll start of simply.

«Caret» and «BlockAnchor»

The «Caret» TextCommand is exactly what it sounds like. It indicates where your Caret (The blinky thing, that emits text when you type) will be placed after your template has been expanded.

The «BlockAnchor» TextCommand is an optional counterpart to the «Caret». If used together, text placed between them will be selected once the template has expanded.

So if you wanted to write a simple C# class template with no constructor you could do so using the following text:

This would emit the basic text and would select the phrase “DefaultClassName”

Markers

You can enhance the template above with the use of a «Marker» TextCommand. We’ll leave a full description of markers until another time, suffice to say that a marker is like a breadcrumb. You (or indeed templates and other features) can leave a trail of them, and then later you can jump back to the most recent one, and pick it up by pressing Esc.

Thus if we amend our previous template like so…

… then the template will emit a small blue triangle called a Marker. When we expand the Template, and overtype the selected area, we can then hit Esc and the caret will jump down to the indicated area and ‘collect’ the Marker.

It’s worth noting that this basic (blue) marker will also disappear if the line it’s on is altered. If you’d like to produce one that does not disappear under these circumstances, than you should use the alternative «HardMarker» TextCommand. This type of Marker will only disappear if it is ‘collected’.

Links

The «Link» TextCommand is used in groups of 2 or more, to connect identical pieces of text to each other, and to keep them the same if one of them is edited.

The classical example of this, is seen through the C# version of the c<space> template.

The creators of C# took the decision that constructors should be named after classes they exist within. So if you create a C# class called MyVerySpecialClassWhichDoesSomethingVeryClever, then you have to use this (rather lengthy) name for any constructors that you create. The downside of this, is that you’ll have to do a lot more typing than if you were able to use a simple keyword for the same task.

By using a couple of «Link» TextCommands, we can link the name of the class to that of the constructor, ensuring that the actual naming need only be done once.

In this manner, the class name and the constructor name are linked together at the moment of expansion, and as one changes, so will the other.

A Link TextCommand links itself to all other Links that contain the same text. This allows the creator of the template, to link several pieces of text together.

The user may also navigate between linked items through the use of either Tab or Shift+Tab.

Check out this template for creating properties (of the non auto-implemented variety)

It links together 4 separate instances of the phrase “MyVariable”. When one is altered, all are altered. This enables the property, it’s underlying field and the 2 references to the field, to be renamed as a unit.

I think you’ll agree that this is very useful indeed.

Other Types of Link

The «Link» TextCommand accepts only characters that are valid in an identifier. ie alphanumeric characters or an underscore (‘_’).  If you wish to create links which allow additional characters within them, consider the use of either a «TypeLink» or a «TextLink».

A «TypeLink» can accept any character which is deemed valid as a part of a Type, therefore it will also accept periods ('.'), commas (','), spaces, angle brackets ('<>') in C#, square brackets ('[]') in C# and parentheses ('()') in VB.

Finally, the least restrictive of the link types is the «TextLink». If you require the user of your Template to be able to type characters not listed above, then you should consider using a «TextLink» TextCommand instead.

So far we’ve shown Templates which highlight some of their emitted text, and allow the user to make amendments to it. Further we have shown how bits of text can be linked together so that alterations to one, will affect others.

These links can be very useful, but what if we want the user to be able to make several such edits once the expansion of the template has occurred? Well you can place as many sets of links within a Template as you like, but your user will have to navigate between them on their own. By themselves, links provide no method for navigation to other link sets.

However we do have fields….

Fields

Each «Field» TextCommand in a Template represents a distinct point of data entry. Upon expansion, the caret is deposited, in the first «Field» and as usual the user is free to modify the resulting text or indeed move elsewhere. If the user hits enter whilst the caret within a field, the field will be accepted, will disappear and the caret will jump to the next field.

A simple example of the use of fields is the following template designed for creating auto-implemented properties.

The first field is positioned to allow the user to indicate the Type of the property. The second is to allow for the Name.

If the example given doesn’t seem so useful, consider the following custom Template, used in the creation of my own CodeRush plugins.

When expanded this Template provides the following output:

In this example we see a few techniques being used together. We have 3 fields, one of which is linked to 8 separate other locations via links. At this stage, you may or may not know much about plugin creation, but you can clearly see that there’s a whole lot of typing to be saved using this template. As for the previously unmentioned «FieldStart» and «FieldEnd», these are simply another form of the «Field» TextCommand.

So why do we need another form of the «Field» TextCommand? Well it’s for times like the one demonstrated, when you need to wrap other TextCommands in a field. If you recall, TextCommands don’t return a result in the same way as StringProviders do, and the standard Field TextCommand requires a parameter. The «FieldStart» and «FieldEnd» TextCommands do not require such a parameter, instead acquiring the data they need from the text rendered between them.

The last Template in this group is «FinalTarget». This TextCommand works within the context of a template already using 1 or more fields. It acts as the final field in a sequence. The difference being, that it is a point rather than a range and it requires no parameter. Use this TextCommand to indicate where the caret should jump to when all fields have been filled.

And Finally

The last 2 TextCommands I’d like to mention in this post are «AddAssemblyReference» and «AddNamespace». They perform pretty much as you’d expect, acting on the periphery of any function they supplement.

«AddAssemblyReference» takes a single parameter which indicates the name of the reference to add. This results in no direct changes to the active TextDocument, but as you might imagine, the project to which it is attached receives a minor alteration adding a reference to the passed assembly.

«AddNamespace» likewise takes a single parameter. This time indicating a single namespace which should be referenced by this file via an “Imports” or “Using” directive as appropriate. Said directive is added at the top of the file.

..and that about wraps it up for this post.

We’ve covered the ins and outs of 13 separate TextCommands. That’s a little over 20% of the 61 TextCommands in my copy of CodeRush. As before this should be enough to get your feet wet, and also help you to understand a much larger quantity of the shipping templates that use them.

Free DevExpress Products - Get Your Copy Today