Class: Explainer

• Inheritance
• Description
• Class protocol
  • explaining
  • explaining-naive
  • naive type inferer
  • utilities
• Private classes

Inheritance:

   Object
   |
   +--Scanner
      |
      +--Parser
         |
         +--Explainer

Package:

stx:libcomp

Category:

System-Compiler

Version:

rev: 1.260 date: 2024/04/22 17:39:16

user: stefan

file: Explainer.st directory: libcomp

module: stx stc-classLibrary: libcomp

Description:

a very simple explainer - much more should be added...

This one is involved, when the 'explain' menu function is used in a
codeView (popup or via CMD-E), or if the mouse button is clicked
on some code construct in the new browser (then a short explanation
is shown in the lower info area).

Most of the texts returned here are heuristically motivated,
based on the experience with beginners and their frequently asked questions.

TODO:
this is in an experimental stage; the naive type inferer replicates code
found in DWIM support; it should use the code there.


copyright
COPYRIGHT (c) 1993 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 explainLiteralNode: node in: code forClass: cls short: short interval: intervalIfKnown

allBold

 explainMessageNode: node in: code forClass: aClassOrNil short: short interval: intervalIfKnown

answer a string which explains node

 explainMethodNode: node in: code forClass: cls short: short interval: intervalIfKnown

sendingMethods numSendingMethods sendingClasses

 explainNode: node in: code forClass: cls short: short

 explainNode: node in: code forClass: cls short: short interval: intervalIfKnown

parsetree based explanations

 explainVariableNode: node in: code forClass: aClassOrNil short: short interval: intervalIfKnown

allBold

 fetchCommentOfMethod: mthd

retrieve the comment of a method
(if possible and there is one; otherwise, return nil)

 fetchDescriptionOfMethod: mthd

retrieve a desription of a method
(if possible and there is one; otherwise, return nil)

 guessPossibleClassesFor: node in: code forClass: aClassOrNil

given a node of some code of a method in cls,
return a collection of possible types of the node.

 withWaitCursorDo: aBlock

with wait cursor;
however: this class is in libcomp (should be in libtool)
so check if WindowGroup (from libview) is present

 colorForValue: val

 explain: someText in: source forClass: aClassOrNil

Given a source and a substring of it, return a string containing
an explanation.
This is just a q&d implementation - to be correct, it should use the parser,
and explain from the parsetree (instead of doing string matches).
This leads to some wrong explanations, for example if some string is
used as selector within a string, or if a variable is named like a
message selector. I.e. the explanation should be context sensitive.
Also, there could be much more detailed explanations.

 explain: someText in: source forClass: aClassOrNil short: shortText

Given a source and a substring of it, return a string containing
an explanation.
This is just a q&d implementation - to be correct, it should use the parser,
and explain from the parsetree (instead of doing string matches).
This leads to some wrong explanations, for example if some string is
used as selector within a string, or if a variable is named like a
message selector. I.e. the explanation should be context sensitive.
Also, there could be much more detailed explanations.

 explainGlobal: string inClass: aClassOrNil short: shortText

return an explanation or nil

 explainGlobalOrPoolVariable: varName inClass: aClassOrNil short: shortText

return an explanation or nil

 explainHereIn: aClassOrNil short: shortText

return an explanation

 explainInstanceVariable: instVarName inClass: aClass short: shortText

look for instances

 explainKnownSymbol: string inClass: aClass

return an explanation or nil

 explainKnownSymbol: string inClass: aClassOrNil short: shortText

return an explanation or nil

 explainPseudoVariable: string in: aClass

return an explanation for the pseudoVariables self, super etc.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 explainPseudoVariable: string in: aClassOrNil short: shortText

return an explanation for the pseudoVariables self, super etc.

 explainSelector: string inClass: aClassOrNil short: shortText

return an explanation or nil

 explainSelfIn: aClassOrNil short: shortText

return an explanation

 explainStringsForSyntax: stringArg in: fullSource

returns a triple:
long text,
source-fragment
short text

 explainSuperIn: aClassOrNil short: shortText

return an explanation

 explainSyntax: string

try syntax ...; return explanation or nil

 explainSyntax: stringArg in: fullSource short: shortText

try syntax ...; return explanation or nil.
This is meant for beginners...

 explainSyntax: string short: shortText

try syntax ...; return explanation or nil.
This is meant for beginners...

 safeValueStringFor: aValue

 typeDescriptionFor: setOfTypes andSelector: selectorOrNil

up to 3 types are shown by name; more are simply counted

 typeDescriptionFor: setOfTypes andSelector: selectorOrNil wordBetween: wordbetween

up to 3 types are shown by name; more are simply counted

 valueStringFor: aValue

