Perhaps a few words of why I created Click! is in order before we
dive off into seeing how we can use it.
First off, I do not intend for Click! to be the ultimate source code
reformatter. (but it's pretty good!)
Over the years, I have run into so much badly written/formatted
code, which I would tediously reformat line by line just to make it
barely readable, that I decided to create a tool which would
automate _MANY_ of the tasks of turning ugly code into usable code.
What I have found while creating Click! is that the CA-Clipper
language is very robust, and therefore any source code scanner that
is worth anything must also be quite robust. Thanks to many fine
beta testers, I believe that Click! has acheived an excellent
capability of handling extremely diverse code.
I suspect that the optimum use of Click! would be to run it once on
ugly code, and that would be the last time. Once you begin to
customize the look of the code, it would be stupid to run Click!
again and toss it all down the drain.
There is NO WAY to create the ultimate source code reformatter, and
if you just want a good re-indenter, you should not be using Click!.
Use DST.EXE available on The Oasis.
Every programmer has a style all his own. Click! is not an attempt
to be as flexible as every programmer.
Of course, if you like the way that Click! formats source code,
there is no reason why you can't use it everyday on all of your
source code.
So, here are some of the basic rules that Click! runs on today.
0. If you already have carefully formatted code, do not use Click!
Click! is the infantry, not the Green Beret.
1. The line is parsed into it's component parts, like strings,
words, operators and spaces. Words are looked up in the .INI file
and are assigned to either Command, Function or Variable status.
Finally, any word that is followed by a ( is called a Function,
except IF, which is assumed a function until proven to be a
command.
2. The spaces between the elements are thrown away.
Think about this. All previous alignment is down the drain. This
has it's good points and it's bad points.
3. The spaces are put back in with a single space between each
element.
( Note: It would be lovely if we could teach a program to have
artificial intelligence so that it could look around and see that
the lines before it or the several lines following it all have
something in common, and should be lined up to make them pretty
for our eyes. This means that the code is torn apart and put back
together with a single space between each element.)
( Later note: The Aligner was created to overcome this
shortcoming in the main pass. It recognizes sequences of code,
reviews them as a unit and performs alignments based on the unit
of code. I found this was impossible to do in the main pass,
which we are talking about here... )
Once the line is reassembled, I do a few things that can make it
look better.
The fallback modes are:
a) If I can't figure out how to indent something on a continued
line, it defaults to DEFAULT_INDENT (defaults to 8) spaces
indent for the rest of the continuation.
b) Spaces are removed in certain places. Spaces are removed
before commas, before and after : and => and \, before ( in
certain circumstances, after @ and ! unless it is the first
element of a line, always after ::, etc.
4. Multi command lines are broken up into their components to make
it obvious where control structures lie.
This means that...
for x := 1 to 10; qqout( x ); next
...will become...
for x := 1 to 10
qqout( x )
next
Some of you are really not going to like this, but please feel
free to write your own if you can do it better. I'll toss mine
and use yours. ;)
It makes it ever so much easier to understand code when it has
been broken up this way, and the compiler certainly doesn't care.
Furthermore, this allows Click! to indent mysterious code easily.
5. If there is a = in the second position, it becomes :=. Same with
for/next. The = will become a := .
This will not happen if you run Click! in S87 mode.
6. There is some elaborate code in there to figure out whether an IF
is a command or a function. This is perhaps the most difficult
part of the code. I have tried this about twenty or thirty
different ways.
Here is the rule today: (which seems to work pretty reliably on
plain clipper code)
If there is an IF followed by a parenthesis, begin going through
the operator parts of the line. Count up one for each open paren
and down one for each close paren. If the paren count is at 1 and
you find a comma that is not inside a string, the IF is a
function. If the paren count goes above 1 and then reaches 0,
stop looking.
Any other occurance of IF is a command.
If any of you have a better way, please feel free to elaborate.
7. Reindenting takes place along the way, and is a byproduct of what
Click! is doing. The real thrust is to straighten up the actual
code into some type of regularity.
In general, if there is something that you don't like about
Click! that is a matter of style, it is probably not something
easy to do. I will work on it, and will take your suggestions.
Currently, there is little or no support for OO code.
8. There are no guarantees that any output of Click! will compile,
so of course, the first thing you MUST do is create a backup or
even more preferably, work in a junk directory, so that any
valuable code is not touched in any way.
9. Click! creates a log if there is a structure underflow or
overflow. The log file name is definable in the .INI file and
defaults to CLICK.LOG.
You can use it to help report things that went badly, since it
will point you to the end of the function that failed. You will
have to manually compare the input and output to see where the
actual problem occurred.
If you find some code that breaks Click!, please condense the
code to the smallest reproducable chunk. Then, email me with that
chunk. I do not need the CLICK.LOG file. That is for you to find
the error with. It will do me no good, and I should be able to
reproduce the error with your code snippet.
10. # commands which cover more than a single line are written 'as
is' in the output. No formatting takes place on #defines, etc..
The only exception to this is that the first line, which starts
with the # character, is left justified.
12. CLICK.INI belongs in the same directory as CLICK.EXE. You do not
have to put it in the working directory and if you do, it will
override the one that is in the same directory as CLICK.EXE