Introducing Ada-ASSURED

Introducing Ada-ASSURED

Introduction

Ada-ASSURED is a ``smart'' source code tool intended to help software engineers and quality assurance engineers produce high-quality Ada programs. Ada-ASSURED is smart because it knows the rules of Ada. Its powerful language-sensitive features increase productivity, prevent errors, and enforce compliance with software standards. Ada-ASSURED automates many common tasks so engineers can concentrate their valuable talent where it really counts...on content.

Ada-ASSURED is designed to be flexible:

• It handles both Ada 83 and Ada 95 programs.

• It is designed to support the Software Productivity Consortium (SPC) quality and style guidelines[Note: Ada Quality and Style: Guidelines for Professional Programmers, Software Productivity Consortium, Herndon, Virginia, SPC-91061-CMC, Version 02.01.01 December 1992.   Ada 95 Quality and Style: Guidelines for Professional Programmers (Working Draft Version), Software Productivity Consortium, Herndon, Virginia, SPC-94093-CMC, Version 01.00.10 October 1995.] recommended by the Ada Joint Program Office (AJPO), but can be customized to suit individual project needs.

• It runs on all major Unix engineering workstations and on Microsoft Windows platforms.

• It works both in X Windows settings, and under the Microsoft^® Windows^® operating system.

• It integrates easily with all major Ada compilers and other tools.

• It runs interactively and in batch mode.

• It can be used on new projects and on existing Ada code.

• It empowers experienced Ada programmers, but also guides Ada novices.

• It is programmable and extensible.

• language-sensitive editor,

• browser,

• quality assurance tool and standards enforcer,

• code analyzer and transformer, and

• pretty-printer or formatter.

• Automatic Ada-based functions are provided for what are otherwise manual tasks:

  • Built-in templates insert code fragments guaranteed to be syntactically correct and well-formatted. Templates are easily customized to include project-specific headers. Using code templates speeds coding and fosters up-front compliance with style guidelines by prompting for needed documentation.

  • Typed text is automatically analyzed and formatted.

  • Whole Ada constructs are selected in a single mouse click, even when they extend off-screen, eliminating time-consuming and error-prone searches. Cut-and-paste of such selections is guaranteed not to mangle code structure.

  • Code is automatically reformatted after each modification. Multi-line comments automatically word wrap as they are modified.

  • Many style violations detected by the standards enforcer can be eliminated in a single mouse click by invoking a built-in corrective transform.

• Time-consuming and costly rework cycles are reduced:

  • Local syntax errors are prevented during editing, which eliminates many recompilations.

  • Nonlocal errors can be found and corrected quickly. Compiler and editor are tightly integrated. Compiler error messages ``stick'' to the referenced code lines, so that fixing one error does not ``skew the line numbers'', which would otherwise make it hard to find the remaining errors.

  • QA rejections are diminished because many style and standards violations are detected and corrected in advance.

• Multiple buffers and windows support simultaneous displays of multiple files and file regions.

• Hypertext library navigation provides quick access to name definitions.

• Library queries give rapid context-sensitive access to the names database. You pose a query and find all matches in the library. Searches are optionally sensitive to the with, use, and rename context.

• Standard formatting using multiple fonts, colors, and display styles makes code easier to read and understand.

• Multiple views let you easily see what is relevant:

  • A code file and a summary of its style violations are displayed simultaneously. A click in the summary scrolls to the offending construct in the code.

  • Elision hides details you want to suppress.

  • Formatting adjusts to window width so code remains intelligible even when you need to tile the display with many narrow windows.

• Reads existing code created with any editor.

• Displays and outputs diagnostics in-line, or in a separate summary view, or both. Provides hypertext navigation from each diagnostic message to the appropriate section of the style guideline.

• Runs both interactively and in batch mode. The same diagnostics are available to the programmer creating code and the quality assurance engineer reviewing code.

• The built-in suite of style and standards checks can be customized. New analyses can be created using the tool's scripting language.

• Runs scripts that can traverse, analyze, and modify files according to their syntactic structure. Powerful, yet easily programmed, manipulations are possible because each Ada compilation unit is provided as a structured data object in the script language.

• Custom metrics can be collected; project standards can be enforced.

• Runs both interactively and in batch mode.

• Ultra-high quality formatting. In fact, Ada-ASSURED was used by the Software Productivity Consortium (SPC) to format all of the examples, in whole or in part, in its Ada Quality and Style: Guidelines for Professional Programmers.

• Formatted output to both ASCII files and PostScript printers.

Effective Use of Documentation

Documentation for Ada-ASSURED consists of:

• an Installation Guide;

• this manual, the User Guide & Reference Manual (both on-line and in hardcopy);

• on-line Tutorial Introduction;

• on-line context-sensitive help;

• the Ada-ASSURED Scripting Language: Supplemental Manual.

• Ada 83 and Ada 95 Language Reference Manuals

• Ada 95 Quality and Style: Guidelines for Professional Programmers.

If Ada-ASSURED is already installed and running smoothly, you should have no need to refer to the Installation Guide. If you need to install Ada-ASSURED, finish reading this chapter, and then do the installation.

Using this Manual

This manual is structured in two parts. Part I is the User Guide, and Part II is the Reference Manual.

