{Begin SubSec Command Language}
{Title Command Language}
{Text
The user communicates with Masterscope using an English-like command language, e.g., {lisp WHO CALLS PRINT}. With these commands, the user can direct that functions be analyzed, interrogate Masterscope's database, and perform other operations. The commands deal with sets of functions, variables, etc., and relations between them (e.g., call, bind). Sets correspond to English nouns, relations to verbs.
A set of atoms can be specified in a variety of ways, either {it explicitly}, e.g., {lisp FUNCTIONS ON FIE} specifies the atoms in {lisp (FILEFNSLST 'FIE)}, or {it implicitly}, e.g., {lisp NOT CALLING Y}, where the meaning must be determined in the context of the rest of the command. Such sets of atoms are the basic building blocks which the command language deals with.
Masterscope also deals with relations {it between} sets. For example, the relation {lisp CALL} relates functions and other functions; the relations {lisp BIND} and {lisp USE FREELY} relate functions and variables. These relations are what get stored in the Masterscope database when functions are analyzed. In addition, Masterscope "knows" about file package conventions; {lisp CONTAIN} relates files and various types of objects (functions, variables).
Sets and relations are used (along with a few additional words) to form sentence-like {it commands}. For example, the command {lisp WHO ON 'FOO USE 'X FREELY} will print out the list of functions contained in the file {lisp FOO} which use the variable {lisp X} freely. The command {lisp EDIT WHERE ANY CALLS 'ERROR} will call {fn EDITF} on those functions which have previously been analyzed that directly call {fn ERROR}, pointing at each successive expression where the call to {fn ERROR} actually occurs.
{Begin SubSec Commands}
{Title Commands}
{Text
{index *PRIMARY* Masterscope commands}
The normal mode of communication with Masterscope is via "commands". These are sentences in the Masterscope command language which direct Masterscope to answer questions or perform various operations.
Note: any command may be followed by {index OUTPUT (Masterscope Command)}{lisp OUTPUT {arg FILENAME}} to send output to the given file rather than the terminal, e.g. {lisp WHO CALLS WHO OUTPUT CROSSREF}.
{Def {Type (Masterscope Command)}
{Name ANALYZE} {Args SET} {NoParens}
{Text
Analyze the functions in {arg SET} (and any functions called by them) and include the information gathered in the database. Masterscope will not re-analyzing a function if it thinks it already has valid information about that function in its database. The user may use the command {lisp REANALYZE} (below) to force re-analysis.
Note that whenever a function is referred to in a command as a "subject" of one of the relations, it is automatically analyzed; the user need not give an explicit {lisp ANALYZE} command. Thus, {lisp WHO IN MYFNS CALLS FIE} will automatically analyze the functions in {lisp MYFNS} if they have not already been analyzed.
Note also that only expr definitions will be analyzed; that is, Masterscope will not analyze compiled code. If necessary, the definition will be {fn DWIMIFY}ed before analysis. If there is no in-core definition for a function (either in the function definition cell or an {prop EXPR} property), Masterscope will attempt to read in the definition from a file. Files which have been explicitly mentioned previously in some command are searched first. If the definition cannot be found on any of those files, Masterscope looks among the files on {var FILELST} for a definition. If a function is found in this manner, Masterscope will print a message "{lisp (reading from {arg FILENAME})}". If no definition can be found at all, Masterscope will print a message "{lisp {arg FN} can't be analyzed}". If the function previously was known, the message "{lisp {arg FN} disappeared!}" is printed.
}}
{Def {Type (Masterscope Command)}
{Name REANALYZE} {Args SET} {NoParens}
{Text
Causes Masterscope to reanalyze the functions in {arg SET} (and any functions called by them) even if it thinks it already has valid information in its database. For example, this would be necessary if the user had disabled or subverted the file package, e.g. performed {fn PUTD}'s to change the definition of functions.
}}
{Def {Type (Masterscope Command)}
{Name ERASE} {Args SET} {NoParens}
{Text
Erase all information about the functions in {arg SET} from the database.
{lisp ERASE} by itself clears the entire database.
}}
{Def {Type (Masterscope Command)}
{Name SHOW PATHS} {Args PATHOPTIONS} {NoParens}
{Text
Displays a tree of function calls. This is described on {PageRef (Masterscope Command) SHOW PATHS}.
}}
{Def {Type (Masterscope Command)}
{Name RELATION}
{PrintName {lisp {arg SET} {arg RELATION} {arg SET}}}
}
{Def {Type (Masterscope Command)}
{Name IS}
{PrintName {lisp {arg SET} IS {arg SET}}}
}
{Def {Type (Masterscope Command)}
{Name ARE}
{PrintName {lisp {arg SET} ARE {arg SET}}}
{Text
This command has the same format as an English sentence with a subject (the first {arg SET}), a verb (the {arg RELATION} or {lisp IS} or {lisp ARE}), and an object (the second {arg SET}). Any of the {arg SET}s within the command may be preceded by the question determiners {lisp WHICH} or {lisp WHO} (or just {lisp WHO} alone). For example, {lisp WHICH FUNCTIONS CALL X} prints the list of functions that call the function {lisp X}. {arg RELATION} may be one of the relation words in present tense ({lisp CALL}, {lisp BIND}, {lisp TEST}, {lisp SMASH}, etc.) or used as a passive (e.g., {lisp WHO IS CALLED BY WHO}). Other variants are allowed, e.g. {lisp WHO DOES X CALL, IS FOO CALLED BY FIE}, etc.
The interpretation of the command depends on the number of question elements present:
(1) If there is {it no} question element, the command is treated as an assertion and Masterscope returns either {lisp T} or {lisp NIL}, depending on whether that assertion is true. Thus, {lisp ANY IN MYFNS CALL HELP} will print {lisp T} if any function in {lisp MYFNS} call the function {fn HELP}, and {lisp NIL} otherwise.
(2) If there is {it one} question element, Masterscope returns the list of items for which the assertion would be true. For example {lisp MYFN BINDS WHO USED FREELY BY YOURFN} prints the list of variables bound by {lisp MYFN} which are also used freely by {lisp YOURFN}.
(3) If there are two question elements, Masterscope will print a doubly indexed list:
{lispcode
←. WHO CALLS WHO IN /FNS{CRSYMBOL}
RECORDSTATEMENT -- /RPLNODE
RECORDECL1 -- /NCONC, /RPLACD, /RPLNODE
RECREDECLARE1 -- /PUTHASH
UNCLISPTRAN -- /PUTHASH, /RPLNODE2
RECORDWORD -- /RPLACA
RECORD1 -- /RPLACA, /SETTOPVAL
EDITREC -- /SETTOPVAL}
}}
{Def {Type (Masterscope Command)}
{Name EDIT WHERE} {Args SET RELATION SET [{lisp -} EDITCOMS]} {NoParens}
{Text
({lisp WHERE} may be omitted.) The first {arg SET} refers to a set of functions.
The {lisp EDIT} command calls the editor on each expression where the {arg RELATION} actually occurs. For example, {lisp EDIT WHERE ANY CALL ERROR} will call {fn EDITF} on each (analyzed) function which calls {fn ERROR} stopping within a {lisp TTY:} at each call to {fn ERROR}.
Currently one cannot {lisp EDIT WHERE} a file which {lisp CONTAINS} a datum, nor where one function {lisp CALLS} another {lisp SOMEHOW}.
{arg EDITCOMS}, if given, are a list of commands passed to {fn EDITF} to be performed at each expression.
For example, {lisp EDIT WHERE ANY CALLS MYFN DIRECTLY - (SW 2 3) P} will switch the first and second arguments to {lisp MYFN} in every call to {lisp MYFN} and print the result.
{lisp EDIT WHERE ANY ON MYFILE CALL ANY NOT @ GETD} will call the editor on any expression involving a call to an undefined function.
Note that {lisp EDIT WHERE X SETS Y} will point only at those expressions where {lisp Y} is actually set, and will skip over places where {lisp Y} is otherwise mentioned.
}}
{Def {Type (Masterscope Command)}
{Name SHOW WHERE} {Args SET RELATION SET} {NoParens}
{Text
Like the {lisp EDIT} command except merely prints out the expressions without calling the editor.
}}
{Def {Type (Masterscope Command)}
{Name EDIT} {Args SET [{lisp -} EDITCOMS]} {NoParens}
{Text
Calls {fn EDITF} on each function in {arg SET}.
{arg EDITCOMS}, if given, will be passed as a list of editor commands to be executed.
For example {lisp EDIT ANY CALLING FN1 - (R FN1 FN2)} will replace {lisp FN1} by {lisp FN2} in those functions that call {lisp FN1}.
}}
{Def {Type (Masterscope Command)}
{Name DESCRIBE} {Args SET} {NoParens}
{Text
Prints out the {lisp BIND}, {lisp USE FREELY} and {lisp CALL} information about the functions in {arg SET}.
For example, the command {lisp DESCRIBE PRINTARGS} might print out:
{lispcode
PRINTARGS[N,FLG]
binds: TEM,LST,X
calls: MSRECORDFILE,SPACES,PRIN1
called by: PRINTSENTENCE,MSHELP,CHECKER}
This shows that {lisp PRINTARGS} has two arguments, {lisp N} and {lisp FLG}, binds internally the variables {lisp TEM}, {lisp LST} and {lisp X}, calls {lisp MSRECORDFILE}, {lisp SPACES} and {lisp PRIN1} and is called by {lisp PRINTSENTENCE}, {lisp MSHELP}, and {lisp CHECKER}.
The user can specify additional information to be included in the description. {var DESCRIBELST}{index DESCRIBELST Var} is a list each of whose elements is a list containing a descriptive string and a form. The form is evaluated (it can refer to the name of the funtion being described by the free variable {index FN Var}{var FN}); if it returns a non-{lisp NIL} value, the description string is printed followed by the value. If the value is a list, its elements are printed with commas between them. For example, the entry {lisp ("types: " (GETRELATION FN '(USE TYPE) T)} would include a listing of the types used by each function.
}}
{Def {Type (Masterscope Command)}
{Name CHECK} {Args SET} {NoParens}
{Text
Checks for various anomolous conditions (mainly in the compiler declarations) for the files in {arg SET} (if {arg SET} is not given, {var FILELST} is used). For example, this command will warn about variables which are bound but never referenced, functions in {lisp BLOCKS} delarations which aren't on the file containing the declaration, functions declared as {lisp ENTRIES} but not in the block, variables which may not need to be declared {lisp SPECVARS} because they are not used freely below the places where they are bound, etc.
}}
{Def {Type (Masterscope Command)}
{Name FOR} {Args VARIABLE SET I.S.TAIL} {NoParens}
{Text
This command provides a way of combining {lisp CLISP} iterative statements with Masterscope. An iterative statement will be constructed in which {arg VARIABLE} is iteratively assigned to each element of {arg SET}, and then the iterative statement tail {arg I.S.TAIL} is executed. For example,
{lispcode FOR X CALLED BY FOO WHEN CCODEP DO (PRINTOUT T X ,,, (ARGLIST X) T)}
will print out the name and argument list of all of the compiled functions which are called by {lisp FOO}.
}}
}{End SubSec Commands}
{Begin SubSec Relations}
{Title Relations}
{Text
{index *PRIMARY* Relations in Masterscope}
A relation is specified by one of the keywords below. Some of these "verbs" accept modifiers. For example, {lisp USE}, {lisp SET}, {lisp SMASH} and {lisp REFERENCE} all may be modified by {lisp FREELY}. The modifier may occur anywhere within the command. If there is more than one verb, any modifier {it between} two verbs is assumed to modify the first one. For example, in {lisp USING ANY FREELY OR SETTING X}, the {lisp FREELY} modifies {lisp USING} but not {lisp SETTING}; the entire phrase is interpreted as the set of all functions which either use any variable freely or set the variable {lisp X}, whether or not {lisp X} is set freely. Verbs can occur in the present tense (e.g., {lisp USE}, {lisp CALLS}, {lisp BINDS}, {lisp USES}) or as present or past participles (e.g., {lisp CALLING}, {lisp BOUND}, {lisp TESTED}). The relations (with their modifiers) recognized by Masterscope are:
{Def {Type (Masterscope Relation)} {Name CALL}
{Text
Function {lisp F1} calls {lisp F2} if the definition of {lisp F1} contains a form {lisp (F2 --)}. The {lisp CALL} relation also includes any instance where a function uses a name as a function, as in {lisp (APPLY (QUOTE F2) --)}, {lisp (FUNCTION F2)}, etc.
}}
{Def {Type (Masterscope Relation)} {Name CALL SOMEHOW}
{Text
One function calls another {lisp SOMEHOW} if there is some path from the first to the other. That is, if {lisp F1} calls {lisp F2}, and {lisp F2} calls {lisp F3}, then {lisp F1 CALLS F3 SOMEHOW}.
This information is not stored directly in the database; instead, Masterscope stores only information about direct function calls, and (re)computes the {lisp CALL SOMEHOW} relation as necessary.
}}
{Def {Type (Masterscope Relation)} {Name USE}
{Text
If unmodified, the relation {lisp USE} denotes variable usage in any way; it is the union of the relations {lisp SET}, {lisp SMASH}, {lisp TEST}, and {lisp REFERENCE}.
}}
{Def {Type (Masterscope Relation)} {Name SET}
{Text
A function {lisp SET}s a variable if the function contains a form {lisp (SETQ var --)}, {lisp (SETQQ var --)}, etc.
}}
{Def {Type (Masterscope Relation)} {Name SMASH}
{Text
A function {lisp SMASH}es a variable if the function calls a destructive list operation ({fn RPLACA}, {fn RPLACD}, {fn DREMOVE}, {fn SORT}, etc.) on the value of that variable. Masterscope will also find instances where the operation is performed on a "part" of the value of the variable; for example, if a function contains a form {lisp (RPLACA (NTH X 3) T)} it will be noted as {lisp SMASHING X}.
Note that if the function contains a sequence {lisp (SETQ Y X)}, {lisp (RPLACA Y T)} then {lisp Y} is noted as being smashed, but not {lisp X}.
}}
{Def {Type (Masterscope Relation)} {Name TEST}
{Text
A variable is {lisp TEST}ed by a function if its value is only distinguished between {lisp NIL} and non-{lisp NIL}. For example, the form {lisp (COND ((AND X --) --))} {it tests} the value of {lisp X}.
}}
{Def {Type (Masterscope Relation)} {Name REFERENCE}
{Text
This relation includes all variable usage {it except} for {lisp SET}.
}}
The verbs {lisp USE}, {lisp SET}, {lisp SMASH}, {lisp TEST} and {lisp REFERENCE} may be modified by the words {lisp FREELY} or {lisp LOCALLY}.{index FREELY (use in Masterscope)}{index LOCALLY (use in Masterscope)} A variable is used {lisp FREELY} if it is not bound in the function at the place of its use; alternatively, it is used {lisp LOCALLY} if the use occurs within a {lisp PROG} or {lisp LAMBDA} that binds the variable.
Masterscope also distinguishes between {lisp CALL DIRECTLY}{index CALL DIRECTLY (Masterscope Relation)} and {lisp CALL INDIRECTLY}.{index CALL INDIRECTLY (Masterscope Relation)} A function is called {lisp DIRECTLY} if it occurs as {fn CAR}-of-form in a normal evaluation context. A function is called {lisp INDIRECTLY} if its name appears in a context which does not imply its {it immediate} evaluation, for example {lisp (SETQ Y (LIST (FUNCTION FOO) 3))}. The distinction is whether or not the compiled code of the caller would contain a direct call to the callee. Note that an occurrence of {lisp (FUNCTION FOO)} as the functional argument to one of the built-in mapping functions which compile open is considered to be a direct call.
In addition, {lisp CALL FOR EFFECT}{index CALL FOR EFFECT (Masterscope Relation)} (where the value of the function is not used) is distinguished from {lisp CALL FOR VALUE}.{index CALL FOR VALUE (Masterscope Relation)}
{Def {Type (Masterscope Relation)} {Name BIND}
{Text
The {lisp BIND} relation between functions and variables includes both variables bound as function arguments and those bound in an internal {fn PROG} or {lisp LAMBDA} expression.
}}
{Def {Type (Masterscope Relation)} {Name USE AS A FIELD}
{Text
Masterscope notes all uses of record field names within {lisp FETCH}, {lisp REPLACE} or {lisp CREATE} expressions.
}}
{Def {Type (Masterscope Relation)} {Name FETCH}
{Text
Use of a field within a {lisp FETCH} expression.
}}
{Def {Type (Masterscope Relation)} {Name REPLACE}
{Text
Use of a record field name within a {lisp REPLACE} or {lisp CREATE} expression.
}}
{Def {Type (Masterscope Relation)} {Name USE AS A RECORD}
{Text
Masterscope notes all uses of record names within {lisp CREATE} or {lisp TYPE?} expressions. Additionally, in {lisp (fetch (FOO FIE) of X)}, {lisp FOO} is used as a record name.
}}
{Def {Type (Masterscope Relation)} {Name CREATE}
{Text
Use of a record name within a {lisp CREATE} expression.
}}
{Def {Type (Masterscope Relation)} {Name USE AS A PROPERTY NAME}
{Text
Masterscope notes the property names used in {fn GETPROP}, {fn PUTPROP}, {fn GETLIS}, etc. expressions if the name is quoted. E.g. if a function contains a form {lisp (GETPROP X (QUOTE INTERP))}, then that function {lisp USE}s {lisp INTERP} as a property name.
}}
{Def {Type (Masterscope Relation)} {Name USE AS A CLISP WORD}
{Text
Masterscope notes all iterative statement operators and user defined CLISP words as being used as a CLISP word.
}}
{Def {Type (Masterscope Relation)} {Name CONTAIN}
{Text
Files {it contain} functions, records, and variables. This relation is not stored in the database but is computed using the file package.
}}
{Def {Type (Masterscope Relation)} {Name DECLARE AS LOCALVAR}}
{Def {Type (Masterscope Relation)} {Name DECLARE AS SPECVAR}
{Text
Masterscope notes internal "calls" to {fn DECLARE} from within functions.
}}
The following abbreviations are recognized:
{lisp FREE}={lisp FREELY}, {lisp LOCAL}={lisp LOCALLY}, {lisp PROP}={lisp PROPERTY}, {lisp REF}={lisp REFERENCE}. Also, the words {lisp A}, {lisp AN} and {lisp NAME} (after {lisp AS}) are "noise" words and may be omitted.
Note: Masterscope uses "templates" ({PageRef Tag Templates}) to decide which relations hold between functions and their arguments. For example, the information that {fn SORT} {lisp SMASH}es its first argument is contained in the template for {lisp SORT}. Masterscope initially contains templates for most system functions which set variables, test their arguments, or perform destructive operations. The user may change existing templates or insert new ones in Masterscope's tables via the {fn SETTEMPLATE} function ({PageRef Fn SETTEMPLATE}).
}{End SubSec Relations}
{Begin SubSec Set Specifications}
{Title Set Specifications}
{Text
{index *PRIMARY* Sets in Masterscope}
A "set" is a collection of things (functions, variables, etc.). A set is specified by a set phrase, consisting of a {it determiner} (e.g., {lisp ANY}, {lisp WHICH}, {lisp WHO}) followed by a {it type} (e.g., {lisp FUNCTIONS}, {lisp VARIABLES}) followed by a {it specification} (e.g., {lisp IN MYFNS}, {lisp @ SUBRP}). The determiner, type and specification may be used alone or in combination.
For example, {lisp ANY FUNCTIONS IN MYFNS}, {lisp ANY @ SUBRP}, {lisp VARIABLES IN GLOBALVARS}, and {lisp WHO} are all acceptable set phrases. Set specifications are explained below:
{index *PRIMARY* Set specifications in Masterscope}
{Def {Type (Masterscope Set Specification)} {Name '}
{PrintName {lisp '{arg ATOM}}}
{Text
The simplest way to specify a set consisting of a single thing is by the name of that thing. For example, in the command {lisp WHO CALLS 'ERROR}, the function {fn ERROR} is referred to by its name. Although the {lisp '} can be left out, to resolve possible ambiguities names should usually be quoted; e.g., {lisp WHO CALLS 'CALLS} will return the list of functions which call the function {fn CALLS}.
}}
{Def {Type (Masterscope Set Specification)} {Name '}
{PrintName {lisp '{arg LIST}}}
{Text
Sets consisting of several atoms may be specified by naming the atoms. For example, the command {lisp WHO USES '(A B)} returns the list of functions that use the variables {lisp A} or {lisp B}.
}}
{Def {Type (Masterscope Set Specification)}
{Name IN} {Args EXPRESSION} {NoParens}
{Text
The form {arg EXPRESSION} is evaluated, and its value is treated as a list of the elements of a set. For example, {lisp IN GLOBALVARS} specifies the list of variables in the value of the variable {var GLOBALVARS}.
}}
{Def {Type (Masterscope Set Specification)}
{Name @} {Args PREDICATE} {NoParens}
{Text
A set may also be specified by giving a predicate which the elements of that set must satisfy. {arg PREDICATE} is either a function name, a {lisp LAMBDA} expression, or an expression in terms of the variable {lisp X}. The specification {lisp @ {arg PREDICATE}} represents all atom for which the value of {arg PREDICATE} is non-{lisp NIL}. For example, {lisp @ EXPRP} specifies all those atoms which have expr definitions; {lisp @ (STRPOSL X CLISPCHARRAY)} specifies those atoms which contain CLISP characters. The universe to be searched is either determined by the context within the command (e.g., in {lisp WHO IN FOOFNS CALLS ANY NOT @ GETD}, the predicate is only applied to functions which are called by any functions in the list {lisp FOOFNS}), or in the extreme case, the universe defaults to the entire set of things which have been noticed by Masterscope, as in the command {lisp WHO IS @ EXPRP}.
}}
{Def {Type (Masterscope Set Specification)}
{Name LIKE} {Args ATOM} {NoParens}
{Text
{arg ATOM} may contain {lisp ESC}s; it is used as a pattern to be matched (as in the editor). For example, {lisp WHO LIKE /R$ IS CALLED BY ANY} would find both {lisp /RPLACA} and {lisp /RPLNODE}.
}}
A set may also be specified by giving a relation its members must have with the members of another set:
{Def {Type (Masterscope Set Specification)}
{Name ING} {PrintName {lisp {arg RELATION}ING {arg SET}}}
{Text
{lisp {arg RELATION}ING} is used here generically to mean any of the relation words in the present participle form (possibly with a modifier), e.g., {lisp USING}, {lisp SETTING}, {lisp CALLING}, {lisp BINDING}. {lisp {arg RELATION}ING {arg SET}} specifies the set of all objects which have that relation with some element of {arg SET}. For example, {lisp CALLING X} specifies the set of functions which call the function {lisp X}; {lisp USING ANY IN FOOVARS FREELY} specifies the set of functions which uses freely any variable in the value of {lisp FOOVARS}.
}}
{Def {Type (Masterscope Set Specification)}
{Name ED BY} {PrintName {lisp {arg RELATION}ED BY {arg SET}}}
}
{Def {Type (Masterscope Set Specification)}
{Name ED IN} {PrintName {lisp {arg RELATION}ED IN {arg SET}}}
{Text
This is similar to the {lisp {arg RELATION}ING} construction.
For example, {lisp CALLED BY ANY IN FOOFNS} represents the set of functions which are called by any element of {lisp FOOFNS}; {lisp USED FREELY BY ANY CALLING ERROR} is the set of variables which are used freely by any function which also calls the function {fn ERROR}.
}}
{Def {Type (Masterscope Set Specification)} {Name OF}
{PrintName {lisp {arg BLOCKTYPE} OF {arg FUNCTIONS}}}
}
{Def {Type (Masterscope Set Specification)} {Name ON}
{PrintName {lisp {arg BLOCKTYPE} ON {arg FILES}}}
{Text
These phrases allow the user to ask about {lisp BLOCKS} declarations on files (see {PageRef Tag BlockDeclarations}). {arg BLOCKTYPE} is one of {lisp LOCALVARS}, {lisp SPECVARS}, {lisp GLOBALVARS}, {lisp ENTRIES}, {lisp BLKFNS}, {lisp BLKAPPLYFNS}, or {lisp RETFNS}.
{index LOCALVARS (in Masterscope Set Specification)}
{index SPECVARS (in Masterscope Set Specification)}
{index GLOBALVARS (in Masterscope Set Specification)}
{index ENTRIES (in Masterscope Set Specification)}
{index BLKFNS (in Masterscope Set Specification)}
{index BLKAPPLYFNS (in Masterscope Set Specification)}
{index RETFNS (in Masterscope Set Specification)}
{lisp {arg BLOCKTYPE} OF {arg FUNCTIONS}} specifies the names which are declared to be {arg BLOCKTYPE} in any blocks declaration which contain any of {arg FUNCTIONS} (a "set" of functions). The "functions" in {arg FUNCTIONS} can either be block names or just functions in a block. For example, {lisp WHICH ENTRIES OF ANY CALLING 'Y BIND ANY GLOBALVARS ON 'FOO}.
{lisp {arg BLOCKTYPE} ON {arg FILES}} specifies all names which are declared to be {arg BLOCKTYPE} on any of the given {arg FILES} (a "set" of files).
}}
{Def {Type (Masterscope Set Specification)}
{Name FIELDS OF} {Args SET} {NoParens}
{Text
{arg SET} is a set of records.
This denotes the field names of those records. For example, the command {lisp WHO USES ANY FIELDS OF BRECORD} returns the list of all functions which do a {lisp fetch} or {lisp replace} with any of the field names declared in the record declaration of {lisp BRECORD}.
}}
{Def {Type (Masterscope Set Specification)} {Name KNOWN}
{Text
The set of all functions which have been analyzed.
For example, the command {lisp WHO IS KNOWN} will print out the list of functions which have been analyzed.
}}
{Def {Type (Masterscope Set Specification)} {Name THOSE}
{Text
The set of things printed out by the last Masterscope question.
For example, following the command {lisp WHO IS USED FREELY BY PARSE}, the user could ask {lisp WHO BINDS THOSE} to find out where those variables are bound.
}}
{Def {Type (Masterscope Set Specification)}
{Name ON PATH} {Args PATHOPTIONS} {NoParens}
{Text
Refers to the set of functions which {it would be} printed by the command {lisp SHOW PATHS {arg PATHOPTIONS}}. For example, {lisp IS FOO BOUND BY ANY ON PATH TO 'PARSE} tests if FOO might be bound "above" the function {lisp PARSE}. {lisp SHOW PATHS} is explained in detail on {PageRef (Masterscope Command) SHOW PATHS}.
}}
Note: sets may also be specified with "relative clauses" introduced by the word {lisp THAT}, e.g. {lisp THE FUNCTIONS THAT BIND 'X}.
}{End SubSec Set Specifications}
{Begin SubSec Set Determiners}
{Title Set Determiners}
{Text
{index *PRIMARY* Determiners in Masterscope}
Set phrases may be preceded by a {it determiner}. A determiner is one of the words {lisp THE}, {lisp ANY}, {lisp WHO} or {lisp WHICH}. The "question" determiners ({lisp WHO} and {lisp WHICH}) are only meaningful in some of the commands, namely those that take the form of questions. {lisp ANY} and {lisp WHO} (or {lisp WHOM}) can be used alone; they are "wild-card" elements, e.g., the command {lisp WHO USES ANY FREELY}, will print out the names of all (known) functions which use any variable freely. If the determiner is omitted, {lisp ANY} is assumed; e.g. the command {lisp WHO CALLS '(PRINT PRIN1 PRIN2)} will print the list of functions which call {it any} of {fn PRINT}, {fn PRIN1}, {fn PRIN2}. {lisp THE} is also allowed, e.g. {lisp WHO USES THE RECORD FIELD FIELDX.}
}{End SubSec Set Determiners}
{Begin SubSec Set Types}
{Title Set Types}
{Text
{index *PRIMARY* Types in Masterscope}
Any set phrase has a {it type}; that is, a set may specify either functions, variables, files, record names, record field names or property names. The type may be determined by the context within the command (e.g., in {lisp CALLED BY ANY ON FOO}, the set {lisp ANY ON FOO} is interpreted as meaning the {it functions} on {lisp FOO} since only functions can be {lisp CALLED}), or the type may be given explicitly by the user (e.g., {lisp FUNCTIONS ON FIE}). The following types are recognized: {lisp FUNCTIONS}, {lisp VARIABLES}, {lisp FILES}, {lisp PROPERTY NAMES}, {lisp RECORDS}, {lisp FIELDS}, {lisp I.S.OPRS}. Also, the abbreviations {lisp FNS}, {lisp VARS}, {lisp PROPNAMES} or the singular forms {lisp FUNCTION}, {lisp FN}, {lisp VARIABLE}, {lisp VAR}, {lisp FILE}, {lisp PROPNAME}, {lisp RECORD}, {lisp FIELD} are recognized. Note that most of these types correspond to built-in "file package types" (see {PageRef Tag FilePkgTypes}).
The type is used by Masterscope in a variety of ways when interpreting the set phrase:
(1) Set types are used to disambiguate possible parsings. For example, both commands {lisp WHO SETS ANY BOUND IN X OR USED BY Y} and {lisp WHO SETS ANY BOUND IN X OR CALLED BY Y} have the same general form. However, the first case is parsed as {lisp WHO SETS ANY (BOUND BY X OR USED BY Y)} since both {lisp BOUND BY X} and {lisp USED BY Y} refer to variables; while the second case as {lisp WHO SETS ANY BOUND IN (X OR CALLED BY Y)}, since {lisp CALLED BY Y} and {lisp X} must refer to functions. Note that parentheses may be used to group phrases.{note put this somewhere else?}
(2) The type is used to determine the modifier for {lisp USE}: {lisp FOO USES WHICH RECORDS} is equivalent to {lisp FOO USES WHO AS A RECORD FIELD}.
(3) The interpretation of {lisp CONTAIN} depends on the type of its object: the command {lisp WHAT FUNCTIONS ARE CONTAINED IN MYFILE} prints the list of functions in {lisp MYFILE}; {lisp WHAT RECORDS ARE ON MYFILE} prints the list of records.
(4) The implicit "universe" in which a set expression is interpreted depends on the type: {lisp ANY VARIABLES @ GETD} is interpreted as the set of all variables which have been noticed by Masterscope (i.e., bound or used in any function which has been analyzed) that also have a definition. {lisp ANY FUNCTIONS @ (NEQ (GETTOPVAL X) 'NOBIND)} is interpreted as the set of all functions which have been noticed (either analyzed or called by a function which has been analyzed) that also have a top-level value.
}{End SubSec Set Types}
{Begin SubSec Conjunctions of Sets}
{Title Conjunctions of Sets}
{Text
{index *PRIMARY* Conjunctions in Masterscope}
Sets may be joined by the conjunctions {lisp AND} and {lisp OR} or preceded by {lisp NOT} to form new sets. {lisp AND} is always interpreted as meaning "intersection"; {lisp OR} as "union", while {lisp NOT} means "complement". For example, the set {lisp CALLING X AND NOT CALLED BY Y} specifies the set of all functions which call the function {lisp X} but are not called by {lisp Y}.
Masterscope's interpretation of {lisp AND} and {lisp OR} follow LISP conventions rather than the conventional English interpretation. For example "calling {lisp X} and {lisp Y}" would, in English, be interpreted as the intersection of {lisp (CALLING X)} and {lisp (CALLING Y)}; but Masterscope interprets {lisp CALLING X AND Y} as {lisp CALLING ('X AND 'Y)}; which is the null set. Only sets may be joined with conjunctions: joining modifiers, as in {lisp USING X AS A RECORD FIELD OR PROPERTY NAME}, is not allowed; in this case, the user must say {lisp USING X AS A RECORD FIELD OR USING X AS A PROPERTY NAME}.
As described above, the type of sets is used to disambiguate parsings. The algorithm used is to first try to match the type of the phrases being joined and then try to join with the longest preceding phrase. In any case, the user may group phrases with parentheses to specify the manner in which conjunctions should be parsed.
}{End SubSec Conjunctions of Sets}
}{End SubSec Command Language}
{Begin SubSec SHOW PATHS}
{Title SHOW PATHS}
{Text
{index *PRIMARY* Paths in Masterscope}
{index *PRIMARY* SHOW PATHS (Masterscope Command)}
In trying to work with large programs, the user can lose track of the hierarchy of functions. The Masterscope {lisp SHOW PATHS} command{index SHOW PATHS (Masterscope Command)} aids the user by providing a map showing the calling structure of a set of functions. {lisp SHOW PATHS} prints out a tree structure showing which functions call which other functions. For example, the command {lisp SHOW PATHS FROM MSPARSE} will print out the structure of Masterscope's parser:
{Begin LispCode}
1.MSPARSE MSINIT MSMARKINVALID
2. | MSINITH MSINITH
3. MSINTERPRET MSRECORDFILE
4. | MSPRINTWORDS
5. | PARSECOMMAND GETNEXTWORD CHECKADV
6. | | PARSERELATION {bracket a}
7. | | PARSESET {bracket b}
8. | | PARSEOPTIONS {bracket c}
9. | | MERGECONJ GETNEXTWORD {bracket 5}
10. | GETNEXTWORD {bracket 5}
11. | FIXUPTYPES SUBJTYPE
12. | | OBJTYPE
13. | FIXUPCONJUNCTIONS MERGECONJ {bracket 9}
14. | MATCHSCORE
15. MSPRINTSENTENCE
------------------------------------------------------ overflow - a
16.PARSERELATION GETNEXTWORD {bracket 5}
17. CHECKADV
------------------------------------------------------ overflow - b
19.PARSESET PARSESET
20. GETNEXTWORD {bracket 5}
21. PARSERELATION {bracket 6}
22. SUBPARSE GETNEXTWORD {bracket 5}
------------------------------------------------------ overflow - c
23.PARSEOPTIONS GETNEXTWORD {bracket 5}
24. PARSESET {bracket 19}
{End LispCode}
The above printout displays that the function {lisp MSPARSE} calls {lisp MSINIT}, {lisp MSINTERPRET}, and {lisp MSPRINTSENTENCE}. {lisp MSINTERPRET} in turn calls {lisp MSRECORDFILE}, {lisp MSPRINTWORDS}, {lisp PARSECOMMAND}, {lisp GETNEXTWORD}, {lisp FIXUPTYPES}, and {lisp FIXUPCONJUNCTIONS}. The numbers in braces {lisp {lbracket}{rbracket}} after a function name are backward references: they indicate that the tree for that function was expanded on a previous line. The lowercase letters in braces are {it forward} references: they indicate that the tree for that function will be expanded below, since there is no more room on the line. The vertical bar is used to keep the output aligned.
Note: Loading the Browser library package modifies the {lisp SHOW PATHS} command so the command's output is displayed as an undirected graph.
{index *PRIMARY* Path options in Masterscope}
The {lisp SHOW PATHS} command takes the form: {lisp SHOW PATHS} followed by some combination of the following {it path options:}
{Def {Type (Masterscope Path Option)} {Name FROM} {Args SET} {NoParens}
{Text
Display the function calls from the elements of {arg SET}.
}}
{Def {Type (Masterscope Path Option)} {Name TO} {Args SET} {NoParens}
{Text
Display the function calls leading {it to} elements of {arg SET}. If {lisp TO} is given before {lisp FROM} (or no {lisp FROM} is given), the tree is "inverted" and a message, {lisp (inverted tree)} is printed to warn the user that if {lisp FN1} appears after {lisp FN2} it is because {lisp FN1} is {it called by} {lisp FN2}.
}}
When both {lisp FROM} and {lisp TO} are given, the first one indicates a set of functions which are to be displayed while the second restricts the paths that will be traced; i.e., the command {lisp SHOW PATHS FROM X TO Y} will trace the elements of the set {lisp CALLED SOMEHOW BY X AND CALLING Y SOMEHOW}.
If {lisp TO} is not given, {lisp TO KNOWN OR NOT @ GETD} is assumed; that is, only functions which have been analyzed or which are undefined will be included. Note that Masterscope will analyze a function while printing out the tree if that function has not previously been seen and it currently has an expr definition; thus, any function which {it can be} analyzed will be displayed.
{Def {Type (Masterscope Path Option)} {Name AVOIDING} {Args SET} {NoParens}
{Text
Do not display any function in {arg SET}. {lisp AMONG} is recognized as a synonym for {lisp AVOIDING NOT}.{index AMONG (Masterscope Path Option)} For example, {lisp SHOW PATHS TO ERROR AVOIDING ON FILE2} will not display (or trace) any function on {lisp FILE2}.
}}
{Def {Type (Masterscope Path Option)} {Name NOTRACE} {Args SET} {NoParens}
{Text
Do not trace from any element of {arg SET}. {lisp NOTRACE} differs from {lisp AVOIDING} in that a function which is marked {lisp NOTRACE} will be printed, but the tree beyond it will not be expanded; the functions in an {lisp AVOIDING} set will not be printed at all. For example, {lisp SHOW PATHS FROM ANY ON FILE1 NOTRACE ON FILE2} will display the tree of calls eminating from {lisp FILE1}, but will not expand any function on {lisp FILE2}.
}}
{Def {Type (Masterscope Path Option)} {Name SEPARATE} {Args SET} {NoParens}
{Text
Give each element of {arg SET} a separate tree. Note that {lisp FROM} and {lisp TO} only insure that the designated functions will be displayed. {lisp SEPARATE} can be used to guarantee that certain functions will begin new tree structures. {lisp SEPARATE} functions are displayed in the same manner as overflow lines; i.e., when one of the functions indicated by {lisp SEPARATE} is found, it is printed followed by a forward reference (a lower-case letter in braces) and the tree for that function is then expanded below.
}}
{Def {Type (Masterscope Path Option)} {Name LINELENGTH} {Args N} {NoParens}
{Text
Resets {fn LINELENGTH} to {arg N} before displaying the tree. The linelength is used to determine when a part of the tree should "overflow" and be expanded lower.
}}
}{End SubSec SHOW PATHS}
{Begin SubSec Error Messages}
{Title Error Messages}
{Text
When the user gives Masterscope a command, the command is first parsed, i.e. translated to an internal representation, and then the internal representation is interpreted. If a command cannot be parsed, e.g. if the user typed {lisp SHOW WHERE CALLED BY X}, the message "{lisp Sorry, I can't parse that!}"{index SORRY, I CAN'T PARSE THAT Error} is printed and an error is generated. If the command is of the correct form but cannot be interpreted (e.g., the command {lisp EDIT WHERE ANY CONTAINS ANY}) Masterscope will print the message "{lisp Sorry, that isn't implemented!}"{index SORRY, THAT ISN'T IMPLEMENTED Error} and generate an error. If the command requires that some functions having been analyzed (e.g., the command {lisp WHO CALLS X}) and the database is empty, Masterscope will print the message "{lisp Sorry, no functions have been analyzed!}"{index SORRY, NO FUNCTIONS HAVE BEEN ANALYZED Error} and generate an error.
}{End SubSec Error Messages}