"

 COPYRIGHT (c) 1988 by Claus Gittinger

 COPYRIGHT (c) 2015 Jan Vrany

 COPYRIGHT (c) 2023 LabWare

	      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:libbasic' }"

"{ NameSpace: Smalltalk }"

Object subclass:#UndefinedObject

	instanceVariableNames:''

	classVariableNames:'CreateMinimumProtocolInNewSubclassQuery'

	poolDictionaries:''

	category:'Kernel-Objects'

!

!UndefinedObject class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1988 by Claus Gittinger

 COPYRIGHT (c) 2015 Jan Vrany

 COPYRIGHT (c) 2023 LabWare

	      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

"

    there is only one instance of this class: nil,

    representing an undefined or otherwise unspecified object.

    All instance variables, array elements and even method/block local

    variables are initially set to nil.

    Since in Smalltalk/X (and in other smalltalks), nil is represented by

    a special pointer value (NULL), there can be only one instance of UndefinedObject,

    and no subclassing is possible.

    (to be exact: subclassing UndefinedObject is technically possible,

     but instances of it would not be recognized as being nil

     - therefore, subclassing is blocked and an error is raised when it is tried)

    For advanced users:

      Beside the above role, nil can be subclassed (!!).

      This creates a class which inherits no protocol whatsoever - not even

      the basic interfaces as defined by the Object class. Subclasses of nil

      are useful if all messages send to instances should trap into the

      #doesNotUnderstand: method. For example, proxy objects are typically defined

      this way.

    [author:]

        Claus Gittinger

"

! !

!UndefinedObject class methodsFor:'initialization'!

initialize

    CreateMinimumProtocolInNewSubclassQuery isNil ifTrue:[

        CreateMinimumProtocolInNewSubclassQuery := QuerySignal new.

        CreateMinimumProtocolInNewSubclassQuery nameClass:self message:#createMinimumProtocolInNewSubclassQuery.

        CreateMinimumProtocolInNewSubclassQuery defaultAnswer:false.

    ].

    "

     UndefinedObject initialize

    "

    "Created: 3.1.1997 / 15:02:40 / cg"

    "Modified: 3.1.1997 / 15:18:33 / cg"

! !

!UndefinedObject class methodsFor:'instance creation'!

basicNew

    "catch new - there MUST be only one nil in the system"

    ^ nil

!

basicNew:size

    "catch new - there MUST be only one nil in the system"

    ^ nil

! !

!UndefinedObject class methodsFor:'Signal constants'!

createMinimumProtocolInNewSubclassQuery

    "return the signal used to ask if the minimum required protocol

     should be created for nil subclasses.

     By default, this is not done, however, the browser answers true

     here, to avoid big trouble with nil subclasses which do not define

     some methods which the inspector needs."

    ^ CreateMinimumProtocolInNewSubclassQuery

    "Created: 3.1.1997 / 15:05:48 / cg"

    "Modified: 3.1.1997 / 15:06:15 / cg"

! !

!UndefinedObject class methodsFor:'queries'!

canBeSubclassed

    "return true if it is allowed to create subclasses of the receiver.

     Return false here - since it is NOT possible for UndefinedObject.

     (due to the representation of nil as a 0-pointer)"

    ^ false

    "Modified: / 5.11.1998 / 16:11:43 / cg"

!

hasImmediateInstances

    "return true if this class has immediate instances

     i.e. if the instances are represented in the pointer itself and

     no real object header/storage is used for the object.

     Redefined from Behavior"

    ^ true

    "Created: 3.6.1997 / 12:01:39 / cg"

!

hasSharedInstances

    "return true if this class has shared instances, that is, instances

     with the same value are identical.

     True returned here - there is only one nil."

    ^ true

!

isBuiltInClass

    "return true if this class is known by the run-time-system,

     i.e. you cannot add/remove instance variables without recompiling

     the VM.

     Here, true is returned for myself, false for subclasses."

    ^ self == UndefinedObject

! !

!UndefinedObject methodsFor:'Compatibility-Squeak'!

subclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString category:cat

    ^ self subclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString poolDictionaries: '' category:cat

    "Created: / 24-07-2015 / 19:29:19 / Jan Vrany <jan.vrany@fit.cvut.cz>"

! !

!UndefinedObject methodsFor:'converting'!

asBoolean

    ^ false

!

asNilIfEmpty

    "I am nil, so answer nil"

    ^ self

!

doIfNotNil:aBlock

    "if I am a collection, then enumerate myself into aBlock.

     if I am nil, then do nothing.

     Return the receiver.

     Otherwise, evaluate aBlock with myself as argument. 

     Here, answer nil"

    ^ nil

    "Created: / 20-03-2018 / 15:37:11 / stefan"

    "Modified (comment): / 05-08-2018 / 11:26:32 / Claus Gittinger"

!

literalArrayEncoding

    "encode myself as an array literal, from which a copy of the receiver

     can be reconstructed with #decodeAsLiteralArray."

    ^ self

    "Created: 25.2.1997 / 19:18:47 / cg"

! !

!UndefinedObject methodsFor:'copying'!

copy

    "return a shallow copy of myself

     - since there is only one nil in the system return self"

    ^ self

!

deepCopy

    "return a deep copy of myself

     - since there is only one nil in the system return self"

    ^ self

!

deepCopyUsing:aDictionary postCopySelector:postCopySelector

    "return a deep copy of myself

     - since there is only one nil in the system, return self"

    ^ self

!

shallowCopy

    "return a shallow copy of myself

     - since there is only one nil in the system return self"

    ^ self

!

simpleDeepCopy

    "return a deep copy of myself

     - since there is only one nil in the system return self"

    ^ self

! !

!UndefinedObject methodsFor:'dependents access'!

addDependent:someObject

    "raise an error here - nil may not have dependents (it never changes anyway)"

    self error:'nil may not have dependents' mayProceed:true

    "Modified: / 28-07-2010 / 19:20:36 / cg"

!

dependents

    "nil has no dependents"

    ^#()

!

release

    "ignored here - nil has no dependents"

!

removeDependent:someObject

    "ignored here - nil has no dependents"

! !

!UndefinedObject methodsFor:'error catching'!

basicAt:index

    "catch array access - it's illegal.

     Redefined here since basicAt: in Object ommits the nil-check"

    ^ self notIndexed

!

basicAt:index put:anObject

    "catch array access - it's illegal.

     Redefined here since basicAt:put: in Object ommits the nil-check"

    ^ self notIndexed

! !

!UndefinedObject methodsFor:'printing & storing'!

printOn:aStream

    "append a printed representation of the receiver to the

     argument, aStream"

    aStream nextPutAll:'nil'

!

printString

    "return a string for printing myself"

    ^ 'nil'

!

storeOn:aStream

    "append a printed representation of the receiver to the

     argument, aStream, which allows reconstruction of it"

    ^ self printOn:aStream

!

storeString

    "return a string for storing myself"

    ^ 'nil'

! !

!UndefinedObject methodsFor:'queries'!

basicSize

    "return the number of indexed instvars

     defined here since size in Object ommits the nil-check"

    ^ 0

!

size

    "return the number of indexed instvars

     defined here since size in Object ommits the nil-check"

    ^ 0

! !

!UndefinedObject methodsFor:'subclass creation'!

