Skip to content

suppressing-compiler-messages.md

Latest commit

 

History

History
90 lines (61 loc) · 4.08 KB

suppressing-compiler-messages.md

File metadata and controls

90 lines (61 loc) · 4.08 KB
Raw

Suppressing compiler messages

The BrighterScript compiler emits errors and warnings when it encounters potentially invalid code. Errors and warnings may also be emitted by compiler plugins, such as by the BrighterScript linter.

Developers may want to suppress some of these messages. There are two ways to do so.

Modifying compiler diagnostics using bsconfig.json

There are three bsconfig.json settings which modify the reporting of compiler messages: diagnosticFilters, diagnosticLevel, and diagnosticSeverityOverride.

diagnosticFilters allows users to ignore specific errors and specific file paths. It is useful for targetted suppression of errors.

diagnosticLevel allows users to toggle the level of diagnostics which they wish to see. For example, it allows one to hide all warnings and only show errors.

diagnosticSeverityOverride allows users to manually change the severity of a diagnostic, such as setting a particular kind of error to instead by reported as a warning or vice versa. This works in conjunction with the other two options.

Ignoring errors and warnings on a per-line basis

In addition to modifying errors using bsconfig.json, you may also disable errors for a subset of the complier rules within a file with the following comment flags:

  • bs:disable-next-line
  • bs:disable-next-line: code1 code2 code3
  • bs:disable-line
  • bs:disable-line: code1 code2 code3

Here are some examples:

sub Main()
    'disable errors about invalid syntax here
    'bs:disable-next-line
    DoSomething(

    DoSomething( 'bs:disable-line

    'disable errors about wrong parameter count
    DoSomething(1,2,3) 'bs:disable-line

    DoSomething(1,2,3) 'bs:disable-line:1002
end sub

sub DoSomething()
end sub

The primary motivation for this feature was to provide a stopgap measure to hide incorrectly-thrown errors on legitimate BrightScript code due to parser bugs. It is recommended that you only use these comments when absolutely necessary.

Ignoring errors and warnings for a block of code or whole file

Use bs:disable and bs:enable to suppress diagnostics for a span of code. A bs:disable opens a suppression block, and a matching bs:enable closes it. If no bs:enable follows, the block runs to the end of the file, so a bare bs:disable at the top of a file suppresses the whole file.

  • bs:disable: suppress all diagnostics from this line until the next bs:enable
  • bs:disable: code1 code2 code3: suppress only the listed codes
  • bs:enable: close any open bs:disable block
  • bs:enable: code1 code2 code3: re-enable specific codes from an open bs:disable
' bs:disable: 1001 1002

sub Main()
    DoSomething()
end sub
<?xml version="1.0" encoding="utf-8" ?>
<!-- bs:disable: 1006 -->
<component name="Foo">
</component>

bs:enable: <code> after a bare bs:disable re-enables one diagnostic while keeping the rest suppressed:

' bs:disable
'   1006 is still suppressed below, but 1001 reports normally
' bs:enable: 1001

sub Main()
    DoSomething()
end sub

Quick fixes

The BrighterScript language server offers two quick-fix actions on every diagnostic so you can suppress the message without leaving your editor:

  • Disable {code} for this line: {message}: if a bs:disable-line or bs:disable-next-line directive already exists on or above the diagnostic line, the code is appended to it. Otherwise a new bs:disable-next-line: {code} comment is inserted above the diagnostic.
  • Disable {code} for this file: {message}: if a header-level bs:disable directive already exists, the code is appended to it. Otherwise a new bs:disable: {code} comment is inserted at the top of the file.

These actions appear after the standard quick fixes for a diagnostic.