A S I S t a n t User's Guide Version 1.5 Author: Vasiliy Fofanov, Ada Core Technologies, Inc. Co-authors: Sergey Rybin, Ada Core Technologies, Inc. Alfred Strohmeier, Swiss Federal Institute of Technology in Lausanne Date: March 2, 2000 Revisions history V1.5 02.03.2000 Online help expanded (see 8.) V1.4 15.11.1999 Source location search capability added (see 4.5.3.4.) Browser capability expanded (see 5.) V1.3.3 11.11.1999 Special script processing mode added (see 2.) V1.3.2 23.06.1999 Interactive script execution added (see 7.) V1.3.1 03.06.1999 Partial support for Asis.Data_Decomposition V1.2 21.01.1999 ASIStant commands may now optionally terminate with ';' Several bugs fixed V1.1 31.10.1998 Browser capability added (see 5.) Output section revised (see 4.5.2.4.) V1.0 15.10.1998 Original version Contents 1. Introduction 2. Launching ASIStant 3. General ASIStant Language Description 4. Language Components 4.1. Data Types 4.2. Constants 4.3. Variables 4.4. Expressions 4.5. Function Calls 4.5.1. ASIS Queries 4.5.2. ASIStant Utilities 4.5.2.1. Help system 4.5.2.2. Environment control 4.5.2.3. Variable handling 4.5.2.4. Output 4.5.2.5. Conditional execution 4.5.3. ASIStant Service Functions 4.5.3.1. Access to components of ASIS record types 4.5.3.2. List handling 4.5.3.3. Functions for the types String, Boolean and Integer 4.5.3.4. Source location search capability 5. Browser capability 5.1. Access to the Browser capability from inside ASIStant 5.2. Browser environment 5.3. Displaying the current Element 5.4. Advanced traversal 5.5. Going to a different source location. 6. Log Management 7. Script Management 8. Online help 8.1. Help on query syntax profile 8.2. Help on applicable queries 9. Implementation Limitations of ASIStant 9.1. Syntax and Run-Time Limitations 9.2. Default Parameters 9.3. Not Implemented ASIS Queries 9.4. Ambiguous ASIS Queries 9.5. Package Asis.Data_Decomposition 10. References 1. Introduction ASIStant, a contraction of ASIS Tester And iNTerpreter, pronounced like assistant, is an interactive ASIS interpreter with scripting and integrated ASIS Browser capability. It may be used for learning ASIS, i.e. the user may try out interactively the effects of the various ASIS queries. It might also be used as an assistant (sic!) when experimenting with ASIS queries, e.g. in order to find out a way of implementing a part of an ASIS application, or to correct it. ASIStant was developed jointly with ASIS-for-GNAT [1,2] and is extensively used during the debugging and testing of ASIS-for-GNAT implementation. ASIStant allows the user to call ASIS queries interactively. For this purpose a command language is provided. Commands may also be grouped in a script, and such a script can be called both interactively and in batch mode. Both the input and the output of a session can be logged in a file. The input commands can then be replayed in another session. Acknowledgments The original version of this tool, then called ASIStint, was developed as part of the collaboration between Software Engineering Laboratory of the Swiss Federal Institute of Technology in Lausanne, Switzerland, and the Scientific Research Computer Center of Moscow University, Russia, supported by a grant from the Swiss National Science Foundation, no 7SUPJ048247, funding a project "Development of ASIS for GNAT with industry quality" [3]. The original version of the ASIS Browser tool was created by Alain Le Guennec. 2. Launching ASIStant Provided that the executable for ASIStant is named "asistant", the command line syntax for ASIStant is asistant [-o] If no filename is specified, ASIStant enters the interactive mode and its command prompt appears. The key -o, followed by a number from 0 to 6, allows to change the amount of output to the screen. This is typically used in the batch mode to filter unnecessary output. When -o0 is specified, everything is displayed, while in -o6 mode, nothing. For explanation of other values, refer to 4.5.2.2. The following script enables logging the session to the file "dummy.log", initializes an ASIS environment and prepares the compilation unit "dummy" for further work: log ("dummy.log") -- log session to file "dummy.log". Initialize ("") -- initialize an ASIS environment; will call Asis.Implementation.- -- Initialize, and pass "" as parameter to this ASIS query. set (Ctx) -- create an undefined Asis.Context variable Ctx. Associate (Ctx, "", "") -- call Asis.Environments.Associate with empty strings as parameters; -- this call assigns the context by default to the previously created -- variable Ctx. Open (Ctx) -- call to Asis.Environments.Open with Ctx as a parameter. set (Dummy_Unit, Library_Unit_Declaration ("dummy", Ctx)) -- fetch the library unit "dummy" from the context Ctx; will call the -- Asis.Compilation_Units.Library_Unit_Declaration query. Although identifiers are not case-sensitive, we will use all small letters for identifiers of ASIStant-specific operations, i.e. log, set, and initial capital letters for ASIS queries, i.e. Initialize, Associate, Open, Library_Unit_Declaration, and for variable names, i.e. Ctx, Dummy_Unit. If the previous script is in a file named "dummy.scr", it can be launched automatically upon startup with the following command: asistant dummy.scr After finishing the script, ASIStant switches to command-line mode with the variables Ctx and Dummy_Unit properly initialized. ASIStant only interprets calls to ASIS queries, and it does not produce any calls to ASIS queries on its own. Therefore, to simulate the correct behavior of an ASIS application when working with ASIStant, one should follow the general rules given in the root package of the ASIS 95 specification. An ASIStant session should therefore start by initializing an ASIS implementation; then it should define a context variable and associate it with an Ada environment, called a context in ASIS; then the context must be opened, before issuing any query for it. NOTE: ASIStant is considered to be running in a special script mode when it is launched with the command asistant -o5 In this mode, ASIStant will quit whenever it would normally enter interactive mode (i.e. upon script errors or script termination). 3. General ASIStant Language Description The ASIStant command language is a simple functional language. An ASIStant program is a sequence of function calls, also called commands when at the level of the program. Function calls may take other function calls as arguments. The function Set allows the user to define an arbitrary number of variables of all ASIS types. In a command-line mode, a function call must fit on a single line. In a script, line breaks may appear wherever a blank space is allowed. There are no other formatting limitations: spaces, tabs and line terminators are not significant and can be present in any number. Ada-style comments are allowed: a comment starts with a double hyphen "--" and lasts to the end of the line. An ASIStant program can be stored on disk as a script file; there are no restrictions on script file names. Identifiers are not case sensitive. 4. Language Components 4.1. Data Types ASIStant supports the following predefined Ada types: Integer, Boolean, and String, but only with a limited set of operations (see 4.5.3.3.). All ASIS composite types are supported by ASIStant. All ASIS record types are implemented as private types in ASIStant. For these types, functions are provided for accessing their components; e.g. for the Asis.Span type, there are the service functions First_Line, First_Column, etc. that take a Span as a parameter and return the value of the corresponding component. The values of ASIS enumeration types are mapped to string literals, in conformance to the 'Image attribute. The values of the Ada.Calendar.Time type are represented by Strings. For variables of the ASIS list types, i.e. Element_List, etc., indexing is defined: () 4.2. Constants Literals for the predefined Ada types Integer, Boolean and String are supported. There are also predefined constants for the composite ASIS types, which have a nil value. The prefix Nil is used in their names: Nil_Element, Nil_Element_List, etc. 4.3. Variables ASIStant variables are used to store values returned from queries, in order to display them, and in order to pass them to subsequent calls. ASIStant variables can be of any ASIStant type. A variable name is an Ada-style identifier. Variables are created and assigned by the ASIStant Set utility. There are no predefined variables at the start of a session. The first (or the only) parameter of the Set utility must be a variable name. The second parameter (if any) is an ASIStant expression. ASIStant starts by creating dynamically a variable of the given name, if there is not yet such a variable. In any case, the variable inherits the type of the expression provided by the second parameter. Finally, the value of the expression is assigned to the variable. In one case, the Set utility has only one parameter. It is provided for creating a context variable, which is of a limited type and therefore cannot be initialized by means of an assignment. Thus the command set (My_Context) creates an undefined context variable My_Context which can then be initialized by a call to the Associate query. 4.4. Expressions An ASIStant expression is either an ASIStant constant, an ASIStant variable, an indexed ASIStant list variable, or an ASIStant function call. All ASIStant variables used in expressions should previously be (dynamically) initialized. 4.5. Function Calls An ASIStant function call follows the Ada syntax for a function call, but only positional parameter association is allowed. There are two kinds of functions: ASIS queries and ASIStant-specific functions, which are in turn divided into ASIStant utilities and ASIStant service functions. ASIStant function calls may have empty results, and are then procedures alike; this holds for all ASIStant utilities, but also for some ASIS queries, e.g. Initialize, Open, etc. A script is a sequence of function calls; the result of such a function call at the level of a script, also called a command, is always ignored. An ASIStant command may optionally be terminated by a semicolon. 4.5.1. ASIS Queries ASIStant supports all queries defined by ASIS 95, except for the generic procedure Traverse_Element which does not fit consistently in the interpretation-oriented concept. 4.5.2. ASIStant Utilities In this subsection means and means . 4.5.2.1. Help system Help Displays a list and a brief description of ASIStant utilities. Help () Displays the help specific to the . Info Displays ASIS and ASIStant technical information. 4.5.2.2. Environment control - Program exit: Quit [ () ] Exits the program, after setting the operating system execution environment variable to the value specified by the expression, which should be an integer expression, or to 0 if the expression is omitted. A script file to be used in batch mode should finish with a Quit command. - Log control: Log ("") Opens file and uses it for the session log. Log Closes the current log file. Loglevel () Sets the log control level to the natural value ; the default value is 1. All output is always displayed, but only output with a level higher or equal to the specified one is sent to the log file. The available control levels are: Level 5: ASIS exceptions, and Print output. Level 4: ASIStant warnings. Level 3: ASIStant standard messages. Level 2: Command prompts, and input logging. Level 1: Reserved for future extensions. Level 0: Internal ASIStant debugging information. NOTE: Regardless of the log control level, ASIStant keeps track of all I/O throughout the session in the files "input.log" (input) and "session.log" (input+output). Therefore, it is usually enough to set the log control level to 5. - Script control: Run ("") IRun ("") Launches the script in the file , reading further commands from it. Pause Pauses the current script, and switches to command mode. Run IRun Resumes the current script, which was previously paused. Exit Exits the script and returns to the calling script or to command mode. 4.5.2.3. Variable handling Set ( , ) For the first (dynamically) occurrence of the given ID, the corresponding ASIStant variable is created. ID is further used as its name. The type and the value of the variable is inherited from . If contains a call to an ASIS query that raises an exception, the variable is not created; any further reference to it is hence invalid. If the ASIStant variable ID already exists, its type and value are changed to those of . If contains a call to an ASIS query that raises an exception, the variable is not changed. can be of any ASIStant type, except Asis.Context. Set () Creates a variable with name of the type Asis.Context. 4.5.2.4. Output Print ( ) Displays the value of the expression : - For standard predefined types (Integer, Boolean and String) the value is directly displayed. - For ASIS.Text.Span type the value is displayed in the form (First_Line:First_Column)-(Last_Line:Last_Column) - For ASIS.Element type the value by default is displayed in the form where Element kind is the exact position of an Element in the ASIS Element classification hierarchy (e.g., An_Assignment_Statement, but not A_Statement), and position is represented by the span of the Element's text image. On demand, the Element's Debug_Image and Text Image may be displayed. This is controlled by the Printdetail utility (see below). - For ASIS.Compilation_Unit type and ASIS.Context type the value is displayed by means of Debug_Image query. - For ASIS.Element_List and ASIS.Compilation_Unit_List types, first the length of the list is displayed, and then the values of all its components Printdetail("{d|D}{t|T}") Switches display of additional information for Elements on or off. The parameter is the string of two characters "DT", both of which can be in the upper or lower case. 'D' controls the output of Debug_Image, and 'T' - the output of Text Image. The use of upper case switches the corresponding option on, and the lower case switches it off. The default is "dt". 4.5.2.5. Conditional execution If ( , [, ] ) Evaluates the boolean expression , and then executes if is True, and executes , if any, if is False. For example, set ( Debug, True ) if ( Debug, Initialize("-asisd"), Initialize("") ) -- switch on the ASIS-for-GNAT internal debugging mode depending -- on the state of the Debug flag There are no restrictions on the parts. Therefore, several If statements can be nested. The execution of another script can be conditionally started with a command like if ( Debug , run ("debug.scr") ) 4.5.3. ASIStant Service Functions 4.5.3.1. Access to components of ASIS record types - Asis.Span function First_Line (Sp: in Span) return Integer function First_Column (Sp: in Span) return Integer function Last_Line (Sp: in Span) return Integer function Last_Column (Sp: in Span) return Integer - Asis.Compilation_Units.Relations.Relationship function Consistent (R: in Relationship) return Compilation_Unit_List function Inconsistent (R: in Relationship) return Compilation_Unit_List function Missing (R: in Relationship) return Compilation_Unit_List function Circular (R: in Relationship) return Compilation_Unit_List 4.5.3.2. List handling function Length (L: in 'any ASIS list type') return Integer A set of overloaded queries for all ASIS list types, e.g. Compilation_Unit_List. 4.5.3.3. Functions for the types String, Boolean and Integer - String function Concat (S1, S2: in String) return String function Eq (S1, S2: in String) return Boolean function Lt (S1, S2: in String) return Boolean function Gt (S1, S2: in String) return Boolean - Boolean function Not (B: in Boolean) return Boolean function And (B1, B2: in Boolean) return Boolean function Or (B1, B2: in Boolean) return Boolean - Integer function Add (I1, I2: in Integer) return Integer function Sub (I1, I2: in Integer) return Integer function Eq (I1, I2: in Integer) return Boolean function Lt (I1, I2: in Integer) return Boolean function Gt (I1, I2: in Integer) return Boolean 4.5.3.4. Source location search capability The service function Find_Element allows to go to the innermost ASIS Element that corresponds to a given source location (SLOC). This function accepts three parameters, the first one, a Compilation_Unit corresponding to the source text, the second, SLOC line, and the third, SLOC column. It returns an Element that contains this SLOC or Nil_Element if none do or Nil_Compilation_Unit was supplied. If the column value supplied is outside the line bounds, the search of a deepest Element on this line is performed. This function is extremely helpful if a user wants to experiment with a certain fragment of the source text but would like to avoid having to build entire ASIS execution context that leads to the subtree he is interested in. 5. Browser capability 5.1. Access to the Browser capability from inside ASIStant Browser is invoked from the ASIStant command line by calling the ASIStant service function BROWSE. BROWSE disables the ASIStant command interpreter and enables the command interpreter of Browser. The Browser 'Q' command switches back into the ASIStant environment by enabling ASIStant command interpreter and disabling the Browser interpreter. BROWSE has a single parameter of Element type, and it starts browsing the ASIS tree starting from its argument Element. BROWSE returns the result of Element type, an Element on which the process of tree browsing was stopped. In the ASIStant environment Browse can be called as an ordinary ASIS query or ASIStant command. E.g. if a user types > set (e0, Browse (e1)) he will start ASIS tree browsing from e1, and when he finishes the browsing, e0 will represent the last Element being visited during the browsing. If a user types > Browse (e1) he will be able to browse the ASIS tree, but the last element of the browsing will be discarded. Additionally, a version that starts with a Compilation_Unit is supplied. Calling Browse for Compilation_Unit C is exactly equivalent to calling Browse for Unit_Declaration (C), but saves a lot of keystrokes. 5.2. Browser environment In a loop, the Browser displays (see 5.3.) the ASIS Element it currently points at and expects one of the following keystrokes: U - one step up the ASIS tree (equivalent to calling the ASIS Enclosing_Element query); D - one step down the ASIS tree, to the left-most component of the current Element N - go to the right sibling (to the next element in the ASIS tree hierarchy) P - go to the left sibling (to the previous element in the ASIS tree hierarchy) \