Ada-ASSURED/Ada-Utilities Scripting Language Tutorial

Ada-ASSURED's scripting language is an extension of the Scheme programming language. It can be used for customization, integration, code analysis, and code transformation. This tutorial describes how to write such scripts. You do not need to know Scheme beforehand because footnotes describe each Scheme feature as it is introduced.

The tutorial describes features of Ada-ASSURED supported in Release 3.1.2.

Ada-ASSURED is an interactive editor, library browser, standards enforcer, and quality assurance tool. The scripting language is used to extend it with customized commands that perform additional language-sensitive analyses and manipulations during interactive use.

Ada-ASSURED, when used in conjunction with Ada-Utilities, is also a batch standards checker, quality assurance tool, and code transformation system. The scripting language is used to implement analyses and manipulations of Ada code to be executed by Ada-ASSURED's Batch Processing Module.

The power of Ada-ASSURED's scripting language comes from its structured internal representation of your code. Ada-ASSURED automatically categorizes each construct in your file. In contrast, if you use text-oriented tools like awk, sed, grep, or perl, you must do the categorization yourself. As a result, tasks performed with difficulty using a text-oriented tool are often trivial in Ada-ASSURED.

A simple example illustrates the difference. To count the number of assignment statements in a file, you can't just count how many times ":=" occurs in the file. For example, procedure p contains only one assignment statement, not three:

    procedure p(a: in integer := 0) is
  begin -- p
     a := 1; -- Only one assignment on this line! :=(
  end p;

A text-oriented script must distinguish among occurrences of ":=" that are parameter initializers, assignment statements, and commentary. In contrast, Ada-ASSURED has already done this categorization for you. The script expression

traverses the entire file and calls function increment-count once for each assignment statement. It couldn't be simpler.

Scripts can easily be packaged for both interactive and batch use. As a consequence, programmers writing and modifying code can have interactive access to the same diagnostics the QA team has in batch. Programmers can bring code into compliance before QA and avoid costly rework cycles.

Ada-ASSURED used in interactive mode makes a powerful development environment for authoring batch analysis tools. Scripts can be edited in one buffer while an Ada test file is edited in another buffer. Scripts can be written and tested incrementally using the built-in Scheme interpreter.

The following font conventions are adopted:

The volume Ada-ASSURED Scripting Language: Supplemental Manual, which is distributed with Ada-ASSURED, contains:

The Ada-ASSURED User Guide and Reference Manual, which is distributed with Ada-ASSURED, contains:

Ada-ASSURED's online documentation subsystem contains the following hypertext material:

Good books about Scheme include:

We start with the standard "Hello World" example. Function sg:write-message prints a message in the status pane of an Ada-ASSURED window^[1]. For example, executing the script^[2]

displays the text "Hello World".

A simple way to enter and execute a short script is to use the eval-string command (menu: Tools/Scripts/Eval String). Invoking eval-string pops up a dialog box in which the script can be entered. After typing the script, clicking OK or striking RETURN in the dialog box triggers script execution.

A user seated at a workstation interacts with Ada-ASSURED by invoking commands. There are numerous ways to invoke commands: typing a name in the command pane, selecting a menu item, striking a key, clicking a mouse button, etc.

Every command corresponds to a function in the scripting language. For example, command save corresponds to function sg:save. In general, each command c corresponds to function sg:c. Thus, any action that a user can manually perform can also be invoked in a script by a function call.

Invoking a command with no parameters calls the corresponding scripting function with no arguments. For example, invoking command save does exactly the same thing as using command eval-string to execute the script^[3]

If a command has parameters, then invoking it pops up a dialog box in which the needed arguments are specified. Clicking OK or striking RETURN in the dialog box calls the corresponding scripting function with the arguments that have been specified. For example, suppose command save-as is invoked and parameters "Text", "foo", and "BASEVIEW" are entered in the appropriate fields of the dialog box. Then clicking OK does exactly the same thing as using command eval-string to execute the script^[4]

Commands and scripting functions are so similar that you may wonder how they differ. The few differences are:

Another point of possible confusion concerns the name of a command, e.g., save-as, and the textual label for the command in a menu, e.g., Save As. In general, the two are not the same. To learn the name of the command associated with a given menu item, use command describe-menus (menu: Help/Describe Menus).

Buffer *transcript* provides a convenient interface to the scripting language interpreter. When Ada-ASSURED is used in interactive mode, the *transcript* buffer is effectively the standard input, standard output, and standard error device of the script interpreter.

Use command switch-to-buffer (menu: View/Buffers/Switch to Buffer) to create a separate window displaying buffer *transcript*. The buffer may already contain output from previous evaluations using command eval-string. If it does, just erase it.

If you type a Scheme expression in the *transcript* window and strike RETURN, the expression is evaluated and its value is printed on the next line. For example, typing the expression^[5]

and striking RETURN causes the output 14 to be printed on the next line.

A runtime error in a script causes the script to terminate with an error message that is printed in buffer *transcript*. For example, entering the type-incorrect expression^[6]

and striking RETURN causes the following error message to appear in *transcript*:

The stack trace shows the nesting of function calls within which the error occurred. Function sg:send-input is the function that is invoked when you strike RETURN; it submits the line of script text to the Scheme interpreter for evaluation. All script errors are reported in buffer *transcript* regardless of how the script was started.

Striking RETURN in buffer *transcript* evaluates whatever text appears on the current line. Thus, a previously entered expression can be re-edited and re-evaluated without retyping it. Just select the line containing the expression, re-edit as desired, and strike RETURN.

A very common error in Scheme is to mismatch parentheses. Here is an example that illustrates what to expect if you leave off a right parenthesis:

The "end of file" referred to in the error message is the end of the *transcript* buffer. Here is an example that illustrates what to expect if you have an extra right parenthesis:

The *transcript* buffer is designed for convenient entry and evaluation of single-line expressions. Suppose you want to enter and evaluate an expression that spans several lines. Striking RETURN after entering the first line would cause an error because the first line, by itself, is not syntactically correct. Instead, you can terminate the first line, and each subsequent line, with LINEFEED (^J). Striking RETURN at the end of the last line would also cause an error because the last line, by itself, is not syntactically correct. The entire expression can be evaluated by selecting it, i.e., dragging over it with the mouse, and invoking command eval-selection (menu: Tools/Scripts/Eval Selection).

The scripting language supports numerous forms of output, as we now illustrate.

Our first "Hello World" program used function sg:write-message to output the message to the status pane of the current window. When a script is initiated by eval-string, the current window is the window from which eval-string was invoked. This is useful for providing status information and short answers to user queries in interactive mode. In batch mode, messages written by sg:write-message in scripts are directed to the UNIX stderr stream.

A second "Hello World" program outputs the message to Scheme's standard output port:

In interactive mode, the output is appended to buffer *transcript*. In batch mode, the output is appended to the UNIX stdout stream.

A third "Hello World" program always outputs its message to a specific file regardless of whether Ada-ASSURED is run in batch or interactive mode. Executing the script^[7]

opens output file /tmp/world, writes the message to that file, and closes the file. This is just standard Scheme code.

A fourth "Hello World" program invokes a shell to output the message. Executing the script^[8]

outputs its message to the UNIX stdout stream. Using this mechanism, a script can invoke any other program by an appropriate shell command line.

Defining a new command that has no parameters can involve the following steps:

• "Tools" is the menu into which the menu item is inserted.
• "Analyze" is the textual label of the menu item.
• 99 indicates the new item should follow the 99^th item --- presumably last.
• #\A is a mnemonic for the item.^[11]
• #\b indicates the item is a button (as opposed to, say, a descending menu).
• '() means the menu item is always enabled, i.e., it is never shaded out.
• "analyze" is the name of the command invoked by selecting the menu item, i.e., analyze.

Script Files

Defining Commands With Parameters

• "analyze" is the name of the procedure to be called when OK is clicked. Whatever text appears in the dialog box parameter slot at the time OK is clicked is passed as an argument to analyze.
• "Enter Message" is a title for the dialog box.
• "Text:" is a label for the parameter slot.

Structural Representation of Ada Code

Structurally Traversing a Buffer

• search for Ada code fragments of particular interest,
• transform Ada code fragments of particular interest, or
• compute properties of the Ada code.

Simple Patterns

Nested Patterns

Traversing the Structural Selection

• The representation of lists as terms (e.g., the list of four statements above).
• The representation of sublist selections (e.g., the selected sublist of two statements above).

Simple Metrics

Sample Metrics Report for foo.a

File: foo.a
Generated: 3/5/97 by joe_user

The concepts illustrated by the example include:

The script is included with Ada-ASSURED in $AAHOME/scripts/bean.stk.

Two global variables are used for the table of counts and the name of the generated file:

Function bean:start implements command bean:^[19]

Once function bean:start has been defined, we can define command bean and add an item for it to the Tools menu:

Function bean:count is used to increment the counter associated with a given bean type. It must distinguish between the first occurrence of a construct (in which case the count is initialized to 1) and subsequent occurrences of the construct (in which case the count is incremented).^[20]

Function bean:traverse increments the appropriate count for each occurrence of one of the constructs of interest. For exposition purposes, we have used pattern variables below to indicate the contents of various operator arguments. Because these pattern variables are not used, however, they could have been wildcards instead.

Once the buffer has been traversed and all counts have been incremented, the HTML file is output. We assume you have a passable reading knowledge of HTML, and will not explain the HTML here:^[21]

The header and trailer of the HTML file are pretty standard. The details have more to do with HTML than Scheme or Ada-ASSURED:^[22]

Terms are abstract, non-textual representations of Ada code fragments. To display a term as readable text, the term must be converted to a string. The following example illustrates how this is done.

Suppose we want to print out the text of each assignment statement in a file. We have seen that it is easy to locate each assignment statement using sg:traverse:

Within the body of a (pattern body) pair, the name $$ refers to the matched subterm. Thus, to print each assignment statement, we must print term $$. However, if we were to write:

the statements would be displayed in an opaque representation, e.g.,

  [Term 2c64ac]
  [Term 2d3240]
  etc.

In order for the statements to be readable, we must convert each term to its string representation for display.

Function (sg:term->string term) converts term to a string using the standard formatting rules for Ada. Thus, the correct definition of function print-assignments is:

To try out print-assignments as a version of command analyze, function analyze should be redefined as follows:

A string must be analyzed to obtain its representation as a term. The analysis process is called parsing. One string may have different representations as terms of different phyla. The following example illustrates how strings are converted to terms.

Suppose we wish to replace every assignment statement of the form:

by the assignment statement

where n is an arbitrary name. We wish to find all assignment statements of the given form regardless of how they are formatted on the page, e.g., even if the statement is split across multiple lines.

The structural representation of expression ABC+DEF*GHI-1 is

where abc, def, and ghi are the representations of the identifiers as names, and one is the representation of 1 as a number. Because this is tedious, we would prefer to avoid writing an explicit pattern for the expression. In fact, we can avoid any detailed understanding of the term representation of the expression, as shown below.

First, we obtain the term representations of expressionABC+DEF*GHI-1 and expressionf(ABC,DEF,GHI). Function (sg:string->term string phylum) converts a string to a term of a given phylum. If string is not syntactically correct as a phylum, the null list '() is returned. Function(sg:string->phylum string) returns the phylum named string. Thus, the term representations of the two expressions are computed by:

To find all occurrences of assignment statements with the given form, we can use a hybrid between pattern matching and testing for term equality: ^[23]

Function (sg:replace! term₁ term₂) replaces term₁ with term₂. Function sg:replace! is the scripting language's assignment statement for subterms. Term₁ is replaced in its context by term₂. Thus, we can complete function replace-assignments! as follows:

We end with two caveats about the functions introduced this section:

In well-written programs, comments and code are consistent. An Ada-ASSURED script can be used to check for such consistency. We develop a script that meets the following specification:

The example is obviously scaled down for tutorial purposes, but illustrates many techniques required in more realistic settings.

The relevant portion of the Ada grammar dealing with full-line comments is:

Full-line comments are instances of operator LeftCommentLine, which contains a comment_text part. The comment_text part will be an instance of operator CommentText, which contains two STR parts. The first STR is the character immediately after the "--", and the second STR is the rest of the comment.

Function fix-comments traverses the contents of the buffer in preorder and calls do-replacement!at each full-line comment satisfying the relevant-header-comment? predicate.^[24] The value of symbol $$ is the subterm currently matched by sg:traverse.

Predicate relevant-header-comment? considers a comment relevant if it contains the substring "procedure body:". In practice, a more careful test would be written, e.g., taking the position of the substring into account. Function sg:term->string is used to turn c, the subterm containing the comment text, into a string.

Function do-replacement! computes the new comment by finding the name of the next procedure (proc-name), forming the appropriate comment text (new-text), and translating it into its term representation (new-term). The old comment (cur-term) is then replaced by the new comment (new-term) using sg:replace!. ^[25]

Function next-procedure finds the name of the next procedure. The relevant portion of the Ada grammar is:^[26]

Thus, next-procedure searches forward until it finds the next occurrence of operator SubprogramSpecificationProcedure. When the procedure specification is found, its name is converted to a string using sg:term->string, the name is assigned to local variable proc-name, and the traversal is aborted. If we didn't abort the traversal, proc-name would be set at every procedure in the traversed term, and next-procedure would return the name of the last procedure encountered, instead of the first. If no procedure is found, the empty string is returned.

We use sg:ordered-traverse to specify that the traversal should continue beyond the comment-term itself. Recall that (sg:traverse term (pattern body) …)only traverses the given term. But the procedure we seek will appear after, not within the comment-term. The fourth argument #t specifies that after completing the traversal of the term, the traversal continues all the way to the end of the surrounding context (unless terminated by 'abort).

Function mk-comment-term turns a string into a term of phylum left_comment_line. Because function sg:string->term does not support parsing strings as phylum left_comment_line, we build the term explicitly:

Scripts are often written to be run in batch mode using Ada-ASSURED's Batch Processing Module. Suppose the entire script has been saved in file fix_comments.stk. Then it can be executed on files f1.a and f2.a by running the following command from the shell:

More specifically, this command:

Note that the same script function fix-comments can be used in either interactive or in batch modes.

Additional demonstration scripts are included with Ada-ASSURED and are described in the file $AAHOME/scripts/README.

1. Names in Scheme can include special characters like colon and hyphen. Thus, sg:write-message is one name.

Scheme has no formal notion of module or package. A collection of related names informally constituting a module are typically given related names. By convention, prefix m: is used for all global names of module m. The prefix sg: stands for Synthesizer Generator, technology that underlies Ada-ASSURED.

Names are case insensitive unless bracketed by vertical bars ( | ). Letters in names without brackets are mapped to lower case. Thus, SG:write-message is the same as sg:write-message, but |SG:write-message| is different from sg:write-message.

2. Expression (sg:write-message "Hello World") is a Scheme function call. In Scheme, the left parenthesis of a function call appears before, rather than after, the function name.

3. Expression (sg:save) is a Scheme function call. As with the previous example, the left parenthesis of the function call appears before the function name. Because function sg:save takes no arguments, the right parenthesis immediately follows the function name.

4. Expression (sg:save-as "Text" "foo" "BASEVIEW") is a Scheme function call. Function sg:save-as requires three string arguments. Note that arguments in a function call are not separated by commas.

5. There are no infix operators in Scheme. Even arithmetic operations are written in functional notation. Thus, what in Ada would be written as 2 + 3 * 4 is written in Scheme as (+ 2 (* 3 4)). Because there are no infix operators, parentheses are never used in Scheme to express precedence.

6. Type errors in Scheme expressions are detected dynamically during execution. Primitive functions, like -, check the types of their arguments on entry to the function.

7. Scheme construct (define name expression) declares variable name and sets its value to the value of expression. If name has already been declared, its value is overwritten. Function open-output-file takes a string argument, opens an output file with that name, and returns a port (i.e., a file descriptor) for that file. Function close-output-port takes a port argument and closes that port. Thus, the given script sets variable fd to a descriptor for the opened file /tmp/world, writes "Hello World" to that file, and closes the file.

8. STk function system takes a string argument and directs the given string to the system shell /bin/sh.

9. The general form of a Scheme function definition is (define(name parameters) expressions), where name is the name of the function, parameters is a list of zero or more parameter names, and expressions is a list of one or more expressions. When a function has several parameters, they are not separated by commas. Similarly, when the body of the function consists of several expressions, they are not separated by any punctuation marks. Running the given script defines function analyze, but does not call it.

10. In Scheme, arguments are passed to functions by value. In the call (sg:add-command "analyze" analyze), the value of the first argument is a string containing seven letters. The value of the second argument is the value of variable analyze, i.e., the function itself. In Scheme, functions are first class values. This example illustrates that functions can be passed to other functions as arguments. The argument is not the result of calling function analyze, but the definition of function analyze.

11. The character constant for the character c is written as #\c in Scheme.

12. One might well ask why there is no syntactic category for Scheme programs so scripts could be edited with a Scheme structure editor. Such a capability is planned for a future Ada-ASSURED release.

13. In Scheme, if name already exists, evaluating (define (name parameters) expressions) or (define name expression) redefines name. Similarly, sg:add-command will redefine an existing command.

14. Expression (let ((v₁ e₁) ... (v_n e_n)) body) declares local variables v₁, ..., v_n and initializes them to the values of expressions e₁, ..., e_n, respectively. Body is a list of one or more expressions. The value of the let-expression is the value of the last expression in the body. A let-expression is similar to an Ada block: it introduces a local scope that contains initialized variable declarations. Unlike Ada, the variables are typeless and the block has a value.

Evaluating expression (set! v e) stores the value of expression e in variable v. The exclamation point in set! is part of the name of the assignment operation. It is a convention in Scheme to give operations with side effects names ending with the emphatic ! character.

15. A single semicolon signifies that the rest of the line is a comment. It is a common convention to repeat the semicolon (as the first few characters of the comment) for emphasis.

16. Function number-string converts a Scheme number (like the count returned by count-nodes) to a string (as required by sg:write-message).

17. Usually, an identifier refers to a variable with the given name. For example, the identifier count refers to a variable named count. In Scheme, a identifier itself can also be a legitimate value. Such values are known as symbols. To denote the symbol skip rather than a variable named skip, the identifier skip must be quoted; otherwise, the interpreter will look for a variable named skip to evaluate. Writing 'skip is equivalent to writing (quote skip).

18. The list containing 0 elements, known as the empty list, is denoted '(). If h is any Scheme value and t is a list, then the value of expression (cons h t) is the list with first element h and remaining elements t. For example, expression (cons 1 (cons 2 (cons 3 (cons 4 '() )))) constructs the list (1 2 3 4).