only show the value, if it is really short...

 addTypeOfExpressionNode: expr forAssignmentTo: varName to: setOfTypes

pick up low hanging type information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypeOfMessageNode: expr forAssignmentTo: varName to: setOfTypes

pick up low hanging type information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypesAssignedToInstvar: instVarName inClass: aClass method: methodOrNil source: code to: setOfTypes

look to asssignments to an instance variable, and pick up low hanging class information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypesAssignedToInstvar: instVarName inClass: aClass method: aMethod to: setOfTypes

look to asssignments to an instance variable, and pick up low hanging class information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypesAssignedToInstvar: instVarName inClass: aClass to: setOfTypes

look to asssignments to an instance variable, and pick up low hanging class information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypesAssignedToInstvar: instVarName inTree: tree to: setOfTypes using: visitor

look to asssignments to an instance variable, and pick up low hanging class information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypesAssignedToLocal: localName inTree: tree to: setOfTypes

look to asssignments to a local variable, and pick up low hanging class information.
This is far from being complete, but often gives a hint good enough for code completion
and info in the browser.

 addTypesOfInstvar: instVarName inClass: aClass fromExistingInstancesTo: setOfTypes

look for existing instances and see that type is there

 compressSetOfTypes: setOfTypes

reduce by eliminating common superclasses...

 rememberType: aClass in: setOfTypes

 actionToBrowseClass: class

 actionToBrowseClass: class selector: selectorOrNil

 actionToBrowseClass: class selector: selectorOrNil info: info

 actionToBrowseClasses: classes

Tools::NewSystemBrowser browseClasses:classes

 actionToBrowseImplementorsOf: selector

 actionToBrowseImplementorsOf: selector in: classes

 actionToBrowseInstvarRefsTo: instVarName inClass: class

 actionToBrowseMethod: mthd

 actionToOpenMethodFinderFor: selector

 asClassLink: nameOfClass

return text with a hyperlink to browse a class by that name

 asLink: aString info: info to: actionOrNil

 asLink: aString to: actionBlockOrNil

 infoStringForClasses: aCollectionOfClasses withPrefix: prefix

get a nice user readable list for some classes.
Up to 4 are listed by name, otherwise the count is presented.
The prefix can be sth like 'other ', 'sub', 'super',
'implementing ' etc.
Or it can be an empty string.
The returned string is meant to be shown in the info line at the bottom.

Usage example(s):

self infoStringForClasses:{ Array } withPrefix:'sub' self infoStringForClasses:{ Array . Point } withPrefix:'sub' self infoStringForClasses:{ Array . Point . Integer . Float} withPrefix:'sub' self infoStringForClasses:{ Array . Point . Integer . Float . Fraction} withPrefix:'sub' self infoStringForClasses:{ Number . Integer . Float . Fraction . SmallInteger} withPrefix:'sub'

 infoStringForClasses: aCollectionOfClasses withPrefix: prefix actionGenerator: actionGeneratorOrNil

get a nice user readable list for some classes.
Up to 4 are named, otherwise the count is presented.
The prefix can be sth like ' other', ' sub', ' super',
' implementing' etc. Or it can be an empty string.
To be shown in the info line at the bottom.

 infoStringForMethods: aCollectionOfMethods withPrefix: prefix

get a nice user readable list for some methods.
Up to 3 are named, otherwise the count is presented.
The prefix can be sth like ' other', ' sender', ' implementor',
Or it can be an empty string.
Result is meant to be shown in the info line at the bottom of a browser.

Usage example(s):

Time millisecondsToRun:[ self infoStringForMethods:(SystemBrowser allCallsOn:#'at:put:') withPrefix:'' ]. Time millisecondsToRun:[ self infoStringForMethods:(SystemBrowser allCallsOn:#'actionToBrowseClasses:') withPrefix:'' ].

 methodImplementorsInfoFor: aMethod inEnvironment: environment

get something about the implementors of aMethod
to be shown in the info line at the bottom

 methodInheritanceInfoFor: aMethod

allBold

 methodRedefinitionInfoFor: aMethod

return a user readable string telling in how many subclasses
a method is redefined.
To be shown in the info line of a browser

 methodSendersInfoFor: selector inEnvironment: environment

get something about the senders of a message.
to be shown in the info line at the bottom.
This may be slow; so think about doing it in background...

 methodSpecialInfoFor: aMethod

handles special cases - such as documentation methods

 thisOrNewBrowserInto: aTwoArgBlock

I am invoked when user clicks on a link in the info line.
If I am invoked by a browser, invoke the twoArgBlock with it and a #newBuffer arg.
Otherwise, create a new (invisible) browser and pass it to the block
with a #newBrowser arg.

Private classes:

    ActionWithInfo