README.md

VSCode Extension for Crystal Language

This extension provides support for The Crystal programming language.

Features

• Snippets
• Formatting
• Problems finder
• Document Symbols
• Syntax highlighting
• Show variable type on Hover
• Show and Peek Implementations
• Increment and decrements indentation
• Method completion for Literals and Symbols

Requirements

You need Crystal installed in your system to get compiler features like goTo implementation and diagnostics.

Other features like syntax highlighting, snippets, symbols and basic completion work without Crystal compiler.

Configuration

crystal-lang provides some useful configuration inside settings.json:

{
  "crystal-lang.problems": "syntax",
  "crystal-lang.maxNumberOfProblems": 10,
  "crystal-lang.mainFile": "",
  "crystal-lang.processesLimit": 3,
  "crystal-lang.implementations": true,
  "crystal-lang.completion": true,
  "crystal-lang.types": true,
  "crystal-lang.server": "",
  "crystal-lang.logLevel": "error"
}

On Windows the document must use LF instead of CRLF to allow symbols completion.

Problems

crystal-lang.problems allow setting different error levels. By default, the problem finder just check syntax errors. The options are:

• syntax: check syntax and tokens (default).
• build: check requires, objects and methods without code gen (resource heavy).
• none: disable problem finder.

{
  "crystal-lang.problems": "syntax | build | none",
}

Problems are checked when a crystal document is opened or saved.

Syntax checking is activated on type allowing live diagnostics.

Features like implementations and show type on hover can find errors.

PoblemsLimit

crystal-lang.maxNumberOfProblems allow to limit the amount of problems that appears in problems view. The default value is 20.

MainFile

crystal-lang.mainFile says to the compiler which file should analyze.

It is useful when "crystal-lang.problems" = "build" in project where a main file do require "/**"

Also is used by features like implementations and show type on hover to specify the tool scope.

Be sure that mainFile is a valid absolute filepath.

{
  "crystal-lang.mainFile": "/absolute/path/src/main.cr",
}

ProcessesLimit

This extension block the amout of crystal processes executing in parallel because it doesn't use a language server yet, see Scry.

Commonly crystal takes milliseconds to do something like formatting, but in some projects other features like implementations or completion can take a moment. To prevent using too many resources you can set the amount of processes with:

{
  "crystal-lang.processesLimit": 3,
}

By default, is 3. In my computer each crystal process uses almost 50 MB and less than 1 second.

Implementations

You can use this feature to peek or go to implementation of a method.

Completion

This setting ensure to enable instance method completion using crystal tool context.

Suggestion of methods and subtypes while typing is not supported. You need to type . (dot) or :: (colons) and then press CTRL + SPACE or CMD + SPACE to call method suggestion.

Basic code completion is always enabled. (Top Level, Symbols and Snippets)

However, you can totally disable completions in settings.json:

{
  "editor.quickSuggestions": {
    "other": true,
    "comments": false,
    "strings": false
  }
}

Types

Show type information for variables only. This feature uses crystal tool context to get types. Information is recalculated when the cursor changes line position.

Server (NEW)

It's Experimental feature using Scry and Language Server Protocol.

Reload your editor after enable this feature.

The following features are implemented:

• Formatting
• Live Diagnostics
• GoTo Definition
• Peek Definition

Scry server isn't distributed with this extension. You need to compile it from scry-vscode-crystal-lang and configure on settings.json

{
  "crystal-lang.server": "/absolute/path/bin/scry",
}

LogLevel

Controls the amount of data logged by Scry server.

You can see logs in .scry.out located in your home directory or your workspace.

Levels avaliables:

{
  "type": "string",
  "default": "error",
  "enum": [
    "debug",
    "info",
    "warn",
    "error",
    "fatal"
  ]
}

Messages

Sometimes in some projects, crystal tool turns heavy, in this case you can check error and info messages.

Errors and info messages are shown in developer tools:

• ERROR: spawn: when crystal program not exist in path or mainFile is wrong.
• ERROR: JSON parse: when crystal output is different of JSON.
• INFO: processesLimit has been reached: your project is taking too much time to analyze.

The following images show crystal status bar messages:

Know issues

• Linter and formatter are implemented using Node.js child_process, so perfomance could be affected. You can use a different problem level.

• macros can produce some unwanted behaviors, disable peek implementations, instance method completions and types on hover to hide errors.

• ECR syntax is very basic. You can use vscode text.html instead or enable emmet for text.ecr in your settings.json:

{
  "emmet.syntaxProfiles": {
    "ecr": "html"
  }
}

• In some big projects like crystal compiler itself, the setting "crystal-lang.problems" = "build" could be very unresponsible, use "syntax" instead.

• Scry server is experimental, some bug can appear. Scry is a bit heavy, it uses from 5 Mb until 500Mb of RAM in my computer.

More Screenshots

Increment and decrement identation

Decrement end keyword on type is now avaliable in vscode insiders #2262.

Formatting code support

Syntax highlighting

Snippets

Symbols

Code Outline (NEW)

Recent version of VSCode (1.13.1) allow to extensions creators show symbols in tree view. You can use the awesome Code Outline extension to see code tree of crystal document.

Debugging

Native Debug is an excelent extension that allow you to debug crystal and other languages that compile to binary.

Be sure of compile your crystal code with --debug flag

Icon theme

You can use the wonderful Nomo Dark icon theme to see crystal icon.

Roadmap

• Translate Crystal syntax from .tmLanguage to .json.
• Full Support for Language Server Protocol, see Scry

Release Notes

See Changelog

Contributing

1. Fork it https://github.com/faustinoaq/vscode-crystal-lang/fork
2. Create your feature branch git checkout -b my-new-feature
3. Commit your changes git commit -am 'Add some feature'
4. Push to the branch git push origin my-new-feature
5. Create a new Pull Request

Contributors

• @faustinoaq Faustino Aguilar - creator, maintainer