First Hour

Once Ada-ASSURED has been installed, and before you start to experiment on your own, we suggest that you read the following chapters of the User Guide and follow their instructions:

• Chapter Editing an Ada Program
• Chapter Browsing a Library
• Chapter Auditing for Quality
• Chapter Running an Editor Script
• Chapter Prettyprinting a File

Initial Customization

• Chapter Initial Customization

Second Hour

• Chapter Editor Overview
• Chapter Whitespace
• Chapter Comments
• Chapter Hypertext Documentation
• Chapter Tool Integration
• Chapter Using a Preprocessor

As Needed

Consult the Reference Manual and refer back to the User Guide as needed.

Conventions Used in this Manual

This manual uses the following typographical conventions:

• Bold font is used for the names of Ada-ASSURED commands (e.g., open).

• Italic font is used for

  • the introduction of new terminology (e.g., object pane),

  • command parameters (e.g., parameter file of command open),

  • placeholders (e.g., <statement>).

  • miscellaneous other parameters (e.g., aahome is the full path name of the Ada-ASSURED directory).

• Helvetica font is used for

  • keys (e.g., Enter),

  • mouse buttons (e.g., Select),

  • menus (e.g., Help),

  • graphical buttons (e.g., procedure-body),

  • editor parameters (e.g., Auto Save Enabled),

  • enforcement parameters (e.g., Goto Enforcement),

  • Ada-ASSURED resources (e.g., geometry),

  • files (e.g., /usr/local/bin/aa),

  • buffers (e.g., *untitled*),

  • views (e.g., MESSAGES).

• Courier font is used for
  • Ada program text (e.g., with Text_IO),

  • functions and expressions in the script language (e.g., sg:exit), and

  • text on shell command lines (e.g., aa -language 95).

Ada-ASSURED runs under both Unix and Microsoft^® Windows^®, which leads to some variation in appearance and operation of the editor in the two settings, as well as in the documentation. Where the documenation diverges for the two systems, it will be clearly marked. For example, with

X	X Windows documentation here, and
MS	Microsoft® Windows® documentation here.

Some differences that the reader should be prepared to encounter are as follows.

• Ada-ASSURED is invoked differently from different operating systems.

• Windows and buffers are treated somewhat differently in different systems.

• Some commands have different names in different systems. Others are specific to one particular system and have no counterpart in another.

• Key bindings and menu paths differ between systems.

• Customization is carried out differently under different systems.

One of the important differences between operating systems is notational. For simplicity, this manual sometimes uses the notation of one operating system in preference to the other.

Return/Enter key

The key labeled Return on Unix keyboards is labeled Enter on PC keyboards. We will use Enter to refer to that key on all keyboards.

Control key

The Unix notation for chording the Control key with, say, the `C' key is ``^C''. While this notation is sometimes used in the manual, we prefer the Microsoft<sup>®</sup> Windows<sup>®</sup> notation, ``Control+C''.

Mouse buttons

We will use the mouse button vocabularies from both X Windows and Microsoft^® Windows^®, usually each in its own domain. Sometimes the vocabularies cross, however, so the reader should be aware that the Select button is the same button as Left Button, while the Menu button is the same button as Right Button (unless deliberate steps have been taken to map the buttons differently).

Directory separator

The directory separator character is `/' in Unix, but `\' in Microsoft^® Windows^®. The documentation will usually be split into two parallel parts when issues involving filenames arise, but not always. For short explanations that are not split, the Unix conventions will be used for filenames. The reader should be prepared to understand ``C:\temp\demo.a'' for ``/tmp/demo.a'', for example.

Using the Tutorial Introduction

An easy-to-follow on-line tutorial gently introduces new users to Ada-ASSURED. Much of the same material is replicated in Chapter Editor Overview without the tutorial's step-by-step ``hands-on'' experience. You are encouraged to work through the tutorial, or read Chapter Editor Overview, or both. Start the tutorial by invoking the command tutorial, which can be found in the Help menu.

Using On-line Help

The on-line hypertext help system includes documentation for:

• Each command.

• Each Ada syntactic category used in Ada-ASSURED.

• Each Ada code template and code transform.

• Each ERROR, VIOLATION, and INDICATOR message.

• help-for-editor, which takes you to the table of contents of the hypertext web. By clicking with the left button on successive index terms, you navigate through the web of documentation.

• describe-command, which provides documentation on a particular command, or a set of commands whose names share a common substring.

• describe-context, which provides a description of your current syntactic context, and a cross-reference to the appropriate chapter and section in the LRM where this syntactic category is defined.

• describe-transform, which provides documentation on the currently enabled transforms and code templates.

• describe-menus, which provides the correspondence between menu items and commands.

• Clicking with the left mouse button on a diagnostic message number (e.g., [E11], [V7], or [I3]) navigates to the appropriate text in either the LRM or the SPC Quality and Style Guidelines.

Cautionary Note

You will soon be trying Ada-ASSURED on your own files. Ada-ASSURED is like a high-performance sports car. It is very powerful, so be careful when you are experimenting with it. You will find Ada-ASSURED will enable you to manipulate code faster and with greater precision than conventional editors. Until you are reasonably comfortable with it, we recommend that you work from copies of your files, not the masters.