MatchTool

Epic Prolog

While working on this project I felt myself as a true software archeologist. I was dusting the walls of an old pyramid to uncover the knowledge of the past civilizations and understand why this structure was built in a place with such unstable weather conditions. My attention was caught by an odd square shape that was different from the other carvings on the wall. I pushed it, and the square collapsed into the wall. Something clicked and a big section of the wall moved away revealing a well-ventilated hallway lit with artificial light. I followed the hallway and entered a large chamber with an absolutely astonishing levitating sphere in the middle. Over some time I learned that the sphere is an ancient artifact that can control the weather. However it was very complicated to operate, so I spent the rest of my time adding handles, indicators, and other helpers that aid in the usage of the artifact. Nowadays we can use the power of the weather sphere to mitigate droughts in the desert areas or flooding caused by heavy rains.

Introduction

Have you ever looked at the code of RBParseTreeLintRule or RBTransformationRule subclasses? The main logic of these rules looks at least like this:

And I bet you don't have a clue what this line stands for:

'`@i to: `@j do: [:`e | | `@temps | `@.Stmts. `x := `x + 1. `@.Stmts2]'

That purple string with smalltalkish code and some weird characters is definitely hard to read and understand. Or even if you figure out what this "should" do, how do you see what is actually detected by this rule? You can use CriticBrowser to run the rule on some packages and see violations. But this rule in particular has 4 pattern expressions, and what if one of them is not working? How would you investigate the issue? Remove the other 3 patterns, simplify the one that is not working and run the CriticBrowser again? That's such a huge feedback loop. And in the end, how do you know what are these magical backticks and at signs? You Google it? You ask on a mailing list and people give you links to a Lukas Renggli blogpost? Lukas did an amazing job here and there, but searching for blog posts to understand how to use a powerful framework that comes pre-packaged with your image… not cool. This is why I've built the MatchTool:

MatchTool

Behold of the tool that had to be in the image for 10 years already :).

The tool can be loaded from the catalog for Pharo 6, and launched from the World Menu > Tools section.

The key idea of MatchTool is to increase understanding of pattern code. So if you look at the Pattern code area at the upper left part of the tool you will see the same expression that we mentioned before, but not as a purple string anymore. MatchTool has a text area that properly highlights pattern code, underlining special pattern nodes so it is easier to see them. This code highlighting feature required plenty of effort to implement. But because the default highlighting is based on the RefactoringBrowser AST, I was able to reuse all the parsing/visiting features.

Once you have your pattern code entered, move to the Test code area below the pattern code. This area expects a normal Smalltalk code that will be matched against the pattern expression. In the example screenshot, I've entered an example code that I've invented myself, but you can simply copy a part of a real method. You can even paste there a complete method, just select the "Method" checkbox (same applies to the pattern code).

The main magic happens when you press the Match button (which has a handy cmd + enter or ctrl + enter shortcut depending on your platform). The tool will scan all the Test code and try to match each part of it with the pattern code. The results will be displayed under the match button as a list. Selecting an item from the result list will highlight the matched interval in the Test code area, and display the mapped nodes in the rightmost list. Now you can be completely sure what `e or `@.Stmts were mapped to in that case.

Finally, you may want to write your own pattern code, but you do not know what is the meaning of all the strange characters. Click the button with the question mark next to the Match button and enjoy a help book dedicated to MatchTool and pattern code.

The Spec Tutorial Video

Yes, I am the one complaining about Spec all the time, so I've decided to build MatchTool with Spec. And also to make a tutorial video about how to do that. At the moment there is only a first part of the tutorial with the basic functionality, so please comment on whether this video makes sense and if I should continue.

Epilog

I came across the pattern code while working on improving quality rules. From time to time I needed a bit more functionality than the standard rules provide. Each time I tried to go deeper to add the desired functionality, I discovered that it is more or less already there, just hidden behind a very cryptic API of the top layers. Finally, I have arrived at the point where I uncover the gems from low layers and put them into new and useful sockets, so we can prosper from the power that we had for such a long time.