The next paragraphs will describe how to actually vahunz a little example program consisting of only a few source files. All terms and techniques will be described when they are used first.
For most options, default values will be used, to make the whole process easier to understand. You can set several options to modify the behavior of Vahunz, but they will not be described in the tutorial, but in the reference section later on.
The source files used during this tutorial can be found in vahunz/example. To perform all the steps, you will have to open a CLI and set its current directory to vahunz/example.
In the beginning, the example directory contains four files. Three of them are simple ANSI-C source codes:main()
grow_older(), a function
called by main() in sepp.c
grow_older()
and is included by sepp.c
make. This will not be touched by Vahunz.
First, you do not need to compile the example program to continue with this tutorial.
If you really want to, you will need a make-tool and an ANSI-C
compiler with a cc-like calling-syntax. By default, the makefile is
designed for gcc, but you can easily change the symbol
CC to dcc or whatever, if you like.
Any more details would be out of scope.
The program itself does nothing remarkable: it simulates a guy named Sepp and lets him grow older until he dies. The output will look like:
Sepp grows older. Sepp is 79 years old. Sepp grows older. Sepp is 80 years old. Sepp grows older. Sepp is 81 years old. Sepp grows older. Sepp is 82 years old. Sepp grows older. Sepp is 83 years old. Sepp died.
There are only few variables and functions, and it should be straight forward what is going on, even when you are unfamiliar to C.
First of all, Vahunz needs to know which source files it should touch. By default, it looks for a file named vahunz.files, which will have to contain all filenames relative to the current directory. Each filename has to be in an own line.
In our case, we can easily create this list by typing:list >vahunz.files (#?.c|#?.h) lformat="%p%n"This will create vahunz.files with the following content:
sepp.c older.c older.h
Note that the %p in LFORMAT (for "path")
would not have been necessary in this case, as there are no files
located in any deeper sub-directories. However, it also did not cause
any harm, and you should provide it when creating the file list using
list.
More complex programs than this simple example often reside within
several directories, and then you will need to specify the full path
relative to the current directory. And this is exactly what
%p does.
Of course you can also create the file list manually, but this will usually take longer and is more error prone.
vahunzThe output should look like this:
Vahunz - Make source code un-/more legible. Version 1.2 (14.4.1998), (C) Thomas Aglassinger 1998 using `C' as language reading existing files vahunz.files building dictionaries sepp.c older.c older.h writing dictionaries The dictionary has been written to `vahunz.names' and should be modified now.
Although the program suggest to modify the dictionary right now, we are going to do this a bit later. Therefor, the contents of vahunz.names should look like this:
EXIT_SUCCESS age exit grow_older main name print_sepp printf sepp_age sepp_name stdio stdlib
These are all names Vahunz could find within the source files specified in the file list, omitting language specific keywords and names shorter than three characters - these are considered to be already unlegible.
Note that the first column entirely consist of blanks. Do not touch anything yet.
As the dictionary now exists, Vahunz is ready to transform the
files. With the command line option --output you can specify a
directory where the vahunzed files should end up. If you do not
specify one, t: will be used.
In this tutorial, for some reason it seems convenient to store the vahunzed sources in ram:vahunzed. Therefor enter:
vahunz --output ram:vahunzed
There is no need to create the directory first, as this will be done automatically when the first file is attempted to be written to it.
The interesting part of the output should look like this:updating dictionaries sepp.c older.c older.h building vahunzed dictionary in memory 0 names vahunzed writing dictionaries writing vahunzed files ram:vahunzed (created) ram:vahunzed/sepp.c ram:vahunzed/older.c ram:vahunzed/older.h 3 files vahunzed.
It tells that all source files have been rescanned and the name list has been updated, in case there would have been any new names since the creation. Of course, there weren't any yet, but its good to know that Vahunz takes care of this.
It then states that "0 names vahunzed" which means all
the names are still meaningful. However, if you take a look at for
example ram:vahunzed/sepp.c, you will notice that all the
comments and indention are gone.
To tell Vahunz to replace a meaningful name by some garbage, you
have to mark the first column in vahunz.names with a
"+". Load this file in your editor, and modify it so that
it looks something like this:
EXIT_SUCCESS +age exit +grow_older main +name +print_sepp printf +sepp_age +sepp_name stdio stdlib
Take care that you only change lines with names
you have created, and are not a function or constants
declared somewhere in the standard library, like for example
printf or EXIT_SUCCESS. The same applies to
main and stdio, as for obvious reasons the
program will not compile anymore when these names are garbled.
vahunz --output ram:vahunzedThe output now has changed a bit. Most remarkable, it now tells:
6 names vahunzed
The 6 apparently corresponds to the number of "+" in
vahunz.names. If you now look at ram:vahunzed/sepp.c,
you will see that it looks a bit different as before. For example,
the original main() was:
int main(void)
{
while (sepp_age < 83)
{
/* Simulate one year in the life of Sepp */
grow_older(sepp_name, &sepp_age);
print_sepp();
}
/* Announce the bad news */
printf("\n%s died.\n", sepp_name);
/* World ends here. */
exit(EXIT_SUCCESS);
}
The vahunzed version might look like this:
int main(void)
{
while (s2E < 83)
{
z1I(d6T, &s2E);
r0H();
}
printf("\n%s died.\n", d6T);
exit(EXIT_SUCCESS);
}
The names do not necessarily have to look like this, as they are
created randomly on every invocation. In this case, for example
grow_older has been renamed to z1I.
When creating the names, Vahunz will take care that they do not already exist for another substitute, and are also not used within the names of original source. Usually they will have only three letters, but if there are many names to garble, they can also become longer.
But the best part: you can now copy the Makefile to ram:vahunzed, recompile the program and execute it. You will notice that it still does the same as before.
Maybe you also noticed a files named vahunz.ignore. This one is called dignorary. This strange word is derived from ignore and dictionary, because that's exactly what it is: a dictionary with names to be ignored (or: left untouched) during vahunzation.
Currently, it only consists of two lines-older -sepp
Obviously, these are the names of our input files. Vahunz assumes
that the user does not want them to be replaced, as a possible import
or #include would fail then.
But the main feature is: the user does not see these names when he is browsing the normal dictionary. Load vahunz.names into your editor again, and change it that it looks like this:
-EXIT_SUCCESS +age -exit +grow_older -main +name +print_sepp -printf +sepp_age +sepp_name -stdio -stdliband invoke Vahunz as before:
vahunz --output ram:vahunzedYou will notice that all lines starting with a hyphen (
-) have been moved
to vahunz.ignore, and therefor vahunz.names has become much cleaner.
This finishes the tutorial. You should now know how to utilize with the basic concepts.
Still, there are some things to left, so you can use Vahunz more
efficient: There are some ready dignoraries included in this distribution,
so for example you do not have to mark printf
manually.
There also exist several command line options, with most of them being discussed in the use-cases or the reference section in the later part of the manual.