TOC PREV NEXT INDEX DOC LIST MASTER INDEX



CHAPTER 6:

Ada Repair

Ada Repair is a separate product that complements the Ada Analyzer. Ada Repair supports two capabilities: repair of coding violations and renaming of declarations within some body of Ada code.


Repairing
Violations

This component of Ada Repair takes static analysis of coding violations a step further. It automatically creates new versions of Ada programs that no longer contain violations. The resulting code is semantically equivalent to the original but with improved maintainability, consistency, and readability.

For example, the following procedure call embedded in a case statement

could be updated to add the missing named parameter association and the default parameter to the procedure call. The addition of named parameter association makes the call more readable; the addition of the default parameter reduces the risk of future defects when the default is changed. Expanding the case range and when others will make the software more robust and less prone to future defects.

Supported Updates

The following repairs can be made to Ada software. Each update is a separate option in the dialog box of the Analyzer:Ada Repair:Repair Violations command.

Code Modification
Benefits
1.
Add named parameter association to procedure calls.
Makes procedure calls more readable and maintainable.
2.
Add named association to aggregates.
Makes aggregates more readable and maintainable.
3.
Add named association to generic instantiations.
Makes generic instantiations more readable and maintainable.
4.
Add explicit default parameters to calls using the default.
Makes procedure calls less susceptible to errors resulting from future changes.
5.
Add missing in mode specifications to subprogram parameters.
Makes procedure declarations more explicit and thus more understandable.
6.
Adjust in out parameters when they are only set (to out mode) or only used (to in mode)
Makes parameters consistent with their actual use.
7.
Move representation clauses immediately after the type they represent.
Makes the software more readable; required by Ada 95.
8.
Generate named number declarations for literals in subprogram bodies and replace the literal with a reference to the named number.
Makes the software less susceptible to errors resulting from future changes to literal values.
9.
Name loops that are nested.
Makes the software more readable and allows exit statements to be made explicit.
10.
Name blocks that are nested.
Makes software more readable.
11.
Replace or and and operators with their short-circuit forms.
Can make software more efficient.
12.
Replace when others in case statements with actual values (enumeration only).
Makes case statements less susceptible to errors resulting from future changes.
13.
Replace literal ranges in case statements with actual values (enumeration only).
Makes case statements less susceptible to errors resulting from future changes.
14.
Replace when others in record aggregates when enumerated.
Makes record aggregates less susceptible to errors resulting from future changes.
15.
Replace if then exit with exit when.
Makes the software more readable and less complex.
16.
Add explicit loop names to exit when possible.
Makes the software more readable and less susceptible to errors from future changes.
17.
Qualify references that are not already fully qualified.
Makes the software more readable, more robust, and can lead to the removal of use clauses.
18.
Add rename declarations for all infix operators used in a unit.
Makes the software more readable and can lead to the removal of use clauses.
19.
Replace anonymous array type specifications with an explicit array type declaration.
Makes the software more explicit and readable.
20.
Generate explicit index types for array types when required.
Makes the software more readable and allows for use of lower-bound, upper-bound, and range attributes.
21.
Replace raise; with an explicit raise.
Makes the software more readable and robust.
22.
Remove unused and redundant with clauses. Move with clauses from the spec to the body when possible.
Reduces dependencies and complexity to minimal requirements. Can reduce recompilation time. Improves program structure.
23.
Alphabetize context clauses.
Makes location of specific with clauses easier.
24.
Alphabetize rename clauses.
Makes location of specific rename clauses easier.
25.
Replace multi-name context clauses with a series of single-name context clauses.
Makes the software more consistent and readable. Allows for better ordering.
26.
Replace multi-name declarations with a series of single-name declarations.
Makes the software more consistent and readable. Allows for separate default values.
27.
Remove use clauses
Removes the open naming that use clauses introduce.

The Update Process

Ada Repair will replace the current version of an Ada unit with one that no longer contains the specified coding violations. If necessary, Ada Repair will also checkout controlled units before they are updated. It will also recompile and checkin units after they have been updated, when requested. Each unit specified for update will be traversed to locate all occurrences of the specified coding violations.

