VitTransform 2.0.0 - a safe, format-preserving code transformer for Clarion

VitTransform 2.0.0 is out - free and open source under the MIT License.

I mentioned with the release of version one of VitTransform (VT1) that it had been seven years in the making. Now here we are only a few MONTHS later with VT2. That, of course, can in significant part be attributed to the changes we are going through with AI.

It would be more accurate to say "Claude wrote the version 2 changes at my direction" rather than "I coded them myself". It is a change many/most programmers are currently going through.

So what does VT2 do above and beyond VT1? The simple answer would be "more of the same". It has got bigger and better - more transformation rules and builtins and various fixes for bugs or obscure "gotchas".

What it does

VitTransform reads your Clarion .clw and .inc files, makes the changes its rules allow, and writes the results to a separate folder - your originals are never touched. Your comments, blank lines and indentation are kept - trailing comments are only lined up into a column, which you can switch off - and every run writes a report of what it changed, what it refused, and why.

Its guiding rule is when in doubt, do nothing. If it cannot prove a change is safe, it leaves the code alone. And code it can show is never used - a variable, a routine, a value stored and never read, code that can never run - is not deleted: it is commented out, with a note saying why.

A taste

  if lower(cmd) = 'fold' or lower(cmd) = 'trimr'
    DoFold()
  elsif lower(cmd) = 'clip'
    DoClip()
  end
  st.setValue(st.getValue() & w, st:clip)

becomes

  case lower(cmd)
  of 'fold' orof 'trimr'
    DoFold()
  of 'clip'
    DoClip()
  end
  st.append(w)
  st.clip()

lower(cmd) is now worked out once instead of once per test, and the StringTheory call says what it does.

What's new in 2.0

  • Styles. plain makes the safe tidy-ups only. optimised - the new default - adds the faster spellings that read just as easily. extreme goes further, and readable goes the other way, to the longer explicit forms.
  • IF chains become CASE, range tests like c < '0' or c > '9' included. A comment on an IF line comes along.
  • StringTheory code tidied. Common patterns take their shorter equivalent: a one-character search becomes a byte search, a scratch copy that is only read is dropped, a loop over a split's lines becomes one call, and more. Each fires only where the tool can prove the result is the same.
  • Unused code commented out, not deleted - a value stored and never read, a statement nothing can reach, a routine nothing calls.
  • Comments lined up in a column. Every choice in that is a switch, so you can keep your own house style.
  • It reads your INCLUDE files to work out what your objects are.
  • Turn off anything - a whole group, a style, or a single rule by name.
  • Write your own rules in a plain text file - no Clarion code needed.

Bruce at CapeSoft kindly incorporated my recent changes to StringTheory that allowed me to include more VT transformations so make sure you get the latest ST version (3.90 or above).

And there are numerous new switches - they are all documented in the readme. For example the alignment of comments turns out to be way more complex than you would imagine so I have exposed all the internal choices as switches so you can do it your own way if you have a preferred "house style".

By the numbers

1.0 2.0
Rules 449 522
Built-in transforms 26 60
Groups 35 67

A rule is a pattern and what to write instead. A built-in transform is a change the tool makes with code of its own, because a pattern cannot see enough - it has to read a whole procedure, or prove something first. A group is a set of them switched on or off together.

In lines of source, VT2 is a little over double the size of VT1 - 34,315 lines across its 18 source files to 71,539 - and the largest class - VitEngine - has roughly tripled in size.

VitStyle

The companion program VitStyle allows you to instantly see the changes different settings make with a before/after comparison and when you get it "just right" you can save that as a profile for future VT runs.

Tested on real code

It is particularly good with code bases that have extensive use of StringTheory, but is still useful with older-style Clarion code. Before release it was run over its own source and two other large Clarion code bases. The transformed programs were rebuilt and their results checked against the originals'. Having said that, I still always recommend you diff the output and do your own testing before adopting the updated code.

Getting it

Both programs are ready to run. The full source is included; building it needs CapeSoft's StringTheory 3.90 or later.

Project and README: GitHub - Geoff-Robinson/VitTransform: A general-purpose, rule-driven source-to-source transformer for Clarion. · GitHub

Download: Release VitTransform 2.0.0 · Geoff-Robinson/VitTransform · GitHub

The README covers everything, with a quick start and an FAQ. Questions and issues welcome - here or on GitHub.

Cheers,
Geoff R

5 Likes