brighterscript 0.65.1 → 0.66.0-alpha.0

package/dist/parser/SGTypes.d.ts

@@ -1,55 +1,143 @@
 import { SourceNode } from 'source-map';
 import type { Range } from 'vscode-languageserver';
-import type { FileReference, TranspileResult } from '../interfaces';
+import type { FileReference } from '../interfaces';
+import { BooleanType } from '../types/BooleanType';
+import { DynamicType } from '../types/DynamicType';
+import { FloatType } from '../types/FloatType';
+import { IntegerType } from '../types/IntegerType';
+import { LongIntegerType } from '../types/LongIntegerType';
+import { StringType } from '../types/StringType';
 import type { TranspileState } from './TranspileState';
 export interface SGToken {
     text: string;
     range?: Range;
 }
-export interface SGAttribute {
-    key: SGToken;
-    openQuote?: SGToken;
-    value: SGToken;
-    closeQuote?: SGToken;
-    range?: Range;
+export declare class SGAttribute {
+    constructor(key: SGToken, equals?: SGToken, openingQuote?: SGToken, value?: SGToken, closingQuote?: SGToken);
+    tokens: {
+        key: SGToken;
+        equals?: SGToken;
+        openingQuote?: SGToken;
+        value?: SGToken;
+        closingQuote?: SGToken;
+    };
+    get key(): string;
+    /**
+     * The value of this attribute. This does not including the opening or closing quote
+     */
+    get value(): string | undefined;
+    set value(val: string | undefined);
+    get range(): Range;
+    private _range;
+    transpile(state: TranspileState): SourceNode;
+    clone(): SGAttribute;
 }
-export declare class SGTag {
-    tag: SGToken;
+export declare class SGElement {
+    constructor(startTagOpen: SGToken, startTagName: SGToken, attributes?: SGAttribute[], startTagClose?: SGToken, elements?: SGElement[], endTagOpen?: SGToken, endTagName?: SGToken, endTagClose?: SGToken);
+    tokens: {
+        /**
+         * The first portion of the startTag. (i.e. `<` or `<?`)
+         */
+        startTagOpen: SGToken;
+        /**
+         * The name of the opening tag (i.e. CoolTag in `<CoolTag>`).
+         */
+        startTagName: SGToken;
+        /**
+         * The last bit of the startTag (i.e. `/>` for self-closing, `?>` for xml prologue, or `>` for tag with children)
+         */
+        startTagClose?: SGToken;
+        /**
+         * The endTag opening char `<`
+         */
+        endTagOpen?: SGToken;
+        /**
+         * The name of the ending tag (i.e. CoolTag in `</CoolTag>`)
+         */
+        endTagName?: SGToken;
+        /**
+         * The endTag closing char `>`
+         */
+        endTagClose?: SGToken;
+    };
+    /**
+     * Array of attributes found on this tag
+     */
     attributes: SGAttribute[];
-    range?: Range;
-    constructor(tag: SGToken, attributes?: SGAttribute[], range?: Range);
+    /**
+     * The array of direct children AST elements of this AST node
+     */
+    elements: SGElement[];
+    get range(): Range;
+    private _range;
+    /**
+     * Is this a self-closing tag?
+     */
+    get isSelfClosing(): boolean;
     get id(): string;
     set id(value: string);
+    /**
+     * Get the name of this tag.
+     */
+    get tagName(): string;
+    /**
+     * Find all direct children by their tag name (case insensitive).
+     * This does not step into children's children.
+     *
+     */
+    getElementsByTagName<T extends SGElement>(tagName: string): readonly T[];
+    /**
+     * Add a child to the end of the children array
+     */
+    addChild<T extends SGElement>(tag: T): T;
+    /**
+     * Remove a child from the children array.
+     * @returns true if node was found and removed, false if the node wasn't there and thus nothing was done
+     */
+    removeChild(tag: SGElement): boolean;
+    /**
+     * Does this node have the specified attribute?
+     */
+    hasAttribute(name: string): boolean;
+    /**
+     * Get an SGAttribute by its name (case INsensitive)
+     */
     getAttribute(name: string): SGAttribute | undefined;
+    /**
+     * Get an attribute value by its name
+     */
     getAttributeValue(name: string): string | undefined;
-    setAttribute(name: string, value: string): void;
+    /**
+     * Set an attribute value by its name. If no attribute exists with this name, it is created
+     */
+    setAttributeValue(name: string, value: string): void;
+    /**
+     * Remove an attribute by its name. DO NOT USE this to edit AST (use ASTEditor)
+     * @returns true if an attribute was found and removed. False if no attribute was found
+     */
+    removeAttribute(name: string): boolean;
     transpile(state: TranspileState): SourceNode;
-    protected transpileBody(state: TranspileState): (string | SourceNode)[];
-    protected transpileAttributes(state: TranspileState, attributes: SGAttribute[]): (string | SourceNode)[];
+    protected transpileBody(state: TranspileState): SourceNode;
+    protected transpileAttributes(state: TranspileState, attributes: SGAttribute[]): SourceNode;
 }
-export declare class SGProlog extends SGTag {
-    transpile(state: TranspileState): SourceNode;
+export declare class SGProlog extends SGElement {
 }
-export declare class SGNode extends SGTag {
-    children: SGNode[];
-    constructor(tag: SGToken, attributes?: SGAttribute[], children?: SGNode[], range?: Range);
-    protected transpileBody(state: TranspileState): (string | SourceNode)[];
+export declare class SGNode extends SGElement {
 }
-export declare class SGChildren extends SGNode {
-    constructor(tag?: SGToken, children?: SGNode[], range?: Range);
+export declare class SGChildren extends SGElement {
 }
-export declare class SGScript extends SGTag {
+export declare class SGCustomization extends SGElement {
+}
+export declare class SGScript extends SGElement {
     cdata?: SGToken;
-    constructor(tag?: SGToken, attributes?: SGAttribute[], cdata?: SGToken, range?: Range);
     get type(): string;
     set type(value: string);
     get uri(): string;
     set uri(value: string);
-    protected transpileBody(state: TranspileState): (string | SourceNode)[];
-    protected transpileAttributes(state: TranspileState, attributes: SGAttribute[]): (string | SourceNode)[];
+    protected transpileBody(state: TranspileState): SourceNode;
+    protected transpileAttributes(state: TranspileState, attributes: SGAttribute[]): SourceNode;
 }
-export declare class SGField extends SGTag {
-    constructor(tag?: SGToken, attributes?: SGAttribute[], range?: Range);
+export declare class SGInterfaceField extends SGElement {
     get type(): string;
     set type(value: string);
     get alias(): string;
@@ -61,33 +149,173 @@ export declare class SGField extends SGTag {
     get alwaysNotify(): string;
     set alwaysNotify(value: string);
 }
+export declare enum SGFieldType {
+    integer = "integer",
+    int = "int",
+    longinteger = "longinteger",
+    float = "float",
+    string = "string",
+    str = "str",
+    boolean = "boolean",
+    bool = "bool",
+    vector2d = "vector2d",
+    color = "color",
+    time = "time",
+    uri = "uri",
+    node = "node",
+    floatarray = "floatarray",
+    intarray = "intarray",
+    boolarray = "boolarray",
+    stringarray = "stringarray",
+    vector2darray = "vector2darray",
+    colorarray = "colorarray",
+    timearray = "timearray",
+    nodearray = "nodearray",
+    assocarray = "assocarray",
+    array = "array",
+    roarray = "roarray",
+    rect2d = "rect2d",
+    rect2darray = "rect2darray"
+}
 export declare const SGFieldTypes: string[];
-export declare class SGFunction extends SGTag {
-    constructor(tag?: SGToken, attributes?: SGAttribute[], range?: Range);
+export declare function getBscTypeFromSGFieldType(sgFieldType: string): DynamicType | FloatType | IntegerType | LongIntegerType | StringType | BooleanType;
+export declare class SGInterfaceFunction extends SGElement {
     get name(): string;
     set name(value: string);
 }
-export declare class SGInterface extends SGTag {
-    fields: SGField[];
-    functions: SGFunction[];
-    constructor(tag?: SGToken, content?: SGTag[], range?: Range);
-    getField(id: string): SGField;
-    setField(id: string, type: string, onChange?: string, alwaysNotify?: boolean, alias?: string): void;
-    getFunction(name: string): SGFunction;
-    setFunction(name: string): void;
-    protected transpileBody(state: TranspileState): (string | SourceNode)[];
+export declare type SGInterfaceMember = SGInterfaceField | SGInterfaceFunction;
+export declare class SGInterface extends SGElement {
+    get fields(): readonly SGInterfaceField[];
+    get functions(): readonly SGInterfaceFunction[];
+    get members(): readonly SGInterfaceMember[];
+    /**
+     * Check if there's an SGField with the specified name
+     */
+    hasField(id: string): boolean;
+    /**
+     * Check if there's an SGFunction with the specified name
+     */
+    hasFunction(name: string): boolean;
+    /**
+     * Find a field by its ID
+     */
+    getField(id: string): SGInterfaceField;
+    /**
+     * Set the value of a field. Creates a new field if one does not already exist with this ID
+     */
+    setField(id: string, type: string, onChange?: string, alwaysNotify?: boolean, alias?: string): SGInterfaceField;
+    /**
+     * Remove a field from the interface
+     * @returns true if a field was found and removed. Returns false if no field was found with that name
+     */
+    removeField(id: string): boolean;
+    /**
+     * Get the interface function with the specified name
+     */
+    getFunction(name: string): SGInterfaceFunction;
+    /**
+     * Add or replace a function on the interface
+     */
+    setFunction(name: string): SGInterfaceFunction;
+    /**
+     * Remove a function from the interface
+     * @returns true if a function was found and removed. Returns false if no function was found with that name
+     */
+    removeFunction(name: string): boolean;
 }
-export declare class SGComponent extends SGTag {
-    constructor(tag?: SGToken, attributes?: SGAttribute[], content?: SGTag[], range?: Range);
-    api: SGInterface;
-    scripts: SGScript[];
-    children: SGChildren;
-    customizations: SGNode[];
+/**
+ * The `<component>` element in SceneGraph. Not to be confused about usages of components like `<Rectangle>`, those are considered `SGNode` instances.
+ */
+export declare class SGComponent extends SGElement {
+    /**
+     * Get all the <Field> and <Function> elements across all <Interface> nodes in this component
+     */
+    get interfaceMembers(): readonly SGInterfaceMember[];
+    get scriptElements(): readonly SGScript[];
+    /**
+     * Get the <interface> element from this component (if present), or undefined if not.
+     * NOTE: Roku supports and merges multiple <interface> elements in a component, but this
+     * property points to the FIRST one. If you need to check whether a member exists,
+     * look through `this.interfaceMemebers` instead.
+     */
+    get interfaceElement(): SGInterface | undefined;
+    /**
+     * Get the `<children>` element of this component. (not to be confused with the AST `childTags` property).
+     * If there are multiope `<children>` elements, this function will return the last `<children>` tag because that's what Roku devices do.
+     */
+    get childrenElement(): SGChildren;
+    get customizationElements(): readonly SGCustomization[];
+    /**
+     * Specifies the name of the component, that allows you to create the component in your application.
+     * For example, if the name of the component is `CastMemberInfo`, you could create instances of the component declaratively
+     * in a child node element of a component `<children>` element (`<CastMemberInfo/>`), or using BrightScript in a `<script>`
+     * element (`createObject("roSGNode","CastMemberInfo")`).
+     *
+     * The name attribute is case-sensitive. You cannot successfully create or declare a component unless the component name exactly
+     *  matches the name attribute, including case. Also be aware that two components with the exact same name in the same application
+     * components directory will have undefined and generally undesirable results if you attempt to create a component object with that name in the application.
+     */
     get name(): string;
     set name(value: string);
+    /**
+     * Specifies the name of the built-in or extended SceneGraph scene or node class whose functionality is extended by this component.
+     *
+     * For example, `extends="Group"` specifies that the component has all of the functionality of the Group node class (it can have child nodes, has translation/scale/rotation fields, and so forth).
+     *
+     * By default, a component extends the Group node class.
+     */
     get extends(): string;
     set extends(value: string);
-    protected transpileBody(state: TranspileState): (string | SourceNode)[];
+    /**
+     * Specifies the ID of a node declared in the XML file to have the initial remote control focus when the component is instantiated.
+     */
+    get initialFocus(): string;
+    set initialFocus(value: string);
+    /**
+     * Specifies the version of the SceneGraph API. The default is 1.0 if not specified.
+     */
+    get version(): string;
+    set version(value: string);
+    /**
+     * Does the specified field exist in the component interface?
+     */
+    hasInterfaceField(id: string): boolean;
+    /**
+     * Does the specified function exist in the component interface?
+     */
+    hasInterfaceFunction(name: string): boolean;
+    /**
+     * Get an interface field with the specified name
+     */
+    getInterfaceField(name: string): SGInterfaceField | undefined;
+    /**
+     * Return the first SGInterface node found, or insert a new one then return it
+     */
+    private ensureInterfaceNode;
+    /**
+     * Create or update a <field> interface element.
+     * This will create a new `<interface>` element if there are none on the component already
+     */
+    setInterfaceField(id: string, type: string, onChange?: string, alwaysNotify?: boolean, alias?: string): SGInterfaceField;
+    /**
+     * Create or update a <function> interface element.
+     * This will create a new `<interface>` element if there are none on the component already
+     */
+    setInterfaceFunction(name: string): SGInterfaceFunction;
+    /**
+     * Remove an interface field.
+     * @returns true if a field was found and removed. Returns false if no field was found with that name
+     */
+    removeInterfaceField(id: string): boolean;
+    /**
+     * Get an interface field with the specified name
+     */
+    getInterfaceFunction(name: string): SGInterfaceFunction | undefined;
+    /**
+     * Remove an interface function.
+     * @returns true if a function was found and removed. Returns false if no function was found with that name
+     */
+    removeInterfaceFunction(name: string): boolean;
 }
 export interface SGReferences {
     name?: SGToken;
@@ -95,9 +323,9 @@ export interface SGReferences {
     scriptTagImports: Pick<FileReference, 'pkgPath' | 'text' | 'filePathRange'>[];
 }
 export declare class SGAst {
-    prolog?: SGProlog;
-    root?: SGTag;
-    component?: SGComponent;
-    constructor(prolog?: SGProlog, root?: SGTag, component?: SGComponent);
-    transpile(state: TranspileState): TranspileResult;
+    prologElement?: SGProlog;
+    rootElement?: SGElement;
+    componentElement?: SGComponent;
+    constructor(prologElement?: SGProlog, rootElement?: SGElement, componentElement?: SGComponent);
+    transpile(state: TranspileState): SourceNode;
 }