Managing Change

Since Ada Repair modifies the files containing Ada units, it is important to ensure that all changes made are desired changes. As users continue to use Ada Repair, they will gradually gain confidence that the updates are made correctly and are consistent with their coding standards. Several safeguards capture the updates and allow one to revert to the previous version of a unit when the updates are not desired.

1. All units should be placed under CMVC control. Before units are updated they should be checked-in to ensure that a baseline version is recorded. Ada Repair will then check the units out (when the Allow_Check_Out option is enabled), creating a new updated version. The differences between the two versions can then be displayed for inspection and acceptance. If the new version is unacceptable, the user can revert to the previous version or make manual changes to the new version to correct any problems. Alternatively, a user could not enable the Allow_Check_Out option, and then check out only those units for which updates are desired. Differences could still be computed using the Control:Show:Differences operation.

2. If the Replace_Existing_Units option is not selected, the new version of the unit will be saved in a file called <ada_unit_name>.new, and the Ada unit file will remain untouched. Files can then be copied or deleted as desired to accept or reject the updates made by Ada Repair. This provides a manual method of version control that is automated with the CMVC approach in step 1.

3. An Effort_Only option is available to list in the log all changes that would be made without actually making the updates to the Ada files. This allows the user to view potential change before requesting that they be made.

Conflicting Updates

It is possible that two or more updates will attempt to modify the same span of code in an Ada unit. Ada Repair recognizes when updates would conflict with each other and makes only the first update. When conflicting updates are found, they are noted in the log and no conflicting updates are not made to the software. It is possible to run Ada Repair again in this case (after the new units are recompiled). The second execution will not have the original conflict and the update rejected during the first execution will be made.


Repair_Violations

Command-Line Interface

repair_violations
      -Replace_Existing_Units
      -Allow_Check_Out
      -Compile_After_Update
    -Checkin_After_Update
      -Effort_Only
      -Announce_Updates

    -Name_Parameter_Associations
      -Name_Aggregate_Associations
      -Name_Instance_Associations
      -Add_Default_Parameters
      -Add_Parameter_Modes
      -Adjust_In_Out_Paramters
      -Expand_Multi_Name_Declarations
      -Expand_Multi_Name_Withs
      -Move_Representation_Clauses
      -Name_Literals
      -Name_Nested_Loops
      -Name_Nested_Blocks
      -Add_Short_Circuits
      -Replace_Case_Others
      -Replace_Case_Ranges
      -Replace_Aggregate_Others
      -Convert_To_Exit_When
      -Add_Loop_Name_To_Exit
      -Qualify_References
      -Add_Operator_Renames
      -Remove_Use_Clauses
      -Make_Anonymous_Array_Types_Explicit
      -Add_Explicit_Index_Types
      -Make_Raises_Explicit
      -Repair_With_Clauses
      -Alphabetize_Context_Clauses
      -Alphabetize_Rename_Declarations
      -Use_Configuration [string-expression, default = ""]
   <list of units>

Nonstandard Parameters

Note: The following options enable the updates described in section "Supported Updates".


Declaration
Renaming

Ada Repair also provides a separate but related capability to move and/or rename declarations within some body of code. Declarations can be given a new name within a specified unit, moved to another existing compilation unit, or moved to and simultaneously renamed within an existing compilation unit. This capability is invoked with the Analyzer:Ada Repair:Rename Declarations menu item. This capability can be used to restructure code to improve its organization, reduce cross dependencies, and improve architectural integrity.

All references to the new declaration names will be updated to maintain compilation integrity. All views that have potential references must be specified in the list of units to repair. Units in views left out of the list will not be updated and may be inconsistent with the new declarations. Such inconsistencies must be repaired by hand. As a precaution, most declarations will be copied (not renamed in place) to ensure that unmodified references will still compile. This will allow subsequent processing of units with obsolete references. Some declarations must be renamed in place as specified below. Eventually, the renamed or moved declarations will have no remaining dependencies and can then be deleted. Options are available to comment out or delete the renamed or moved declarations.

