SaffronTreeDecls.ThreeC4
Copyright Ó 1987 by Xerox Corporation. All rights reserved.
Shoup, August 8, 1986 5:34:38 pm PDT
Bill Jackson (bj) April 27, 1987 3:51:50 pm PDT
Lucy Hederman August 21, 1987 11:48:22 am PDT
Sturgis, July 21, 1987 3:23:25 pm PDT
James Rauen, July 28, 1988 4:10:15 pm PDT
Last edited by: James Rauen August 25, 1988 3:25:11 pm PDT
Environments and Interfaces
DoTop:
The main top-level function
TreeRecursiveFunction [Tree,
ROPE.fileName, Environment
.arg, CompilerState.arg]
Returns [Environment.res]
DamagedReps [Environment.arg];
TreeRecursiveFunction [Tree, ROPE, Environment.arg, CompilerState.arg]
Returns [Environment.res, InterfaceVal, CompilerState.res]
DamagedReps [Environment.arg, CompilerState.arg];
Explore:
A top-level function which enters included files in the environment but does no other work
TreeRecursiveFunction [Tree, ROPE.fileName, Environment.arg, CompilerState.arg]
Returns [Environment.res, CompilerState.res]
DamagedReps [Environment.arg, CompilerState.arg];
TreeRecursiveFunction [Tree, ROPE, Environment.arg, CompilerState.arg]
Returns [Environment.res, InterfaceVal, CompilerState.res]
DamagedReps [Environment.arg, CompilerState.arg];
MakeEnvironment:
This is the main function, in fact. DoTop simply calls this.
TreeRecursiveFunction [Tree,
ROPE.fileName,
Environment
.arg, CompilerState]
Returns [Environment.res]
DamagedReps [Environment.arg];
ProcessDirectoryClause:
Applied to Directory and IncludeItem. For each IncludeItem, if the file does not already appear in the environment a parse tree for the specified file is obtained and the main function MakeEnvironment is applied to it, yielding an updated environment, and an interface for the file. Otherwise the interface for the file is retrieved from the envirpnment.
The filename, a locally visible TGN and an interfaceTGN are then entered into the localContext.
TreeRecursiveFunction [Tree, FieldList.arg, LocalContext.arg, Environment
.arg, CompilerState]
Returns [FieldList.res, LocalContext.res, Environment.res]
DamagedReps [FieldList.arg, LocalContext.arg, Environment.arg];
ProcessDirectoryClause:
Applied to Directory and IncludeItem. For each IncludeItem, if the file does not already appear in the environment a parse tree for the specified file is obtained and the main function MakeEnvironment is applied to it, yielding an updated environment, and an interface for the file. Otherwise the interface for the file is retrieved from the envirpnment.
The filename, a locally visible TGN and an interfaceTGN are then entered into the localContext.
TreeRecursiveFunction [Tree, LocalContext.arg, Environment.arg, CompilerState.arg]
Returns [LocalContext.res, Environment.res, CompilerState.res]
DamagedReps [LocalContext.arg, Environment.arg, CompilerState.arg];
ProcessDirectoryItem:
TreeRecursiveFunction [Tree, LocalContext.arg, Environment.arg, CompilerState]
Returns [Field, LocalContext.res, Environment.res]
DamagedReps [LocalContext.arg, Environment.arg];
ProcessDirectoryItem:
TreeRecursiveFunction [Tree, LocalContext.arg, Environment.arg, CompilerState.arg]
Returns [LocalContext.res, Environment.res, CompilerState.res]
DamagedReps [LocalContext.arg, Environment.arg, CompilerState.arg];
ExploreDirectoryClause:
Like ProcessDirectoryClause except that only ExploreEnvironment is applied to the new file.
TreeRecursiveFunction [Tree, LocalContext.arg, Environment.arg, CompilerState.arg]
Returns [LocalContext.res, Environment.res, CompilerState.res]
DamagedReps [LocalContext.arg, Environment.arg, CompilerState.arg];
ExploreDirectoryItem:
TreeRecursiveFunction [Tree, LocalContext.arg, Environment.arg, CompilerState.arg]
Returns [LocalContext.res, Environment.res, CompilerState.res]
DamagedReps [LocalContext.arg, Environment.arg, CompilerState.arg];
RestrictNamedTGN:
Applied to Using clauses. The second argument is a named TGN whose type field is an interface type graph node.
TreeRecursiveFunction [Tree, TypeGraphNode.arg]
Returns [TypeGraphNode.res]
DamagedReps [TypeGraphNode.arg];
MakeInterfaceTGN:
Applied to Using clauses; Creates an empty interface TGN for the interface passed in and puts in the items mentioned if any, or just creates an interface TGN for the entire interface (if no Using clause)
TreeRecursiveFunction [Tree, LocalContext.arg, InterfaceVal]
Returns [ LocalContext.res, TypeGraphNode ]
DamagedReps [ LocalContext.arg ];
AddIdsToRestrictionList
:
Applied to IdList.
TreeRecursiveFunction [Tree, TypeGraphNode.named]
Returns [TypeGraphNode.res]
DamagedReps [TypeGraphNode.named];
AddIdsToInterfaceTGN:
Applied to IdList. Calls the base function AddTGNToInterfaceTGN for each Id.
TreeRecursiveFunction [Tree, LocalContext.arg, TypeGraphNode.interface, InterfaceVal]
Returns [ LocalContext.res]
DamagedReps [ LocalContext.arg ];
BuildInterfaceTGN:
Applied to DefHeads
TreeRecursiveFunction [Tree, LocalContext.arg, BOOLEAN.cedar, CompilerState]
Returns [LocalContext.res, TypeGraphNode.interface]
DamagedReps [LocalContext.arg];
BuildImplementationTGN:
Applied to ProgHeads
TreeRecursiveFunction [Tree, LocalContext.arg, BOOLEAN.cedar, CompilerState]
Returns [LocalContext.res, TypeGraphNode.implementation]
DamagedReps [LocalContext.arg];
Context Trees
MakeContextTree:
Each new scope is required to make a ContextTree. The basic algorithm is
1. Create an empty local context.
2. Update it - fill in the new information.
3. Freeze the local context into a rib.
4. Make a context tree with the rib.
5. Hang trees for nested contexts from it.
TreeRecursiveFunction [ Tree, ContextRib,
BOOLEAN.PaintRecords, CompilerState ]
Returns [ ContextTree ];
MakeContextTree1:
Makes the Context Tree for everything in Scope other than the bindlist; i.e. it makes the context that is nested within bindList. This is needed because of the problem that semantically nested things are not syntactically nested.
TreeRecursiveFunction [ Tree, ContextRib,
BOOLEAN.PaintRecords, CompilerState ]
Returns [ ContextTree ];
MakeBindListContextTreeWithScope:
Used to pass the job of making a context tree onto the BindList
Makes the Context Tree for a bindList and its nested context - everything else in Scope.
TreeRecursiveFunction [ Tree.bindList, ScopePTree, ContextRib,
BOOLEAN.PaintRecords, CompilerState ]
Returns [ ContextTree ];
MakeBindListContextTreeWithDefBody:
Used to pass the job of making a context tree onto the DefBody
Makes the Context Tree for a bindList and its nested context - everything else in DefBody.
TreeRecursiveFunction [ Tree.bindList, DefBodyPTree, ContextRib,
BOOLEAN.PaintRecords, CompilerState ]
Returns [ ContextTree ];
HangContextsFromContextTree:
Each Scope hangs the ContextTrees for nested Scopes from its own ContextTree.
TreeRecursiveFunction [ Tree, ContextTree.arg, ContextRib,
BOOLEAN.PaintRecords, CompilerState ]
Returns [ ContextTree.res ]
DamagedReps [ ContextTree.arg ];
LocalContext
UpdateLocalContext:
For DecList this function is implemented 'in two passes' with FillInLocalContext and PutNewNamesInLocalContext
For BindList and Directory it is implemented by simple calls to base functions
TreeRecursiveFunction [ Tree, LocalContext.arg,
BOOLEAN.PaintRecords, CompilerState ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
AddDeclarationsToFieldList:
Applied to DecLists.
TreeRecursiveFunction [Tree, FieldList.arg, LocalContext.arg, CompilerState]
Returns [FieldList.res, LocalContext.res]
DamagedReps [FieldList.arg, LocalContext.arg];
AddDeclarationToFieldList:
Applied to Declarations.
TreeRecursiveFunction [Tree, FieldList.arg, LocalContext.arg, CompilerState]
Returns [FieldList.res, LocalContext.res]
DamagedReps [FieldList.arg, LocalContext.arg];
PutNewNamesInLocalContext:
This function is applied to DecList and Declaration on a 'first pass' that finds all the locally visible type names.
TreeRecursiveFunction [ Tree, LocalContext.arg, CompilerState ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
PutNewTypeNamesInLocalContext:
This function is applied to IdentList by PutNewNamesInLocalContext. It has the extra Access field: the access on a Declaration is common to all Ids in the Declaration.
TreeRecursiveFunction [ Tree, LocalContext.arg, AccessVal ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
PutNewVariableNamesInLocalContext:
This function is applied to IdentList by PutNewNamesInLocalContext. The BOOLEAN argument is true if the names are for runtime constants, false if they are for variables.
TreeRecursiveFunction [ Tree, LocalContext.arg, AccessVal, BOOLEAN ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
FillInLocalContext:
This function implements the 'second pass' of UpdateLocalContext and fills in the type information for the previously recorded type names in the currect context.
TreeRecursiveFunction [ Tree, LocalContext.arg, BOOLEAN.PaintRecords, CompilerState ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
RecAddArcsfromLVTGNtoTGN:
This function does the work for FillInLocalContext; it is applied to IdentList, and associates each (previously recorded) type name (Id) with its TypeGraphNode and access and default values.
TreeRecursiveFunction [ Tree, LocalContext.arg, AccessVal, TypeGraphNode, DefaultExp ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
RecAddArcsFromLocalNameToInstance:
This function does the work for FillInLocalContext; it is applied to IdentList, and associates each (previously recorded) name (Id) with its instance and access values.
TreeRecursiveFunction [ Tree, LocalContext.arg, AccessVal, Instance ]
Returns [ LocalContext.res ]
DamagedReps [ LocalContext.arg ];
Type Construction
MakeType:
TreeRecursiveFunction [Tree, LocalContext.a, BOOLEAN.PaintRecords, CompilerState]
Returns [ LocalContext.b, TypeGraphNode ]
DamagedReps [ LocalContext.a ];
LookupTypeId:
For TypeId type expressions. Might actually involve some creation of TGNs because not all possible variants and interface type TGNs are created when the variant record or interface is created. MakeType of a TypeId is implemented by this function - but this name seemed appropriate since the intention of a TypeId is that it should describe types that already exist.
TreeRecursiveFunction [ Tree, LocalContext.arg]
Returns [ LocalContext.res, TypeGraphNode ]
DamagedReps [ LocalContext.arg ];
MakeArgumentLists:
For Transfer types.
TreeRecursiveFunction [ Tree, LocalContext.a, BOOLEAN.PaintRecords, CompilerState ]
Returns [ LocalContext.b, FrozenFieldList.input, FrozenFieldList.output ]
DamagedReps [ LocalContext.a ];
MakeFieldList:
For Record type constructors.
TreeRecursiveFunction [ Tree, LocalContext.a, BOOLEAN.PaintRecords, CompilerState ]
Returns [ LocalContext.b, FieldList ]
DamagedReps [ LocalContext.a ];
AddPairsToFieldList:
For named field lists.
TreeRecursiveFunction [Tree, LocalContext.a, FieldList.a,
BOOLEAN.PaintRecords, CompilerState]
Returns [ LocalContext.b, FieldList.b ]
DamagedReps [ LocalContext.a, FieldList.a ];
AddToFieldList:
For unnamed field lists.
TreeRecursiveFunction [Tree, LocalContext.a, FieldList.a,
BOOLEAN.PaintRecords, CompilerState]
Returns [ LocalContext.b, FieldList.b ]
DamagedReps [ LocalContext.a, FieldList.a ];
AddNamesToFieldList:
This function is applied to IdList by AddPairsToFieldList and adds <Id, FrozenFieldList> pairs to the FieldList
TreeRecursiveFunction [ Tree, AccessVal, TypeGraphNode, DefaultExp, FieldList.a ]
Returns [ FieldList.b ]
DamagedReps [ FieldList.a ];
AddTypeDeclarationToFieldList:
TreeRecursiveFunction [Tree, FieldList.arg, LocalContext.arg, CompilerState, AccessVal.id, AccessVal.type, TypeGraphNode, TypeExpPTree, DefaultExp]
Returns [FieldList.res, LocalContext.res]
DamagedReps [FieldList.arg, LocalContext.arg];
AddValueDeclarationToFieldList:
TreeRecursiveFunction [Tree, FieldList.arg, CompilerState, DeclarationPTree, AccessVal, TypeGraphNode, InitializationPTree]
Returns [FieldList.res]
DamagedReps [FieldList.arg];
AddNamedFieldsToFieldList:
jrr - July 29, 1988 1:55:12 pm PDT
TreeRecursiveFunction [Tree, Field.template, FieldList.arg]
Returns [FieldList.res]
DamagedReps [FieldList.arg];
MakeElementList:
For enumerated types.
TreeRecursiveFunction [ Tree, LocalContext.arg,
BOOLEAN.machineDependent ]
Returns [ LocalContext.res, TypeGraphNode ]
DamagedReps [ LocalContext.arg ];
ElementInfo:
TreeRecursiveFunction [ Tree ]
Returns [ Id, Value ];
GetPointerTypeInfo:
TreeRecursiveFunction [Tree, LocalContext.arg,
BOOLEAN.PaintRecords, CompilerState]
Returns [ LocalContext.res, BoundsVal, BOOLEAN.readOnly, TypeGraphNode]
DamagedReps [ LocalContext.arg ];
MakeTransferMode:
TreeRecursiveFunction [ Tree ]
Returns [ROPE];
Union and Sequence Types
MakeUnionList:
For Union types.
TreeRecursiveFunction [ Tree, LocalContext.a, BOOLEAN.paintRecords, CompilerState]
Returns [ LocalContext.b, UnionList ]
DamagedReps [ LocalContext.a ];
AddVariantsToUnionList:
TreeRecursiveFunction [ Tree, LocalContext.arg, UnionList.arg, BOOLEAN.paintRecords, CompilerState]
Returns [LocalContext.res, UnionList.res]
DamagedReps [LocalContext.arg, UnionList.arg];
AddNamesToUnionList:
This function is applied to IdList by AddVariantsToUnionList and adds Id, FrozenFieldList pairs to the UnionList
TreeRecursiveFunction [ Tree, FrozenFieldList, UnionList.arg]
Returns [UnionList.res]
DamagedReps [UnionList.arg];
MakeTagType:
TreeRecursiveFunction [Tree, LocalContext.a,
BOOLEAN.PaintRecords, CompilerState]
Returns [ LocalContext.b, TypeGraphNode.tag, BOOLEAN.isStarTagType ]
DamagedReps [ LocalContext.a ];
MakeStarTagType:
This function makes an enumerated type from the Ids in a VariantList for * type Tag fields
TreeRecursiveFunction [Tree, LocalContext.a]
Returns [ LocalContext.b, TypeGraphNode ]
DamagedReps [ LocalContext.a ];
AddVariantNamesToEnumTypeTGN:
This function is applied to VariantList by MakeStarTagType to build an enumerated type
TreeRecursiveFunction [Tree, LocalContext.a, TypeGraphNode]
Returns [LocalContext.b]
DamagedReps [ LocalContext.a ];
MakeVariantFlavor:
Variants for Union types come in three flavors: Vanilla, Overlaid, Computed.
TreeRecursiveFunction [Tree, CompilerState]
Returns [VariantFlavor];
GetIdentInfo:
Currently only used by MakeVariantFlavor to obtain Id and Position from a tag Ident.
TreeRecursiveFunction [ Tree]
Returns [Id, PositionVal ];
GetSequenceTagInfo:
TreeRecursiveFunction [Tree, CompilerState]
Returns [Id, PositionVal, AccessVal];
Compiling Expressions
Implemented in SaffronExpressionCompileMethods.ThreeC4
The various Evaluate routines are used while the dependency graph is being walked (the local context is still being built). The values they return are always compile time constants. The Compile routines are used by other assorted Compile routines.
EvaluateExpression:
TreeRecursiveFunction [Tree, LocalContext, FieldList, CompilerState, TypeGraphNode.targetType]
Returns [Value];
CompileExpression:
Applied to Exp's. Constructs and returns a value corresponding to the Exp.
Very important: Since there are no guarantees about the type of the instance returned, this function should only be called:
(1) by CompileAndTypeCheckExpression, or
(2) to compile an argument of a polymorphic operator.
In the second case, the code related to the polymorphic operator is responsible for performing any necessary type checking.
Note that the targetType is only used to provide hints for evaluating the Exp; it does not affect the type of the returned value. CompileAndTypeCheckExpression is responsible for testing that the type of the returned value is compatible with the target type.
TreeRecursiveFunction [Tree, ContextTree.arg, CompilerState, TypeGraphNode.targetType]
Returns [Value, ContextTree.res]
DamagedReps [ContextTree.arg];
EvaluateSizeOfTypeExpression:
TreeRecursiveFunction [Tree, LocalContext, FieldList, CompilerState, TypeGraphNode.targetType]
Returns [BigINT];
CompileSizeOfTypeExpression:
TreeRecursiveFunction [Tree, ContextTree.arg, CompilerState, TypeGraphNode.targetType]
Returns [BigINT];
EvaluateFirstOfTypeExpression:
TreeRecursiveFunction [Tree, LocalContext, FieldList, CompilerState, TypeGraphNode.targetType]
Returns [Value];
CompileFirstOfTypeExpression:
TreeRecursiveFunction [Tree, ContextTree.arg, CompilerState, TypeGraphNode.targetType]
Returns [Value];
EvaluateLastOfTypeExpression:
TreeRecursiveFunction [Tree, LocalContext, FieldList, CompilerState, TypeGraphNode.targetType]
Returns [Value];
CompileLastOfTypeExpression:
TreeRecursiveFunction [Tree, ContextTree.arg, CompilerState, TypeGraphNode.targetType]
Returns [Value];
CompileLValue:
TreeRecursiveFunction [Tree, ContextTree, CompilerState]
Returns [ParameterizedFieldDescriptor, TypeGraphNode];
IsPlus:
TreeRecursiveFunction [Tree]
Returns [
BOOLEAN];
IsMinus:
TreeRecursiveFunction [Tree]
Returns [
BOOLEAN];
IsTimes:
TreeRecursiveFunction [Tree]
Returns [
BOOLEAN];
IsDivide:
TreeRecursiveFunction [Tree]
Returns [
BOOLEAN];
IsMod:
TreeRecursiveFunction [Tree]
Returns [
BOOLEAN];
Applied to MultOp's.
GetRelationOp:
TreeRecursiveFunction [Tree]
Returns [RelationOp];
IntegerValue
FromLiteral:
Applied to Num's (number literals). Returns a Value for the literal.
TreeRecursiveFunction [Tree]
Returns [BigINT];
CompileQualifiedExpression:
TreeRecursiveFunction [Tree, Value.ofExp, ContextTree.arg, CompilerState, TypeGraphNode.targetType]
Returns [Value.res, ContextTree.res]
DamagedReps [ContextTree.arg];
Declarations
InitializationIsEmpty: TreeRecursiveFunction [Tree] Returns [BOOLEAN];
InitializationIsBinding: TreeRecursiveFunction [Tree] Returns [BOOLEAN];
InitializationIsAssignment: TreeRecursiveFunction [Tree] Returns [BOOLEAN];
GetInitialValue:
Applied to Initializations (and then to InitialValues). Returns an unparsed or dummy value. (No, I don't know what it's supposed to do when it encounters other kinds of initial values.)
TreeRecursiveFunction [Tree]
Returns [Value];
Compiling Statements and Blocks
Implemented in SaffronBlockCompileMethods.ThreeC4
Frame blocks = blocks corresponding to frame on the stack. Nested blocks = BEGIN..END structures nested within frame blocks. There are also definitions blocks???
Compile:
TreeRecursiveFunction [Tree, ContextTree.arg, ProgramGraph.arg, CompilerState]
Returns [ContextTree.res, ProgramFragment, ProgramGraph.res]
DamagedReps [ContextTree.arg, ProgramGraph.arg];
CompileFrameBlock:
Applied to Blocks.
TreeRecursiveFunction [Tree, TypeGraphNode.transferType, ContextTree.parent, ProgramGraph.arg, CompilerState]
Returns [ContextTree, ProgramFragment, ProgramGraph.res]
DamagedReps [ContextTree.parent, ProgramGraph.arg];
CompileNestedBlock:
Applied to Blocks.
TreeRecursiveFunction [Tree, ContextRib.parent, CompilerState]
Returns [ContextTree, ProgramFragment];
InternalCompileBlock:
Applied to Blocks. This is the guts of the block compiler; CompileFrameBlock and CompileNestedBlock both call InternalCompileBlock. The LocalContext argument either is an empty local context (for nested blocks) or contains field info for the transfer type's arguments and results.
TreeRecursiveFunction [Tree, LocalContext.withinBlock, FieldList.arg, ProgramGraph.arg, CompilerState]
Returns [ContextTree, ProgramFragment, ProgramGraph.res]
DamagedReps [LocalContext.withinBlock, FieldList.arg, ProgramGraph.arg];
CompileScope:
TreeRecursiveFunction [Tree, LocalContext.withinScope, FieldList.arg, ProgramGraph.arg, CompilerState]
Returns [ContextTree, ProgramFragment, ProgramGraph.res]
DamagedReps [LocalContext.withinScope, FieldList.arg, ProgramGraph.arg];
CompileStatement:
Applied to Statements. (note: when CompileStatement encounters a block statement, it simply calls CompileNestedBlock.)
TreeRecursiveFunction [Tree, LocalContext, CompilerState]
Returns [ContextTree, ProgramFragment];
CompileInitialization:
Applied to Initializations and InitialValues. If the BOOLEAN value returned is FALSE, then no initialization code has to be executed. Otherwise, the ProgramFragment returned is code to place the appropriate initial value on the top of the runtime stack.,
TreeRecursiveFunction [Tree, ContextTree.arg, ProgramGraph.arg, CompilerState, TypeGraphNode.targetType]
Returns [ContextTree.res, Value, ProgramGraph.res]
DamagedReps [ContextTree.arg, ProgramGraph.arg];
MakeCodeToStoreTOSInVariousLocalFrameSlots:
Applied to IdentLists and Idents.
TreeRecursiveFunction [Tree, ContextTree]
Returns [ProgramFragment];
Dependency Graph
Implemented in SaffronDependencyGraphMethods.ThreeC4
AddValueDependencies:
Applied to Exps and Initializations. Adds dependencies of the form (DGN depends on foo), where DGN is the argument DependencyGraphNode.arg and the foos are based on the Exp.
TreeRecursiveFunction [Tree, DependencyGraph.arg, DependencyGraphNode.arg]
Returns [DependencyGraph.res]
DamagedReps [DependencyGraph.arg];
AddSizeDependencies:
Applied to TypeExps. Adds dependencies of the form (DGN depends on foo), where DGN is the argument DependencyGraphNode.arg and the foos are based on the Exp.
TreeRecursiveFunction [Tree, DependencyGraph.arg, DependencyGraphNode.arg]
Returns [DependencyGraph.res]
DamagedReps [DependencyGraph.arg];
AddFirstDependencies:
TreeRecursiveFunction [Tree, DependencyGraph.arg, DependencyGraphNode.arg]
Returns [DependencyGraph.res]
DamagedReps [DependencyGraph.arg];
AddLastDependencies:
TreeRecursiveFunction [Tree, DependencyGraph.arg, DependencyGraphNode.arg]
Returns [DependencyGraph.res]
DamagedReps [DependencyGraph.arg];
AddDependencies:
TreeRecursiveFunction [Tree, DependencyGraph.arg, DependencyGraphNode.arg]
Returns [DependencyGraph.res]
DamagedReps [DependencyGraph.arg];
TypeOpIsCode: TreeRecursiveFunction [Tree] Returns [BOOLEAN];
TypeOpIsFirst: TreeRecursiveFunction [Tree] Returns [BOOLEAN];
TypeOpIsLast: TreeRecursiveFunction [Tree] Returns [BOOLEAN];
TypeOpIsNil: TreeRecursiveFunction [Tree] Returns [BOOLEAN];