### Template String Examples

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Illustrates creating template strings for variable interpolation and multi-line strings.

```brighterscript
name = `John Smith`

text = `hello ${name}`

text = `first line text
second line text`
```

--------------------------------

### Annotation Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Example of using an annotation for potential plugin functionality.

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

--------------------------------

### Install BrighterScript via npm

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Install the BrighterScript command-line interface globally using npm. This command makes the `bsc` tool available in your terminal.

```bash
npm install brighterscript -g
```

--------------------------------

### Example BrightScript Code

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

This is an example of BrightScript code that will be modified by a plugin.

```brightscript
sub main()
    print "hello <FIRST_NAME>"
end sub
```

--------------------------------

### Tagged Template String Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/template-strings.md

Provides a simple example of a tagged template string, showing how the tag function processes string parts and expression values.

```BrighterScript
function zombify(strings, values)
    result = ""
    for i = 0 to strings.count() - 1
        value = values[i]
        if value = "Human" then
          value = "Zombie"
        end if
        result = result + strings[i] + value
    end for
    result += strings[i]
    return result
end function

function main()
  name = "Human"
  print zombify`Hello ${name}` ' prints "Hello Zombie"
end function
```

```BrightScript
function zombify(strings, values)
    result = ""
    for i = 0 to strings.count() - 1
        value = values[i]
        if value = "Human" then
            value = "Zombie"
        end if
        result = result + strings[i] + value
    end for
    result += strings[i]
    return result
end function

function main()
    name = "Human"
    print zombify(["Hello ", ""], [name]) ' prints "Hello Zombie"
end function
```

--------------------------------

### Transpiled BrightScript for Class Constructor

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

The transpiled version of the BrighterScript constructor example, illustrating how the 'new' method is translated into BrightScript.

```BrightScript
sub __Duck_method_new(name as string)
    m.name = invalid
    m.end sub = invalid
    m.name = name
end sub
function __Duck_builder()
    instance = {}
    instance.new = __Duck_method_new
    return instance
end function
function Duck(name as string)
    instance = __Duck_builder()
    instance.new(name)
    return instance
end function
```

--------------------------------

### Minimal bsconfig.json example

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

A basic bsconfig.json file for a new BrighterScript project. Specifies source directory, files to include, staging folder, and auto-import component script.

```jsonc
{
    "rootDir": "src",
    "files": [
        "**/*"
    ],
    "stagingFolderPath": "dist",
    "retainStagingFolder": true,
    "autoImportComponentScript": true,
    "sourceMap": true
}
```

--------------------------------

### BrighterScript Annotations Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/annotations.md

Demonstrates the syntax for applying annotations like @expose, @task, @export_fields, and @configure to classes and functions. Annotations are placed before the statement they modify.

```brighterscript
@expose
class MyComp
end class

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

@configure(
    "value",
    42,
    true,
    {
        hello: "world",
        scene: "MainScene"
    }
)
function main()
end
```

--------------------------------

### Install bslib with alias using ropm CLI

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Installs the bslib package from npm with a 'bslib' alias, recommended for NodeJS 12+ for smaller transpiled code.

```bash
ropm install bslib@npm:@rokucommunity/bslib
```

--------------------------------

### Install bslib directly using ropm CLI

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Installs the bslib package directly from npm without an alias. This is for NodeJS versions less than 12.

```bash
ropm install @rokucommunity/bslib
```

--------------------------------

### Install and Transpile Plugin Manually

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

Installs necessary modules and manually transpiles a TypeScript plugin to JavaScript using the TypeScript compiler. Includes options for source maps and watching for changes.

```bash
# install modules needed to compile a plugin
npm install brighterscript typescript @types/node -D

# transpile to JS (with source maps for debugging)
npx tsc myPlugin.ts -m commonjs --sourceMap

# add --watch for continuous transpilation
npx tsc myPlugin.ts -m commonjs --sourceMap --watch
```

--------------------------------

### Combine Regular and Advanced File Patterns

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

An example demonstrating how to include both direct file paths and advanced object-based file specifications within the 'files' array. This allows for a mix of simple copies and more complex routing.

```jsonc
{
    "rootDir": "C:/projects/CatVideoPlayer",
    "files": [
        "source/main.brs",
        {
          "src": "../common/promise.brs",
          "dest": "source/common"
        }
    ]
}
```

--------------------------------

### BrighterScript Class Inheritance Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Demonstrates inheritance with Animal, Duck, and BabyDuck classes, showcasing method overriding and super calls. Use this to understand hierarchical class structures.

```BrighterScript
class Animal
    sub new(name as string)
        m.name = name
    end sub

    name as string

    sub move(distanceInMeters as integer)
        print m.name + " moved " + distanceInMeters.ToStr() + " meters"
    end sub
end class

class Duck extends Animal
    override sub move(distanceInMeters as integer)
        print "Waddling..."
        super.move(distanceInMeters)
    end sub
end class

class BabyDuck extends Duck
    override sub move(distanceInMeters as integer)
        super.move(distanceInMeters)
        print "Fell over...I'm new at this"
    end sub
end class

sub Main()
    smokey = new Animal("Smokey")
    smokey.move(1)
    '> Bear moved 1 meters

    donald = new Duck("Donald")
    donald.move(2)
    '> Waddling...\nDonald moved 2 meters

    dewey = new BabyDuck("Dewey")
    dewey.move(3)
    '> Waddling...\nDewey moved 2 meters\nFell over...I'm new at this
end sub
```

--------------------------------

### Install and Run Plugin with ts-node

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

Installs necessary modules and runs the BrighterScript CLI using ts-node to transpile a TypeScript plugin dynamically. This simplifies the development workflow by handling TypeScript compilation on the fly.

```bash
# install modules needed to compile a plugin
npm install brighterscript typescript @types/node ts-node -D

#run the brighterscript cli and use ts-node to dynamically transpile your plugin
npx bsc --sourceMap --require ts-node/register --plugins myPlugin.ts
```

--------------------------------

### Transpiled BrightScript for Class Inheritance

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

The transpiled version of the BrighterScript inheritance example, showing how BrighterScript classes are converted to BrightScript functions and subroutines.

```BrightScript
sub __Animal_method_new(name as string)
    m.name = invalid
    m.name = name
end sub
sub __Animal_method_move(distanceInMeters as integer)
    print m.name + " moved " + distanceInMeters.ToStr() + " meters"
end sub
function __Animal_builder()
    instance = {}
    instance.new = __Animal_method_new
    instance.move = __Animal_method_move
    return instance
end function
function Animal(name as string)
    instance = __Animal_builder()
    instance.new(name)
    return instance
end function
sub __Duck_method_new(name as string)
    m.super0_new(name)
end sub
sub __Duck_method_move(distanceInMeters as integer)
    print "Waddling..."
    m.super0_move(distanceInMeters)
end sub
function __Duck_builder()
    instance = __Animal_builder()
    instance.super0_new = instance.new
    instance.new = __Duck_method_new
    instance.super0_move = instance.move
    instance.move = __Duck_method_move
    return instance
end function
function Duck(name as string)
    instance = __Duck_builder()
    instance.new(name)
    return instance
end function
sub __BabyDuck_method_new(name as string)
    m.super1_new(name)
end sub
sub __BabyDuck_method_move(distanceInMeters as integer)
    m.super1_move(distanceInMeters)
    print "Fell over...I'm new at this"
end sub
function __BabyDuck_builder()
    instance = __Duck_builder()
    instance.super1_new = instance.new
    instance.new = __BabyDuck_method_new
    instance.super1_move = instance.move
    instance.move = __BabyDuck_method_move
    return instance
end function
function BabyDuck(name as string)
    instance = __BabyDuck_builder()
    instance.new(name)
    return instance
end function

sub Main()
    smokey = Animal("Smokey")
    smokey.move(1)
    '> Bear moved 1 meters
    donald = Duck("Donald")
    donald.move(2)
    '> Waddling...\nDonald moved 2 meters
    dewey = BabyDuck("Dewey")
    dewey.move(3)
    '> Waddling...\nDewey moved 2 meters\nFell over...I'm new at this
end sub
```

--------------------------------

### BrighterScript Class Constructor Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Defines a 'Duck' class with a 'new' constructor that initializes the 'name' property. Use this for basic class instantiation.

```BrighterScript
class Duck
    sub new(name as string)
        m.name = name
    end sub

    name as string
end sub
```

--------------------------------

### BrighterScript Class Instance Binding Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Demonstrates how `m` refers to the class instance when methods are invoked directly on an object. Shows that lifting a function off the object results in `m` referring to the global scope.

```brighterscript
class Person
    sub new(name as string)
        m.name = name
    end sub
    sub sayHello()
        print m.name
    end sub
end class

sub main()
    m.name = "Main method"
    bob = new SomeClass("bob")

    'works as expected...the `m` reference is `bob`
    bob.sayHello() 'prints "Bob"

    'lift the function off of `bob`
    sayHello = bob.sayHello

    '`m` is actually the global `m` scope
    sayHello() ' prints "Main method"
end sub
```

```BrightScript
sub __Person_method_new(name as string)
    m.name = name
end sub
sub __Person_method_sayHello()
    print m.name
end sub
function __Person_builder()
    instance = {}
    instance.new = __Person_method_new
    instance.sayHello = __Person_method_sayHello
    return instance
end function
function Person(name as string)
    instance = __Person_builder()
    instance.new(name)
    return instance
end function

sub main()
    m.name = "Main method"
    bob = SomeClass("bob")
    'works as expected...the `m` reference is `bob`
    bob.sayHello() 'prints "Bob"
    'lift the function off of `bob`
    sayHello = bob.sayHello
    '`m` is actually the global `m` scope
    sayHello() ' prints "Main method"
end sub
```

--------------------------------

### Diagnostic Plugin Example (No Underscores)

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

An example of a BrighterScript diagnostic plugin that checks for and reports function names containing underscores. It uses the `afterFileValidate` hook to inspect function statements.

