DEVELOPMENT.md

Development

What's in the folder

• package.json - this is the manifest file in which you declare your language support and define the location of the grammar file that has been copied into your extension.
• syntaxes/vcl.tmLanguage.json - this is the Text mate grammar file that is used for tokenization.
• language-configuration.json - this is the language configuration, defining the tokens that are used for comments and brackets.
• client/ - this is the Language Server Protocol client that talks to the LSP server (fastly-vcl-lsp).

Building and running this extension

You'll need Node.js and npm:

brew install npm
npm i node@lts

To develop this extension on your machine, clone this repository and install its dependencies:

gh repo clone fastly/vscode-fastly-vcl
cd vscode-fastly-vcl
npm i

Local development server

1. Open this folder in VS Code.
2. Run Cmd+Shift+B to start compiling the client in watch mode.
3. Press Cmd+Shift+D to switch to the Run and Debug View in the sidebar.
4. Select Fastly VCL Client from the drop down.
5. Press ▷ to run the launch config with the debugger attached (F5).
6. In the Extension Development Host instance of VSCode, open a document in Fastly VCL language mode.
7. Save the file with a .vcl extension.
8. Use it as a scratchpad to try out all the features!

Testing

To run the grammar tests:

npm test

The test cases are stored as markdown files under test/colorize-fixtures. Grammar test results are stored under test/colorize-results, which are automatically generated from the fixtures.

To run the LSP tests:

npm run test-client

Packaging and installation

Run the following command to compile the VSCode extension as a .vsix file.

npm run package

Then, either run code --install-extension vscode-fastly-vcl-{VERSION}.vsix or follow the steps below to install the extension:

1. Press Cmd+Shift+X to go to the VS Code extension tab.
2. Click the ellipsis (above "Search Extensions in Marketplace") and pick Install from VSIX... from the dropdown.
3. Install the .vsix file you created.

Contributing

Please open a pull request with your changes.

Functionality

Syntax highlighting (VSCode capability)

This uses a JSON TextMate language grammar: syntaxes/vcl.tmLanguage.json, a structured collection of regular expressions, to tokenize the text into scopes such as:

• keyword.control.vcl
• variable.other.vcl
• string.quoted.double.vcl
• comment.line.number-sign.vcl

For example, the extension scopes Fastly code macros as control keywords using a regular expression in JSON:

{
  "name": "keyword.control.vcl",
  "match": "^\\s*#FASTLY\\s+(deliver|error|fetch|hash|hit|log|miss|pass|recv)\\s*$"
}

Visual Studio Code themes such as GitHub Dark Default or the default Light+ map scopes to colours and styles.

The GitHub Dark default theme maps the keyword scope to red using a JavaScript object:

{
  scope: "keyword",
  settings: {
    foreground: lightDark(scale.red[5], scale.red[3])
  }
}

Fastly VCL LSP capabilities

The Fastly VCL Language Server Protocol (LSP) server works for .vcl files. The server is still in an early state. The following list tracks the protocol features that are supported:

• textDocument/codeAction
• textDocument/completion (incl. completion/resolve)
• textDocument/definition
• textDocument/didChange (incremental)
• textDocument/didClose
• textDocument/didOpen
• textDocument/didSave
• textDocument/documentHighlight
• textDocument/documentSymbol
• textDocument/executeCommand
• textDocument/formatting
• textDocument/hover
• textDocument/inlayHint
• textDocument/prepareCallHierarchy
• callHierarchy/incomingCalls
• callHierarchy/outgoingCalls
• textDocument/prepareRename
• textDocument/rangeFormatting
• textDocument/references
• textDocument/rename
• textDocument/selectionRange
• textDocument/signatureHelp
• workspace/symbol
• workspace/didChangeConfiguration
• workspace/executeCommand