BrighterScript

Annotations are metadata markers that can be used, most commonly by plugins, to change or manipulate code during the compilation lifecycle based on the presence of the annotation.

'mostly useful for plugins that change code based on annotations
@logOnException()
sub doSomething()
    '...
end

You can define hierarchical namespaces in two ways:

1. Dotted Identifiers: Using a single declaration with dots (e.g., namespace A.B).
2. Nested Blocks: Declaring a namespace inside another namespace block.

Both methods result in the same underscore-separated transpiled names.

namespace Vertibrates
    namespace Birds
        sub Quack()
        end sub
    end namespace

    namespace Reptiles
        sub Hiss()
        end sub
    end namespace
end namespace

BrighterScript uses two different transpilation strategies for the ?? operator to balance performance and safety:

1. Simple Transpilation: If BrighterScript determines that both the consequent (left side) and the alternate (right side) are side-effect free and will not cause a rendezvous, it uses a high-performance call to bslib_coalesce.

2. Scope Capturing: If the expressions involve side effects or potential rendezvous, BrighterScript wraps the operation in an immediately-invoked-function-expression (IIFE). This captures local variables and ensures that the consequent is evaluated exactly once, and the alternate is only evaluated if the consequent is invalid.

// Simple (side-effect free)
userId = createdUserId ?? -1

// Scope Capturing (potential side effects/rendezvous)
name = userA.name ?? userB.name

Annotations allow you to attach metadata to statements, functions, or classes. This metadata is used by plugins during the compilation process to modify how code is transpiled or analyzed.

Important: Annotations are purely for compile-time use. They are completely removed during transpilation and are not available at runtime in the resulting BrightScript code.

@expose
class MyComp
end class

@task @export_fields([content, result])
function init()
end function

Use the import keyword to bring in code from other files using the pkg:/ URI scheme.

import "pkg:/source/util.bs"
sub main()
    print util_toUpper("hello world")
end sub

The language server determines which files to process by combining multiple exclusion sources. The final set of processed files is the result of applying all the following rules:

1. VS Code built-in exclusions:
   • files.exclude: Files hidden from the VS Code file explorer.
   • files.watcherExclude: Files ignored by the file watcher.
   • search.exclude: Files ignored during search operations.
2. BrighterScript-specific exclusions:
   • brightscript.languageServer.projectDiscoveryExclude: Files ignored during project discovery.
3. Standard exclusions:
   • Patterns defined in .gitignore.
   • Common directories: node_modules, .git, out, and .roku-deploy-staging.

You can define immutable values using the const keyword.

const API_URL = "https://api.acme.com/v1/"
sub main()
    print API_URL
end sub

BrighterScript provides a LanguageServer class that implements Microsoft's Language Server Protocol (LSP). This allows developers to integrate BrighterScript support into any IDE that supports LSP.

The vscode-BrightScript-language extension for Visual Studio Code is a primary example of an implementation using this class.

To improve discoverability on npm, follow these naming conventions when publishing your plugins:

• Unscoped packages: Use the prefix bsc-plugin- (e.g., bsc-plugin-auto-findnode).
• Scoped packages: Use the format @<scope>/bsc-plugin-<plugin-name> (e.g., @rokucommunity/bsc-plugin-auto-findnode) or @<scope>/bsc-plugin (e.g., @maestro/bsc-plugin).