Commenting out nodes

warning

In the previous versions of MPS language authors had to provide their own implementations of the comment-out functionality for their languages. Thus, it may happen that the old language-specific functionality will clash with the new generic functionality of MPS 3.3, especially the keyboard shortcut Ctrl0/ is now taken by the generic comment-out action and will not work for the specific implementations, if they were using this keyboard shortcut before. It is advisable for the language authors to:

1. choose a different key combination to trigger the specific comment out/uncomment functionality

2. deprecate the custom comment-out functionality

3. customize the generic comment-out functionality

4. provide a migration that automatically replaces usages of the custom comment-out functionality with the generic one

5. eventually remove the custom comment-out functionality

A semi-automated migration process is available in MPS 3.3 to help you migrate painlessly. Check out the Migrating away from your custom commenting out functionality section below.

You can select any node in MPS, except roots, and press Ctrl0/. That node will be commented out. Lets watch some examples:

The node that you select or point the cursor at will get commented out. Every single non-root node can be commented out - irrespective of whether it occupies a whole line, several lines, or whether it is nested deeply in an expression-like hierarchy.

If you comment out a node, it will be physically removed from its place in the model. If the commented-out node occupied a requested child link, an empty cell is provided so that the user can fill in a new child value.

In BaseLanguage, for example, this gives you possibilities beyond what the Java parsers allows. You can comment out an IfStatements condition:

a method parameter:

or a variable type:

To give another example, the editor definition language allows you to comment out an editor cell, for example:

tip

To uncomment a commented-out node you press Ctrl0/ while positioned on it.

The comment and uncomment actions have some intelligence in them in order to decide, which node to comment/uncomment.

• if a node or a set of nodes is selected, this node/nodes will be commented out/uncommented

• if no node is selected, the editor attempts to comment out/uncomment the current "line" - to achieve this a search starts in the node under caret to identify the closest ancestor vertical collection and an ancestor of the node under caret that is a member of this vertical collection will be commented out/uncommented

tip

You may get finer-grained control over the mechanism of detecting the ancestor line of the node under caret - simply define a handler for the COMMENT action on a collection of cells as follows:

When a node is commented out, it is placed as a child (wrapped) in a special child attribute, called BaseCommentAttribute. Then the instance of this attribute is attached to the commented nodes link in the former parent of the commented node. A ChildAttribute is same as the LinkAttribute concept, except that ChildAttribute gets attached to aggregation links. So the commented nodes are not stored as the usual children, and they won't appear normal queries for child roles. Also, the node.children operation ignores commented-out nodes. Use node.childrenAndChildAttributes<role> to collect children from comments as well. The node.descendants operation currently returns the commented-out nodes, which may change in the future version of MPS to make it consistent with the node.children operation.

The MPS editor knows about comments and it will draw children as well as the commented-out nodes, in this role.

tip

The BaseCommentAttribute annotation comes from jetbrains.mps.lang.core, so this language needs to be listed among used languages in models that contain commented-out nodes.

The smodel language gives you options to query for the commented nodes. You use the same syntax that works for any attributes, only that the comment attribute allows for parametrization by the containment link. For example, if a node has a child collection named commands, querying whether any of the commands children has been commented out might look like:

node.@comment<commands>.isNotEmpty

By default every commented node is drawn surrounded by /* */. You can override the visual appearance of a commented-out node by defining a custom commented editor for the concept. Just define the usual editor with the hint comment:

tip

For the comment hint to be available, your editor model needs to import the jetbrains.mps.lang.core.editor model.

The style of the editor should be changed so that the user can easily visually distinguish commented code.

You can either re-use the pre-defined Comment style, which uses a gray color with italics style, or you may create your own style for commented-out nodes.

Note: The children of the commented node should be drawn with their usual editor so you need to remove the comment hint in child cells:

The next applicable editor cell gives you a more convenient way to customize the look of commented-out nodes - you may address several concepts in a hierarchy with a single customized comment editor.

The next applicable editor cell simply removes the comment hint and redirects the request to find the original editor of the concept (IfStatement). This avoids the need for repetition of the editor definition. You may further simplify the task, if you define a single editor bound to the comment hint for a common super-concept - this way all subconcepts will get the customized comment editor.

The CommentUtil class from jetbrains.mps.editor.runtime can be used to comment out and uncomment nodes from code, such as actions, intentions or key maps. This gives you options to further customize the behavior of commented-out nodes.

The CellAction_CommentOrUncomment and its inheritors class come from the same package. They give you the way to simply comment the node and restore the selection or uncomment the node if it is currently commented.

The response to the comment/uncomment action can also be customized on the node level. You can set the handler for COMMENT action in the cell's action map:

For example, if we want to prevent the user from commenting out conditions in the robot's Kaja While statement, we attach the above action map to the While editor's cell representing the condition :

Since the COMMENT action is customized it will do what is indicated.

The action will work only if the condition node is selected.

Since we create the CellAction_CommentOrUncommentNode with the node as the parameter, where the node is the While statement, the action will process the While statement:

1) If it is not commented, the action will comment it out.

2) If it is commented out, the action will uncomment it.

Thus the commenting of the condition will be disabled.

MPS can create a Migration for you, provided you indicate, which concepts represent the old custom comments using the IOldCommentAnnotation and IOldCommentContainer. Since there were two typical ways to create custom comments in the past, there need to be two interface:

• IOldCommentAnnotation - should be implemented by the NodeAttribute that indicates a node is commented out, if attributes were used annotate commented-out nodes

• IOldCommentContainer - in case commented nodes were represented by a dedicated concept, such as SingleLineComment, these dedicated concepts should be marked with this concept interface

These marker concept interfaces come from jetbrains.mps.lang.core, so this language needs to extended by your language in order to use them. Once annotated, the generic comment-out functionality will be ceased on the nodes of these concepts in favor of the old custom comment out functionality.

Additionally, the old commenting-out concepts will have warnings reported on them - Old comment container should be migrated or Old comment annotation should be migrated. The quick-fixes for these warnings will create the necessary migrations to convert your old custom commenting-out scheme into the generic one painlessly. Just trigger the quick fixes, check the generated migrations and then migrate your projects.

You may create the migration fully manually. Typically all that your migration needs to do is to find all nodes being commented out in the old custom way, uncomment them and call CommentUtil.comment() on each node to get it commented out in the new way. The CommentUtil class comes from jetbrains.mps.editor.runtime.

The generic comment out functionality marks commented-out nodes with the BaseCommentAttribute annotation that is attached to the parent of the commented-out node, holds the original role of the commented-out node and comes from jetbrains.mps.lang.core, so this language needs to be used in models that contain commented-out nodes. An automatic migration should add such language dependency to all altered models. You may take inspiration from The ReplaceSingleLineCommentsWithGenericComments migration, which migrated SingleLineComment nodes in BaseLanguage: