Lumine API reference

This is necessary on Windows since it doesn’t support shebang #! lines.

Examples#

  const {BufferedNodeProcess} = require('lumine')

Examples#

const {BufferedProcess} = require('lumine')

const command = 'ps'
const args = ['-ef']
const stdout = (output) => console.log(output)
const exit = (code) => console.log(`ps -ef exited with ${code}`)
const process = new BufferedProcess({command, args, stdout, exit})

An instance of this class is always available as the lumine.clipboard global.

This class owns what the clipboard holds, not what a paste does with it. To intercept a paste before the editor inserts it as text — to handle an image, say — register a provider with PasteProviderRegistry through lumine.pasteProviders.

It is also the only supported route to the native clipboard from a package: Electron exposes its Promise-based clipboard only in the main process, so every programmatic read and write here crosses the process boundary (see src/clipboard-bridge.js). Native ClipboardEvents use a synchronous DataTransfer-backed adapter for the duration of the event.

Examples#

await lumine.clipboard.write('hello')

console.log(await lumine.clipboard.read()) // 'hello'

The global command registry facilitates a style of event handling known as event delegation that was popularized by jQuery. Lumine commands are expressed as custom DOM events that can be invoked on the currently focused element via a key binding or manually via the command palette. Rather than binding listeners for command events directly to DOM nodes, you instead register command event listeners globally on lumine.commands and constrain them to specific kinds of elements with CSS selectors.

Command names must follow the namespace:action pattern, where namespace will typically be the name of your package, and action describes the behavior of your command. If either part consists of multiple words, these must be separated by hyphens. E.g. awesome-package:turn-it-up-to-eleven. All words should be lowercased.

As the event bubbles upward through the DOM, all registered event listeners with matching selectors are invoked in order of specificity. In the event of a specificity tie, the most recently registered listener is invoked first. This mirrors the “cascade” semantics of CSS. Event listeners are invoked in the context of the current DOM node, meaning this always points at event.currentTarget. As is normally the case with DOM events, stopPropagation and stopImmediatePropagation can be used to terminate the bubbling process and prevent invocation of additional listeners.

Example#

Here is a command that inserts the current date in an editor:

lumine.commands.add('lumine-text-editor', {
  'user:insert-date'(event) {
    const editor = this.getModel()
    editor.insertText(new Date().toLocaleString())
  }
})

These are very useful when subscribing to multiple events.

Examples#

const { CompositeDisposable } = require("lumine");

class Something {
  constructor() {
    this.disposables = new CompositeDisposable();
    const editor = lumine.workspace.getActiveTextEditor();
    this.disposables.add(editor.onDidChange(() => {}));
    this.disposables.add(editor.onDidChangePath(() => {}));
  }

  destroy() {
    this.disposables.dispose();
  }
}

An instance of this class is always available as the lumine.config global.

Getting and setting config settings.#

// Note that with no value set, ::get returns the setting's default value.
lumine.config.get('my-package.myKey') // -> 'defaultValue'

lumine.config.set('my-package.myKey', 'value')
lumine.config.get('my-package.myKey') // -> 'value'

// Change only this window until it reloads, without saving to config.json.
lumine.config.set('my-package.myKey', 'temporary', { local: true })
lumine.config.unset('my-package.myKey', { local: true })

You may want to watch for changes. Use #observe to catch changes to the setting.

lumine.config.set('my-package.myKey', 'value')
lumine.config.observe('my-package.myKey', (newValue) => {
  // `observe` calls immediately and every time the value is changed
  console.log('My configuration changed:', newValue)
})

If you want a notification only when the value changes, use #onDidChange.

lumine.config.onDidChange('my-package.myKey', ({ newValue, oldValue }) => {
  console.log('My configuration changed:', newValue, oldValue)
})

Value Coercion#

Config settings each have a type specified by way of a schema. For example we might want an integer setting that only allows integers greater than 0:

// When no value has been set, `::get` returns the setting's default value
lumine.config.get('my-package.anInt') // -> 12

// The string will be coerced to the integer 123
lumine.config.set('my-package.anInt', '123')
lumine.config.get('my-package.anInt') // -> 123

// The string will be coerced to an integer, but it must be greater than 0, so is set to 1
lumine.config.set('my-package.anInt', '-20')
lumine.config.get('my-package.anInt') // -> 1

Defining settings for your package#

Declare a configSchema in your package’s package.json:

{
  "name": "my-package",
  "configSchema": {
    "someInt": {
      "title": "Some Int",
      "description": "How many of the thing to do.",
      "type": "integer",
      "minimum": 1,
      "default": 23
    }
  }
}

The schema is read before the package activates, so its settings appear in the settings view and its defaults apply whether or not the package has been loaded yet. Export a config object from the package’s main module only when the schema cannot be written down ahead of time and has to be built at runtime.

See the package tutorial for more info.

Config Schemas#

