Skip to main content

Namespaces

BrighterScript provides a means of grouping functions and classes into Namespaces. BrightScript has no support for namespaces. Generally Roku developers will simulate namespaces by using underscores. However, that causes a large amount of clutter for the intellisense results.

Basic usage​

namespace Vertebrates.Birds
    function GetDucks()
    end function
end namespace
sub main()
    Vertebrates.Birds.GetDucks()
end sub
View the transpiled BrightScript code
function Vertebrates_Birds_GetDucks()
end function

sub main()
    Vertebrates_Birds_GetDucks()
end sub

As you can see, behind the scenes, BrighterScript will convert all periods found within namespace names into underscores so that it will be compatible with regular BrightScript.

Classes​

Namespaces can also contain classes, interfaces and constants. See Classes for more detailed information.

Namespace inference​

Functions and classes within a namespace do not need to be prefixed with the full namespace name when called from another location in the same namespace. For example,

namespace Vertebrates.Birds
    function GetAllBirds()
        return [
            GetDuck(),
            GetGoose()
        ]
    end function

    function GetDuck()
    end function

    function GetGoose()
    end function
end namespace
View the transpiled BrightScript code
function Vertebrates_Birds_GetAllBirds()
    return [
        Vertebrates_Birds_GetDuck()
        Vertebrates_Birds_GetGoose()
    ]
end function

function Vertebrates_Birds_GetDuck()
end function

function Vertebrates_Birds_GetGoose()
end function

Notice how we didn't need to specify Vertebrates.Birds in front of GetDuck() and GetGoose(). That's because the compiler is smart enough to recognize where those functions come from.

Works in assignments as well​

The compiler is smart enough to recognize namespaces in assignments as well.

namespace Vertebrates.Birds
    sub Quack()
    end sub

    sub Waddle()
    end sub

    sub Live()
        'assign based on fully-qualified namespace name
        speak = Vertebrates.Birds.Quack

        'infer Current namespace
        walk = Waddle
    end sub
end namespace
View the transpiled BrightScript code
sub Vertebrates_Birds_Quack()
end sub

sub Vertebrates_Birds_Waddle()
end sub

sub Vertebrates_Birds_Live()
    'assign based on fully-qualified namespace name
    speak = Vertebrates_Birds_Quack
    'infer Current namespace
    walk = Vertebrates_Birds_Waddle
end sub

Sharing name of namespaced item and non-namespaced items​

The compiler allows a namespaced function with the same name as a global function. As per the name-shadowing rules, the function inside the namespace will be used in the transpiled code. The same rule applies to classes.

sub Quack()
end sub
namespace Vertebrates.Birds
    sub Quack()
    end sub

    sub Speak()
        Quack() ' calls the function Vertebrates.Birds.Quack()
    end sub
end namespace
View the transpiled BrightScript code
sub Quack()
end sub
sub Vertebrates_Birds_Quack()
end sub

sub Vertebrates_Birds_Speak()
    Vertebrates_Birds_Quack() ' calls the function Vertebrates.Birds.Quack()
end sub

Nesting namespaces​

In the above examples, nested namespaces are formed by specifying a dotted identifier (NameA.NameB). You can also declare namespaces within other namespaces to form a dotted namespace identifier which contains its parent namespaces.

namespace Vertebrates
    namespace Birds
        sub Quack()
        end sub
    end namespace

    namespace Reptiles
        sub Hiss()
        end sub
    end namespace
end namespace
View the transpiled BrightScript code
sub Vertebrates_Birds_Quack()
end sub
sub Vertebrates_Reptiles_Hiss()
end sub

Calling parent namespace functions​

Brighterscript does not support accessing a function (or other entity) of a parent namespace without fully qualifying the name of the function.

namespace Vertibrates
    sub Move()
    end sub

    namespace Birds
        sub Fly()
            Move() ' this is an error - no global Move() function
            Vertibrates.Move() ' this is allowed
        end sub
    end namespace
end namespace
View the transpiled BrightScript code
sub Vertibrates_Move()
end sub
sub Vertibrates_Birds_Fly()
    Move() ' this is an error - no global Move() function
    Vertibrates_Move() ' this is allowed
end sub

Caveats​

ObserveField and ObserveFieldScoped​

It's incredibly difficult for BrighterScript to know when it's safe to transpile strings that happen to look like namespace names. As such, the ObserveField and ObserveFieldScoped functions in BrighterScript do not automatically transpile string-based function names into their BrightScript-compatible underscore format.

This means that if you pass a namespaced identifier as a string (i.e Vertebrates.Birds.Quack) it will not be converted to Vertebrates_Birds_Quack during transpilation. Developers need to ensure they manually provide the transpiled function name when using these functions to avoid runtime errors (i.e. Vertebrates_Birds_Quack).

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

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