{Begin Chapter Masterscope}
{Title Masterscope}
{Text

{Begin Note}
Edited extensively 6/14/83 by jds.
Edited Wed, 20 Jul 83 10:39 PDT by Sannella
{End Note}

{Tag MasterScope}

{index *PRIMARY* Masterscope}

{note Masterscope was designed and implemented by L. M. Masinter.}


Masterscope is an interactive program for analyzing and cross referencing user programs.  It contains facilities for analyzing user functions to determine what other functions are called, how and where variables are bound, set, or referenced, as well as which functions use particular record declarations.  Masterscope is able to analyze definitions directly from a file as well as in-core definitions.


Masterscope maintains a database of the results of the analyses it performs.  Via a simple command language, the user may interrogate the database, call the editor on those expressions in functions that were analyzed which use variables or functions in a particular way, or display the tree structure of function calls among any set of functions.


Masterscope is interfaced with the editor and file package so that when a function is edited or a new definition loaded in, Masterscope knows that it must re-analyze that function.



The following sample session illustrates some of these facilities.


{Begin LispCode}
50←. ANALYZE FUNCTIONS ON RECORD
...............................
NIL
51←. WHO CALLS RECFIELDLOOK
(RECFIELDLOOK ACCESSDEF ACCESSDEF2 EDITREC)
52←. EDIT WHERE ANY CALL RECFIELDLOOK
RECFIELDLOOK :
(RECFIELDLOOK (CDR Y) FIELD)
tty:
5*OK  
ACCESSDEF :
(RECFIELDLOOK DECLST FIELD VAR1)
6*OK  
(RECFIELDLOOK USERRECLST FIELD)
7*N VAR1
8*OK
ACCESSDEF2 :
(RECFIELDLOOK (RECORD.SUBDECS TRAN) FIELD)
tty:
(RECFIELDLOOK (RECORD.SUBDECS TRAN) FIELD)
9*N (CAR TAIL]
10*OK  
EDITREC :
(RECFIELDLOOK USERRECLST (CAR EDITRECX))
11*OK 
NIL
53←. WHO CALLS ERROR
..
(EDITREC)
54←. SHOW PATHS TO RECFIELDLOOK FROM ACCESSDEF
(inverted tree)

1. RECFIELDLOOK RECFIELDLOOK
2.                   ACCESSDEF
3.                   ACCESSDEF2 ACCESSDEF2
4.                                     ACCESSDEF
5.                                     RECORDCHAIN ACCESSDEF
NIL
55←. WHO CALLS WHO IN /FNS
RECORDSTATEMENT --  /RPLNODE
RECORDECL1 --       /NCONC, /RPLACD, /RPLNODE
RECREDECLARE1 --    /PUTHASH
UNCLISPTRAN --      /PUTHASH, /RPLNODE2
RECORDWORD --       /RPLACA
RECORD1 --          /RPLACA, /SETTOPVAL
EDITREC --          /SETTOPVAL
{End LispCode}



{Begin Labeledlist explanations of Masterscope example}

{Label Statement 50}
{Text
The user directs that the functions on file {lisp RECORD} be analyzed.  The leading period and space specify that this line is a Masterscope command.  The user may also call Masterscope directly by typing {lisp (MASTERSCOPE)}.  Masterscope prints a greeting and prompts with "{lisp ←. }".  Within the top-level executive of Masterscope, the user may issue Masterscope commands, programmer's assistant commands, (e.g., {pacom REDO}, {pacom FIX}), or run programs.  The user can exit from the Masterscope executive by typing {lisp OK}.{index OK (Masterscope Command)}  The function {lisp .}{index . (in Masterscope)} is defined as a nlambda nospread function which interprets its argument as a Masterscope command, executes the command and returns.

Masterscope prints a {lisp .}{index . (printed by Masterscope)} whenever it (re)analyzes a function, to let the user know what it is happening.  The feedback when Masterscope analyzes a function is controlled by the flag {var MSPRINTFLG}{index MSPRINTFLG Var}: if {var MSPRINTFLG} is the atom "{lisp .}", Masterscope will print out a period.  (If an error in the function is detected, "{lisp ?}" is printed instead.)  If {var MSPRINTFLG} is a number {arg N}, Masterscope will print the name of the function it is analyzing every {arg N}th function.  If {var MSPRINTFLG} is {lisp NIL}, Masterscope won't print anything.  Initial setting is "{lisp .}".  Note that the function name is printed when Masterscope starts analyzing, and the comma is printed when it finishes.
}

{Label Statement 51}
{Text
The user asks which functions call {lisp RECFIELDLOOK}.  Masterscope responds with the list.
}



{Label Statement 52}
{Text
The user asks to edit the expressions where the function {lisp RECFIELDLOOK} is called.  Masterscope calls {fn EDITF} on the functions it had analyzed that call {lisp RECFIELDLOOK}, directing the editor to the appropriate expressions.  The user then edits some of those expressions.  In this example, the teletype editor is used.  If Dedit is enabled as the primary editor, it would be called to edit the appropriate functions (see {PageRef Term Dedit}).
}


{Label Statement 53}
{Text
Next the user asks which functions call {fn ERROR}.  Since some of the functions in the database have been changed, Masterscope re-analyzes the changed definitions (and prints out {lisp .}'s for each function it analyzes).  Masterscope responds that {fn EDITREC} is the only analyzed function that calls {fn ERROR}.
}

{Label Statement 54}
{Text
The user asks to see a map of the ways in which {lisp RECFIELDLOOK} is called from {lisp ACCESSDEF}.
A tree structure of the calls is displayed.
}

{Label Statement 55}
{Text
The user then asks to see which functions call which functions in the list {lisp /FNS}.  Masterscope responds with a structured printout of these relations.
}

{End Labeledlist explanations of Masterscope example}




{Begin note}
Masterscope "idioms" from talk with lmm:

. WHO USING X FREE IS NOT ON PATH FROM A

. WHO ON MYFILE CALLS ANY NOT @ GETD

. WHO ON MYFILE IS NOT ON PATH FROM ANY IN TOPFNS

. EDIT WHERE ANY ON MYFILE CALLS X - (IF (EQ (## 1) 'X)(GETD)(TTY:]
{End note}




{Include MSLang}



{Include MSorg}


}{End Chapter Masterscope}