We use json schema which allows you to define your value’s default, the type it should be, etc. Every example below is the value of the configSchema key. A simple one, providing an enableThing and a thingVolume:

{
  "enableThing": {
    "type": "boolean",
    "default": false
  },
  "thingVolume": {
    "type": "integer",
    "minimum": 1,
    "maximum": 11,
    "default": 5
  }
}

The type keyword allows for type coercion and validation. If a thingVolume is set to a string '10', it will be coerced into an integer.

lumine.config.set('my-package.thingVolume', '10')
lumine.config.get('my-package.thingVolume') // -> 10

// It respects the min / max
lumine.config.set('my-package.thingVolume', '400')
lumine.config.get('my-package.thingVolume') // -> 11

// If it cannot be coerced, the value will not be set
lumine.config.set('my-package.thingVolume', 'cats')
lumine.config.get('my-package.thingVolume') // -> 11

Supported Types#

The type keyword can be a string with any one of the following. You can also chain them by specifying multiple in an array. For example

{
  "someSetting": {
    "type": ["boolean", "integer"],
    "default": 5
  }
}

lumine.config.set('my-package.someSetting', 'true')
lumine.config.get('my-package.someSetting') // -> true

lumine.config.set('my-package.someSetting', '12')
lumine.config.get('my-package.someSetting') // -> 12

string#

Values must be a string.

{
  "someSetting": {
    "type": "string",
    "default": "hello"
  }
}

integer#

Values will be coerced into integer. Supports the (optional) minimum and maximum keys.

{
  "someSetting": {
    "type": "integer",
    "minimum": 1,
    "maximum": 11,
    "default": 5
  }
}

number#

Values will be coerced into a number, including real numbers. Supports the (optional) minimum and maximum keys.

{
  "someSetting": {
    "type": "number",
    "minimum": 1.5,
    "maximum": 11.5,
    "default": 5.3
  }
}

boolean#

Values will be coerced into a Boolean. 'true' and 'false' will be coerced into a boolean. Numbers, arrays, objects, and anything else will not be coerced.

{
  "someSetting": {
    "type": "boolean",
    "default": false
  }
}

array#

Value must be an Array. The types of the values can be specified by a subschema in the items key. An item that does not conform to that subschema is dropped rather than rejecting the whole array. Supports the (optional) minItems and maxItems keys, which bound the length of the array that survives; a value outside those bounds is rejected and the setting keeps its previous value.

{
  "someSetting": {
    "type": "array",
    "items": {
      "type": "integer",
      "minimum": 1.5,
      "maximum": 11.5
    },
    "minItems": 1,
    "maxItems": 3,
    "default": [1, 2, 3]
  }
}

color#

Values will be coerced into a Color with red, green, blue, and alpha properties that all have numeric values. red, green, blue will be in the range 0 to 255 and value will be in the range 0 to 1. Values can be any valid CSS color format such as #abc, #abcdef, white, rgb(50, 100, 150), and rgba(25, 75, 125, .75).

{
  "someSetting": {
    "type": "color",
    "default": "white"
  }
}

object / Grouping other types#

A config setting with the type object allows grouping a set of config settings. The group will be visually separated and has its own group headline. The sub options must be listed under a properties key.

{
  "someSetting": {
    "type": "object",
    "properties": {
      "myChildIntOption": {
        "type": "integer",
        "minimum": 1.5,
        "maximum": 11.5
      }
    }
  }
}

Other Supported Keys#

enum#

All types support an enum key, which lets you specify all the values the setting can take. enum may be an array of allowed values (of the specified type), or an array of objects with value and description properties, where the value is an allowed value, and the description is a descriptive string used in the settings view.

In this example, the setting must be one of the 4 integers:

{
  "someSetting": {
    "type": "integer",
    "enum": [2, 4, 6, 8],
    "default": 4
  }
}

In this example, the setting must be either ‘foo’ or ‘bar’, which are presented using the provided descriptions in the settings pane:

{
  "someSetting": {
    "type": "string",
    "enum": [
      { "value": "foo", "description": "Foo mode. You want this." },
      { "value": "bar", "description": "Bar mode. Nobody wants that!" }
    ],
    "default": "foo"
  }
}

If you only have a few elements, you can display your enum as a list of radio buttons in the settings view rather than a select list. To do so, specify radio: true as a sibling property to the enum array.

{
  "someSetting": {
    "type": "string",
    "enum": [
      { "value": "foo", "description": "Foo mode. You want this." },
      { "value": "bar", "description": "Bar mode. Nobody wants that!" }
    ],
    "radio": true,
    "default": "foo"
  }
}

Usage:

lumine.config.set('my-package.someSetting', '2')
lumine.config.get('my-package.someSetting') // -> 2

// a value outside the enum is rejected, and the setting keeps what it had
lumine.config.set('my-package.someSetting', '3')
lumine.config.get('my-package.someSetting') // -> 2

