Class: UndefinedObject

• Inheritance
• Description
• Class protocol
  • Signal constants
  • initialization
  • instance creation
  • queries
• Instance protocol
  • Compatibility - Squeak
  • Compatibility-Squeak
  • Javascript support
  • converting
  • copying
  • debugging
  • dependents access
  • error catching
  • inspecting
  • printing & storing
  • queries
  • subclass creation
  • subclass creation-private
  • testing
  • tracing
  • visiting

Inheritance:

   Object
   |
   +--UndefinedObject

Package:

stx:libbasic

Category:

Kernel-Objects

Version:

rev: 1.105 date: 2024/01/30 07:48:27

user: cg

file: UndefinedObject.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

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.

copyright
COPYRIGHT (c) 1988 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:

 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.

 initialize

UndefinedObject initialize

 basicNew

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

 basicNew: size

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

 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)

 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

 hasSharedInstances

return true if this class can share instances when stored binary,
that is, instances with the same value can be stored by reference.
True returned here - there is only one nil.

 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.

Instance protocol:

 asSwikiLink
( an extension from the stx:goodies/webServer/comanche package )

 subclass: nameSymbol instanceVariableNames: instVarNameString classVariableNames: classVarNameString package: packageName

create a new class as a subclass of an existing class (the receiver).
The subclass will have indexed variables if the receiving-class has.
Squeak uses the category as package

 js_typeof
( an extension from the stx:libjavascript package )

return a string describing what I am

 asBoolean

 asCollectionOrEmptyIfNil

answer an empty collection

 asNilIfEmpty

return mySelf, or nil if I am empty.
I am nil, so answer nil

 doIfNotNil: aBlock

if I am a collection, then enumerate myself into aBlock.
if I am nil, then do nothing.
Otherwise, evaluate aBlock with myself as argument.
Return the receiver.
Here, answer nil

 literalArrayEncoding

encode myself as an array literal, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.

 copy

return a shallow copy of myself
- since there is only one nil in the system return self

 deepCopy

return a deep copy of myself
- since there is only one nil in the system return self

 deepCopyUsing: aDictionary postCopySelector: postCopySelector

return a deep copy of myself
- since there is only one nil in the system, return self

 shallowCopy

return a shallow copy of myself
- since there is only one nil in the system return self

 simpleDeepCopy

return a deep copy of myself
- since there is only one nil in the system return self

 assertNotNil

fail and report an error, if the receiver is nil

Usage example(s):

self assertNotNil nil assertNotNil

 haltIfNil

halt if the receiver is nil

Usage example(s):

3 haltIfNil nil haltIfNil

 haltIfNotNil

halt if the receiver is not nil

Usage example(s):

3 haltIfNotNil nil haltIfNotNil

 addDependent: someObject

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

 dependents

nil has no dependents

 onChangeSend: selector to: someOne

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

 release

ignored here - nil has no dependents

 removeDependent: someObject

ignored here - nil has no dependents

 basicAt: index

catch array access - it's illegal.
Redefined here since basicAt: in Object omits the nil-check

 basicAt: index put: anObject

catch array access - it's illegal.
Redefined here since basicAt:put: in Object omits the nil-check

 inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package )

returns the icon to be shown alongside the value list of an inspector

 inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )

returns a string to be shown in the inspector's list

 printOn: aStream

append a printed representation of the receiver to the
argument, aStream

 printString

return a string for printing myself

 storeOn: aStream

append a printed representation of the receiver to the
argument, aStream, which allows reconstruction of it

 storeString

return a string for storing myself

 basicSize

return the number of indexed instvars
defined here since size in Object omits the nil-check

 size

return the number of indexed instvars
defined here since size in Object omits the nil-check

 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.

 subclass: nameSymbol

create a new class as a subclass of an existing class (the receiver).
The subclass will have indexed variables if the receiving-class has.

 subclass: nameSymbol instanceVariableNames: instVarNameString

create a new class as a subclass of an existing class (the receiver).
The subclass will have indexed variables if the receiving-class has.

 subclass: nameSymbol instanceVariableNames: instVarNameString classVariableNames: classVarString

create a new class as a subclass of an existing class (the receiver).
The subclass will have indexed variables if the receiving-class has.

 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.

 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.

 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.

 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.

 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.

 ? defaultValue