19. Function (make-hash-table function) creates an empty hash table that uses the binary predicate function to test equality between index keys. Function string=? is Scheme's built-in equality predicate between strings.

Function (sg:load-html-file path file) directs Ada-ASSURED's HTML browser to open path/file. Function (getcwd) returns the path of the current working directory as a string.

20. Function (hash-table-get table key default) returns the hash table entry associated with key in table, if present, and otherwise returns the value default.

Predicate (integer? e) returns #t (i.e., true) if the value of expression e is integer, and otherwise returns #f (i.e., false).

Function (hash-table-put! table key e) associates the value of expression e with key in table, deleting any other association for key.

21. Function (format port string e₁ ... e_n) outputs the values of expressions e₁ ... e_n to port according to the format string. The values are displayed left-to-right at the occurrences of ~a in the format string. Each ~% in string signifies a newline.

Function (hash-table-map table function) applies function to each item in table. Function must be a function of two arguments: the key of the item and its associated value. In the example, the function that is passed to hash-table-map is created using form (lambda arguments body). Function
     (lambda (s c)(bean:html-counts port s c))
is an unnamed function of two arguments, s and c, that calls function bean:html-counts with the three arguments port, s and c. Variable port, which is declared in a surrounding lexical scope, is accessed by the anonymous function as a nonlocal variable. This is analogous to what is possible with nested function declarations in Ada, where the inner function can access the local variables of the enclosing function.