Additional with clauses will be added to units where required to compile newly added references. Obsolete with clauses no longer required due to modified references will not be removed. This can be performed with the Repair Violations capability in another command invocation.

Usage Tip: It is possible to specify that more than one declaration be renamed or moved with a single command invocation. In some cases, multiple declarations must be moved to avoid cross-withing of specifications. It is recommended that the user limit to a reasonable number the number of declarations specified in any one command invocation. This will avoid undue complexity that may result in inconsistent code. Note that all modifications can be undone by abandoning changes in controlled units.

Command-Line Interface

repair_violations
      -Replace_Existing_Units
      -Allow_Check_Out
      -Compile_After_Update
    -Checkin_After_Update
      -Effort_Only
      -Announce_Updates

   -Rename_Declarations

   -Replace_References_Only
   -Remove_Renamed_Declarations
   -Comment_Out_Renamed_Declarations
   -Copy_Preceeding_Attached_Comments
   -Copy_Succeeding_Attached_Comments
   <list of views>

Nonstandard Parameters

Specifying Declarations to Rename or Move

The configuration-policy file ada_repair/declaration_mapping is used to specify the declarations that should be renamed or moved. All entries in this file should be of the form:

The source_pkg_name must be an Ada library unit within the set of views specified for processing and the source_decl_name must be a declaration within that package. It need not be in the specification. Additional nesting is allowed:

If the source_pkg_name and the destination_pkg_name are the same, then the mapping is considered a rename of the declaration. If the source_pkg_name and the destination_pkg_name are different, the declaration is specified to be moved from one unit to another. It is possible to both move and rename a declaration at the same time.

The destination_pkg_name must be an existing library unit and be either a package or package body declaration. If the Replace_References_Only option is enabled, the destination_decl_name must already exist within that package. If this option is not enabled, the destination_decl_name must not already exist within that package. If a declaration is being moved to a specific destination package, that package may not itself be renamed or moved.

By default, source declarations located in a specification will be moved to the specification of the destination container. Declarations located in the body will be moved into the body part of the destination container. It is possible to override this default placement with the `spec and `body attributes to specifically designate a specification or body of the destination container.

Some Ada declarations are two-part declarations. Package, procedure, function, task, entry, deferred constant, and incomplete type declarations are all two-part. Packages, subprograms, and tasks may also be subunits with an additional subunit stub declaration in the body. If the specification part of any two-part declaration is specified to be renamed or moved, then its corresponding body-part declaration and subunit stub (if present) will be treated similarly. Subunits will be created if necessary, but never deleted since they are normally controlled objects. Removal of obsolete subunits is left to the user.

Any declaration (including parameter, record discriminant, record component, generic formal, enumeration literal, or declarations declared locally within a subprogram) can be referenced by a qualified name containing all intervening declaration names. For example, it is possible to reference subprogram parameters with the following reference:

Record components can be referenced with:

Enumeration literals can be referenced with:

It is possible to move or rename any declaration, with the following exceptions:

Note: This can result in inconsistencies. Units that are not processed may reference the old declaration name that has been replaced. Other declarations that are copied may contain references to the old declaration name as well. The new copy of the declaration should not contain such references, but the old declaration from which the copy is made may have such references.

Renaming Compilation Units

Normally, it is only possible to move and rename declarations within compilation units. It is possible to rename compilation units with the following process. The user must first copy the compilation unit to a new name and compile it. The entire family (unit body and all subunits) must be included in the copy. Next, the declaration_mapping configuration-policy file should be updated with an entry of the form old_comp_unit_name => new_comp_unit_name. In this case, an exception is made to the format requirements of this file. Finally, the rename declarations capability of Ada Repair should be invoked with the Replace_References_Only option. This will replace all references to the old compilation unit with references to the new one.


Rational Software Corporation  http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2000, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX DOC LIST MASTER INDEX