Class: KipperProgramContext
compiler.KipperProgramContext
The program context class used to represent a program for a compilation.
This stores all related data for a compilation, such as the AST, the semantic data, the type data, the scope tree, etc. and will handle all issues according to the this.compileConfig compileConfig.
Since
0.0.3
Table of contents
Constructors
Properties
- _antlrParseTree
- _builtInFunctionReferences
- _builtInVariableReferences
- _channels
- _compiledCode
- _errors
- _internalReferences
- _rootASTNode
- _stream
- _universeScope
- _warnings
- builtInFunctions
- builtInVariables
- compileConfig
- internals
- lexer
- logger
- optimiser
- parser
- semanticChecker
- target
- typeChecker
- warningIssuer
Accessors
- antlrParseTree
- builtInFunctionReferences
- builtInVariableReferences
- builtIns
- compiledCode
- errorHandler
- errors
- fileName
- filePath
- globalScope
- hasFailed
- internalReferences
- rootASTNode
- stream
- tokenStream
- universeScope
- warnings
Methods
- _initUniversalReferenceables
- addBuiltInReference
- addInternalReference
- clearBuiltInFunctions
- clearBuiltInVariables
- compileProgram
- generateAbstractSyntaxTree
- generateRequirements
- getBuiltInFunction
- getBuiltInVariable
- optimise
- registerBuiltInFunctions
- registerBuiltInVariables
- reportError
- reportWarning
- semanticAnalysis
- semanticCheck
- translate
- typeCheck
- warningCheck
Constructors
constructor
• new KipperProgramContext(lexerParserData
, logger
, target
, internals
, compileConfig
, semanticChecker?
, typeChecker?
, optimiser?
, warningIssuer?
)
Parameters
Name | Type |
---|---|
lexerParserData |
LexerParserData |
logger |
KipperLogger |
target |
KipperCompileTarget |
internals |
InternalFunction [] |
compileConfig |
EvaluatedCompileConfig |
semanticChecker? |
KipperSemanticChecker |
typeChecker? |
KipperTypeChecker |
optimiser? |
KipperOptimiser |
warningIssuer? |
KipperWarningIssuer |
Defined in
kipper/core/src/compiler/program-ctx.ts:181
Properties
_antlrParseTree
• Private
Readonly
_antlrParseTree: CompilationUnitContext
Defined in
kipper/core/src/compiler/program-ctx.ts:57
_builtInFunctionReferences
• Private
Readonly
_builtInFunctionReferences: BuiltInReference
<ScopeFunctionDeclaration
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:63
_builtInVariableReferences
• Private
Readonly
_builtInVariableReferences: BuiltInReference
<ScopeVariableDeclaration
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:65
_channels
• Private
Readonly
_channels: Object
The channels in which the lexer operated and placed all the lexed tokens.
See
compiler/lexer-parser/lexer-channels.ts
Since
0.11.0
Type declaration
Name | Type | Description |
---|---|---|
ALL |
CommonTokenStream |
Token stream which contains all tokens regardless of channel. Since 0.11.0 |
COMMENT |
Token [] |
The comment channels where all comments are stored. Since 0.11.0 |
DEFAULT_TOKEN_CHANNEL |
Token [] |
The default channel which all parser-relevant tokens are stored. Since 0.11.0 |
HIDDEN |
Token [] |
The hidden channel where all whitespaces and newlines are stored. Since 0.11.0 |
PRAGMA |
Token [] |
The pragma channel where all pragma instructions are stored which modify the compiler behaviour. Since 0.11.0 |
Defined in
kipper/core/src/compiler/program-ctx.ts:75
_compiledCode
• Private
_compiledCode: undefined
| TranslatedCodeLine
[]
The field compiledCode that will store the cached code, once 'compileProgram' has been called. This is to avoid running the function unnecessarily and generate code again, even though it already exists.
Defined in
kipper/core/src/compiler/program-ctx.ts:84
_errors
• Private
Readonly
_errors: KipperError
[]
Defined in
kipper/core/src/compiler/program-ctx.ts:59
_internalReferences
• Private
Readonly
_internalReferences: InternalReference
<InternalFunction
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:67
_rootASTNode
• Private
_rootASTNode: undefined
| RootASTNode
Defined in
kipper/core/src/compiler/program-ctx.ts:77
_stream
• Private
Readonly
_stream: KipperFileStream
Defined in
kipper/core/src/compiler/program-ctx.ts:55
_universeScope
• Private
Readonly
_universeScope: UniverseScope
The universe scope, which contains all built-in types and functions.
Since
0.11.0
Defined in
kipper/core/src/compiler/program-ctx.ts:179
_warnings
• Private
Readonly
_warnings: KipperWarning
[]
Defined in
kipper/core/src/compiler/program-ctx.ts:61
builtInFunctions
• Readonly
Private
builtInFunctions: BuiltInFunction
[]
Returns the built-in global functions registered for this Kipper program. These global functions defined in the array will be available in the Kipper program and callable using their specified identifier.
This is designed to allow calling external compiler-generated functions, which are natively implemented in the this.target target language
Since
0.8.0
Defined in
kipper/core/src/compiler/program-ctx.ts:163
builtInVariables
• Readonly
Private
builtInVariables: BuiltInVariable
[]
Returns the built-in global variables registered for this Kipper program. These global variables defined in the array will be available in the Kipper program and can be accessed using their specified identifier.
This is designed to allow accessing external compiler-generated variables, which are natively implemented in the this.target target language.
Defined in
kipper/core/src/compiler/program-ctx.ts:173
compileConfig
• Readonly
Private
compileConfig: EvaluatedCompileConfig
The compilation config for this program.
Since
0.10.0
Defined in
kipper/core/src/compiler/program-ctx.ts:137
internals
• Readonly
internals: InternalFunction
[]
Contains all the internal functions, which are used by Kipper to provide internal functionality. These internal built-ins are commonly used to provide the logic for keywords and other internal logic.
This contains every internal functions that also must be implemented by the this.target target's KipperTargetBuiltInGenerator.
Since
0.8.0
Defined in
kipper/core/src/compiler/program-ctx.ts:152
lexer
• Readonly
Private
lexer: KipperLexer
Returns the KipperLexer, which lexed this program and generated the tokens for it.
Defined in
kipper/core/src/compiler/program-ctx.ts:130
logger
• logger: KipperLogger
The logger that should be used to log warnings and errors.
Defined in
kipper/core/src/compiler/program-ctx.ts:142
optimiser
• Readonly
optimiser: KipperOptimiser
Kipper Code Optimiser, which performs
Since
0.8.0
Defined in
kipper/core/src/compiler/program-ctx.ts:112
parser
• Readonly
parser: KipperParser
Returns the KipperParser, which parsed this program and generated the this.antlrParseTree parse tree.
Defined in
kipper/core/src/compiler/program-ctx.ts:124
semanticChecker
• Readonly
semanticChecker: KipperSemanticChecker
Kipper Semantic Checker, which asserts that semantic logic and cohesion is valid and throws errors in case that an invalid use of AST nodes is detected.
Since
0.7.0
Defined in
kipper/core/src/compiler/program-ctx.ts:99
target
• Readonly
target: KipperCompileTarget
Represents the compilation translation target for the program. This contains the:
- KipperTargetSemanticAnalyser, which performs semantic analysis specific for the target.
- KipperTargetCodeGenerator, which translates the Kipper code (AST) into another language.
- KipperTargetBuiltInGenerator, which generates the internal and built-in functions for the target.
Defined in
kipper/core/src/compiler/program-ctx.ts:92
typeChecker
• Readonly
typeChecker: KipperTypeChecker
Kipper Type Checker, which asserts that type logic and cohesion is valid and throws errors in case that an invalid use of types and identifiers is detected.
Since
0.7.0
Defined in
kipper/core/src/compiler/program-ctx.ts:106
warningIssuer
• Readonly
warningIssuer: KipperWarningIssuer
The warning issuer, which is used to check for certain conditions and issues if needed.
Since
0.10.0
Defined in
kipper/core/src/compiler/program-ctx.ts:118
Accessors
antlrParseTree
• get
antlrParseTree(): CompilationUnitContext
The root node of the Antlr4 generated parse tree.
This parse tree can be used in a KipperFileASTGenerator to generate an abstract syntax tree.
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:283
builtInFunctionReferences
• get
builtInFunctionReferences(): BuiltInReference
<ScopeFunctionDeclaration
>[]
A list of all references to built-in functions. This is used to determine which built-ins are used and which aren't.
This is primarily used for optimisations in KipperOptimiser, by applying tree-shaking to unused built-in functions, so they will not be generated.
Since
0.10.0
Returns
BuiltInReference
<ScopeFunctionDeclaration
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:352
builtInVariableReferences
• get
builtInVariableReferences(): BuiltInReference
<ScopeVariableDeclaration
>[]
A list of all references to built-in variables. This is used to determine which built-ins are used and which aren't.
This is primarily used for optimisations in KipperOptimiser, by applying tree-shaking to unused built-in variables, so they will not be generated.
Since
0.10.0
Returns
BuiltInReference
<ScopeVariableDeclaration
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:364
builtIns
• get
builtIns(): (BuiltInVariable
| BuiltInFunction
)[]
Returns an array of all built-in functions and variables.
Since
0.10.0
Returns
(BuiltInVariable
| BuiltInFunction
)[]
Defined in
kipper/core/src/compiler/program-ctx.ts:414
compiledCode
• get
compiledCode(): undefined
| TranslatedCodeLine
[]
Returns the cached compiled code.
If the function compileProgram has not been called yet, this item will be an empty array.
Returns
undefined
| TranslatedCodeLine
[]
Defined in
kipper/core/src/compiler/program-ctx.ts:328
errorHandler
• get
errorHandler(): ANTLRErrorListener
<Token
>[]
Returns the ANTLRErrorListener instances, which actively listen for errors on this "virtual" file.
Considering this file is only generated after the lexing and parse step, no more errors will be handled by these listeners, though they may be used to manually raise errors, so they are properly handled and formatted.
Returns
ANTLRErrorListener
<Token
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:293
errors
• get
errors(): KipperError
[]
The list of errors that were raised during the compilation process.
Errors are fatal errors, which are raised when the compiler encounters a situation that it considers to be problematic, which prevents it from compiling the program.
Since
0.10.0
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:396
fileName
• get
fileName(): string
Returns the file name of the Kipper file.
Returns
string
Defined in
kipper/core/src/compiler/program-ctx.ts:260
filePath
• get
filePath(): string
Returns the path of the Kipper file.
Returns
string
Defined in
kipper/core/src/compiler/program-ctx.ts:267
globalScope
• get
globalScope(): undefined
| GlobalScope
The global scope of this file, which contains all ScopeDeclaration instances that are accessible in the entire program.
May be undefined if generateAbstractSyntaxTree has not been called yet.
Returns
undefined
| GlobalScope
Defined in
kipper/core/src/compiler/program-ctx.ts:319
hasFailed
• get
hasFailed(): boolean
Returns true if the file has any errors, false otherwise.
This is equivalent to checking if the length of errors is greater than 0.
Since
0.10.0
Returns
boolean
Defined in
kipper/core/src/compiler/program-ctx.ts:406
internalReferences
• get
internalReferences(): InternalReference
<InternalFunction
>[]
A list of all references to internal functions. This is used to determine which internal functions are used and which aren't.
This is primarily used for optimisations in KipperOptimiser, by applying tree-shaking to unused internal functions, so they will not be generated.
Since
0.8.0
Returns
InternalReference
<InternalFunction
>[]
Defined in
kipper/core/src/compiler/program-ctx.ts:340
rootASTNode
• get
rootASTNode(): undefined
| RootASTNode
Returns the abstract syntax tree, which is a converted antlr4 parse tree in a specialised Kipper form, which allows it to be used for semantic analysis and translation to other languages.
If the function compileProgram has not been called yet, this item will be undefined.
Returns
undefined
| RootASTNode
Defined in
kipper/core/src/compiler/program-ctx.ts:374
stream
• get
stream(): KipperFileStream
Returns the KipperFileStream which contains the raw file data.
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:274
tokenStream
• get
tokenStream(): TokenStream
Returns the TokenStream, which contains all lexer tokens in a stream.
Returns
TokenStream
Defined in
kipper/core/src/compiler/program-ctx.ts:300
universeScope
• get
universeScope(): UniverseScope
The global scope of this file, which contains all ScopeDeclaration instances that are accessible in the entire program.
Since
0.11.0
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:309
warnings
• get
warnings(): KipperWarning
[]
The list of warnings that were raised during the compilation process.
Warnings are non-fatal errors, which are raised when the compiler encounters a situation that it considers to be problematic, which do not prevent the program from being compiled.
Since
0.9.0
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:385
Methods
_initUniversalReferenceables
▸ Private
_initUniversalReferenceables(compileConfig
): void
Initialises the universal Referenceables for the program context, by registering all built-in functions and variables as well as adding all the extension functions and variables.
This will initialise this._universeScope.
Since
0.11.0
Parameters
Name | Type | Description |
---|---|---|
compileConfig |
EvaluatedCompileConfig |
The compile configuration for the program. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:793
addBuiltInReference
▸ addBuiltInReference(exp
, refTarget
): void
Adds a new built-in reference.
Since
0.8.0
Parameters
Name | Type | Description |
---|---|---|
exp |
Expression <ExpressionSemantics , ExpressionTypeSemantics , CompilableASTNode <SemanticData , TypeData >> |
The expression referencing refTarget. |
refTarget |
ScopeVariableDeclaration | ScopeFunctionDeclaration |
The built-in identifier referenced. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:758
addInternalReference
▸ addInternalReference(exp
, ref
): void
Adds a new internal reference.
Since
0.8.0
Parameters
Name | Type | Description |
---|---|---|
exp |
Expression <ExpressionSemantics , ExpressionTypeSemantics , CompilableASTNode <SemanticData , TypeData >> |
The expression referencing ref. |
ref |
InternalFunction |
The internal identifier referenced. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:777
clearBuiltInFunctions
▸ clearBuiltInFunctions(): void
Clears all built-in functions. This removes any built-in functions that were registered for the target.
Since
0.10.0
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:738
clearBuiltInVariables
▸ clearBuiltInVariables(): void
Clears all built-in variables. This removes any built-in functions that were registered for the target.
Since
0.10.0
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:747
compileProgram
▸ compileProgram(): Promise
<undefined
| TranslatedCodeLine
[]>
Translate the parse tree of this virtual file into the target language.
Steps of compilation:
- Generating a Kipper abstract syntax tree - (generateAbstractSyntaxTree)
- Semantically analysing the AST - (semanticAnalysis)
- Optimising the AST - (optimise)
- Generating the final source code for the specified target - (translate)
Returns
Promise
<undefined
| TranslatedCodeLine
[]>
Defined in
kipper/core/src/compiler/program-ctx.ts:585
generateAbstractSyntaxTree
▸ Private
generateAbstractSyntaxTree(listener?
): Promise
<RootASTNode
>
Converting and processing the antlr4 parse tree into a Kipper parse tree that may be used to semantically analyse the program and compile it.
Since
0.8.0
See
Parameters
Name | Type | Description |
---|---|---|
listener? |
KipperFileASTGenerator |
The listener instance to walk through the antlr4 parse tree. If undefined a new default one is created based on the metadata from this KipperProgramContext. |
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:452
generateRequirements
▸ Private
generateRequirements(): Promise
<{ global
: TranslatedCodeLine
[] ; local
: TranslatedCodeLine
[] }>
Generates the required code for the execution of this Kipper program.
This primarily includes the Kipper built-ins, which require target-specific generation.
Since
0.8.0
See
Returns
Promise
<{ global
: TranslatedCodeLine
[] ; local
: TranslatedCodeLine
[] }>
The generated code for the requirements.
Defined in
kipper/core/src/compiler/program-ctx.ts:626
getBuiltInFunction
▸ getBuiltInFunction(identifier
): undefined
| BuiltInFunction
Searches for a built-in function with the specific identifier from the builtIns.
If the identifier is unknown, this function will return undefined.
Since
0.8.0
See
Parameters
Name | Type | Description |
---|---|---|
identifier |
string |
The identifier to search for. |
Returns
undefined
| BuiltInFunction
Defined in
kipper/core/src/compiler/program-ctx.ts:676
getBuiltInVariable
▸ getBuiltInVariable(identifier
): undefined
| BuiltInVariable
Searches for a built-in variable with the specific identifier from the builtIns.
If the identifier is unknown, this function will return undefined.
Since
0.10.0
See
Parameters
Name | Type | Description |
---|---|---|
identifier |
string |
The identifier to search for. |
Returns
undefined
| BuiltInVariable
Defined in
kipper/core/src/compiler/program-ctx.ts:688
optimise
▸ optimise(options?
): Promise
<RootASTNode
>
Processes the rootASTNode and generates a new optimised one based on the options.
Since
0.8.0
See
Parameters
Name | Type | Description |
---|---|---|
options? |
OptimisationOptions |
The options for the optimisation. If undefined, the defaultOptimisationOptions are used. |
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:525
registerBuiltInFunctions
▸ registerBuiltInFunctions(builtInFunctions
): void
Registers new builtIns that are available inside the Kipper program.
Globals must be registered before compileProgram is run to properly include them in the result code.
If builtInFunctions is an empty array, this function will do nothing.
Since
0.8.0
See
Parameters
Name | Type | Description |
---|---|---|
builtInFunctions |
BuiltInFunction | BuiltInFunction [] |
The built-in functions to register. May be a single value or an array. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:702
registerBuiltInVariables
▸ registerBuiltInVariables(builtInVariables
): void
Registers new built-in variables that should be available inside the Kipper program.
Globals must be registered before compileProgram is run to properly include them in the result code.
If builtInVariables is an empty array, this function will do nothing.
Since
0.10.0
See
Parameters
Name | Type | Description |
---|---|---|
builtInVariables |
BuiltInVariable | BuiltInVariable [] |
The built-in variables to register. May be a single value or an array. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:723
reportError
▸ reportError(error
): void
Adds a new error to the list of errors for this file and reports the error to the logger.
Since
0.10.0
Parameters
Name | Type | Description |
---|---|---|
error |
KipperError |
The error to add to the list of reported errors of this program. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:433
reportWarning
▸ reportWarning(warning
): void
Adds a new warning to the list of warnings for this file and reports the warning to the logger.
Since
0.9.0
Parameters
Name | Type | Description |
---|---|---|
warning |
KipperWarning |
The warning to add to the list of reported warnings of this program. |
Returns
void
Defined in
kipper/core/src/compiler/program-ctx.ts:423
semanticAnalysis
▸ semanticAnalysis(): Promise
<void
>
Runs the semantic analysis for this program. This function will log debugging messages and warnings using the this.logger logger of this instance and throw errors in case any logical issues are detected.
If this.processedParseTree is undefined, then it will automatically run this.generateAbstractSyntaxTree to generate it.
Since
0.6.0
See
Returns
Promise
<void
>
Defined in
kipper/core/src/compiler/program-ctx.ts:498
semanticCheck
▸ semanticCheck(ctx
): KipperSemanticChecker
Asserts a certain truth.
Parameters
Name | Type | Description |
---|---|---|
ctx |
undefined | CompilableASTNode <SemanticData , TypeData > |
The AST node context item. |
Returns
The this.semanticChecker semantic checker instance, which contains the functions that may be used to check semantic integrity and cohesion.
Defined in
kipper/core/src/compiler/program-ctx.ts:226
translate
▸ translate(): Promise
<TranslatedCodeLine
[]>
Translates the CompilableASTNode contained in the this.processedParseTree. This function should only be used if semanticAnalysis has been run before, otherwise it will throw an UndefinedSemanticsError.
If this.processedParseTree is undefined, then it will automatically run this.generateAbstractSyntaxTree to generate it.
Since
0.6.0
See
Returns
Defined in
kipper/core/src/compiler/program-ctx.ts:557
typeCheck
▸ typeCheck(ctx
): KipperTypeChecker
Performs a type check on the ctx argument.
Parameters
Name | Type | Description |
---|---|---|
ctx |
undefined | CompilableASTNode <SemanticData , TypeData > |
The AST node context item. |
Returns
The this.typeChecker type checker instance, which contains the functions that may be used to check certain types.
Defined in
kipper/core/src/compiler/program-ctx.ts:238
warningCheck
▸ warningCheck(ctx
): KipperWarningIssuer
Performs a warning check on the ctx argument.
Parameters
Name | Type | Description |
---|---|---|
ctx |
undefined | CompilableASTNode <SemanticData , TypeData > |
The AST node context item. |
Returns
KipperWarningIssuer
The this.warningIssuer warning issuer instance, which contains the functions that may be used to issue warnings.
Defined in
kipper/core/src/compiler/program-ctx.ts:251