Language Support

Introduction

Support for languages like HTML, JavaScript and CSS is currently a core part of Brackets. Support on the same level cannot easily be added by extensions. This page documents our efforts to change that.

Ongoing work

• Introduced a new high-level concept "language" and refactored support for LESS based on that (Pull Request)

Caveats

• We should potentially add a central point to extract file extensions for a given file name to support extensions with multiple parts (i.e. ".html.erb"). Then file names wouldn't have just one potential extension, since file names like "1. Introduction.html" (also multiple dots) would also need to be supported.

The language concept

• A language has an ID (i.e. "cpp", "cs") for computers (variables, object keys, file names, etc.)
• A language has a name (i.e. "C++", "C#") for humans (displayed in the status bar)
• A language can have a list of file extensions
• A language can have a prefix for line comments (i.e. "//")
• A language can have a prefix and a suffix for block comments (i.e. "/" and "/")
• A language can refer to one main CodeMirror mode and multiple mode aliases

Places contributing to current language support

Based on LESS Refactoring

Module document/DocumentCommandHandlers

• Method _handleNewItemInProject hardcodes ".js"/"Untitled.js" as the default file extension/name for new files. Should maybe be a per-project setting.

Module document/DocumentManager

• Document.getLanguage uses the language API to determine the language based on the file extension.

Module editor/CodeHintManager

• Method registerHintProvider registers hint providers by mode.

Module editor/CSSInlineEditor

• Inline editor provider htmlToCSSProvider decides to open based on the editor mode. In addition it relies on HTMLUtils and CSSUtils

Module editor/Editor.js

• Method _checkElectricChars adjusts indentation when blocks are ended. The characters to detect block boundaries are hard-coded - ], {, } and )

Module editor/EditorCommandHandlers

• Functions _findCommentStart, _findCommentEnd and _findNextBlockComment use tokens provided by CodeMirror to search for comment boundaries. While the strings they search are provided by a language definition, this prevents us from defining "//~" as the prefix for line comments (like SciTE does) because it is not a prefix of the "//" token.
• Methods blockCommentPrefixSuffix and lineCommentPrefixSuffix have similar constrains as they navigate by tokens instead of characters. In addition they check whether a token's className is different from "comment". Therefore they use tokens provided by CodeMirror.

Module file/FileUtils.js

• Methods isStaticHtmlFileExt and isServerHtmlFileExt use hardcoded lists of file extensions

Module language/CSSUtils

• Method findMatchingRules to find CSS rules matching a selector. Searches an HTML document via language/HTMLUtils if it is the current full editor's document. Also searches CSS files as indexed by project/FileIndexManager in the css index, therefore currently indirectly uses file extensions
• Method extractAllSelectors extracts CSS selectors from a string. Internally uses CodeMirror's css mode as a parser, but that could be swapped out.
• Method findSelectorAtDocumentPos to find the selector(s) of a CSS block, directly uses tokens provided by CodeMirror
• Method getInfoAtPos to provide a context info object for the given cursor position, directly uses tokens provided by CodeMirror

Module language/HTMLUtils

• Method findStyleBlocks to gather info about all <style> blocks in an HTML document, directly uses tokens provided by CodeMirror

Module language/JSLintUtils

• Method run to run JSLint on the current document. Checks if the extension is one of .js, .htm or .html, therefore uses file extensions. Otherwise uses JSLint internally which could be swapped out.

Module language/JSUtils

• Method findAllMatchingFunctionsInText to find all instances of a function name in a string of code. Internally uses CodeMirror's javascript mode as a parser, but that could be swapped out.
• Method findMatchingFunctions to find all functions with a specified name within a set of files. Only uses files ending with ".js", i.e. uses file extensions

Module language/Languages

• Defines the "language" concept
• Loads default languages from language/languages.json
• Method defineLanguage to add a new language (see JSDoc)
• Method getLanguage to get an object representing a language by its ID
• Method getLanguageForFileExtension to map file extensions to languages
• Method getLanguageForMode to map CodeMirror modes to languages
• Used by extension "LESSSupport" to add basic support for LESS

Module LiveDevelopment/LiveDevelopment

• Requires hardcoded list of special documents, namely {CSS,HTML,JS}Document
• Function _setDocInfo determines a root URL biased towards HTML and HTML extensions
• Function _classForDocument uses a hardcoded mapping of file extensions to document types
• Function _openDocument only loads related CSS documents (no JavaScript, not extensible)
• Function _onLoad excludes CSSDocument from being marked as out of sync (not extensible)
• Method open reduces LiveDevelopment support to HTML files based on file extensions
• Method showHighlight only calls doc.updateHighlight() for CSSDocuments
• Function _onDocumentChange closes LiveDevelopment when switching to an HTML file and excludes CSSDocument from being marked as out of sync (not extensible)
• Function _onDocumentSaved only reloads the page if the document is not a CSSDocument (not extensible)
• Function _onDirtyFlagChange only updates the LiveDevelopment status if the dirty file is not a CSSDocument (not extensible)

Module LiveDevelopment/Agents/DOMHelpers

• Contains multiple methods that encapsulate knowledge about HTML, should potentially be tied to the language object

Module LiveDevelopment/Agents/DOMNode

• DOMNode.prototype.toString contains basic knowledge about HTML, should potentially be tied to the language object

Module LiveDevelopment/Agents/GotoAgent

• Has hardcoded support for HTML, CSS and JavaScript

Module LiveDevelopment/Agents/HighlightAgent

• Has hardcoded support for HTML and CSS

Script LiveDevelopment/Agents/RemoteFunctions

• Function _typeColor has hardcoded distinctions between html, css, js and others

Module project/FileIndexManager

• Maintains an index called "css" using only files ending with ".css", i.e. uses file extensions

Module search/QuickOpen

• Method addQuickOpenPlugin
• Uses file extensions
• Used by extensions "QuickOpenCSS", "QuickOpenHTML" and "QuickOpenJavaScript"
• Extension "QuickOpenCSS" uses module language/CSSUtils

Notes

Features we think should be able to be built as plug-ins

From the Extensibility Proposal

• Access to code model
• Quick open / go to symbol
• Index files/code (background process)
• Better code hinting for "supported" languages (e.g. for a particular framework)
• JSLint tools
• Inline editor providers (e.g. CSS gradient editor)
• Language-specific search and replace (e.g. HTML tag search and replace)
• Code cleanup / refactoring tools

LiveDevelopment considerations

• What hooks would need to be added where to allow extension-based language support?
  LiveDevelopment.registerDocumentClass(...)
• What behavior would need to be configurable by extensions?
  turning off auto-reload for LESS files, configuring CodeMirror
• What deployment scenarios do we want to support?
  Dynamic client-side, dynamic server-side, static server-side?
• Do we need to integrate with 3rd-party build tools?
  I.e. run ant/cake/... when changing a LESS file to initiate compliation to CSS
• Do we need a specification to delegate compilation to an existing server?
  The server might use a compiler written in a language other than JS, or might use a JS compiler with specific options that can't be easily extracted
• What can we support without impacting performance too much?
  Running a build tool for every character entered will not work
• How should the user configure Brackets to support server-side compilation?
  What file needs to be compiled how when changed - setting for the entire project or a subdirectory? Exceptions for single files?
• How do we deal with distributed files?
  LESS supports including other LESS files, so changes to these should trigger compilation of the master file