```typescript
// bsc-plugin-no-underscores.ts
import { CompilerPlugin, BscFile, isBrsFile } from 'brighterscript';

// plugin factory
export default function () {
    return {
        name: 'no-underscores',
        // post-parsing validation
        afterFileValidate: (file: BscFile) => {
            if (isBrsFile(file)) {
                // visit function statements and validate their name
                file.parser.references.functionStatements.forEach((fun) => {
                    if (fun.name.text.includes('_')) {
                        file.addDiagnostics([{
                            code: 9000,
                            message: 'Do not use underscores in function names',
                            range: fun.name.range,
                            file
                        }]);
                    }
                });
            }
        }
    } as CompilerPlugin;
};
```

--------------------------------

### Custom files array including additional assets

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Example of a custom 'files' array that includes the default directories plus an additional 'assets' folder. This demonstrates how to specify the entire array when including non-standard directories.

```json
{
    "files": [
        "source/**/*",
        "components/**/*",
        "images/**/*",
        "manifest"
        "assets/**/*"
    ]
}
```

--------------------------------

### Template String Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Utilize template strings for easy string interpolation. Variables within the string are automatically embedded.

```brighterscript
print `Hello ${firstNameVar}`
```

--------------------------------

### Ternary Expression Assignment Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/ternary-operator.md

Illustrates a valid use of the ternary operator within an assignment expression.

```BrightScript
a = myValue ? "a" : "b"
```

--------------------------------

### Class Definition

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Defines a simple 'Movie' class with a title and a method to get actors.

```brighterscript
class Movie
    public title as string
    private _actors = invalid
    public sub getActors()
        if m._actors = invalid
            m._actors = api_get_actors()
        end if
        return m._actors
    end sub
end class
```

--------------------------------

### Hex Integer Enum Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/enums.md

Shows how to use hex integer literals within a numeric enum. The hex values are treated as their decimal equivalents for incrementing purposes.

```BrighterScript
enum Colors
    lessRed = 254
    red = &HFF ' this is 255
    moreRed
end enum
sub main()
    print Colors.lessRed
    print Colors.red
    print Colors.moreRed
end sub
```

```BrightScript
sub main()
    print 254
    print &HFF
    print 256
end sub
```

--------------------------------

### Constructing a Class Instance

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Shows the syntax for creating a new instance of a class, passing arguments to the constructor.

```vb
donald = new Person("Donald")
daisy = new Person("Daisy")
```

```BrightScript
donald = Person("Donald")
daisy = Person("Daisy")
```

--------------------------------

### Basic Template String Syntax

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/template-strings.md

Demonstrates basic template string usage for simple strings, embedded expressions, and multi-line strings.

```BrighterScript
name = `John Smith`

text = `hello ${name}`

text = `first line text
second line text`

text = tag`hello ${name} how are you`
```

```BrightScript
name = "John Smith"
text = ("hello " + bslib_toString(name))
text = ("first line text" + chr(10) + "second line text")
text = tag(["hello ", " how are you"], [name])
```

--------------------------------

### Build and Watch Commands

Source: https://github.com/rokucommunity/brighterscript/blob/master/AGENTS.md

Commands for building the project and watching for file changes during development.

```bash
npm run build          # compile TypeScript (rimraf out && tsc)
npm run watch          # compile in watch mode
```

--------------------------------

### Null-Coalescing Operator Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

The null-coalescing operator provides a default value if the left-hand operand is null or undefined.

```brighterscript
user = m.user ?? getDefaultUser()
```

--------------------------------

### Basic BrighterScript Compilation

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Compile a BrightScript project using the `bsc` command. This command assumes your project structure matches Roku's standard and is run from the project root. It checks for errors and produces a zip file in the `./out/project.zip` directory if successful.

```bash
bsc
```

--------------------------------

### Watch mode with deploy and host configuration

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Runs the compiler in watch mode, redeploying to the Roku device on every change. Requires host IP and password.

```bash
bsc --watch --deploy --host 192.168.1.10 --password secret_password
```

--------------------------------

### Compile from a subdirectory

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Use this command when your project resides in a subdirectory of your workspace folder.

```bash
bsc --root-dir ./rokuSourceFiles
```

--------------------------------

### Null-Conditional Operator Example

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

The null-conditional operator safely accesses nested properties. It returns undefined if any part of the chain is null or undefined.

```brighterscript
userSettings = m.user?.account?.profile?.settings
```

--------------------------------

### Constant Declaration and Usage

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Shows how to declare and use a constant for API URLs.

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

--------------------------------

### Basic BrighterScript Import

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/imports.md

Demonstrates how to use the `import` statement in a BrighterScript file to include external libraries. This is useful for organizing code and reusing functionality across components.

```BrighterScript
import "pkg:/source/lib.bs"

function Init()
    SomeFunctionFromLib()
end function
```

--------------------------------

### Namespace and Function Definition

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Illustrates defining a namespace and a function within it.

```brighterscript
namespace util
    function toUpper(value as string)
        return
    end function
end namespace

sub main()
    print util.toUpper("hello world")
end sub
```

--------------------------------

### Declarative Plugin Configuration

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

Configure plugins by listing their paths or npm package names in the bsconfig.json file. This method is used by the VSCode extension for live diagnostics.

```json
{
    "plugins": [
        "./scripts/myPlugin.js",
        "@rokucommunity/bslint"
    ]
}
```

--------------------------------

### Property Initialization in BrighterScript Classes

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Illustrates how to initialize class properties with default values directly in their declaration.

```BrighterScript
class Duck
    name = "Donald"
    hasChildren = true
end class
```

