eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Explainer':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Explainer


Inheritance:

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

Package:
stx:libcomp
Category:
System-Compiler
Version:
rev: 1.222 date: 2019/08/01 12:07:09
user: cg
file: Explainer.st directory: libcomp
module: stx stc-classLibrary: libcomp
Author:
Claus Gittinger

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 explanaition
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.



Class protocol:

explaining
o  explainLiteralNode: node in: code forClass: cls short: short interval: intervalIfKnown
allBold

o  explainMessageNode: node in: code forClass: aClassOrNil short: short interval: intervalIfKnown
answer a string which explains node

o  explainMethodNode: node in: code forClass: cls short: short interval: intervalIfKnown
sendingMethods numSendingMethods sendingClasses

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

o  explainNode: node in: code forClass: cls short: short interval: intervalIfKnown
parsetree based explanations

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

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

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

o  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.

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

explaining-naive
o  colorForValue: val

o  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.

o  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.

o  explainGlobal: string inClass: aClassOrNil short: shortText
return an explanation or nil

o  explainGlobalOrPoolVariable: varName inClass: aClassOrNil short: shortText
return an explanation or nil

o  explainHereIn: aClassOrNil short: shortText
return an explanation

o  explainInstanceVariable: instVarName inClass: aClass short: shortText
look for instances

o  explainKnownSymbol: string inClass: aClass
return an explanation or nil

o  explainKnownSymbol: string inClass: aClassOrNil short: shortText
return an explanation or nil

o  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) **

o  explainPseudoVariable: string in: aClassOrNil short: shortText
return an explanation for the pseudoVariables self, super etc.

o  explainSelector: string inClass: aClassOrNil short: shortText
return an explanation or nil

o  explainSelfIn: aClassOrNil short: shortText
return an explanation

o  explainSuperIn: aClassOrNil short: shortText
return an explanation

o  explainSyntax: string
try syntax ...; return explanation or nil

o  explainSyntax: string short: shortText
try syntax ...; return explanation or nil.
This is meant for beginners...

o  safeValueStringFor: aValue

o  typeDescriptionFor: setOfTypes andSelector: selectorOrNil
up to 3 types are shown by name; more are simply counted

o  typeDescriptionFor: setOfTypes andSelector: selectorOrNil wordBetween: wordbetween
up to 3 types are shown by name; more are simply counted

o  valueStringFor: aValue
only show the value, if it is really short...

naive type inferer
o  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.

o  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.

o  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.

o  addTypesAssignedToInstvar: instVarName inClass: aClass 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.

o  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.

o  addTypesAssignedToInstvar: instVarName inTree: tree 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.

o  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.

o  addTypesOfInstvar: instVarName inClass: aClass fromExistingInstancesTo: setOfTypes
look for existing instances and see that type is there

o  compressSetOfTypes: setOfTypes
reduce by eliminating common superclasses...

o  rememberType: aClass in: setOfTypes

utilities
o  actionToBrowseClass: class

o  actionToBrowseClass: class selector: selectorOrNil

o  actionToBrowseClass: class selector: selectorOrNil info: info

o  actionToBrowseClasses: classes
Tools::NewSystemBrowser browseClasses:classes

o  actionToBrowseImplementorsOf: selector

o  actionToBrowseImplementorsOf: selector in: classes

o  actionToBrowseInstvarRefsTo: instVarName inClass: class

o  actionToBrowseMethod: mthd

o  actionToOpenMethodFinderFor: selector

o  asClassLink: nameOfClass
return text with a hyperlink to browse a class by that name

o  asLink: aString info: info to: actionOrNil

o  asLink: aString to: actionOrNil

o  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'

o  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.

o  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:''
     ].

o  methodImplementorsInfoFor: aMethod inEnvironment: environment
get something about the implementors of aMethod
to be shown in the info line at the bottom

o  methodInheritanceInfoFor: aMethod
allBold

o  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

o  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...

o  methodSpecialInfoFor: aMethod
handles special cases - such as documentation methods

o  thisOrNewBrowserInto: aTwoArgBlock
I am inviked 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


ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 29 Mar 2024 01:31:32 GMT