XREF -- A simple language independent cross-reference utility
=============================================================

XREF is a cross-referencer that attempts independence of the target
language through use of syntax configuration files to establish such
parameters as commenting conventions and reserved keywords and operator
tokens used in the target language.

XREF will handle multiple input files (wildcards may also be specified)
and will produce on standard output the cross-reference listing for all
identifiers not specified as reserved words in the configuration. Each
identifier is listed in lexicographic order along with its line number
references for each input file in which it occurs.

Invocation is simple:

xref [options] filename {filename ...}

where "filename" is an input filename with optional drive/path specifiers
and wildcards.Supported options are:

-lxxxSpecifies target language configuration file xxx.
File extension defaults to .xfg. If option is omitted,

the default configuration of xref.xfg is used.The
file will be loaded from current working directory or
from the path specified by the XREFPATH environment
variable if it has been defined.

-sCauses console messages to be suppressed during operation.
Messages are written to stderr so they are not normally
redirected from console output as is XREF's cross-
reference output.

-wxSpecifies output width of x characters. Default is 80
characters, but must be a minimum of 40.

XREF's output (excluding console messages) is to stdout, so it may be
redirected to a file. The following, for example, generates a cross
reference listing of all C source and header files in the current
directory and sends output to "project.xrf":

xref -lc *.c *.h > project.xrf

Note that the default configuration xref.xfg as supplied is identical to
the ANSI C configuration c.xfg so the -lc option could be omitted.

The Configuration File
======================

XREF achieves its independence of the input file target language by loading
a syntax configuration file on initialization.This is an ASCII file having
the extension .XFG that may be created with any text editor or word processor
capable of plain ASCII output, and has the following format:

# This is a comment line. Anything after the first '#' is ignored.
# Note that a space must follow the initial '#'.
-- See below for legal directives
.tokens -- this must be the LAST directive
token-list-- which may span multiple lines

The supported directives are:

.casesensitiveSpecifies that tokens in the target
language are case sensitive. Use this
directive for ANSI C or Modula-2, for
example. The default is FALSE.

.comment Specifies tokens that begin and end a
comment that is embedded in the input text.
Any text between and will be
ignored. The comment block may span multiple
lines if necessary. An example (for ANSI C)
would be .comment /* */

.escapechar cSpecifies character c is used as an 'escape'
character in the target language -- i.e. when
it occurs in the input text, the character
following it is given special interpretation.
In C, the '\' is used in this way. In XREF's
context, this escape character and the next
character in the input text will be ignored.

.identchars Specifies what characters (aside from
alphanumeric) are legal for identifiers in
the input text. All non-identifier
characters found will be assumed to be
operators.

.idfield Specifies a field in the input text containing
an embedded identifier to be output in place
of line numbers in the cross-reference
listing (e.g. a "card image number" in some
older-style languages). This field may have
a maximum width of 12 spaces.

.ignoreatbol Specifies that when occurs at the
beginning (e.g. first non-blank position) of
an input line, the remainder of the line is
to be ignored.If is encountered
elsewhere in the line, no special action is
taken.Use this directive to specify, for
example, special usage of '*' in dBASE
dialects, where commented lines begin with
an initial '*'.

.ignoretoeol Specifies that when occurs in an
input line, the remaining text on the line
is to be ignored. This directive may be used
to specify a keyword or symbol that begins
a comment line. For C++ this would be
.ignoretoeol //

.matchlength Specifies that only characters of a
keyword need be specified to match that
keyword in the input text. Note that if a
token in the input text MUST match for its
entire length.For dBASE and its dialects,
for example, only 4 characters of a keyword
are required, so DELETE would be matched by
an occurrence of DELE.

.name Specifies an internal name for the language
configuration.This name will be echoed to
the cross-reference output.

.statementseparator cSpecifies that character c is a "null"
character that separates statements in the
target language. In XREF's context, this
character will be treated just like
whitespace (skipped over when searching for
input tokens).

.tokens This directive must be the last in the
token-listconfiguration.The token list specifies all
symbols that are operators or reserved words
in the target language, and spans all lines
until end of file. Note that if a symbol is
repeated, its second and later occurrences are
ignored. Any symbols added to XREF's keyword
list by this directive are assigned no special
action (unlike symbols specified in earlier
directives); they are simply skipped over in
the input text.

Example target language configurations are included in the distribution for
ANSI C, dBASE III+, Clipper, and Sophco FORCE.

Limitations
===========

Strings are assumed to be bounded by quotes (single ' or double ") -- i.e. if
a string starts with a " it must end with a " (and any occurences of ' within
the string are ignored). This is not implemented as a configurable item; it
is simply assumed for all target languages. Thus XREF would be useless for
cross-referencing human language text.

The PrintTree() function used to write the output recursively performs a
depth-first inorder traversal of the symbol tree. I set _stklen to 16K in
the source which should be sufficiently large for all but the worst possible
cases (very large source files in which cross-referenced symbols "happen" to
occur in sorted order!), and set stack checking on with a #pragma around
PrintTree() (or compile with -N switch for Turbo C 2.0).

I make no claims that XREF uses optimal algorithms. I hacked this program
together over a weekend and made a few refinements because I needed it
quickly!

History
=======

9 Sept 1990v1.1.1 (initial release)

19 Sept 1990v1.1.2
Improved memory efficiency -- symbol buffer allocated in
larger blocks as needed, pointers into symbol pool used for
all symbol references.

=============================

This package is public domain.Use, hack on, and distribute freely. Comments
and suggestions are welcome. I visit Exec-PC regularly (Programming and
Unix forums) and CI$ occasionally (BPROGB, IBMSYS, UNIXFORUM), so I can
be reached on those systems for feedback.

Andy Vitous
Vallejo, CA
CI$ ID: 71620,3353