a syntactic sugar-piece:
if the receiver is nil, return the defaultValue;
otherwise, return the receiver.
This method is redefined from Object;
the argument is returned unconditionally here.

Thus, if foo and bar are simple variables or constants,
foo ? bar
is the same as:
(foo isNil ifTrue:[bar] ifFalse:[foo])

if they are message sends, the equivalent code is:
[
|t1 t2|

t1 := foo.
t2 := bar.
t1 isNil ifTrue:[t2] ifFalse:[t1]
] value

Can be used to provide defaultValues to variables,
as in:
foo := arg ? #defaultValue

Usage example(s):

1 ? #default nil ? #default

 ?+ aOneArgBlock

a syntactic sugar-piece:
aOneArgBlock is executed with self as argument
if self is not nil.

Note: this method should never be redefined in classes other than UndefinedObject.

 ?? defaultValue

a syntactic sugar-piece:
much like ?, but sends value to the argument if required.
If the receiver is nil, return the defaultValues value;
otherwise, return the receiver.
This method is redefined from Object.

Thus, if foo and bar are simple variables or constants,
foo ?? bar
is the same as:
(foo isNil ifTrue:[bar value] ifFalse:[foo])

if they are message sends, the equivalent code is:
[
|t|

t := foo.
t isNil ifTrue:[bar value] ifFalse:[t]
] value

Can be used to provide defaultValues to variables,
as in:
foo := arg ?? [something]

Usage example(s):

1 ?? #default nil ?? #default 1 ?? [Date today] nil ?? [Date today]

 checkNilFileStream

Do nothing if this is a valid FileStream
(i.e. the previous open operation was successful).
Also implemented in UndefinedObject, to raise an Error there.

This is an aid for converting from the old error reporting (returning nil)
to the new error reporting (with real Exceptions).

It will vanish as soon as the conversion has been done

 hash

return an integer useful as a hash key

 identityHash

return an integer useful as a hash key

 ifNil: aBlockOrValue

return myself, or the result from evaluating the argument, if I am nil.
This is much like #?, but sends #value to the argument in case of a nil
receiver.
Notice:
This method is open coded (inlined) by the compiler(s)
- redefining it may not work as expected.

 ifNil: nilBlockOrValue ifNotNil: notNilBlockOrValue

return the value of the first arg, if I am nil,
the result from evaluating the 2nd argument, if I am not nil.
Notice:
This method is open coded (inlined) by the compiler(s)
- redefining it may not work as expected.

 ifNotNil: aBlockOrValue

return myself if nil, or the result from evaluating the argument, if I am not nil.
Notice:
This method is open coded (inlined) by the compiler(s)
- redefining it may not work as expected.

 ifNotNil: notNilBlockOrValue ifNil: nilBlockOrValue

return the value of the 2nd arg, if I am nil,
the result from evaluating the 1st argument, if I am not nil.
Notice:
This method is open coded (inlined) by the compiler(s)
- redefining it may not work as expected.

 ifNotNilDo: aBlock

if the receiver is non-nil, return the value of aBlock, passing myself as argument.
Otherwise do nothing and return nil.

 isEmptyOrNil

return true if I am nil or an empty collection
- since I am nil, return true. (from Squeak)

 isImmediate

return true if I am an immediate object
i.e. I am represented in the pointer itself and
no real object header/storage is used by me.

 isLiteral

return true if the receiver can be used as a literal constant in ST syntax
(i.e. can be used in constant arrays)

 isNil

Return true if the receiver is nil.
Since I am definitely nil, unconditionally return true here.
Notice:
This method is open coded (inlined) by the compiler(s)
- redefining it may not work as expected.

 notEmptyOrNil

Squeak compatibility:
return true if I am neither nil nor an empty collection.

 notNil

Return true if the receiver is not nil.
Since I am definitely nil, unconditionally return false here.
Notice:
This method is open coded (inlined) by the compiler(s)
- redefining it may not work as expected.

 traceInto: aRequestor level: level from: referrer

double dispatch into tracer, passing my type implicitely in the selector

 acceptVisitor: aVisitor with: aParameter

dispatch for visitor pattern; send #visitNil:with: to aVisitor.