// a value inside it is coerced to the declared type and set
lumine.config.set('my-package.someSetting', '4')
lumine.config.get('my-package.someSetting') // -> 4

title and description#

The settings view will use the title and description keys to display your config setting in a readable way. By default the settings view humanizes your config key, so someSetting becomes Some Setting. In some cases, this is confusing for users, and a more descriptive title is useful.

Descriptions will be displayed below the title in the settings view.

For a group of config settings the humanized key or the title and the description are used for the group headline.

{
  "someSetting": {
    "title": "Setting Magnitude",
    "description": "This will affect the blah and the other blah",
    "type": "integer",
    "default": 4
  }
}

Note: You should strive to be so clear in your naming of the setting that you do not need to specify a title or description!

Descriptions allow a subset of Markdown formatting. Specifically, you may use the following in configuration setting descriptions:

• bold - **bold**
• italics - *italics*
• links - [links](https://lumine-code.github.io)
• code spans - `code spans`
• line breaks - line breaks<br/>
• strikethrough - ~~strikethrough~~

order#

The settings view displays your settings in the order the schema declares them, so arranging the schema is all this normally takes.

An explicit order key still takes precedence where one is present, but prefer not to use it: a setting without order sorts after every setting that has one, so adding order to part of a schema reorders the rest of it too.

Manipulating values outside your configuration schema#

It is possible to manipulate(get, set, observe etc) values that do not appear in your configuration schema. For example, if the config schema of the package ‘some-package’ is

{
  "someSetting": {
    "type": "boolean",
    "default": false
  }
}

You can still do the following

const otherSetting = lumine.config.get('some-package.otherSetting')
lumine.config.set('some-package.stillAnotherSetting', otherSetting * 5)

In other words, if a function asks for a key-path, that path doesn’t have to be described in the config schema for the package or any package. However, as highlighted in the best practices section, you are advised against doing the above.

Best practices#

• Don’t depend on (or write to) configuration keys outside of your keypath.

An instance of this class is always available as the lumine.contextMenu global.

Context Menu Object Format#

{
  "lumine-workspace": [
    { "label": "Help", "command": "application:open-documentation" }
  ],
  "lumine-text-editor": [
    {
      "label": "History",
      "submenu": [
        { "label": "Undo", "command": "core:undo" },
        { "label": "Redo", "command": "core:redo" }
      ]
    }
  ]
}

A package declares its context menu in a file under menus/, with the structure above under a context-menu key:

{
  "context-menu": {
    "lumine-workspace": [
      { "label": "Help", "command": "application:open-documentation" }
    ]
  }
}

The format for use in #add is the same minus the context-menu key. See #add for more information.

Decoration objects are not meant to be created directly, but created with TextEditor#decorateMarker. eg.

const range = editor.getSelectedBufferRange() // any range you like
const marker = editor.markBufferRange(range)
const decoration = editor.decorateMarker(marker, { type: 'line', class: 'my-line-class' })

Best practice for destroying the decoration is by destroying the DisplayMarker.

marker.destroy()

You should only use Decoration#destroy when you still need or do not own the marker.

An instance of this class is always available as the lumine.deserializers global.

Examples#

class MyPackageView {
  static deserialize(state) {
    return new MyPackageView(state)
  }

  constructor(state) {
    this.state = state
  }

  serialize() {
    return { deserializer: 'MyPackageView', ...this.state }
  }
}

lumine.deserializers.add(MyPackageView)

Serialized state has to carry the deserializer key: it is the name #deserialize looks the class up by, and state without it is dropped with a warning rather than restored.

DisplayMarker Creation#

Use DisplayMarkerLayer#markBufferRange or DisplayMarkerLayer#markScreenRange rather than creating Markers directly.

Head and Tail#

Markers always have a head and sometimes have a tail. If you think of a marker as an editor selection, the tail is the part that’s stationary and the head is the part that moves when the mouse is moved. A marker without a tail always reports an empty range at the head position. A marker with a head position greater than the tail is in a “normal” orientation. If the head precedes the tail the marker is in a “reversed” orientation.

Validity#

Markers are considered valid when they are first created. Depending on the invalidation strategy you choose, certain changes to the buffer can cause a marker to become invalid, for example if the text surrounding the marker is deleted. The strategies, in order of descending fragility:

• never: The marker is never marked as invalid. This is a good choice for markers representing selections in an editor.
• surround: The marker is invalidated by changes that completely surround it.
• overlap: The marker is invalidated by changes that surround the start or end of the marker. This is the default.
• inside: The marker is invalidated by changes that extend into the inside of the marker. Changes that end at the marker’s start or start at the marker’s end do not invalidate the marker.
• touch: The marker is invalidated by a change that touches the marked region in any way, including changes that end at the marker’s start or start at the marker’s end. This is the most fragile strategy.

See TextBuffer#markRange for usage.