oocn - The OOC Code Navigator

oocn <mode> [options] <module>...

This document is a subset of corresponding chapter of the OOC Reference Manual. For a more detailed description and examples, the reader is referred to the reference manual (see below).

The tool oocn operates on the source code of Oberon-2 modules to produce various manipulations of the text.

The <mode> argument determines the operation performed by oocn; for example, --html sets the mode to translate to HTML. No more than one mode can be specified at at time.

The <module>... argument is a list of one or more modules, or file names of modules. If it is a file name, the directory part and extension are discarded. Modules are then located by means of the PATHS section of the compiler's initialization file.

--modules, -M

List the names of all modules that are directly or indirectly imported by the given modules (and also list the given modules themselves).

The modules are written in an order defined by the IMPORT relation; that is, module Bar is written before module Foo if Foo depends on Bar. For example, the invocation oocn --module Foo lists the names of all modules that are used to build the program Foo, writing the name of the most basic module first, and Foo last. With option --no-internal, the pseudo module SYSTEM is omitted from the output.

This function implicitly adds the option --closure.

-d

Write the interface of the given modules to stdout. Here the term "interface" means the module's source text stripped of all private declarations and all procedure bodies. Comments in the remaining text are preserved.

--html, -H

Convert the given set of modules to HTML text. For every module Foo, a file <output-dir>/Foo.html is created. The default output directory is the current working directory. The HTML text preserves the format of the source text, but adds colours for keywords, comments, strings, and procedure declarations. Identifiers of exported declaration are set in bold. Hyper-links are inserted from the point of use of an object to its declaration. Note that links to all record fields and type-bound procedures can be inserted only if oocn was called with the option --closure.

--xref, -X

Create cross-reference information for the given set of modules. This mode creates a set of HTML files, just like --html, and adds hyper-links from every declaration into a companion file <output-dir>/Foo_xref.html. The cross-reference file lists all uses of each declaration in the scope of the scanned modules. For a redefining type-bound procedure, it includes a link to the base definition, and for an original type-bound procedure definition, it lists all redefinitions and their uses.

This function implicitly adds the option --closure.

--uses <decl>, -U <decl>

The mode --uses acts as a command line interface to the cross-reference data. That is, it locates all references to the specified object and writes them to stdout in the format of oo2c's error messages. The argument <decl> is a string describing a declared object; the string must be the name of a predefined object, or a module name followed by a (possibly empty) sequence of names, with the names separated by dots.

If the designated object is a type-bound procedure, --uses lists the base definition of the procedure, all of its redefinitions, and all calls to the type-bound procedure in the scope of the inspected modules.

This function implicitly adds the option --closure.

--def-txt, --def-html, --def-xref

Using the specified format, write the interface of the given modules to a file in the current output directory. The output format is either plain text in file Foo_def.txt, HTML text in Foo_def.html, or cross-referenced HTML text in Foo_def.html and Foo_def_xref.html. The output directory can be changed using option -o <dir>.

--def-texi

Create draft version of the public interface of the modules in Texinfo format. The output file is named Foo_def.texi. Unlike the other --def-* variants, the output has little resemblance to the original input text, and it will probably need manual intervention to turn it into something more readable.

--filter, -F

Copy the Oberon-2 source code from the input module Foo.Mod to the file Foo.txt in the output directory, possibly applying some code transformation on the way. All symbols are copied as is, without any change to their textual representation. This includes text in comments, pragmas, and program code in inactive conditional compilation clauses. Outside these special symbols, horizontal tabulators are converted to spaces, using a tabulator width of 8. All trailing whitespace is removed from lines, as are any empty lines at the end of the module.

This mode is usually used in conjunction with one or several of the code transformation options, like --strip-pragmas or --mod2foreign.

-o <dir>

Set the output directory for all commands that write to files. The name - specifies stdout.

-v

Select verbose mode. This writes the names of input and output files to stdout.

--closure, -C

Operate on all modules that are imported, either directly or indirectly, by the modules given on the command line. For some modes, the option --closure is enabled by default.

--no-internal

Omit all pseudo modules that are internal to the compiler from the output of --modules. At the moment, this means that SYSTEM does not appear in the module list.

--line-num

Prepend the line number from the original source file to every line of output. This option affects all commands that produce text or HTML directly from the source code.

--colors <name>

Select color set to use when writing HTML text. Currently available variants: hilit (default) and font-lock.

--strip-comments

Remove all comments from the source text before processing it. Comments starting with (** are not discarded, use option --strip-doc-strings for this.

--strip-doc-strings

Remove all documentation strings, that is, comments starting with (**, from the source text.

--strip-pragmas

Remove all pragmas from the source text. Any program text appearing in inactive conditional compilation clauses is also discarded. The evaluation of the guards of conditional compilation clauses uses the current values of the pragma variables. Therefore, applying this filter reduces the source file to the program text that is actually seen by the compiler when translating the module, assuming that the same settings are used for the pragma variables.

--strip-system-flags

Remove all system flags from the source text. If, for example, a module uses any of the flags that are enabled by OOC_EXTENSIONS, applying this filter reduces the module to standard Oberon-2 code.

--strip-mp-ident

Convert multi-part module names to simple identifiers. The colon characters are removed from the name, and import statements without an alias declaration are rewritten to alias to the last part of the previous multi-part name.

--mod2foreign

This code transformation is intended for advanced users, who want to write FOREIGN modules. It turns any Oberon-2 module into a FOREIGN module, by removing all procedures bodies and the module's initialization code, and by adding appropriate default system flags to the module's header.

--foreign2mod

This is the reverse operation to --mod2foreign. It adds empty bodies to all procedures in the module, and replaces the module's system flags with [OOC_EXTENSIONS].

--config <file>

Use given file name for the primary initialization file. An empty name disables parsing of the default initialization file.

--include-config <file>

Include the given initialization file in addition to the default initialization file.

--options <string>

Add the given string to the initialization file section OPTIONS.

--pragmas <string>

Add the given string to the initialization file section PRAGMAS.

--version

Write compiler version and exit.

--help, -h

Write short usage summary and exit.

The exit status is zero after successful completion.

oo2c(1), oob(1), ooef(1), oowhereis(1), OOC Reference Manual

The OOC Reference Manual can be obtained from the OOC Home Page at http://ooc.sourceforge.net/. It is available in info, Postscript, HTML, and texinfo format.

Michael van Acken <acken@informatik.uni-kl.de>