Lumine API reference

Lumine global for dealing with packages, themes, menus, and the window.

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

Main-process application services exposed as serializable values.

Like BufferedProcess, but accepts a Node script as the command to run.

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

Examples

  const {BufferedNodeProcess} = require('lumine')

A wrapper which provides standard error/output line buffering for Node’s ChildProcess.

Examples

{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})

Represents the clipboard used for copying and pasting in Lumine.

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 deprecated require('electron').clipboard in a renderer, so every read and write here goes to the main process instead (see src/clipboard-bridge.js).

Examples

lumine.clipboard.write('hello')

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

A simple color class returned from Config#get when the value at the key path is of type ‘color’.

Associates listener functions with commands in a context-sensitive way using CSS selectors. You can access a global instance of this class via lumine.commands, and commands registered there will be presented in the command palette.

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())
  }
})

Used to access all of Lumine’s configuration details.

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'

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.

Provides a registry for commands that you’d like to appear in the context menu.

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.

The Cursor class represents the little blinking line identifying where text can be inserted.

Cursors belong to TextEditors and have some metadata attached in the form of a DisplayMarker.

Represents a decoration that follows a DisplayMarker. A decoration is basically a visual representation of a marker. It allows you to add CSS classes to line numbers in the gutter, lines, and add selection-line regions around marked ranges of text.

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.

Turns a project URI into a Directory, for local paths.

This is the provider Project falls back to when no package claims a URI. A package supplies its own by providing the project.directory-provider service; the methods below are the shape that contract expects.

Manages the deserializers used for serialized state

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.

Represents a buffer annotation that remains logically stationary even as the buffer changes. This is used to represent cursors, folds, snippet targets, misspelled words, and anything else that needs to track a logical location in the buffer over time.

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.

A container for a related set of markers at the DisplayLayer level. Wraps an underlying MarkerLayer on the TextBuffer.

This API is experimental and subject to change on any release.

A container at the edges of the editor window capable of holding items. You should not create a Dock directly. Instead, access one of the three docks of the workspace via Workspace#getLeftDock, Workspace#getRightDock, and Workspace#getBottomDock or add an item to a dock via Workspace#open.