```BrightScript
sub __Duck_method_new()
    m.name = "Donald"
    m.hasChildren = true
end sub
function __Duck_builder()
    instance = {}
    instance.new = __Duck_method_new
    return instance
end function
function Duck()
    instance = __Duck_builder()
    instance.new()
    return instance
end function
```

--------------------------------

### CLI Plugin Configuration

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

Specify plugins directly on the command line when using the BrighterScript compiler (bsc).

```bash
npx bsc --plugins "./scripts/myPlugin.js" "@rokucommunity/bslint"
```

--------------------------------

### Use a specific bsconfig.json file

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Specifies a bsconfig.json file located in a different folder than the current working directory.

```bash
bsc --project ./some_folder/bsconfig.json
```

--------------------------------

### Print PKG_PATH

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints the pkg path of the file. This is useful for identifying the location of the file within the Roku package structure.

```BrighterScript
function main()
    print PKG_PATH
end function
```

```BrightScript
function main()
    print "pkg:/source/main.brs"
end function
```

--------------------------------

### Source Literal Variables

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Demonstrates the usage of built-in source literal variables.

```brighterscript
print SOURCE_FILE_PATH
print SOURCE_LINE_NUM
print FUNCTION_NAME
print SOURCE_FUNCTION_NAME
print SOURCE_LOCATION
print PKG_PATH
print PKG_LOCATION
```

--------------------------------

### Simple Interface Definition and Usage

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/interfaces.md

Defines a 'Person' interface with a name property and a getName method. Shows how to use this interface as a parameter type.

```BrighterScript
interface Person
    name as string
    function getName() as string
end interface

sub test(bob as Person)
    print bob.name, bob.getName()
end sub
```

```BrightScript
sub test(bob as object)
    print bob.name, bob.getName()
end sub
```

--------------------------------

### Handle File Collisions by Overriding

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Demonstrates how to override files from a base project by specifying alternative files later in the 'files' array. This is useful for managing project variations or updates.

```jsonc
{
    "files": [
        {
            //copy all files from the base project
            "src": "../BaseProject/**/*"
        },
        // Override "../BaseProject/themes/theme.brs"
        // with "${rootDir}/themes/theme.brs"
        "themes/theme.brs"
    ]
}
```

--------------------------------

### Interface Usage in Functions

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/interfaces.md

Demonstrates using interfaces as parameter and return types for functions. These are transpiled to `object` types.

```BrighterScript
interface Dog
    name as string
    function walk()
end interface

sub walkThePuppy(puppy as Dog) as Dog
    puppy.walk()
    return puppy
end sub
```

```BrightScript
sub walkThePuppy(puppy as object) as object
    puppy.walk()
    return puppy
end sub
```

--------------------------------

### Line Continuation in BrightScript Files

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Enables line continuation in `.brs` files when `minFirmwareVersion` is set to `15.3` or higher. BrighterScript (`.bs`) files support this feature regardless of the firmware version due to transpilation.

```brs
' allowed in .brs files when minFirmwareVersion >= 15.3
sub main()
    result = firstValue +
             secondValue

    someFunction(
        arg1,
        arg2
    )
end sub
```

--------------------------------

### Constructor with Inheritance in BrighterScript

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Demonstrates how to call the parent constructor using 'super()' in a child class's constructor. The call to 'super()' must be the first line.

```vb
class Duck
    sub new(name as string)
        m.name = name
    end sub
    name as string
end class

class BabyDuck extends Duck
    sub new(name as string, age as integer)
        'the first line in this constructor must be a call to super()
        super(name)
        m.age = age
    end sub
    age as integer
end class
```

```BrightScript
sub __Duck_method_move(name as string)
    m.name = invalid
    m.name = name
end sub
function __Duck_builder()
    instance = {}
    instance.new = __Duck_method_move
    return instance
end function
function Duck(name as string)
    instance = __Duck_builder()
    instance.new(name)
    return instance
end function
sub __BabyDuck_method_move(name as string, age as integer)
    m.super0_new()
    m.age = invalid
    'the first line in this constructor must be a call to super()
    m.super0_new(name)
    m.age = age
end sub
function __BabyDuck_builder()
    instance = __Duck_builder()
    instance.super0_new = instance.new
    instance.new = __BabyDuck_method_move
    return instance
end function
function BabyDuck(name as string, age as integer)
    instance = __BabyDuck_builder()
    instance.new(name, age)
    return instance
end function
```

--------------------------------

### Interface with Optional Members

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/interfaces.md

Demonstrates defining an interface with optional properties and methods using the `optional` keyword. These members are included in completion but do not cause validation errors if missing.

```BrighterScript
interface Video
    url as string
    length as float
    optional subtitleUrl as string
    optional rating as string
    optional genre as string
end interface
```

--------------------------------

### Lint and Format Commands

Source: https://github.com/rokucommunity/brighterscript/blob/master/AGENTS.md

Commands for maintaining code quality and consistency.

```bash
npm run lint           # eslint + EOL check
npm run format         # format with tsfmt
```

--------------------------------

### Nesting Namespaces

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/namespaces.md

Demonstrates how to declare nested namespaces using dotted identifiers, forming a hierarchical structure for organizing code.

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

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

