Skip to content

Configuration

Jump to bottom
Qingpeng Li edited this page Jun 28, 2022 · 1 revision

Basics

Before changing the built-in settings, please ensure you understand the basic knowledge of VS Code Extension below. Please note that the built-in settings are advanced settings, so incorrect configuration may lead to unexpected behavior. Before you try to change the built-in settings, please use the VS Code settings (such as the editor tab) first.

VS Code Language Feature

VS Code extensions usually enable the Language Features by implementing features with Language Server Protocol or VS Code language API for a language. This extension chooses to use VS Code language API.

VS Code language API used

Lifetime: Disposables

The VS Code API uses the dispose pattern for resources obtained from VS Code. This applies to event listening, commands, interacting with the UI, and various language contributions.
For instance, the setStatusBarMessage(value: string) function returns a Disposable which upon calling dispose() removes the message again. See more patterns-and-principles.

This Extension Design

This extension has a trigger function and will trigger the update process when the code text is changed. The updated process includes parsing, static analysis, etc. Both DocumentSymbolProvider and DocumentSemanticTokensProvider can trigger the update. Also, we have a backup listener to manage triggering in case both two providers are disabled.

Configuration

For configuration schema, see VS Code Extension contributes.configuration.

  • "commonLisp.StaticAnalysis.enabled"
    If you would like to use only TextMate-based highlighting, disable this. This will not enable any providers. This would be useful if you need to save battery life since there is no static analysis occurs at all.

  • "commonLisp.providers.CompletionItemProviders.original.enabled"
    For auto-suggesting all symbols in ANSI Common Lisp.

    "commonLisp.providers.CompletionItemProviders.ampersand.enabled"
    For auto-suggesting lambda list keyword symbols.

    "commonLisp.providers.CompletionItemProviders.asterisk.enabled"
    For auto-suggesting Variable symbols.

    "commonLisp.providers.CompletionItemProviders.colon.enabled"
    For auto-suggesting KEYWORD package symbols.

  • "commonLisp.providers.CompletionItemProviders.tilde.enabled"
    "commonLisp.providers.CompletionItemProviders.sharpsign.enabled"
    These two providers are not enable by default since in most cases, one character auto-suggestion would be not useful.

  • "commonLisp.providers.CompletionItemProviders.user.enabled"
    This provider will collect user-defined global and local variables and auto-suggest them.

  • "commonLisp.providers.HoverProvider.enabled"
    Show documentation for all symbols in ANSI Common Lisp.

  • "commonLisp.providers.DefinitionProvider.enabled"
    Provide Definition feature (Go to Definition).
    "commonLisp.providers.DocumentSymbolProvider.enabled"
    Provide Document Symbol feature (Outline).
    "commonLisp.providers.ReferenceProvider.enabled"
    Provide Reference feature (Go to References).
    "commonLisp.providers.DocumentSemanticTokensProvider.enabled"
    Provide Semantic Tokens feature (Semantic Highlight).
    "commonLisp.providers.CallHierarchyProvider.enabled"
    Provide Call Hierarchy feature (Show Call Hierarchy).

  • "commonLisp.backupUpdater.debounceTimeout"
    When both DocumentSymbolProvider and DocumentSemanticTokensProvider are disabled (by default, the update process is delegated to them), we will add a backupUpdater to control the update process. Thus, we need a debounce timeout to ensure that the update process is triggered not too often. The timeout should be considered the rest time after a series of keystrokes.

  • "commonLisp.Updater.throttleTimeout"
    When both DocumentSymbolProvider and DocumentSemanticTokensProvider are enabled. Two Providers may trigger the update process too often, so we need a throttle timeout. The timeout should be less than < (fastest consecutive keystroke interval ~200ms) to prevent the symbol information of another provider from not being synchronized. If you do not mind providing more performance for it, it can be set to 0.

  • "commonLisp.ReferenceProvider.ExcludedRanges"
    "commonLisp.DefinitionProvider.ExcludedRanges"
    "commonLisp.DocumentSemanticTokensProvider.ExcludedRanges"
    For some certain habits, you may need to treat full-text symbols the same way, even though they are in comments and strings. See vscode #74237. Please note that in static analysis, comments and strings are always excluded. These configs are used to change the behavior of Go to Definition/References and Semantic Highlighting.

  • "commonLisp.DocumentSemanticTokensProvider.SingleQuoteAndBackQuote.Highlight"
    Decide which parts (single quote and backquote) are highlighted. Default conveys the correct semantics. Disable it only if you think this causes inaccurate result.

  • "commonLisp.StaticAnalysis.SingleQuoteAndBackQuote.ExcludedRanges"
    Decide which parts (single quote and backquote) are excluded from static analysis. Default conveys the correct semantics. Disable it only if you think this causes inaccurate result.

  • "commonLisp.ReferenceProvider.BackQuoteFilter.enabled"
    "commonLisp.DefinitionProvider.BackQuoteFilter.enabled"
    Decide how to response when Go to Definition/References from a position in the backquote. If it is enabled, the extension will only respond to the symbol starting with a comma, which conveys the correct semantics. Disable it only if you think this causes the inaccurate result.

Inconsistent behavior

In most cases, new behavior should take effect immediately. However, for some providers, due to VS Code's dispose pattern, some listeners may not take effect or cancel immediately, causing inconsistent static analysis results. Please just reload the VS Code window, and the new behavior should become consistent.

Clone this wiki locally