brighterscript 1.0.0-alpha.5 → 1.0.0-alpha.51

package/dist/parser/Parser.d.ts

@@ -1,14 +1,15 @@
-import type { Token, Identifier } from '../lexer';
-import { TokenKind } from '../lexer';
-import type { Statement } from './Statement';
-import { AssignmentStatement, Body, ClassStatement, FunctionStatement, ImportStatement, LibraryStatement, NamespaceStatement } from './Statement';
-import type { Expression } from './Expression';
-import { CallExpression, FunctionExpression, NewExpression, VariableExpression, AnnotationExpression } from './Expression';
-import type { Diagnostic, Position } from 'vscode-languageserver';
-import { Logger } from '../Logger';
-import type { BscType } from '../types/BscType';
-import { SymbolTable } from '../SymbolTable';
+import type { Token } from '../lexer/Token';
+import { Body } from './Statement';
+import { AnnotationExpression } from './Expression';
+import type { Logger } from '../logging';
+import type { Statement } from './AstNode';
+import type { BsDiagnostic } from '../interfaces';
 export declare class Parser {
+    /**
+     * The minimum Roku firmware version that added native support for multi-line expressions
+     * (line continuation) in plain BrightScript (`.brs`) files.
+     */
+    private static readonly LINE_CONTINUATION_MIN_FIRMWARE_VERSION;
     /**
      * The array of tokens passed to `parse()`
      */
@@ -21,26 +22,15 @@ export declare class Parser {
      * The list of statements for the parsed file
      */
     ast: Body;
-    get statements(): Statement[];
-    symbolTable: SymbolTable;
-    private get currentSymbolTable();
-    /**
-     * References for significant statements/expressions in the parser.
-     * These are initially extracted during parse-time to improve performance, but will also be dynamically regenerated if need be.
-     *
-     * If a plugin modifies the AST, then the plugin should call Parser#invalidateReferences() to force this object to refresh
-     */
-    get references(): References;
-    private _references;
+    get eofToken(): Token;
     /**
-     * Invalidates (clears) the references collection. This should be called anytime the AST has been manipulated.
+     * The top-level symbol table for the body of this file.
      */
-    invalidateReferences(): void;
-    private addPropertyHints;
+    get symbolTable(): import("..").SymbolTable;
     /**
      * The list of diagnostics found during the parse process
      */
-    diagnostics: Diagnostic[];
+    diagnostics: BsDiagnostic[];
     /**
      * The depth of the calls to function declarations. Helps some checks know if they are at the root or not.
      */
@@ -49,19 +39,17 @@ export declare class Parser {
      * The options used to parse the file
      */
     options: ParseOptions;
-    private globalTerminators;
     /**
-     * When a namespace has been started, this gets set. When it's done, this gets unset.
-     * It is useful for passing the namespace into certain statements that need it
+     * Whether line continuation after binary operators is allowed.
+     * Enabled in BrighterScript mode, or when minFirmwareVersion >= 15.3.
      */
-    private currentNamespace;
-    private get currentNamespaceName();
+    private allowLineContinuation;
     /**
-     * When a FunctionExpression has been started, this gets set. When it's done, this gets unset.
-     * It's useful for passing the function into statements and expressions that need to be located
-     * by function later on.
+     * If line continuation is enabled, consumes all immediately following Newline tokens.
+     * Call this after matching a binary operator to allow the right-hand operand on the next line.
      */
-    private currentFunctionExpression;
+    private consumeNewlinesIfAllowed;
+    private globalTerminators;
     /**
      * A list of identifiers that are permitted to be used as local variables. We store this in a property because we augment the list in the constructor
      * based on the parse mode
@@ -78,14 +66,13 @@ export declare class Parser {
     /**
      * Static wrapper around creating a new parser and parsing a list of tokens
      */
-    static parse(source: string, options?: ParseOptions): Parser;
-    static parse(tokens: Token[], options?: ParseOptions): Parser;
+    static parse(toParse: Token[] | string, options?: ParseOptions): Parser;
     /**
      * Parses an array of `Token`s into an abstract syntax tree
      * @param toParse the array of tokens to parse. May not contain any whitespace tokens
      * @returns the same instance of the parser which contains the diagnostics and statements
      */
-    parse(tokens: Token[], options?: ParseOptions): this;
+    parse(toParse: Token[] | string, options?: ParseOptions): this;
     private logger;
     private body;
     private sanitizeParseOptions;
@@ -102,53 +89,86 @@ export declare class Parser {
      */
     private lastDiagnosticAsError;
     private declaration;
+    /**
+     * Try to get an identifier. If not found, add diagnostic and return undefined
+     */
+    private tryIdentifier;
+    private identifier;
+    private enumMemberStatement;
+    /**
+     * Create a new InterfaceMethodStatement. This should only be called from within `interfaceDeclaration`
+     */
+    private interfaceFieldStatement;
+    private consumeAsTokenAndTypeExpression;
+    /**
+     * Create a new InterfaceMethodStatement. This should only be called from within `interfaceDeclaration()`
+     */
+    private interfaceMethodStatement;
+    private interfaceDeclaration;
+    private enumDeclaration;
     /**
      * A BrighterScript class declaration
      */
     private classDeclaration;
-    private classFieldDeclaration;
+    private fieldDeclaration;
     /**
      * An array of CallExpression for the current function body
      */
     private callExpressions;
     private functionDeclaration;
-    private identifier;
     private functionParameter;
     private assignment;
+    private augmentedAssignment;
     private checkLibrary;
+    private checkAlias;
+    private checkTypeStatement;
     private statement;
     private whileStatement;
-    private exitWhile;
+    private exitStatement;
     private forStatement;
     private forEachStatement;
-    private exitFor;
-    private commentStatement;
     private namespaceStatement;
     /**
      * Get an expression with identifiers separated by periods. Useful for namespaces and class extends
      */
-    private getNamespacedVariableNameExpression;
+    private identifyingExpression;
     /**
      * Add an 'unexpected token' diagnostic for any token found between current and the first stopToken found.
      */
     private flagUntil;
     /**
      * Consume tokens until one of the `stopTokenKinds` is encountered
-     * @param tokenKinds
-     * @return - the list of tokens consumed, EXCLUDING the `stopTokenKind` (you can use `this.peek()` to see which one it was)
+     * @param stopTokenKinds a list of tokenKinds where any tokenKind in this list will result in a match
+     * @returns - the list of tokens consumed, EXCLUDING the `stopTokenKind` (you can use `this.peek()` to see which one it was)
      */
     private consumeUntil;
+    private constDeclaration;
     private libraryStatement;
     private importStatement;
+    private typecastStatement;
+    private aliasStatement;
+    private typeStatement;
     private annotationExpression;
     private ternaryExpression;
     private nullCoalescingExpression;
+    private regexLiteralExpression;
     private templateString;
     private tryCatchStatement;
     private throwStatement;
     private dimStatement;
+    private nestedInlineConditionalCount;
     private ifStatement;
     private blockConditionalBranch;
+    private conditionalCompileStatement;
+    private blockConditionalCompileBranch;
+    /**
+     * Parses a block, looking for a specific terminating TokenKind to denote completion.
+     * Always looks for `#end if` or `#else`
+     */
+    private conditionalCompileBlock;
+    private conditionalCompileConstStatement;
+    private conditionalCompileErrorStatement;
+    private ensureNewLine;
     private ensureNewLineOrColon;
     private ensureInline;
     private inlineConditionalBranch;
@@ -165,6 +185,10 @@ export declare class Parser {
      * @returns an AST representation of an `label` statement.
      */
     private labelStatement;
+    /**
+     * Parses a `continue` statement
+     */
+    private continueStatement;
     /**
      * Parses a `goto` statement
      * @returns an AST representation of an `goto` statement.
@@ -211,33 +235,60 @@ export declare class Parser {
     private call;
     private finishCall;
     /**
-     * Tries to get the next token as a type
-     * Allows for built-in types (double, string, etc.) or namespaced custom types in Brighterscript mode
-     * Will always return a token of whatever is next to be parsed
+     * Creates a TypeExpression, which wraps standard ASTNodes that represent a BscType
+     */
+    private typeExpression;
+    /**
+     * Gets a single "part" of a type of a potential Union type
+     * Note: this does not NEED to be part of a union type, but the logic is the same
+     *
+     * @param changedTokens an array that is modified with any tokens that have been changed from their default kind to identifiers - eg. when a keyword is used as type
+     * @returns an expression that was successfully parsed
      */
-    private typeToken;
+    private getTypeExpressionPart;
+    private typedFunctionTypeExpression;
+    private inlineInterface;
+    private inlineInterfaceMember;
     private primary;
+    private arrayLiteral;
+    private aaLiteral;
     /**
      * Pop token if we encounter specified token
      */
     private match;
     /**
      * Pop token if we encounter a token in the specified list
-     * @param tokenKinds
+     * @param tokenKinds a list of tokenKinds where any tokenKind in this list will result in a match
      */
     private matchAny;
+    /**
+     * If the next series of tokens matches the given set of tokens, pop them all
+     * @param tokenKinds a list of tokenKinds used to match the next set of tokens
+     */
+    private matchSequence;
     /**
      * Get next token matching a specified list, or fail with an error
      */
     private consume;
+    /**
+     * Consume next token IF it matches the specified kind. Otherwise, do nothing and return undefined
+     */
+    private consumeTokenIf;
+    private consumeToken;
     /**
      * Consume, or add a message if not found. But then continue and return undefined
      */
     private tryConsume;
+    private tryConsumeToken;
     private consumeStatementSeparators;
     private advance;
     private checkEndOfStatement;
     private checkPrevious;
+    /**
+     * Check that the next token kind is the expected kind
+     * @param tokenKind the expected next kind
+     * @returns true if the next tokenKind is the expected value
+     */
     private check;
     private checkAny;
     private checkNext;
@@ -246,29 +297,25 @@ export declare class Parser {
     private peekNext;
     private peek;
     private previous;
-    private synchronize;
     /**
-     * Get the token at the specified position
-     * @param position
-     */
-    getTokenAt(position: Position): Token;
-    /**
-     * Get the token closest to the position. if no token is found, the previous token is returned
-     * @param position
-     * @param tokens
+     * Sometimes we catch an error that is a diagnostic.
+     * If that's the case, we want to continue parsing.
+     * Otherwise, re-throw the error
+     *
+     * @param error error caught in a try/catch
      */
-    getClosestToken(position: Position): Token;
-    isPositionNextToTokenKind(position: Position, tokenKind: TokenKind): boolean;
-    getTokenBefore(currentToken: Token, tokenKind: TokenKind): Token;
-    tokenFollows(currentToken: Token, tokenKind: TokenKind): boolean;
-    getTokensUntil(currentToken: Token, tokenKind: TokenKind, direction?: -1 | 1): any[];
-    getPreviousToken(token: Token): Token;
+    private rethrowNonDiagnosticError;
     /**
-     * References are found during the initial parse.
-     * However, sometimes plugins can modify the AST, requiring a full walk to re-compute all references.
-     * This does that walk.
+     * Get the token that is {offset} indexes away from {this.current}
+     * @param offset the number of index steps away from current index to fetch
+     * @param tokenKinds the desired token must match one of these
+     * @example
+     * getToken(-1); //returns the previous token.
+     * getToken(0);  //returns current token.
+     * getToken(1);  //returns next token
      */
-    private findReferences;
+    private getMatchingTokenAtOffset;
+    private synchronize;
     dispose(): void;
 }
 export declare enum ParseMode {
@@ -279,60 +326,29 @@ export interface ParseOptions {
     /**
      * The parse mode. When in 'BrightScript' mode, no BrighterScript syntax is allowed, and will emit diagnostics.
      */
-    mode: ParseMode;
+    mode?: ParseMode;
     /**
      * A logger that should be used for logging. If omitted, a default logger is used
      */
     logger?: Logger;
+    /**
+     * Path to the file where this source code originated
+     */
+    srcPath?: string;
+    /**
+     * Should locations be tracked. If false, the `range` property will be omitted
+     * @default true
+     */
+    trackLocations?: boolean;
+    /**
+     * A map of BrightScript constants. If a constant is present in this map, it will be treated as a compile-time constant.
+     */
+    bsConsts?: Map<string, boolean>;
+    /**
+     * The minimum Roku firmware version required to run this project.
+     * When set to '15.3' or higher, line continuation (multi-line expressions in `.brs` files)
+     * is enabled even in BrightScript mode because Roku OS 15.3 added native support for it.
+     * Should be a semver-compatible string (e.g. '15.3.0').
+     */
+    minFirmwareVersion?: string;
 }
-export declare class References {
-    assignmentStatements: AssignmentStatement[];
-    classStatements: ClassStatement[];
-    get classStatementLookup(): Map<string, ClassStatement>;
-    private _classStatementLookup;
-    functionExpressions: FunctionExpression[];
-    functionStatements: FunctionStatement[];
-    /**
-     * A map of function statements, indexed by fully-namespaced lower function name.
-     */
-    get functionStatementLookup(): Map<string, FunctionStatement>;
-    private _functionStatementLookup;
-    importStatements: ImportStatement[];
-    libraryStatements: LibraryStatement[];
-    namespaceStatements: NamespaceStatement[];
-    newExpressions: NewExpression[];
-    propertyHints: Record<string, string>;
-}
-export interface LocalVarEntry {
-    lowerName: string;
-    nameToken: Identifier;
-    type: BscType;
-}
-/**
- * Gets the type of an expression. If it can not be processed, will return DynamicType
- *
- * @param expression the Expression to process
- * @param functionExpression the wrapping function expression
- * @return the best guess type of that expression
- */
-export declare function getBscTypeFromExpression(expression: Expression, functionExpression: FunctionExpression): BscType;
-/**
- * Gets the return type of a function, taking into account that the function may not have been declared yet
- * If the callee already exists in symbol table, use that return type
- * otherwise, make a lazy type which will not compute its type until the file is done parsing
- *
- * @param call the Expression to process
- * @param functionExpression the wrapping function expression
- * @return the best guess type of that expression
- */
-export declare function getTypeFromCallExpression(call: CallExpression, functionExpression: FunctionExpression): BscType;
-/**
- * Gets the type of a variable
- * if it already exists in symbol table, use that type
- * otherwise defer the type until first read, which will allow us to derive types from variables defined after this one (like from a loop perhaps)
- *
- * @param variable the Expression to process
- * @param functionExpression the wrapping function expression
- * @return the best guess type of that expression
- */
-export declare function getTypeFromVariableExpression(variable: VariableExpression, functionExpression: FunctionExpression): BscType;