## Classes

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

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

A container capture. When another capture's node is contained by the definition capture's node, it gets added to this instance.

CaptureOrganizer

Keeps track of @definition.* captures and the captures they may contain.

InvalidProviderError ⇐ Error

An error thrown when a newly added symbol provider does not conform to its contract.

ListController

A class for setting various UI properties on a symbol list palette. This is a privilege given to the “main” (or exclusive) provider for a given task.

This is how we allow a provider to communicate its state to the UI without giving it full control over the SelectListView used to show results.

## Constants

etch

css

This file will manage the updating of autocomplete-css completions.json. We will mainly utilize @webref/css.listAll() function that returns a full CSS list of all properties seperated by their spec shortname. An example of this format is defined below for ease of future modifications.

Some important notes about the data contained here: - Often times the value within the property will be in the following format: <valueGroupName> or even <valueGroupName> | value | value2 or just value | value2 It will be important to build a parser that can handle this format. The <valueGroupName> then can be realized via that specs values where values[x].name will match the <valueGroupName>. Another important note about handling values here is that oftentimes values[x].values[] won't actually contain all possible values. And instead this must be handled by checking values[x].value which is another string of <valueGroupName> | value. So this should be handled by the same parser. - Additionally an important note is that nowhere in this data do we get any kind of description about the data that could lend a hand in being documentation. So the documentation must be gathered seperatly. Likely the best way to collect our documentation data is via mdn/content. Within content/files/en-us/web/css is a directory of folders titled by the name of properties.

The last important thing to note here:
  MDN doesn't have docs on everything. And that's a good thing. But it means
  many of our items don't have any kind of description. For this situation
  we have `manual-property-desc.json` which is a list of manually updated
  descriptions for properties where there are none. This was a last resort
  intended to provide the highest quality of completions possible.
  Overtime many items on this list will likely be able to be removed just as
  new ones are added. After running the update script you'll see a warning
  saying how many properties are without completions that would then need to
  be added to the JSON file.

"spec-shortname": { "spec": { "title": "", "url": "" }, "properties": [ { "name": "", "value": "", "initial": "", "appliesTo": "", "percentages": "", "computedValue": "", "canonicalOrder": "", "animationType": "", "media": "", "styleDeclaration": [ "", "", "" ] } ], "atrules": [ { "name": "", "descriptors": [ { "name": "", "for": "", "value": "", "type": "" } ] } ], "selectors": [], "values": [ { "name": "", "type": "", "prose": "Optional description", "value": "", "values": [ { "name": "", "prose": "Optional Description", "type": "", "value": "" } ] } ], "warnings": [] }

chromiumElementsShim

This file will manage the updating of autocomplete-html completions.json We will partially utilize @webref/elements .listAll() function that returns a full list of HTML Elements along with a defined interface. To use this interface in any meaningful way, we will utilize the dataset of Attributes that apply to each interface from Chromiums DevTools resource https://github.com/ChromeDevTools/devtools-frontend. Finally from here we will utilize https://github.com/mdn/content to parse the Markdown docs of MDN's website to retreive descriptions for each element.

Now for a summary of our completions.json file we aim to generate. There are two top level elements, tags and attributes, both objects. Within tags we expect the following: "tags": { "a": { "attributes": [ "href", "hreflang", "media", "rel", "target", "type" ], "description": "....." } };

When an entry contains no attributes there is no empty array, the element simply doesn't exist.

The attributes object contains keys of different elements that themselves are objects that can contain several valid keys.

global: Seems to be used exclusively for Global Attributes. Is a boolean which when false, the key does not appear.
type: A ?type? for the attribute. It's meaning is not immediately known. Nor a way to reliabley programatically collect it. Some discovered values:

cssStyle: Exclusively used for class attribute boolean: Attributes that only accept true or false flag: For attributes that don't require or accept values. eg autoplay cssId: Exclusively used for the id attribute color: Exclusively used for the bgcolor attribute style: Exclusively used for the style attribute

description: A text description of the attribute
attribOption: A string array of valid values that can exist within the attribute. Such as the case with rel where only so many valid options exist.

Although with our data sources mentioned above, we are able to collect nearly all the data needed. Except the type that is defined within our completions.json as well as the attribOption within our completions.

Studying these closer reveals that all attributes listing with our completions.json do not appear elsewhere, and are nearly all global attributes.

In this case since there is no sane way to collect this data, we will leave this list as a manually maintained section of our completions.json. This does mean that curated-attributes.json is a static document that will require manual updating in the future. Or most ideally, will find a way to automatically generate the needed data.

update

This file aims to run some short simple tests against update.js. Focusing mainly on the Regex used within sanitizeDescription()

## Functions

renderMarkdown(content, givenOpts) ⇒ string

Takes a Markdown document and renders it as HTML.

beforeEach()

conditionPromise()

destroy()

destroyChildren()

releaseChildren()

subscribeToRepository()

updateDiffs()

beforeEach()

isIterable(obj) ⇒ Boolean

Ensures an object can be iterated over.

The contract with the symbol providers is that they return an object that gives us symbol objects when we iterate over it. It'll probably be an array, but we're cool with anything iterable.

timeout(ms) ⇒ Promise.<true>

Returns a promise that resolves after a given number of milliseconds.

getBadgeTextVariant(text) ⇒ String

Given a string of text, returns a hexadecimal character from 0 to f to represent a classification “bucket.” This is used when assigning colors to various symbol badges.

badge(text, options) ⇒ Element

Return a DOM element for a badge for a given symbol tag name.

beforeEach()

conditionPromise()

beforeEach()