```BrightScript
sub Vertibrates_Birds_Quack()
end sub
sub Vertibrates_Reptiles_Hiss()
end sub
```

--------------------------------

### Testing Commands

Source: https://github.com/rokucommunity/brighterscript/blob/master/AGENTS.md

Commands for running tests, with and without code coverage.

```bash
npm run test:nocover   # run all tests without coverage
npm test               # run all tests with coverage (nyc mocha)
npm run test:watch     # run tests in watch mode
```

--------------------------------

### Optional extends in bsconfig.json

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Use the 'extends' property prefixed with '?' to optionally inherit configurations from another bsconfig.json file. This prevents errors if the specified file does not exist.

```json
{
  "extends": "?path/to/optional/bsconfig.json"
}
```

--------------------------------

### Excluding files using negative glob patterns

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Demonstrates how to exclude specific files from being included in the project output using negative glob patterns (prefixed with '!'). The negative pattern must appear after the positive pattern it overrides.

```json
{
    "files": [
        "source/**/*",
        "!source/some/unwanted/file.brs"
    ]
}
```

--------------------------------

### Component XML with Script Includes

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/imports.md

Illustrates how a component XML file includes both the transpiled BrighterScript file and the imported library script using `<script>` tags.

```XML
<?xml version="1.0" encoding="utf-8" ?>
<component name="BaseScene" extends="Scene">
  <children>
    <Rectangle id="myRectangle" color="#FF0000" width="1920" height="1080" opacity=".6" translation="[0,0]" />
  </children>
  <script uri="Widget.brs" />
  <script uri="pkg:/source/lib.brs" />
</component>
```

--------------------------------

### Specify Single File Destination

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Use this configuration when 'src' points to a single file. Ensure that the 'dest' property includes the filename and extension to correctly place the file in the output directory.

```jsonc
{ "src": "lib/Promise/promise.brs", "dest": "source/promise.brs" }
```

--------------------------------

### Interfaces within Namespaces

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/interfaces.md

Shows how to define interfaces within namespaces for better organization. The transpiled code treats them as generic objects.

```BrighterScript
namespace humanoids
    interface Person
        name as string
        function getName() as string
    end interface
end namespace

sub test(bob as humanoids.Person)
    print bob.name, bob.getName()
end sub
```

```BrightScript
sub test(bob as object)
    print bob.name, bob.getName()
end sub
```

--------------------------------

### Basic Regex Literal

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/regex-literals.md

Use regex literals for simple pattern matching. This syntax is a direct replacement for `CreateObject("roRegex", ...)`.

```BrighterScript
print /hello world/ig
```

```BrightScript
print CreateObject("roRegex", "hello world", "ig")
```

--------------------------------

### Optional extends via CLI

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

When using the BrighterScript compiler (bsc) from the command line, you can specify an optional configuration file using the '--extends' flag with a '?' prefix.

```bash
bsc --extends "?path/to/optional/bsconfig.json"
```

--------------------------------

### Add Files Dynamically Plugin

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

This plugin demonstrates how to modify the project's configuration before the program is created. It adds an additional file to the build process by manipulating the `builder.options.files` array.

```typescript
import { CompilerPlugin, ProgramBuilder } from 'brighterscript';

export default function plugin() {
    return {
        name: 'addFilesDynamically',
        beforeProgramCreate: (builder: ProgramBuilder) => {
            if (!builder.options.files) {
                builder.options.files = [];
            }

            builder.options.files.push({
                src: "path/to/plugin/file.bs",
                dest: "some/destination/path/goes/here"
            })
        }
    } as CompilerPlugin;
}
```

--------------------------------

### Optional project via CLI

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

The '--project' argument for the bsc CLI can also be made optional by prefixing the file path with '?'. This is useful for specifying a project configuration that may not always be present.

```bash
bsc --project "?path/to/optional/bsconfig.json"
```

--------------------------------

### Basic Function Namespace

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/namespaces.md

Defines a function within a namespace and shows how to call it. BrighterScript transpiles periods in namespace names to underscores for BrightScript compatibility.

```BrighterScript
namespace Vertibrates.Birds
    function GetDucks()
    end function
end namespace
sub main()
    Vertibrates.Birds.GetDucks()
end sub
```

```BrightScript
function Vertibrates_Birds_GetDucks()
end function

sub main()
    Vertibrates_Birds_GetDucks()
end sub
```

--------------------------------

### Print SOURCE_FILE_PATH

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints the absolute path to the source file, including a leading `file:/` scheme. The literal is concatenated to ensure compatibility with Roku's static analysis tool.

```vb
print SOURCE_FILE_PATH
```

```vb
print "file" + ":///C:/projects/RokuApp/source/main.bs"
```

--------------------------------

### Transpiled BrightScript for Non-String Return

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/template-strings.md

Shows the equivalent BrightScript code after transpilation, illustrating how template strings are converted into array arguments.

```BrightScript
function zombify(strings, values)
    return Zombie(values[0])
end function

function main()
    name = "Human"
    result = zombify(["Hello ", ""], [name])
end function
```

--------------------------------

### Specify Glob Pattern Destination

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Configure this when 'src' is a glob pattern. The 'dest' property should specify the target folder within the output directory where all matching files will be placed.

```jsonc
{ "src": "lib/*.brs", "dest": "source/lib" }
```

--------------------------------

### ObserveField String Caveat

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/namespaces.md

Highlights a limitation with `ObserveField` and `ObserveFieldScoped` where string-based namespace names are not automatically transpiled. Manual conversion to the underscore format is required.

```brighterscript
'this does not work
m.top.observeField("someField", "Vertibrates.Birds.Quack")

'you need to do this instead
m.top.observeField("someField", "Vertibrates_Birds_Quack")
```

--------------------------------

### Run compiler in watch mode

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Enables watch mode to automatically recompile on file changes.

```bash
bsc --watch
```

--------------------------------

### Callfunc Operator Usage

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/readme.md

Demonstrates the alternative Callfunc operator syntax for method invocation.

```brighterscript
'instead of `node.callfunc("someMethod", 1, 2, 3)`, you can do this:
node@.someMethod(1, 2, 3)
```

--------------------------------

### Default files array in bsconfig.json

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

This is the default 'files' array configuration for a standard BrighterScript project. It includes common directories like 'source', 'components', and 'images', along with 'manifest'.

```json
{
    "files": [
        "source/**/*",
        "components/**/*",
        "images/**/*",
        "manifest"
    ]
}
```

--------------------------------

### Ternary Operator with Optional Chaining (Space)

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/ternary-operator.md

Demonstrates correct ternary usage with optional chaining, requiring a space after the question mark.

```BrightScript
data = isTrue ? ["key"] : getFalseData()
data = isTrue ? (1 + 2) : getFalseData()
```

--------------------------------

### Transpiled BrightScript for Animal Class

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

The BrightScript code generated by transpiling the BrighterScript 'Animal' class. This includes builder, constructor, and method functions.

```BrightScript
sub __Animal_method_new()
    m.name = invalid
end sub
function __Animal_method_walk()
end function
function __Animal_builder()
    instance = {}
    instance.new = __Animal_method_new
    instance.walk = __Animal_method_walk
    return instance
end function
function Animal()
    instance = __Animal_builder()
    instance.new()
    return instance
end function
```

--------------------------------

### Classes within Namespaces

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Demonstrates how to define classes within namespaces in BrighterScript. At runtime, namespace periods are converted to underscores.

```BrighterScript
namespace Vertibrates.Birds
    class Animal
    end class

    class Duck extends Animal
    end class
end namespace
```

```BrightScript
sub __Vertibrates_Birds_Animal_method_new()
end sub
function __Vertibrates_Birds_Animal_builder()
    instance = {}
    instance.new = __Vertibrates_Birds_Animal_method_new
    return instance
end function
function Vertibrates_Birds_Animal()
    instance = __Vertibrates_Birds_Animal_builder()
    instance.new()
    return instance
end function
sub __Vertibrates_Birds_Duck_method_new()
    m.super0_new()
end sub
function __Vertibrates_Birds_Duck_builder()
    instance = __Vertibrates_Birds_Animal_builder()
    instance.super0_new = instance.new
    instance.new = __Vertibrates_Birds_Duck_method_new
    return instance
end function
function Vertibrates_Birds_Duck()
    instance = __Vertibrates_Birds_Duck_builder()
    instance.new()
    return instance
end function
```

--------------------------------

### Print FUNCTION_NAME (Anonymous Functions)

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints the name of anonymous functions, including the enclosing function name and an index. Nested anonymous functions have their index appended at each level.

```BrighterScript
function main()
    zombieAttack = function()
        print FUNCTION_NAME
    end function

    humanAttack = function()
        useSword = function()
            print FUNCTION_NAME
        end function
        useSword()
    end function
end function
namespace Human.Versus.Zombie
    function Eat()
        print SOURCE_FUNCTION_NAME
        findFood = function()
            print FUNCTION_NAME
        end function
    end function
end namespace
```

```BrightScript
function main()
    zombieAttack = function()
        print "main$anon0"
    end function
    humanAttack = function()
        useSword = function()
            print "main$anon1$anon0"
        end function
        useSword()
    end function
end function
function Human_Versus_Zombie_Eat()
    print "Human.Versus.Zombie.Eat"
    findFood = function()
        print "Human.Versus.Zombie.Eat$anon0"
    end function
end function
```

--------------------------------

### Using Namespaced Constants

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/computed-property-names.md

Demonstrates the usage of namespaced constants as computed property names in BrighterScript.

```brighterscript
namespace Config
    const PRIMARY_COLOR = "primaryColor"
    const SECONDARY_COLOR = "secondaryColor"
end namespace

sub main()
    theme = {
        [Config.PRIMARY_COLOR]: "#ff0000",
        [Config.SECONDARY_COLOR]: "#0000ff"
    }
end sub
```

--------------------------------

### Mixing Computed and Regular Keys

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/computed-property-names.md

Shows how to combine computed property names with regular keys within the same associative array. This allows for flexible data structure definitions.

```brighterscript
enum Field
    title = "title"
end enum

sub main()
    data = {
        id: 1,
        [Field.title]: "Hello World",
        ["some-meta"]: true
    }
end sub
```

