Reference

File List

Before Vahunz can be invoked at all, the file has to be created. Unless otherwise specified (by means of --base-name), it is called vahunz.files.

In this file, every line represents one file to be scanned. The filenames can also contain relative pathnames. That means, sepp.c and hugo/sepp.c are both allowed. But resi:sepp.c will most likely cause problems when the output should be written.

list >vahunz.files lformat=%p%n (#?.c|#?.h)

Command Line Options

There are a few command line options available. This is a short description of them. Most are used to influence the output or to change the source for getting the file list etc.

All options have a long and a short form causing the same effect. There exist both flags (like --comment) and options requiring an additional argument (like --output). You can not concatenate several flags, therefore instead of -ci you will have to specify -c -i. Option names are case sensitive.

--help, -h

If this flag is enabled, Vahunz will only display a short message about usage and possible command line options, and exit immediately.

--base-name, -b

Base name for supporting files. The respective extensions .files and .names will be appended automatically to this name.

The default is vahunz, which will expect the file list in vahunz.files and the dictionary in vahunz.names.

Example: --base-name vahunz-sepp would use vahunz-sepp.files and vahunz-sepp.names instead.

--comment, -c

--indent, -i

Preserve indention in output.

Normally redundant white space is reduced to a single blank or linefeed. With this option you can oppress this.

--line, -l

Preserve line numbers in output.

Different to --indent, multiple linefeeds will not be reduced to a single one. Blanks and formfeeds still will.

/* this is a
 * multi-line
 * comment */

This option can be useful for tracing back problems during compilation of the vahunzed sources, as line numbers shown in compiler error messages are the same as in the original sources.

--name-length, -n

Vahunz does not take very short names into account when collecting the list of all names from the source files. By default, a name must consist of at least three letters to be considered worth vahunzing.

If you specify

--name-length=1

even names having only one single character show up in the dictionaries.

However, single letters like c and h might be stored in the dignorary automatically, as they are used for suffices and must not be vahunzed because this could break #includes and similar stuff.

Therefor using values smaller than the defaulting three is not really recommended. You better use longer and more meaningful names instead, so they will be vahunzed.

--no-unused, -u

When you use one of the provided dignorary, it is very common that is contains several names that never show up in your source code. Still, they have to be read and updated during every vahunzation. This can significantly slow down the whole process, especially for small source code with only a few files.

If you enable this switch, all unused names will be remove from the dictionary when Vahunz rewrites them the next time.

--no-warning, -w

Do not display warnings.

Warnings are usually caused by redefined names in the dictionaries, or an unknown vahunz mode in the first column of a line. These problems will cause the responsible line to be removed from the dictionary when it is updated after the first pass.

This option has no effect on this behavior, the only difference is that with --no-warning these actions are performed in silence.

--output, -o

The output directory for the vahunzed files. If it does not already exist, it will be created, and also further recursive sub-directories. Of course, the device itself has to exist.

The default is t:, which will normally cause the output files to vanish after a reset.

If the directory specified does not end with a slash (/) or colon (:), a slash will be appended automatically when creating derived output filenames.

Specifying the current directory as output directory will result in an error message. However, this check is not very smart, and can be undermined in several ways. For example, you can do an

assign current_directory: ""

and use current_directory: as argument for --output. This will result in an attempt to overwrite the original source.

--prefix-file, -p

Specifies the name of a file that contains a text that should be used as beginning for all vahunzed files. This text is written `as is' without being vahunzed, that means also comments are preserved in any case.

A common use for this is to create a copyright header. For example, you could have the following text in copyright.c:

/* This source code is part of MyTool Copyright (C) 1998 by Me.
 * All rights reserved. */

Then then use --prefix-file=copyright.c. Note that copyright.c does not have to be part of vahunz.files, as it is not vahunzed. And you do not have to include it from every source file by means of #include "copyright.c" or something similar, as it is written by Vahunz.

--quiet, -q

Shut up - do not display header message, do not show which file is currently processed and all the other things. Error messages will still show up.

--random-seed, -r

Specify random seed used for generation of vahunzed names. If this is omitted, the current time will be used.

This option can be useful if you want to trace back problems during compilation of vahunzed sources.

Example: --random-seed=17

--store, -s

With this option enabled the vahunzed names will be written to the dictionary. This can be useful for fixing problems in the vahunzed sources.

Example: If a name print_record is vahunzed with u73, the dictionary will contain a line

+print_record=u73

This value, here u73, is only valid until the next vahunzation.

--vahunz-length, -v

Normally, Vahunz tries to create as short vahunzed names as possible, but at least three characters long. With this option, you can specify a bigger lower limit, for example:

--vahunz-length=17

will result in names having at least 17 characters. This can make your source code look even more terrifyingly unlegible.

As drawback, the vahunzed source code will use more space, and the whole vahunzation takes more time and memory because strings and their comparisons are more complex.

Dictionaries

There are two dictionaries. By the default, they are named vahunz.names and vahunz.ignore. The later one is also referred to as dignorary. Every line in the dictionary represent exactly one name extracted from the source files.

The first character in every line tells what to do with this name. It represents the vahunz mode. Valid modes are:

Remain/Replace: blank (' ')

Names in this mode will remain in the same in the output. This mode is the default for all names when the dictionary is created, except for the names found in the file list. These will be set to be ignored (see below).

Optionally you can specify an equal sign (=) at the end of the name, followed the name the original should be replaced with. This is usually used to increase the readability and consistency of a program.

Blanks after or before the equal sign are not allowed.

Ignore: hyphen (-)

Tells that the name should be put into the dignorary. It will be treated the same as it would have been marked with a blank. However, it is stored in a separate file, therefore the user will not see it all the time when viewing the dictionary, which contains only the names of interest.

This mode is usually used for names of system libraries.

Vahunz: plus sign (+)

Such names are marked to be vahunzed in the output. Therefore it will be replaced by a random sequence of characters.

If the command line option --store has been specified for the last invocation of Vahunz, every such line will also contain an equal sign, followed by the random name used in the recent vahunzed version of the program. When reading the dictionary the next time, the text after the = will be ignored. To produce the same random names again, use the command line option --random-seed.

New: asterisk (*)

If a name was not already part of the dictionary, it will be added automatically with the first column set to an asterisk. This allows the user to scan the dictionary from time to time for occurrences of this character, and then decide what to do about a new name. Concerning everything else, such names are treated the same as in remain/replace mode.

Unknown modes will cause a warning message, and the line will be ignored.

Although the dictionaries are always written in an alphabetically sorted way, they do not need to be sorted when they are read.

All dictionaries can contain names in every possible mode. For example a name in remain/replace mode can also be stored in the dignorary. However, if the dictionaries are rewritten at the end of the vahunzation, the dignorary will entirely consist of names in ignore mode.