"

 COPYRIGHT (c) 1989 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.

"

"{ Package: 'stx:libcomp' }"

Scanner subclass:#Parser

	instanceVariableNames:'classToCompileFor selfValue contextToEvaluateIn selector

		methodArgs methodArgNames methodVars methodVarNames tree

		currentBlock parseForCode readInstVars readClassVars readGlobals

		usedInstVars usedClassVars usedVars modifiedInstVars

		modifiedClassVars modifiedGlobals usesSuper usedGlobals

		usedSymbols messagesSent messagesPossiblySent messagesSentToSelf

		messagesSentToSuper localVarDefPosition evalExitBlock selfNode

		superNode nilNode hasPrimitiveCode hasNonOptionalPrimitiveCode

		primitiveNr primitiveResource logged warnedUndefVars

		warnedUnknownNamespaces correctedSource foldConstants

		lineNumberInfo currentNamespace currentUsedNamespaces methodNode

		alreadyWarnedClassInstVarRefs localBlockVarDefPosition

		endOfSelectorPosition beginOfBodyPosition startOfBlockPosition

		primitiveContextInfo usedLocalVars modifiedLocalVars

		alreadyWarnedUninitializedVars

		alreadyWarnedUnimplementedSelectors returnedValues currentPackage

		doItTemporaries moreSharedPools inFunctionCallArgument

		didWarnAboutSTXNameSpaceUse didWarnAboutSTXHereExtensionUsed

		parenthesisLevel didWarnAboutBadSupersend

		didWarnAboutSqueakExtensions allowUndeclaredVariables

		interactiveMode variableCorrectActionForAll annotations

		variableTypeOfLastCorrectAction usedPoolVars readPoolVars

		modifiedPoolVars'

	classVariableNames:'PrevClass PrevInstVarNames PrevClassVarNames

		PrevClassInstVarNames LazyCompilation FoldConstants

		LineNumberInfo SuppressDoItCompilation ParseErrorSignal

		RestartCompilationSignal'

	poolDictionaries:''

	category:'System-Compiler'

!

Query subclass:#AskForVariableTypeOfUndeclaredQuery

	instanceVariableNames:'parser nameOfUnknownVariable'

	classVariableNames:''

	poolDictionaries:''

	privateIn:Parser

!

Parser subclass:#PrimitiveSpecParser

	instanceVariableNames:'masterParser'

	classVariableNames:''

	poolDictionaries:''

	privateIn:Parser

!

!Parser class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1989 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.

"

!

documentation