## AtomEnvironment Pulsar global for dealing with packages, themes, menus, and the window. An instance of this class is always available as the `atom` global. **Kind**: global class * [AtomEnvironment](#AtomEnvironment) * _instance_ * [.clipboard](#AtomEnvironment+clipboard) : [Clipboard](#Clipboard) * [.deserializers](#AtomEnvironment+deserializers) : DeserializerManager * [.views](#AtomEnvironment+views) : ViewRegistry * [.notifications](#AtomEnvironment+notifications) : NotificationManager * [.config](#AtomEnvironment+config) : Config * [.keymaps](#AtomEnvironment+keymaps) : KeymapManager * [.tooltips](#AtomEnvironment+tooltips) : TooltipManager * [.commands](#AtomEnvironment+commands) : CommandRegistry * [.grammars](#AtomEnvironment+grammars) : GrammarRegistry * [.styles](#AtomEnvironment+styles) : StyleManager * [.packages](#AtomEnvironment+packages) : PackageManager * [.themes](#AtomEnvironment+themes) : ThemeManager * [.menu](#AtomEnvironment+menu) : MenuManager * [.contextMenu](#AtomEnvironment+contextMenu) : ContextMenuManager * [.project](#AtomEnvironment+project) : Project * [.textEditors](#AtomEnvironment+textEditors) : TextEditorRegistry * [.workspace](#AtomEnvironment+workspace) : Workspace * [.history](#AtomEnvironment+history) : HistoryManager * _Messaging the User_ * [.beep()](#AtomEnvironment+beep) * _static_ * _Event Subscription_ * [.onDidBeep(callback)](#AtomEnvironment.onDidBeep) ⇒ Disposable ### atomEnvironment.clipboard : [Clipboard](#Clipboard) **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.deserializers : DeserializerManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.views : ViewRegistry **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.notifications : NotificationManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.config : Config **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.keymaps : KeymapManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.tooltips : TooltipManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.commands : CommandRegistry **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.grammars : GrammarRegistry **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.styles : StyleManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.packages : PackageManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.themes : ThemeManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.menu : MenuManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.contextMenu : ContextMenuManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.project : Project **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.textEditors : TextEditorRegistry **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.workspace : Workspace **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.history : HistoryManager **Kind**: instance property of [AtomEnvironment](#AtomEnvironment) ### atomEnvironment.beep() Visually and audibly trigger a beep. **Kind**: instance method of [AtomEnvironment](#AtomEnvironment) **Category**: Messaging the User **Emits**: event:beep ### AtomEnvironment.onDidBeep(callback) ⇒ Disposable Invoke the given callback whenever [::beep](::beep) is called. **Kind**: static method of [AtomEnvironment](#AtomEnvironment) **Returns**: Disposable - on which `.dispose()` can be called to unsubscribe. **Category**: Event Subscription | Param | Type | Description | | --- | --- | --- | | callback | function | Function to be called whenever [::beep](::beep) is called. | ## Clipboard **Kind**: global class ### new Clipboard() Represents the clipboard used for copying and pasting in Pulsar. An instance of this class is always available as the `atom.clipboard` global. **Example** ```js // returns 'hello' atom.clipboard.write('hello'); console.log(atom.clipboard.read()); ``` ## Container A container capture. When another capture's node is contained by the definition capture's node, it gets added to this instance. **Kind**: global class ## CaptureOrganizer Keeps track of @definition.* captures and the captures they may contain. **Kind**: global class ## InvalidProviderError ⇐ Error An error thrown when a newly added symbol provider does not conform to its contract. **Kind**: global class **Extends**: Error ## ListController A class for setting various UI properties on a symbol list palette. This is a privilege given to the “main” (or _exclusive_) provider for a given task. This is how we allow a provider to communicate its state to the UI without giving it full control over the `SelectListView` used to show results. **Kind**: global class ## etch **Kind**: global constant **Jsx**: etch.dom ## css This file will manage the updating of `autocomplete-css` `completions.json`. We will mainly utilize `@webref/css`.listAll() function that returns a full CSS list of all properties seperated by their spec shortname. An example of this format is defined below for ease of future modifications. Some important notes about the data contained here: - Often times the `value` within the `property` will be in the following format: `` or even ` | value | value2` or just `value | value2` It will be important to build a parser that can handle this format. The `` then can be realized via that specs `values` where `values[x].name` will match the ``. Another important note about handling values here is that oftentimes `values[x].values[]` won't actually contain all possible values. And instead this must be handled by checking `values[x].value` which is another string of ` | value`. So this should be handled by the same parser. - Additionally an important note is that nowhere in this data do we get any kind of description about the data that could lend a hand in being documentation. So the documentation must be gathered seperatly. Likely the best way to collect our documentation data is via `mdn/content`. Within `content/files/en-us/web/css` is a directory of folders titled by the name of properties. The last important thing to note here: MDN doesn't have docs on everything. And that's a good thing. But it means many of our items don't have any kind of description. For this situation we have `manual-property-desc.json` which is a list of manually updated descriptions for properties where there are none. This was a last resort intended to provide the highest quality of completions possible. Overtime many items on this list will likely be able to be removed just as new ones are added. After running the update script you'll see a warning saying how many properties are without completions that would then need to be added to the JSON file. "spec-shortname": { "spec": { "title": "", "url": "" }, "properties": [ { "name": "", "value": "", "initial": "", "appliesTo": "", "percentages": "", "computedValue": "", "canonicalOrder": "", "animationType": "", "media": "", "styleDeclaration": [ "", "", "" ] } ], "atrules": [ { "name": "", "descriptors": [ { "name": "", "for": "", "value": "", "type": "" } ] } ], "selectors": [], "values": [ { "name": "", "type": "", "prose": "Optional description", "value": "", "values": [ { "name": "", "prose": "Optional Description", "type": "", "value": "" } ] } ], "warnings": [] } **Kind**: global constant ## chromiumElementsShim This file will manage the updating of `autocomplete-html` `completions.json` We will partially utilize `@webref/elements` `.listAll()` function that returns a full list of HTML Elements along with a defined `interface`. To use this `interface` in any meaningful way, we will utilize the dataset of Attributes that apply to each `interface` from Chromiums DevTools resource `https://github.com/ChromeDevTools/devtools-frontend`. Finally from here we will utilize `https://github.com/mdn/content` to parse the Markdown docs of MDN's website to retreive descriptions for each element. Now for a summary of our `completions.json` file we aim to generate. There are two top level elements, `tags` and `attributes`, both objects. Within `tags` we expect the following: "tags": { "a": { "attributes": [ "href", "hreflang", "media", "rel", "target", "type" ], "description": "....." } }; When an entry contains no `attributes` there is no empty array, the element simply doesn't exist. The `attributes` object contains keys of different elements that themselves are objects that can contain several valid keys. - global: Seems to be used exclusively for Global Attributes. Is a boolean which when false, the key does not appear. - type: A ?type? for the attribute. It's meaning is not immediately known. Nor a way to reliabley programatically collect it. Some discovered values: cssStyle: Exclusively used for `class` attribute boolean: Attributes that only accept `true` or `false` flag: For attributes that don't require or accept values. eg autoplay cssId: Exclusively used for the `id` attribute color: Exclusively used for the `bgcolor` attribute style: Exclusively used for the `style` attribute - description: A text description of the attribute - attribOption: A string array of valid values that can exist within the attribute. Such as the case with `rel` where only so many valid options exist. Although with our data sources mentioned above, we are able to collect nearly all the data needed. Except the `type` that is defined within our `completions.json` as well as the `attribOption` within our completions. Studying these closer reveals that all attributes listing with our `completions.json` do not appear elsewhere, and are nearly all global attributes. In this case since there is no sane way to collect this data, we will leave this list as a manually maintained section of our `completions.json`. This does mean that `curated-attributes.json` is a static document that will require manual updating in the future. Or most ideally, will find a way to automatically generate the needed data. **Kind**: global constant ## update This file aims to run some short simple tests against `update.js`. Focusing mainly on the Regex used within `sanitizeDescription()` **Kind**: global constant ## fs **Kind**: global constant **Babel**: ## dalek **Kind**: global constant **Babel**: ## assert **Kind**: global constant **Babel**: ## path **Kind**: global constant **Babel**: ## path **Kind**: global constant **Babel**: ## path **Kind**: global constant **Babel**: ## \_ **Kind**: global constant **Babel**: ## path **Kind**: global constant **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## conditionPromise() **Kind**: global function **Babel**: ## conditionPromise() **Kind**: global function **Babel**: ## destroy() **Kind**: global function **Describe**: Handles tear down of destructables and subscriptions. Does not handle release of memory. This method should only be called just before this object is freed, and should only tear down the main object components that are guarunteed to exist at all times. ## destroyChildren() **Kind**: global function **Describe**: Destroys this objects children (non-freeing), it's intended to be an ease-of use function for maintaing this object. This method should only tear down objects that are selectively allocated upon repository discovery. Example: this.diffs only exists when we have a repository. ## releaseChildren() **Kind**: global function **Describe**: The memory releasing complement function of `destroyChildren`. frees the memory allocated at all child object storage locations when there is no repository. ## subscribeToRepository() **Kind**: global function **Describe**: handles all subscriptions based on the repository in focus ## updateDiffs() **Kind**: global function **Describe**: Uses text markers in the target editor to visualize git modifications, additions, and deletions. The current algorithm just redraws the markers each call. ## beforeEach() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## isIterable(obj) ⇒ Boolean Ensures an object can be iterated over. The contract with the symbol providers is that they return an object that gives us symbol objects when we iterate over it. It'll probably be an array, but we're cool with anything iterable. **Kind**: global function **Returns**: Boolean - Whether the item will respond correctly to a `for..of` loop. | Param | Type | Description | | --- | --- | --- | | obj | ? | Anything. | ## timeout(ms) ⇒ Promise.<true> Returns a promise that resolves after a given number of milliseconds. **Kind**: global function **Returns**: Promise.<true> - A promise that resolves with `true` as its argument. | Param | Type | Description | | --- | --- | --- | | ms | Number | Number of milliseconds after which to resolve. | ## getBadgeTextVariant(text) ⇒ String Given a string of text, returns a hexadecimal character from `0` to `f` to represent a classification “bucket.” This is used when assigning colors to various symbol badges. **Kind**: global function **Returns**: String - A single character that represents a hexadecimal digit. | Param | Type | Description | | --- | --- | --- | | text | String | The text of the badge. | ## badge(text, options) ⇒ Element Return a DOM element for a badge for a given symbol tag name. **Kind**: global function **Returns**: Element - An element for adding to an `atom-select-view` entry. | Param | Type | Description | | --- | --- | --- | | text | String | The text of the tag. | | options | Object | Options. Defaults to an empty object. | | options.variant | Boolean | Whether to add a class name for the badge's “variant.” If enabled, this will attempt to assign a different badge color for each kind of tag. Optional; defaults to `false`. | ## beforeEach() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: ## conditionPromise() **Kind**: global function **Babel**: ## beforeEach() **Kind**: global function **Babel**: