brighterscript-formatter v1.7.1

brighterscript-formatter

A code formatter for BrightScript and BrighterScript.

Installation

npm

npm install brighterscript-formatter -g

Usage

CLI

:exclamation: WARNING: be sure to commit your files before using the --write flag, as that will overwrite your files

bsfmt <files...> [<options>]

# help
bsfmt --help

# format one
bsfmt source/main.brs --write

# check many
bsfmt "source/**/*.brs" --check

# skip loading from bsfmt.json
bsfmt "source/**/*.brs" --no-bsfmt

#path to custom bsfmt.json
bsfmt "source/**/*.brs" --bsfmt-path "../common/bsfmt.json"

bsfmt.json

The CLI reads formatting options from an optional ./bsfmt.json (see formatting options section) which should look like:

{
    "indentStyle": "spaces",
    "indentSpaceCount": 2
}

Excluding files

bsfmt supports excluding files as well. Consider this example. It will include all files, and then exclude the files found in roku_modules

bsfmt "source/**/*.brs" "!**/roku_modules/*.*"

CLI Options

All boolean, string, and integer bsfmt.json options are supported as well. Complex options such as keywordCaseOverride or typeCaseOverride are not currently supported via the CLI and should be provided in the bsfmt.json or through the node API. Feel free to open an issue if you would like to see support for these options via the CLI.

bsfmt.json options

keywordCaseOverride

For more flexibility in how to format the case of keywords, you can specify the case preference for each individual keyword. Here's an example:

{
    //by default, force all keywords to lower case
    "keywordCase": "lower",
    //override these specific keywords to upper case
    "keywordCaseOverride": {
        "and": "upper",
        "or": "upper"
    }
}

The full list of keywords detected by this option can be found here.

typeCaseOverride

For more flexibility in how to format the case of types, you can specify the case preference for each individual type. Here's an example:

{
    //by default, force all types to lower case
    "typeCase": "lower",
    //override these specific type tokens to upper case
    "typeCaseOverride": {
        "string": "upper",
        "boolean": "upper"
    },
}

A type is any token found directly after an as keyword.

Library

General usage

import { Formatter } from 'brighterscript-formatter';

//create a new instance of the formatter
var formatter = new Formatter();

//retrieve the raw BrighterScript/BrightScript file contents (probably from fs.readFile)
var unformattedFileContents = getFileAsStringSomehow();

var formattingOptions = {};
//get a formatted version of the BrighterScript/BrightScript file
var formattedFileContents = formatter.format(unformattedFileContents, formattingOptions);

Source Maps

The formatter also supports source maps, which can be generated alongside of the formatted code by calling formatWithSourceMap

var result = formatter.formatWithSourceMap(unformattedFileContents);
var formattedFileContents = result.code;
var sourceMap = result.map;