```brightscript
sub main()
    data = {
        id: 1
        "title": "Hello World"
        "some-meta": true
    }
end sub
```

--------------------------------

### Namespace Inference for Functions

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/namespaces.md

Demonstrates how functions within the same namespace can be called without explicitly prefixing the namespace. The compiler infers the namespace context.

```BrighterScript
namespace Vertibrates.Birds
    function GetAllBirds()
        return [
            GetDuck(),
            GetGoose()
        ]
    end function

    function GetDuck()
    end function

    function GetGoose()
    end function
end namespace
```

```BrightScript
function Vertibrates_Birds_GetAllBirds()
    return [
        Vertibrates_Birds_GetDuck()
        Vertibrates_Birds_GetGoose()
    ]
end function

function Vertibrates_Birds_GetDuck()
end function

function Vertibrates_Birds_GetGoose()
end function
```

--------------------------------

### Configure ts-node in bsconfig.json

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/plugins.md

Configures the 'require' flag in bsconfig.json to use ts-node for dynamic plugin transpilation. This allows for cleaner bsc command arguments.

```json
{
    "require": ["ts-node/register"]
}
```

--------------------------------

### Numeric Enum with Initializers

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/enums.md

Demonstrates defining a numeric enum with explicit initial values for some members. Subsequent members without explicit values increment from the previous one.

```BrighterScript
enum Direction
    up = 5
    down
    left = 10
    right
end enum
sub main()
    print Direction.up
    print Direction.down
    print Direction.left
    print Direction.right
end sub
```

```BrightScript
sub main()
    print 5
    print 6
    print 10
    print 11
end sub
```

--------------------------------

### Print FUNCTION_NAME (Namespaced)

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints the name of the current function, including its namespace. Namespaces are converted to underscores in the transpiled output.

```BrighterScript
namespace Human.Versus.Zombie
    function RunFromZombie()
        print FUNCTION_NAME
    end function
end namespace
```

```BrightScript
function Human_Versus_Zombie_RunFromZombie()
    print "Human_Versus_Zombie_RunFromZombie"
end function
```

--------------------------------

### Set Diagnostic Reporting to Detailed

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Configure BrighterScript to use the default detailed reporting format for diagnostics, which includes rich, multi-line, and colored output.

```jsonc
"diagnosticReporters": "detailed"
```

--------------------------------

### Optional Chaining Operator (No Space)

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/ternary-operator.md

Shows the syntax for optional chaining where a missing space after the question mark indicates optional chaining.

```BrightScript
data = isTrue ?["key"] : getFalseData()
data = isTrue ?(1 + 2) : getFalseData()
```

--------------------------------

### Basic Constant Declaration

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/constants.md

Declare a constant at the root level of a file. This constant will be inlined at compile-time.

```BrighterScript
const GREETING_MESSAGE = "Hello world"
sub main()
    print GREETING_MESSAGE
end sub
```

```BrightScript
sub main()
    print "Hello world"
end sub
```

--------------------------------

### Multi-line Template String with Newlines

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/template-strings.md

Shows how multi-line template strings are automatically captured and transpiled to BrightScript with chr(10) for newlines.

```BrighterScript
text = `line1
line2
`
```

```BrightScript
text = ("line1" + chr(10) + "line2" + chr(10))
```

--------------------------------

### Print FUNCTION_NAME (Basic)

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints the name of the current function. This is useful for debugging and logging within functions.

```BrighterScript
function RunFromZombie()
    print FUNCTION_NAME
end function
```

```BrightScript
function RunFromZombie()
    print "RunFromZombie"
end function
```

--------------------------------

### Copy Folder Contents Recursively

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

Use the glob syntax with `**/*` to copy an entire folder and its contents recursively. The 'dest' property specifies the target folder in the output directory.

```jsonc
{ "src": "lib/vendor/**/*", "dest": "vendor" }
```

--------------------------------

### Using Constants as Computed Keys

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/computed-property-names.md

Illustrates using string constants as computed keys for associative arrays. The constant values are substituted at compile-time.

```brighterscript
const KEY_NAME = "displayName"
const KEY_AGE = "displayAge"

sub main()
    labels = {
        [KEY_NAME]: "Name",
        [KEY_AGE]: "Age"
    }
end sub
```

```brightscript
sub main()
    labels = {
        "displayName": "Name"
        "displayAge": "Age"
    }
end sub
```

--------------------------------

### Dynamic Typing and Type Inference in Classes

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Shows how BrighterScript fields and methods default to the 'dynamic' type, but types can be inferred from usage or explicitly specified.

```BrighterScript
class Person
    'defaults to type "dynamic"
    name

    'infers type "integer"
    age = 12

    'infers type "integer"
    function getAge()
        return m.age
    end function
end class
```

```BrightScript
sub __Person_method_new()
    m.name = invalid
    m.age = 12
end sub
function __Person_method_getAge()
    return m.age
end function
function __Person_builder()
    instance = {}
    instance.new = __Person_method_new
    'defaults to type "dynamic"
    'infers type "integer"
    'infers type "integer"
    instance.getAge = __Person_method_getAge
    return instance
end function
function Person()
    instance = __Person_builder()
    instance.new()
    return instance
end function
```

--------------------------------

