Context key expressions

Context key expressions are a way to express values dynamically in thefields of a Sourcegraph extension's manifest.

With string interpolation, you can insert these expressions directly into stringfields.

Context keys are like variables that you can use inside of these interpolatedexpressions. Context keys give you access to values that are available to yourextension dynamically, such as resource for the currently viewed resource, orconfig for the configuration settings.

Template interpolation

Context key expressions can be interpolated inside of strings. In manifestfields that support interpolated expressions, you can interpolate an expressionby surrounding it with ${ and } tags.

This syntax for interpolation is based on JavaScript's template interpolationsyntax.

Supported fields in the manifest

These fields in the manifest support context key expressions.

In contributed actions

String fields that accept interpolated expressions, in contributedactions:

  • title
  • category
  • description
  • iconURL
  • actionItem.label
  • actionItem.description
  • actionItem.iconURL
  • actionItem.iconDescription
  • commandArguments: each string item in the array accepts interpolatedexpressions.

Fields that expect a context key expression:

  • actionItem.pressed: renders the action in a pressed state when thisexpression evaluates to true.

In menu contributions

Fields that expect a context key expression, in menucontributions:

  • when: enables the menu contribution when this expression evaluates to true.

Available context keys

Context keys are the variables that you can use inside of expressions.

  • config: a namespace containing all the settings that are available. Forexample, config.sourcegraphBaseUrl contains the sourcegraphBaseUrl valuefrom Sourcegraph settings.
  • resource: the current resource being viewed, such as a file.
    • resource.uri: example git://github.com/sourcegraph/src-cli?6bffe0f39072e56b414712d0b0cf1fde3b2faca2#internal/batches/executor/execution_cache.go
    • resource.basename: example execution_cache.go
    • resource.dirname: example git://github.com/sourcegraph/src-cli?6bffe0f39072e56b414712d0b0cf1fde3b2faca2#internal/batches/executor
    • resource.extname: example .go
    • resource.language: example go
    • resource.type: example textDocument
    • resource.repo: example github.com/sourcegraph/src-cli
    • resource.commit: example 6bffe0f39072e56b414712d0b0cf1fde3b2faca2
    • resource.path: example internal/batches/executor/execution_cache.go
  • component: true if a component is open, such as a panel, directory view, orfile view.
  • component.selections: an object representing the current selections.
  • panel: the panel component, if a panel is open.
    • panel.activeView.id
    • panel.activeView.hasLocations

Available operators

The available operators mimic the behavior of the same operators in JavaScript:

  • Boolean: && || (with the same truthy/falsy semantics as JavaScript)
  • Comparison: == != === !== < > <= >= (with the strict/looseequality rules of JavaScript)
  • Arithmetic: + - * / ^ %
  • Unary: ! + -

Available functions

get(object, key)

Returns the value of a property named key on object or return undefined ifeither the object or the property doesn't exist.

json(object)

Returns the object converted to a JSON string using JSON.stringify.

Limitations

The expression syntax is simple and isn't intended to be a full programminglanguage, so there are some limitations.

  • Lack of operator precedence. Because of the simplicity of the parser,operators do not have any precedence and are simply evaluated left-to-right.Use parentheses to specify precedence.
  • Lack of a ternary operator. Instead of a ternary operator, you can usecombinations of && and || operators to achieve a similar result.