1***************************** 2ASIS Interpreter ``asistant`` 3***************************** 4 5.. index:: asistant 6 7.. index:: ASIS queries 8 9This chapter describes ``asistant``, an interactive interface to ASIS queries. 10 11``asistant`` Introduction 12========================= 13 14The ``asistant`` tool allows you 15to use ASIS without building your own ASIS applications. It 16provides a simple command language that allows you to define variables of ASIS 17types and to assign them values by calling ASIS queries. 18 19This tool may be very useful while you are learning ASIS: 20it lets you try different ASIS queries and see the results immediately. 21It does not crash when there is an error in calling an ASIS query 22(such as passing an inappropriate ``Element``); instead ``asistant`` reports an 23error and lets you try again. 24 25You can also use ``asistant`` as a debug and 'ASIS visualization' tool in 26an ASIS application project. If you have problems 27finding out which query should be used in a given situation, or why a given 28query does not work correctly with a given piece of Ada code, you may use 29``asistant`` to reconstruct the situation that causes the problems, 30and then experiment with ASIS queries. 31 32.. index:: Script file (for asistant) 33 34Though primarily an interactive tool, ``asistant`` also can interpret 35sequences of commands written to a file (called a 'script file' 36below). The ``asistant`` tool can also store in a file the log of an interactive 37session that can then be reused as a script file. 38 39The full documentation of ``asistant`` may be found in the 40``asistant`` Users' Guide (file :file:`asistant.ug` in the ``asistant`` source directory). 41Here is a brief overview of ``asistant`` usage. 42 43.. index:: ASIS-for-GNAT 44 45The executable for ``asistant`` is created in the ``asistant`` 46source directory as a part of the standard procedure of installing 47ASIS-for-GNAT as an Ada library (or it is placed in the :file:`GNATPRO/bin` 48directory when installing ASIS from the binary distribution). Put this 49executable somewhere on your path (unless you have 50installed ASIS from the binary distribution, in which case the executable for 51``asistant`` has been added to other GNAT executables). 52Then type 53'``asistant``' to call ``asistant`` in an interactive mode. As a result, 54the program will output brief information about itself and then the 55``asistant`` prompt '``>``' will appear: 56 57 58:: 59 60 ASIStant - ASIS Tester And iNTerpreter, v1.2 61 (C) 1997-2002, Free Software Foundation, Inc. 62 Asis Version: ASIS 2.0.R 63 64 > 65 66 67Now you can input ``asistant`` commands (``asistant`` supports 68in its command language the same form of comments as Ada, and names in 69``asistant`` are not case-sensitive): 70 71 72.. code-block:: ada 73 74 >Initialize ("") -- the ASIS Initialize query is called with an 75 -- empty string as a parameter 76 77 >set (Cont) -- the non-initialized variable Cont of the ASIS 78 -- Context type is created 79 80 >Associate (Cont, "", "") -- the ASIS Associate query with two empty 81 -- strings as parameters is called for Cont 82 83 >Open (Cont) -- the ASIS Open query is called for Cont 84 85 >set (C_U, Compilation_Unit_Body ("Test", Cont)) -- the variable C_U 86 -- of the ASIS Compilation_Unit type is created and initialized as 87 -- the result of the call to the ASIS query Compilation_Unit_Body. 88 -- As a result, C_U will represent a compilation unit named "Test" 89 -- and contained in the ASIS Context named Cont 90 91 >set (Unit, Unit_Declaration (C_U)) -- the variable Unit of the ASIS 92 -- Element type is created and initialized as the result of calling 93 -- the ASIS Unit_Declaration query 94 95 >print (Unit) -- as a result of this command, some information about 96 -- the current value of Unit will be printed (a user can set 97 -- the desired level of detail of this information): 98 99 A_PROCEDURE_BODY_DECLARATION at ( 1 : 1 )-( 9 : 9 ) 100 101 -- suppose now, that we do make an error - we call an ASIS query for 102 -- an inappropriate element: 103 104 >set (Elem, Assignment_Expression (Unit)) 105 106 -- ASIS will raise an exception, asistant will output the ASIS debug 107 -- information: 108 109 Exception is raised by ASIS query ASSIGNMENT_EXPRESSION. 110 Status : VALUE_ERROR 111 Diagnosis : 112 Inappropriate Element Kind in Asis.Statements.Assignment_Expression 113 114 -- it does not change any of the existing variables and it prompts 115 -- a user again: 116 117 > ... 118 119 120``asistant`` commands 121===================== 122 123.. index:: asistant commands 124 125The list of ``asistant`` commands given in this section is incomplete; 126its purpose is only to give a general idea of ``asistant``'s capabilities. 127Standard metalanguage is assumed (i.e., '[*construct*]' 128denotes an optional instance of '*construct*'). 129 130 131 132*Help [(name)]* 133 134 .. index:: Help (asistant command) 135 136 Outputs the profile of the ASIS query '``name``'; when called with no argument, 137 generates general ``asistant`` help information. 138 139 140*Set (name)* 141 142 .. index:: Set (asistant command) 143 144 Creates a (non-initialized) variable '``name``' of the ASIS ``Context`` type. 145 146 147*Set (name, expr)* 148 Evaluates the expression '``expr``' (it may be any legal ``asistant`` 149 expression; a call to some ASIS query is the most common case in practice) 150 and creates the variable '``name``' of the type and with the value of 151 '``expr``'. 152 153 154*Print (expr)* 155 156 .. index:: Print (asistant command) 157 158 Evaluates the expression '``expr``' and outputs its value (some information may be 159 omitted depending on the level specified by the *PrintDetail* command). 160 161 162*Run* (:file:`filename`) 163 164 .. index:: Run (asistant command) 165 166 Launches the script from a file :file:`filename`, reading further commands from it. 167 168 .. index:: Script file (for asistant) 169 170 171*Pause* 172 173 .. index:: Pause (asistant command) 174 175 Pauses the current script and turns ``asistant`` into interactive mode. 176 177 178*Run* 179 Resumes a previously ``Pause``\ d script. 180 181 182*Browse* 183 184 .. index:: Browse (asistant command) 185 186 Switches ``asistant`` into step-by-step ASIS tree browsing. 187 188 189*Log* (:file:`filename`) 190 191 .. index:: Log (asistant command) 192 193 Opens the file :file:`filename` for session logging. 194 195 196*Log* 197 Closes the current log file. 198 199 200*PrintDetail* 201 202 .. index:: PrintDetail (asistant command) 203 204 Toggles whether the *Print* command outputs additional information. 205 206 207*Quit [(exit-status)]* 208 209 .. index:: Quit (asistant command) 210 211 Quits ``asistant``. 212 213``asistant`` variables 214====================== 215 216.. index:: asistant variables 217 218The ``asistant`` tool lets you define variables with Ada-style (simple) names. 219Variables can be of 220any ASIS type and of conventional ``Integer``, ``Boolean`` and ``String`` type. 221All the variables are created and assigned dynamically by the ``Set`` 222command; there are no predefined variables. 223 224There is no type checking in ``asistant``: each call to a ``Set`` 225command may be considered as creating the first argument from scratch and 226initializing it by the value provided by the second argument. 227 228Browsing an ASIS tree 229===================== 230 231.. index:: Browser (asistant utility) 232 233You perform ASIS tree browsing by invoking the ``asistant`` service function 234``Browse``. This will disable the ``asistant`` command interpreter 235and activate the Browser command interpreter. The Browser ``Q`` command 236switches back into the ``asistant`` environment by enabling the ``asistant`` 237command interpreter and disabling the Browser interpreter. 238 239``Browse`` has a single parameter of ``Element`` type, which establishes 240where the ASIS tree browsing will begin. 241``Browse`` returns a 242result of type ``Element``, namely the ``Element`` at which the tree browsing was 243stopped. Thus, if you type: 244 245 246.. code-block:: ada 247 248 > set (e0, Browse (e1)) 249 250 251you will start ASIS tree browsing from ``e1``; when you finish 252browsing, ``e0`` will represent the last ``Element`` visited during the 253browsing. 254 255If you type: 256 257 258.. code-block:: ada 259 260 > Browse (e1) 261 262 263you will be able to browse the ASIS tree, but the last ``Element`` of the 264browsing will be discarded. 265 266Browser displays the ASIS ``Element`` it currently points at and expects one of 267the following commands: 268 269 270 271*U* 272 Go one step up the ASIS tree (equivalent to calling the ASIS 273 ``Enclosing_Element`` query); 274 275 .. index:: Enclosing_Element query 276 277 278*D* 279 Go one step down the ASIS tree, to the left-most component of the current ``Element`` 280 281 282*N* 283 Go to the right sibling (to the next ``Element`` in the ASIS tree hierarchy) 284 285 286*P* 287 Go to the left sibling (to the previous ``Element`` in the ASIS tree hierarchy) 288 289 290*\\k1k2* 291 where ``k1`` is either ``D`` or ``d``, and 292 ``k2`` is either ``T`` or ``t``. 293 Change the form of displaying the current ``Element``: ``D`` turns ON displaying the 294 debug image, ``d`` turns it OFF. ``T`` turns ON displaying the text image, ``t`` 295 turns it OFF. 296 297 298*<SPACE><query>* 299 Call the <query> for the current ``Element``. 300 301 302*Q* 303 Go back to the ``asistant`` environment; the Browser command interpreter is 304 disabled and the ``asistant`` command interpreter is enabled with the 305 current ``Element`` returned as a result of the call to ``Browse``. 306 307Browser immediately interprets the keystroke and displays the new current 308``Element``. If the message ``"Cannot go in this direction."`` appears, this 309means that traversal in this direction from current node is impossible (that 310is, the current node is either a terminal ``Element`` and it is not possible to go 311down, or it is the leftmost or the rightmost component of some ``Element``, and 312it is not possible to go left or right, or it is the top ``Element`` in its 313enclosing unit structure and it is not possible to go up). 314 315It is possible to issue some ordinary ASIS queries from inside the Browser 316(for example, semantic queries). These queries should accept one parameter of 317type ``Element`` and return ``Element`` as a result. 318 319When you press ``<SPACE>``, you are asked to enter the query name. If the 320query is legal, the current ``Element`` is replaced by the result of the call to 321the given query with the current ``Element`` as a parameter. 322 323Example 324======= 325 326.. index:: ASIS Example 327 328Suppose we have an ASIS ``Compilation_Unit`` ``Demo`` in the source file :file:`demo.adb`: 329 330 331.. code-block:: ada 332 333 procedure Demo is 334 function F (I : Integer) return Integer; 335 336 function F (I : Integer) return Integer is 337 begin 338 return (I + 1); 339 end F; 340 341 N : Integer; 342 343 begin 344 N := F (3); 345 end Demo; 346 347 348Suppose also that the tree for this source is created in the current directory. 349Below is a sequence of ``asistant`` commands which does process this 350unit. Explanation is provided via ``asistant`` comments. 351 352 353.. code-block:: ada 354 355 initialize ("") 356 357 -- Create and open a Context comprising all the tree files 358 -- in the current directory: 359 360 Set (Cont) 361 Associate (Cont, "", "") 362 Open (Cont) 363 364 -- Get a Compilation_Unit (body) named "Demo" from this Context: 365 366 Set (CU, Compilation_Unit_Body ("Demo", Cont)) 367 368 -- Go into the unit structure and get to the expression 369 -- in the right part of the assignment statements in the unit body: 370 371 Set (Unit, Unit_Declaration (CU)) 372 Set (Stmts, Body_Statements (Unit, False)) 373 Set (Stmt, Stmts (1)) 374 Set (Expr, Assignment_Expression (Stmt)) 375 376 -- Output the debug image and the text image of this expression: 377 378 Print (Expr) 379 Print (Element_Image (Expr)) 380 381 -- This expression is of A_Function_Call kind, so it's possible to ask 382 -- for the declaration of the called function: 383 384 Set (Corr_Called_Fun, Corresponding_Called_Function (Expr)) 385 386 -- Print the debug and the text image of the declaration of the called 387 -- function: 388 389 Print (Corr_Called_Fun) 390 Print (Element_Image (Corr_Called_Fun)) 391 392 -- Close the asistant session: 393 394 Quit 395