nilSubclass:action

    "common helper for subclass creation.

     Creates a nil-superclass class.

     If the CreateMinimumProtocolInNewSubclassQuery answers true,

     entries for the minimum required protocol (#class, #isBehavior

     and #doesNotUnderstand:) are also automatically created.

     (this query is typically answered by the browser)

     These are required to avoid getting into deep trouble when

     inspecting or debugging instances of this new class.

     The methods get a modified source code to remind you that these

     methods were automatically generated."

    |newClass methodDict method|

    Class withoutUpdatingChangesDo:[

        newClass := action value

    ].

    newClass notNil ifTrue:[

        newClass setSuperclass:nil.

        newClass class setSuperclass:Class.

        newClass hasMethods ifFalse:[

            Class addChangeRecordForClass:newClass.

            CreateMinimumProtocolInNewSubclassQuery query

            ifTrue:[

                "

                 copy over method objects from Object

                 and modify the source code

                "

                methodDict := MethodDictionary new:3.

                #(#class #isBehavior #doesNotUnderstand:) do:[:sel|

                    method := (Object compiledMethodAt:sel) copy.

                    method source: method source , '

"

*** WARNING

***

*** this method has been automatically created,

*** since all nil-subclasses should respond to some minimum required

*** protocol.

***

*** Inspection and/or debugging of instances may not be possible,

*** if you remove/change this method. 

"

'.

                    methodDict at:sel put:method.

"/                    newClass addChangeRecordForMethod:method

                ].

                newClass methodDictionary:methodDict.

            ]

        ]

    ].

    ^ newClass

    "Modified: / 3.1.1997 / 15:53:21 / cg"

    "Created: / 3.1.1997 / 16:00:34 / cg"

    "Modified: / 18.3.1999 / 18:29:58 / stefan"

!

subclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString poolDictionaries:pool

    "create a new class which has nil as superclass

     - i.e. traps into #doesNotUnderstand: for all of its messages."

    "this method allows fileIn of ST/V and V'Age classes

     (which seem to have no category)"

    ^ self

        subclass:nameSymbol

        instanceVariableNames:instVarNameString

        classVariableNames:classVarString

        poolDictionaries:pool

        category:(Class defaultCategoryForSTVorVAGEClasses).

!

subclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString poolDictionaries:pool category:cat

    "create a new class which has nil as superclass

     - i.e. traps into #doesNotUnderstand: for all of its messages."

    ^ self

        nilSubclass:[

                Object class

                    name:nameSymbol

                    inEnvironment:(Class nameSpaceQuerySignal query)

                    subclassOf:self

                    instanceVariableNames:instVarNameString

                    variable:false

                    words:true

                    pointers:true

                    classVariableNames:classVarString

                    poolDictionaries:pool

                    category:cat

                    comment:nil

                    changed:true

        ]

    "Modified: / 3.1.1997 / 16:00:39 / cg"

    "Modified: / 18.3.1999 / 18:30:07 / stefan"

!

variableByteSubclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString poolDictionaries:pool category:cat

    "create a new class which has nil as superclass

     - i.e. traps into #doesNotUnderstand: for all of its messages."

    ^ self

        nilSubclass:[

                Object class

                    name:nameSymbol  

                    inEnvironment:(Class nameSpaceQuerySignal query)

                    subclassOf:self

                    instanceVariableNames:instVarNameString

                    variable:true

                    words:false

                    pointers:false

                    classVariableNames:classVarString

                    poolDictionaries:pool

                    category:cat

                    comment:nil

                    changed:true

        ]

    "Modified: / 3.1.1997 / 16:00:42 / cg"

    "Modified: / 18.3.1999 / 18:30:11 / stefan"

!

variableSubclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString poolDictionaries:pool category:cat

    "create a new class which has nil as superclass

     - i.e. traps into #doesNotUnderstand: for all of its messages."

    ^ self

        nilSubclass:[

                Object class

                    name:nameSymbol

                    inEnvironment:(Class nameSpaceQuerySignal query)

                    subclassOf:self

                    instanceVariableNames:instVarNameString

                    variable:true

                    words:false

                    pointers:true

                    classVariableNames:classVarString

                    poolDictionaries:pool

                    category:cat

                    comment:nil

                    changed:true

        ]

    "Modified: / 3.1.1997 / 16:00:45 / cg"

    "Modified: / 18.3.1999 / 18:30:16 / stefan"

! !

!UndefinedObject methodsFor:'subclass creation-private'!

subclass:nameSymbol instanceVariableNames:instVarNameString classVariableNames:classVarString poolDictionaries:pool privateIn:ownerClassArg

    "create a new private class which has nil as superclass

     - i.e. traps into #doesNotUnderstand: for all of its messages."

    |category ownerClass|

    (ownerClass := ownerClassArg) isNil ifTrue:[

        self error:'Nil (undefined) owner class - proceed to define as global' mayProceed:true.