"

    Parser is used for both parsing and evaluating smalltalk expressions;

    it first builds a parseTree which is then interpreted (evaluate) or

    compiled. Compilation is done in the subclass ByteCodeCompiler and/or

    the (planned) MachineCodeCompiler.

    methods of main interest are:

	Parser evaluateExpression:...

    and:

	Parser parseExpression:...

	Parser parseMethod:...

    there is protocol to parse complete methods, selector specs, body only etc.

    Parser is also used to find the referenced/modified inst/classvars of

    a method - this is done by sending parseXXX message to a parser and asking

    the parser for referencedXVars or modifiedXVars (see SystemBrowser).

    You can also use parsers for all kinds of other things (ChangesBrowser for

    example analyzes the expressions in the changelist ...) by looking at the

    parsers tree. (Although this is somewhat dangerous, since it exports the

    compilers internals ... better style is to add specialized query methods here)

    One instance of Parser is created to parse one method or expression - i.e.

    its not suggested to reuse parsers.

  Constant folding:

    The parser has various modes for constant folding; by default, only numeric

    expressions involving integers and floats are constant folded

    (i.e. something like 'Float pi sin' or '1.5 + 0.3' will be reduced to a constant).

    Constant folding can be turned off completely (setting FoldConstants to nil)

    to ``secure folding'', which only folds constant numbers (#level1) or to #full.

    In full mode, more constant expressions are folded (for example: '1.0 @ 1.0' is

    reduced to a constant point), but the resulting code may not be compatible with other

    smalltalk systems (consider the case, where the point is modified using #x: or #y: messages).

    Therefore, this mode is a bit dangerous and disabled by default.

    The current implementation, base upon a global constant-folding setting is somewhat stupid

    and intermediate - a better solution would be to allow the optimization to be controlled

    by a method-pragma, since it may make sense to disable optimization on a method level,

    if its known that the used constant objects are subject of modifications as described above.

  Immutable arrays:

    Immutable arrays are experimental and being evaluated.

    Consider the case of a method returning '#(1 2 3 4)', and that array being modified

    by some other method (using #at:put:). Since the array-return is actually a return of

    a reference to the compiler created array, the next invokation of the method will

    return the modified array. These are hard to find bugs.

    By an option, the compiler can generate immutable arrays, which dont allow modification

    of its elements. For clean code, you should enable this option during development.

    As mentioned above, this is experimental. If it is reported to be a useful feature,

    the immutable feature will be extended to strings, point-literals etc. in a future version

    of st/x.

    [Instance variables:]

	classToCompileFor   <Class>             the class (or nil) we are compiling for

	selfValue           <any>               value to use as self when interpreting

	contextToEvaluateIn <Context>           the context (or nil) when interpreting

	selector            <Symbol>            the selector of the parsed method

						(valid after parseMethodSpecification)

	methodArgs                              internal

	methodArgNames      <Collection>        the names of the arguments

						(valid after parseMethodSpecification)

	methodVars                              internal

	methodVarNames      <Collection>        the names of the method locals

						(valid after parseMethodBodyVarSpec)

	tree                <ParseTree>         the parse tree - valid after parsing

	currentBlock                            if currently parsing for a block

	usedInstVars                            set of all accessed instances variables

						(valid after parsing)

	usedClassVars                           same for classVars

	usedVars                                all used variables (inst, class & globals)

	modifiedInstVars                        set of all modified instance variables

	modifiedClassVars                       same for clasVars

	localVarDefPosition <Integer>           the character offset of the local variable

						def. (i.e. the first '|' if any)

						Not yet used - prepared for automatic add of

						undefined variables

	evalExitBlock                           internal for interpretation

	selfNode            <Node>              cached one-and-only 'self' node

	superNode           <Node>              cached one-and-only 'super' node

	hasPrimitiveCode    <Boolean>           true, if it contains ST/X style primitive code

	hasNonOptionalPrimitiveCode

			    <Boolean>           true, if it contains ST/X style primitive code

						which is NOT flagged by the OPTIONAL directive.

	primitiveNr         <Integer>           the parsed ST-80 type primitive number (or nil)

	logged

	warnedUndefVars     <Set>               set of all variables which the parser has

						already output a warning (to avoid multiple

						warnings about the same variable)

    [Class variables:]

	PrevClass           <Class>             class, of which properties are

						cached in:

	PrevInstVarNames      <Collection>      instance variablenames of cached class

	PrevClassVarNames     <Collection>      class variablenames of cached class

	PrevClassInstVarNames <Collection>      class instance variablenames of cached class

	LazyCompilation       <Boolean>         EXPERIMENTAL: lazy compilation

	ArraysAreImmutable    <Boolean>         if true, create array literals

						as instances of ImmutableArray,

						which cannot be stored into.

						Default is false, for compatibility.

						Can be turned on while developping

						new code to make certain that side

						effects are avoided.

	StringsAreImmutable   <Boolean>         same as above for string literals

	WarnST80Directives    <Boolean>         if true, give warnings about

						ST-80 directives (resource defs)

						which are ignored in st/x.

						defaults to false.

	FoldConstants         <Symbol>          controls how constant folding should be

						done.

						Can be one of:

							nil      - no constant folding

							#level1  - numeric optimizations only

							#level2  - secure optimizations only

							#full    - full folding

						level1:   arithmetic on constant numbers

						level2:   above PLUS array conversions with #asFloatArray,

							  #asDoubleArray, string concatenation

						full:     constant points.

    [see also:]

	ByteCodeCompiler Scanner ObjectFileLoader

	Workspace

	SystemBrowser

    [author:]

	Claus Gittinger

"

!

examples

"

									[exBegin]

    Parser

	evaluate:'1+2*3'

	in:nil

	receiver:nil

	notifying:nil

	logged:false

	ifFail:nil

									[exEnd]

									[exBegin]

    Parser undefinedVariableNotification handle:[:ex |

	|badName|

	badName := ex variableName.

	ex proceedWith:(ConstantNode value:5).

    ] do:[

	^ self compilerClass

	    evaluate:'foo * 3'

	    in:nil

	    receiver:nil

	    notifying:nil

	    logged:false

	    ifFail:nil

    ]

									[exEnd]

  the following are experimental...

									[exBegin]

    <pragma: +arrayIndexSyntaxExtension>

    |c|

    c := Array[7].

    c[4] := 4.

    c[6] := 6.

    c[7] := 7.

    c[7] := c[4] - c[6].

									[exEnd]

									[exBegin]

    <pragma: +arrayIndexSyntaxExtension>

    |d|

    d := Dictionary new.

    d['one'] := 'eins'.

    d['two'] := 'zwei'.

    d['three'] := 'drei'.

    d['two'] , d['three']

									[exEnd]

    Reparse whole image...

									[exBegin]

    Smalltalk allClassesDo:[:cls|

	cls isLoaded ifTrue:[

	    Transcript show: cls name; show: '...'.

	    cls methodsDo:[:mth|

		Parser parseMethod: mth source.

	    ].

	    Transcript showCR:'OK'.

	]

    ]

									[exEnd]

"

! !

!Parser class methodsFor:'instance creation'!

for:aStringOrStream in:aClass

    "return a new parser, reading code for aClass from aStringOrStream"

    |parser|

    parser := self for:aStringOrStream.

    parser setClassToCompileFor:aClass.

    ^ parser

! !

!Parser class methodsFor:'Compatibility-ST80'!

parse:aString class:aClass

    "same as #parseMethod:in: for ST80 compatibility."

    |parser|

    parser := self parseMethod:aString in:aClass.

    parser notNil ifTrue:[^ parser tree].

    ^ nil

    "Modified: 19.6.1997 / 16:34:57 / cg"

! !

!Parser class methodsFor:'Compatibility-Squeak'!

evaluate:someString for:aReceiver logged:logged

    ^ self evaluate:someString receiver:aReceiver logged:logged

! !

!Parser class methodsFor:'Signal constants'!

askForVariableTypeOfUndeclaredQuery

    ^ AskForVariableTypeOfUndeclaredQuery

    "Created: / 20-10-2010 / 18:23:12 / cg"

!

parseErrorSignal

    ^ ParseError

!

parseWarningSignal

    ^ ParseWarning

    "Created: / 05-07-2011 / 18:15:33 / cg"

!

restartCompilationSignal

    ^ RestartCompilationSignal

    "Created: / 15.11.2001 / 22:57:05 / cg"

!

undefinedSuperclassError

    ^ UndefinedSuperclassError

!

undefinedVariableError

    ^ UndefinedVariableError

!

undefinedVariableNotification

    ^ UndefinedVariableNotification

! !

!Parser class methodsFor:'change & update'!

flushNameCache

    "unconditional flush name caches"

    [

	PrevClass notNil ifTrue:[

	    PrevClass removeDependent:Parser

	].

	PrevClass := nil.

	PrevInstVarNames := nil.

	PrevClassVarNames := nil.

	PrevClassInstVarNames := nil.

    ] valueUninterruptably

    "Parser flushNameCache"

!

update:something with:someArgument from:changedObject

    "aClass has changed its definition - flush name caches if we have to"

    (changedObject == PrevClass) ifTrue:[

	something == #definition ifTrue:[

	    self flushNameCache

	]

    ].

    (changedObject == Smalltalk) ifTrue:[

	something == #classDefinition ifTrue:[

	    self flushNameCache

	]

    ]

! !

!Parser class methodsFor:'class initialization'!

initialize

    LazyCompilation := false.      "/ usually set to true in your .rc file

    FoldConstants := #level1.

    LineNumberInfo := false.

    ParseErrorSignal isNil ifTrue:[

	ParseErrorSignal := ParseError.

	ParseErrorSignal notifierString:'Parse error:'.

"/        ParseErrorSignal := Error newSignalMayProceed:true.

"/        ParseErrorSignal notifierString:'parse error'.

"/        ParseErrorSignal nameClass:self message:#parseErrorSignal.

    ].

    RestartCompilationSignal := Signal new.

    Smalltalk addDependent:self.

    "

     self initialize

    "

    "Modified: / 22-08-2006 / 13:41:51 / cg"

! !

!Parser class methodsFor:'controlling compilation'!

allowArrayIndexSyntaxExtension

    "experimental"

    ^ ParserFlags allowArrayIndexSyntaxExtension

!

allowArrayIndexSyntaxExtension:aBoolean

    "experimental"

    ParserFlags allowArrayIndexSyntaxExtension:aBoolean.

    "

     self allowArrayIndexSyntaxExtension:true

     self allowArrayIndexSyntaxExtension:false

    "

!

allowFunctionCallSyntaxForBlockEvaluation

    "experimental"

    ^ ParserFlags allowFunctionCallSyntaxForBlockEvaluation

!

allowFunctionCallSyntaxForBlockEvaluation:aBoolean

    "experimental"

    ParserFlags allowFunctionCallSyntaxForBlockEvaluation:aBoolean.

    "

     self allowFunctionCallSyntaxForBlockEvaluation:true

     self allowFunctionCallSyntaxForBlockEvaluation:false

    "

!

allowReservedWordsAsSelectors

    "return true, if self, super, thisContext, nil, true and false are to be allowed

     as unary message selectors."

    ^ ParserFlags allowReservedWordsAsSelectors

!