Skip to content

CodeInspection.md

Latest commit

 

History

History
201 lines (149 loc) · 8.33 KB

CodeInspection.md

File metadata and controls

201 lines (149 loc) · 8.33 KB
Raw

Import :

const CodeInspection = brackets.getModule("language/CodeInspection")

_

Manages linters and other code inspections on a per-language basis. Provides a UI and status indicator for the resulting errors/warnings.

Currently, inspection providers are only invoked on the current file and only when it is opened, switched to, or saved. But in the future, inspectors may be invoked as part of a global scan, at intervals while typing, etc. Currently, results are only displayed in a bottom panel list and in a status bar icon. But in the future, results may also be displayed inline in the editor (as gutter markers, etc.). In the future, support may also be added for error/warning providers that cannot process a single file at a time (e.g. a full-project compiler).

Kind: global constant

CODE_INSPECTION_GUTTER : string

Code inspection gutter

Kind: global constant

Type

Values for problem's 'type' property

Kind: global constant

Type.ERROR

Unambiguous error, such as a syntax error

Kind: static property of Type

Type.WARNING

Maintainability issue, probable error / bad smell, etc.

Kind: static property of Type

Type.META

Inspector unable to continue, code too complex for static analysis, etc. Not counted in err/warn tally.

Kind: static property of Type

getProvidersForPath(filePath) ⇒ Object

Returns a list of provider for given file path, if available. Decision is made depending on the file extension.

Kind: global function

Param Type
filePath string

getProviderIDsForLanguage(languageId) ⇒ Array.<string>

Returns an array of the IDs of providers registered for a specific language

Kind: global function
Returns: Array.<string> - Names of registered providers.

Param Type
languageId string

inspectFile(file, providerList) ⇒ $.Promise

Runs a file inspection over passed file. Uses the given list of providers if specified, otherwise uses the set of providers that are registered for the file's language. This method doesn't update the Brackets UI, just provides inspection results. These results will reflect any unsaved changes present in the file if currently open.

The Promise yields an array of provider-result pair objects (the result is the return value of the provider's scanFile() - see register() for details). The result object may be null if there were no errors from that provider. If there are no providers registered for this file, the Promise yields null instead.

Kind: global function
Returns: $.Promise - a jQuery promise that will be resolved with ?{provider:Object, result: ?{errors:!Array, aborted:boolean}}

Param Type Description
file File File that will be inspected for errors.
providerList Object Array

scrollToProblem(lineNumber) ⇒ jQuery | null

Scrolls to the problem line

Kind: global function

Param Type Description
lineNumber number The line number to scroll to

run(providerName)

Run inspector applicable to current document. Updates status bar indicator and refreshes error list in bottom panel. Does not run if inspection is disabled or if a providerName is given and does not match the current doc's provider name.

Kind: global function

Param Type Description
providerName string name of the provider that is requesting a run

toggleEnabled(enabled, doNotSave)

Enable or disable all inspection.

Kind: global function

Param Type Description
enabled boolean Enabled state. If omitted, the state is toggled.
doNotSave boolean true if the preference should not be saved to user settings. This is generally for events triggered by project-level settings.

Error : Object

Registers a provider for a specific language to inspect files and provide linting results.

The provider is passed the text of the file and its full path. Providers should not assume that the file is open (i.e., DocumentManager.getOpenDocumentForPath() may return null) or that the file on disk matches the text given (the file may have unsaved changes).

Registering any provider for the "javascript" language automatically unregisters the built-in Brackets JSLint provider. This is a temporary convenience until a UI exists for disabling registered providers.

Providers must implement canInspect(), scanFile(), or scanFileAsync(). If both scanFile() and scanFileAsync() are implemented, scanFile() is ignored.

  • canInspect(fullPath): A synchronous call to determine if the file can be scanned by this provider.
  • scanFile(text, fullPath): A synchronous function returning linting results or null.
  • scanFileAsync(text, fullPath): An asynchronous function returning a jQuery Promise resolved with the same type of value as scanFile(). Rejecting the promise is treated as an internal error in the provider.

Each error object in the results should have the following structure:

             { pos:{line,ch},
               endPos:?{line,ch},
               message:string,
               htmlMessage:string,
               type:?Type ,
               fix: { // an optional fix, if present will show the fix button
                    replace: "text to replace the offset given below",
                    rangeOffset: {
                        start: number,
                        end: number
               }}}

Kind: global typedef

Param Type Description
languageId string The language ID for which the provider is registered.
provider Object The provider object.
provider.name string The name of the provider.
provider.scanFile function Synchronous scan function.
provider.scanFileAsync function Asynchronous scan function returning a Promise.

Properties

Name Type Description
pos Object The start position of the error.
pos.line number The line number (0-based).
pos.ch number The character position within the line (0-based).
endPos Object The end position of the error.
endPos.line number The end line number (0-based).
endPos.ch number The end character position within the line (0-based).
message string The error message to be displayed as text.
htmlMessage string The error message to be displayed as HTML.
type Type The type of the error. Defaults to Type.WARNING if unspecified.
fix Object An optional fix object.
fix.replace string The text to replace the error with.
fix.rangeOffset Object The range within the text to replace.
fix.rangeOffset.start number The start offset of the range.
fix.rangeOffset.end number The end offset of the range. If no errors are found, return either null(treated as file is problem free) or an object with a zero-length errors array. Always use message to safely display the error as text. If you want to display HTML error message, then explicitly use htmlMessage to display it. Both message and htmlMessage can be used simultaneously. After scanning the file, if you need to omit the lint result, return or resolve with {isIgnored: true}. This prevents the file from being marked with a no errors tick mark in the status bar and excludes the linter from the problems panel.