"

 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.

"

Scanner subclass:#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 interrest 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,

    which will be done incrementally.)

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

    its not suggested to reuse parsers.

    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.

"

! !

!Parser class methodsFor:'evaluating expressions'!

evaluate:aStringOrStream

    "return the result of evaluating an expression in aStringOrStream.

     No doit-entry is added to the changeLog."

    ^ self 

	evaluate:aStringOrStream 

	in:nil 

	receiver:nil 

	notifying:nil 

	logged:false

	ifFail:nil 

	compile:true

    "

     Compiler evaluate:'1 + 2'

     Compiler evaluate:'''hello world'' asSortedCollection displayString printNL'

     Compiler evaluate:'''hello world'' asSortedCollection printNL'

    "

!

evaluate:aStringOrStream compile:compile

    "return the result of evaluating aString, 

     The compile argument specifies if the string should be compiled down to 

     bytecode or instead be interpreted from the parseTree.

     The first should be done for doIts etc, where a readable walkback is

     required.

     The latter is better done for constants, styleSheet and resource

     reading and simple sends, where the overhead of compilation is bigger

     than the interpretation overhead."

    ^ self 

	evaluate:aStringOrStream

	in:nil

	receiver:nil 

	notifying:nil 

	logged:false

	ifFail:nil

	compile:compile 

!

evaluate:aStringOrStream ifFail:failBlock

    "return the result of evaluating an expression in aStringOrStream.

     In case of any syntax errors, return the value of failBlock.

     No doit-entry is added to the changeLog."

    ^ self 

	evaluate:aStringOrStream 

	in:nil 

	receiver:nil 

	notifying:nil 

	logged:false

	ifFail:failBlock 

	compile:true

    "

     Compiler evaluate:'1 +' ifFail:['oops']   

    "

!

evaluate:aStringOrStream in:aContext receiver:anObject notifying:requestor ifFail:failBlock

    "return the result of evaluating aStringOrStream, errors are reported to requestor. 

     Allow access to anObject as self and to its instVars (used in the inspector).

     No doIt entry is added to the change-file. 

     If the failBlock argument is non-nil, it is evaluated if an error occurs."

    ^ self 

	evaluate:aStringOrStream

	in:nil

	receiver:anObject

	notifying:requestor

	logged:false

	ifFail:nil

	compile:true

!

evaluate:aStringOrStream in:aContext receiver:anObject notifying:requestor logged:logged ifFail:failBlock

    "return the result of evaluating aStringOrStream, errors are reported to requestor. 

     Allow access to anObject as self and to its instVars (used in the inspector).

     If logged is true, an entry is added to the change-file. If the failBlock argument

     is non-nil, it is evaluated if an error occurs."

    ^ self 

	evaluate:aStringOrStream

	in:aContext

	receiver:anObject

	notifying:requestor

	logged:logged 

	ifFail:failBlock 

	compile:true

!

evaluate:aStringOrStream in:aContext receiver:anObject notifying:requestor logged:logged ifFail:failBlock compile:compile

    "return the result of evaluating aStringOrStream, errors are reported to requestor. 

     Allow access to anObject as self and to its instVars (used in the inspector).

     If logged is true, an entry is added to the change-file. If the failBlock argument

     is non-nil, it is evaluated if an error occurs.

     Finally, compile specifies if the string should be compiled down to 

     bytecode or instead be interpreted from the parseTree.

     The first should be done for doIts etc, where a readable walkback is

     required.

     The latter is better done for constants, styleSheet and resource

     reading and simple sends, where the overhead of compilation is bigger

     than the interpretation overhead."

    |parser tree mustBackup loggedString chgStream value s sReal m|

    aStringOrStream isNil ifTrue:[^ nil].

    aStringOrStream isStream ifTrue:[

	parser := self for:aStringOrStream.

	mustBackup := true

    ] ifFalse:[

	loggedString := aStringOrStream.

	parser := self for:(ReadStream on:aStringOrStream).

	mustBackup := false

    ].

    parser parseForCode. 

    parser setSelf:anObject.

    parser setContext:aContext.

    parser notifying:requestor.

    parser nextToken.

    tree := parser parseMethodBodyOrEmpty.

    "if reading from a stream, backup for next expression"

    mustBackup ifTrue:[

	parser backupPosition

    ].

    (parser errorFlag or:[tree == #Error]) ifTrue:[

	failBlock notNil ifTrue:[

	    ^ failBlock value

	].

	^ #Error

    ].

    tree notNil ifTrue:[

	(logged

	and:[loggedString notNil

	and:[Smalltalk logDoits]]) ifTrue:[

	    chgStream := Class changesStream.

	    chgStream notNil ifTrue:[

		chgStream nextChunkPut:loggedString.

		chgStream cr.

		chgStream close

	    ].

	].

	"

	 if compile is false, or the parse tree is that of a constant, 

	 quickly return its value.

	 This is used for example, when reading simple objects

	 via #readFrom:. 

	 The overhead of compiling a method is avoided in this case.

	"

	(compile not 

	 or:[tree isConstant

	 or:[aStringOrStream isStream]]) ifTrue:[

	    ^ tree evaluate

	] ifFalse:[

	    "

	     if I am the ByteCodeCompiler,

	     generate a dummy method, execute it and return the value.

	     otherwise, just evaluate the tree; slower, but not too bad ...

	     This allows systems to be delivered without the ByteCodeCompiler,

	     and still evaluate expressions (neede for example, to read resource

	     files or to process .rc files).

	    "

	    self == Parser ifTrue:[

		parser evalExitBlock:[:value | parser release. ^ value].

		value := tree evaluate.

		parser evalExitBlock:nil.

	    ] ifFalse:[

		aStringOrStream isStream ifTrue:[

		    s := parser collectedSource.  "/ does not work yet ...

		] ifFalse:[

		    s := aStringOrStream

		].

		sReal := 'doIt ^[\' withCRs , s , '\] value' withCRs.

		m := self 

			compile:sReal 

			forClass:anObject class

			inCategory:'_temporary_' 

			notifying:requestor 

			install:false 

			skipIfSame:false 

			silent:true.

		m notNil ifTrue:[

		    m ~~ #Error ifTrue:[

			"

			 fake: patch the source string, to what the user expects

			 in the browser

			"

			m source:'       \' withCRs , s .

			value := m valueWithReceiver:anObject 

					   arguments:#() 

					    selector:#doIt 

					      search:nil

					      sender:nil.

		    ] ifFalse:[

			parser evalExitBlock:[:value | parser release. ^ value].

			value := tree evaluate.

			parser evalExitBlock:nil.

		    ]

		].

	    ]

	]

    ].

    parser release.

    ^ value