Introduction

## Command Line Parsing of Source Code with undada

A commad line tool for creating and building Understand for Ada databases is undada. It is a command line program that parses your Ada 83 or Ada 95 source code to populate the database with information that can be browsed or reported on.

Creating a new database is a two-step process. First create the database with the -createdb option and then load the files into the database with either the -add option. Once the database is initially populated, subsequent parsing is incremental, meaning that a file only needs to be re-parsed when it has changed, or something it depends on changes. Refer to the following sections for command line examples.

The command line options for undada are:

Option | Explanation
--- | ---
-create_95 | Specify Ada95 language. This is the default.
-create_83 | Specify Ada 83 language.
| Neither create option will overwrite anexisting database of same name. The database must be created before it can be populated with either the -add option.
-db database | Specify name of database. An extension of .uda is provided if no extension is given.
-delete [file...] | Removes a file or files from the database and from future parses. -d may be used as well. .
-add file [files...] [@listfile] | Specify one or more files to add to the database. Wildcards are expanded by the command shell. Files preceded by a @ are listfiles than hold lists of files to be added (one per line). Full or relative paths may be used. # on the first column of a line in the listfile indicates a comment. -a may be used as well.
-help | Print a list of command line options. -h may be used as well..
-rebuild | Reparses all source files in the project.
-refresh | Bring the database up to date by parsing files that have changed and the files that they affect.
-libunit_defs [before | after | both | none] | If comment association is turned on then this option tells where to collect comments from for top level library units (e.g. package, separates, etc...). Before indicates before the definition but after last definition. After indicates after definition but before next. After is the default.
-nestunit_defs [before | after | both | none] | Similar to -libunit_defs only for nested cprogram units. These may have a different commenting convention. After is the default.
-typeobject_defs [before | after |both | none] | Similar to -libunit_defs but controls comment association for types and objects. After is the default.
-error error_file | Specify where error messages should be logged to. If omitted then errors are sent to the standard error.
--list | Lists files in the project.
-standard directorypath | Optional. Specifies path where source for Ada standard library resides. Use to override standard library provided with Understand and to specify alternate if your compiler uses an alternate standard.. Only valid in conjunction with -create_83 or -create_95.
-verbose | Print descriptions of what is happening to standard output. -v may be used as well.

### Example: Create an Ada 95 Database

This example creates a database populated with the Standard library for Ada 95:

undada -create_95 -db myproject

The resulting database, myproject.uda, can then be used in the analysis of Ada 95 source code.

Use -create_83 instead of -create_95 if you have entirely Ada 83 source code. Use -create_95 if you have a mixed Ada 93/Ada 95 project.

Tip: To save space, specify the Ada 83 option if you have only Ada 83 code. The Ada 95 library is six times larger.

### Example: Processing all files in a directory

If you have a small amount of source files then it may be easiest to just supply their names to the analyzer using the wildcarding abilities of your operating system shell. In this example we will process all Ada specification files (.ads) and Ada body files (.adb):

undada -db myproject -add *.ads *.adb
undada -db myproject -rebuild

### Example: Creating and Processing a list of files (in UNIX)

Note that in some cases there maybe too many files to use the -files technique. A common command line limitation is 255 characters. A directory with hundreds or thousands of files may easily exceed this limit. In this case, or when you want more fine-grained/repeatable control over what files are processed, then you should create a "process list file". This file, the format of which is one filename per line:

myproject.ads
myproject.adb
mainpackage.adb

is processed via the -process command line option:

undada -db myproject -add @myproject_files.lst

Note that there is no limit on the number of files.

On Unix here are a couple ways to create such a file:

- use the `ls' command, as in
ls *.ads *.adb *.sep > my_project.lst
- use the `find' command to recurse sub-directories, as in
find . -name "*.ads *.adb *.sep" -print > my_project.lst

In a Windows NT/95 command shell:

- use the dir command with the /b option:
dir /b *.ads *.adb > my_project.lst
- use the /s option to recurse sub-directories, as in
dir /b /s *.ads *.adb > my_project.lst

### Example: Keeping a database up to date

Once you have successfully parsed your code for the first time, keeping the database up to date is simple:

undada -db myproject -refresh

will check each file previously parsed into the repository to see if it has changed. If it has changed then it will re-parse it, and any files that depend on it (and so on) until the database is fully refreshed.

Use this feature to keep your database up to date while keeping your parsing to a minimum.

### Example: Using Libraries to Partition Analysis

Suppose you have 3 separate areas in my project:

- Radar
- Avionics
- Test and Support

Ideally you would like to create a repository matching the structure of your software, thus permitting you to have reports of your whole system, or of each individual system.
An example way to accomplish this is to create a database, and to use undada three times - once for each partition. For instance:

undada -create_83 -db myproject
undada -db myproject -add @avionics.lst -l avionics
undada -db myproject -add @radar.lst -l radar
undada -db myproject -add @test_support.lst -l test_support

This creates a database that has 4 library partitions in it, Standard (there when you started), Radar, Avionics, and Test_Support. These libraries can then be browsed separately, or in combination. Reports can also be constrained as well.

Scientific Toolworks, Inc. http://www.scitools.com Voice: (802) 763-2995 Fax: (802) 763-3066 support@scitools.com sales@scitools.com