### Transpiled BrightScript Output

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/annotations.md

Shows the BrightScript code generated after transpiling the BrighterScript code with annotations. Note that all annotations are removed.

```brightscript
sub __MyComp_method_new()
end sub
function __MyComp_builder()
    instance = {}
    instance.new = __MyComp_method_new
    return instance
end function
function MyComp()
    instance = __MyComp_builder()
    instance.new()
    return instance
end function

function init()
end function

function main()
end
```

--------------------------------

### Transpiled BrightScript Code

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/imports.md

Shows the equivalent BrightScript code after BrighterScript transpilation, where the import statement is commented out and the imported script is handled separately.

```BrightScript
'import "pkg:/source/lib.bs"

function Init()
    SomeFunctionFromLib()
end function
```

--------------------------------

### Print SOURCE_NAMESPACE_ROOT_NAME

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints only the lowest-level namespace name. This literal is useful for debug logs and logging filters, providing a concise namespace identifier.

```BrighterScript
namespace Human.Versus.Zombie
    function Eat()
        print SOURCE_NAMESPACE_ROOT_NAME
    end function
end namespace
```

```BrightScript
function Human_Versus_Zombie_Eat()
    print "Human"
end function
```

--------------------------------

### Using String Literals as Computed Keys

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/computed-property-names.md

Demonstrates the basic use case of employing string literals within brackets as computed property names for associative arrays.

```brighterscript
sub main()
    headers = {
        ["Content-Type"]: "application/json",
        ["X-Api-Key"]: "abc123"
    }
end sub
```

```brightscript
sub main()
    headers = {
        "Content-Type": "application/json"
        "X-Api-Key": "abc123"
    }
end sub
```

--------------------------------

### Basic 'callfunc' Operator Usage

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/callfunc-operator.md

Use the '@.' operator for a familiar method call syntax. BrighterScript transpiles this to the BrightScript 'callfunc' method.

```BrighterScript
node@.someMethod(1,2,3)
```

```BrightScript
node.callfunc("someMethod", 1, 2, 3)
```

--------------------------------

### Using Namespaced Enum Members

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/computed-property-names.md

Shows how to use namespaced enum members as computed keys in BrighterScript.

```brighterscript
namespace Api
    enum Path
        login = "/login"
        profile = "/profile"
    end enum
end namespace

sub main()
    handlers = {
        [Api.Path.login]: loginHandler,
        [Api.Path.profile]: profileHandler
    }
end sub
```

--------------------------------

### Run compiler as a linter only

Source: https://github.com/rokucommunity/brighterscript/blob/master/README.md

Configures the compiler to function solely as a linter, disabling package creation and copying to staging. Watch mode is supported.

```bash
bsc --create-package false --copy-to-staging false
```

--------------------------------

### Print SOURCE_NAMESPACE_NAME

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/source-literals.md

Prints the full namespace name, including all parent namespaces, using dot notation. This literal is useful for debug logs and logging filters.

```BrighterScript
namespace Human.Versus.Zombie
    function Eat()
        print SOURCE_NAMESPACE_NAME
    end function
end namespace
```

```BrightScript
function Human_Versus_Zombie_Eat()
    print "Human.Versus.Zombie"
end function
```

--------------------------------

### Optional project via Node.js API

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/bsconfig.md

The 'project' option within the ProgramBuilder constructor for the BrighterScript Node.js API can be set as optional by prefixing the path with '?'.

```javascript
var programBuilder = new ProgramBuilder({
    "project": "?path/to/optional/bsconfig.json"
});
```

--------------------------------

### Calling Parent Method from Child Override in BrighterScript

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Illustrates how to call the original parent method from within an overridden method in a child class using 'super.method()'.

```vb
class Duck
    public sub walk(meters as integer)
        print "Walked " + meters.ToStr() + " meters"
    end sub
end class

class BabyDuck extends Duck
    public override sub walk(meters as integer)
        print "Tripped"
        super.walk(meters)
    end sub
end class
```

```BrightScript
sub __Duck_method_new()
end sub
sub __Duck_method_walk(meters as integer)
    print "Walked " + meters.ToStr() + " meters"
end sub
function __Duck_builder()
    instance = {}
    instance.new = __Duck_method_new
    instance.walk = __Duck_method_walk
    return instance
end function
function Duck()
    instance = __Duck_builder()
    instance.new()
    return instance
end function
sub __BabyDuck_method_new()
    m.super0_new()
end sub
sub __BabyDuck_method_walk(meters as integer)
    print "Tripped"
    m.super0_walk(meters)
end sub
function __BabyDuck_builder()
    instance = __Duck_builder()
    instance.super0_new = instance.new
    instance.new = __BabyDuck_method_new
    instance.super0_walk = instance.walk
    instance.walk = __BabyDuck_method_walk
    return instance
end function
function BabyDuck()
    instance = __BabyDuck_builder()
    instance.new()
    return instance
end function
```

--------------------------------

### BrighterScript Class Declaration

Source: https://github.com/rokucommunity/brighterscript/blob/master/docs/classes.md

Define a simple BrighterScript class named 'Animal' with a public 'name' property and a 'walk' method.

```vb
class Animal
    public name as string

    public function walk()

    end function

end class
```