22. Function (exec string) invokes the program string and returns its return value. Function (getenv string) returns the value of environment variable string.

23. Expression (if expression₀ expression₁ expression₂) is Scheme's conditional expression. If the value of expression₀ is #t, i.e., true, the value of expression₁ is returned, otherwise the value of expression₂ is returned. If expression₂ is omitted and the value of expression₀ is not #t, then the value of the conditional expression is unspecified.

Expression (equal? expression₀ expression₁) tests equality between two Scheme values. Two structured values are equal if they have the same shape. Function equal? does not require that its two arguments be identical values, i.e., one and the same value, just that they have the same shapes.

24. The question mark in relevant-header-comment? is part of the name of the function. It is a convention in Scheme to give functions that return #t (i.e., true) or #f (i.e., false) names ending with the quizzical ? character.

25. Expression (let* ((v₁ e₁) ... (v_n e_n)) body) is similar to a regular let without the *. The difference is that in a let*, occurrences of variables v₁, ..., v_n in expressions e₁, ..., e_n refer to the new variables declared in the let*, whereas in (let ((v₁ e₁) ... (v_n e_n)) body), occurrences of variables v₁, ..., v_n in expressions e₁, ..., e_n refer to variables declared in a surrounding scope.

26. This is the rule for Ada 95. The corresponding rule for Ada 83 is has name in place of expanded_name.