BeautificationManager

Import :

const BeautificationManager = brackets.getModule("features/BeautificationManager")

features/BeautificationManager

Beautification manager interacts with beautify extensions to determine what to do when user issues beautify code command. Beautification providers can use this module to register new providers to beautify new languages.

API

registerBeautificationProvider

Register a Beautification provider with this api.

Example

// syntax
BeautificationManager.registerBeautificationProvider(provider, supportedLanguages, priority);

The API requires three parameters:

1. provider: must implement a beautifyEditorProvider and beautifyTextProvider function. See doc below:
2. supportedLanguages: An array of languages that the provider supports. If ["all"] is supplied, then the provider will be invoked for all languages. Restrict to specific languages: Eg: ["javascript", "html", "php"]
3. priority: Used to break ties among providers for a particular language. Providers with a higher number will be asked for beatified code before those with a lower priority value. Defaults to zero. Example

// to register a provider that will be invoked for all languages. where provider is any object that implements
// a `beautifyEditorProvider` and `beautifyTextProvider` function
BeautificationManager.registerBeautificationProvider(provider, ["all"]);

// to register a provider that will be invoked for specific languages
BeautificationManager.registerBeautificationProvider(provider, ["javascript", "html", "php"]);

removeBeautificationProvider

Removes a registered Beautification provider. The API takes the same arguments as registerBeautificationProvider. Example

// syntax
BeautificationManager.removeBeautificationProvider(provider, supportedLanguages);
// Example
BeautificationManager.removeBeautificationProvider(provider, ["javascript", "html"]);

provider.beautifyEditorProvider

Each provider must implement the beautifyEditorProvider function that returns a promise. The promise either resolves with the beautified code details or rejects if there is nothing to beautify for the provider. Example

// function signature
provider.beautifyEditorProvider = function(editor) {
        return new Promise((resolve, reject)=>{
            resolve({
                originalText: "the original text sent to beautify",
                changedText: "partial or full text that changed.",
                // Optional cursor offset if given will set the editor cursor to the position after beautification.
                // either `cursorOffset` or `ranges` can be specified, but not both.
                cursorOffset: number,
                // Optional: If range is specified, only the given range will be replaced. else full text is replaced
                ranges:{
                    replaceStart: {line,ch},
                    replaceEnd: {line,ch}
                }
            });
        });
    };

The resolved promise object

The resolved promise should either be null(indicating that the extension itself has prettified the code and doesn't want any further processing from BeautificationManager.) or contain the following details:

1. originalText - string, the original text sent to beautify
2. changedText - string, this should be the fully prettified text of the whole originalText or a fragment of pretty text in originalText if a range was selected. If a fragment is returned, then the ranges object must be specified.
3. cursorOffset - Optional number, if given will set the editor cursor to the position after beautification. either cursorOffset or ranges can be specified, but not both.
4. ranges - Optional object, set of 2 cursors that gives details on what range to replace with given changed text. If range is not specified, the full text in the editor will be replaced. range has 2 fields:
   1. replaceStart{line,ch} - the start of range to replace
   2. replaceEnd{line,ch} - the end of range to replace

provider.beautifyTextProvider

Each provider must implement the beautifyTextProvider function that returns a promise. The promise either resolves with the beautified code details(same as beautifyEditorProvider) or rejects if there is nothing to beautify for the provider. Example

// function signature.
provider.beautifyTextProvider = function(textToBeautify, filePathOrFileName) {
        return new Promise((resolve, reject)=>{
            resolve({
                originalText: "the original text sent to beautify",
                changedText: "partial or full text that changed.",
                // Optional: If range is specified, only the given range is assumed changed. else full text changed.
                ranges:{
                    replaceStart: {line,ch},
                    replaceEnd: {line,ch}
                }
            });
        });
    };

Parameters

The beautifyTextProvider callback will receive the following arguments.

1. textToBeautify - string
2. filePathOrFileName - string. This will either be a valid file path, or a file name to deduce which language the beautifier is dealing with.

The resolved promise object

The resolved object has the same structure as beautifyEditorProvider resolved promise object.

• features/BeautificationManager
  • .beautifyEditor(editor) ⇒ Promise
  • .beautifyText(textToBeautify, filePathOrFileName) ⇒ Promise

features/BeautificationManager.beautifyEditor(editor) ⇒ Promise

Beautifies text in the given editor with available providers.

Kind: inner method of features/BeautificationManager
Returns: Promise - - A promise that will be resolved to null if the selected text is beautified or rejects if beautification failed.

Param
editor

features/BeautificationManager.beautifyText(textToBeautify, filePathOrFileName) ⇒ Promise

Beautifies text with available providers.

Kind: inner method of features/BeautificationManager
Returns: Promise - - A promise that will be resolved to null if the selected text is beautified or rejects if beautification failed..

The resolved promise object

The resolved promise object contain the following details:

1. originalText - string, the original text sent to beautify
2. changedText - string, the prettified text.
3. ranges - Optional. if range object is returned, it means that only a part of the original text changed in the original text textToBeautify. The part that changed is supplied by two cursor positions below:
   1. replaceStart{line,ch} - the start of range to replace
   2. replaceEnd{line,ch} - the end of range to replace

Param	Type	Description
textToBeautify	string
filePathOrFileName	string	Note that the file path may not actually exist on disk. It is just used to infer what language beautifier is to be applied.