30 KiB
Classes
- AtomEnvironment
Pulsar global for dealing with packages, themes, menus, and the window.
An instance of this class is always available as the
atom
global.- Clipboard
- Container
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 theproperty
will be in the following format:<valueGroupName>
or even<valueGroupName> | value | value2
or justvalue | value2
It will be important to build a parser that can handle this format. The<valueGroupName>
then can be realized via that specsvalues
wherevalues[x].name
will match the<valueGroupName>
. Another important note about handling values here is that oftentimesvalues[x].values[]
won't actually contain all possible values. And instead this must be handled by checkingvalues[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 viamdn/content
. Withincontent/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 definedinterface
. To use thisinterface
in any meaningful way, we will utilize the dataset of Attributes that apply to eachinterface
from Chromiums DevTools resourcehttps://github.com/ChromeDevTools/devtools-frontend
. Finally from here we will utilizehttps://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
andattributes
, both objects. Withintags
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 accepttrue
orfalse
flag: For attributes that don't require or accept values. eg autoplay cssId: Exclusively used for theid
attribute color: Exclusively used for thebgcolor
attribute style: Exclusively used for thestyle
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 ourcompletions.json
as well as theattribOption
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 thatcurated-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 withinsanitizeDescription()
- fs
- dalek
- assert
- path
- path
- path
- _
- path
Functions
- renderMarkdown(content, givenOpts) ⇒
string
Takes a Markdown document and renders it as HTML.
- beforeEach()
- beforeEach()
- conditionPromise()
- conditionPromise()
- destroy()
- destroyChildren()
- releaseChildren()
- subscribeToRepository()
- updateDiffs()
- beforeEach()
- beforeEach()
- beforeEach()
- 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
tof
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()
- beforeEach()
- 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
- instance
- .clipboard :
Clipboard
- .deserializers :
DeserializerManager
- .views :
ViewRegistry
- .notifications :
NotificationManager
- .config :
Config
- .keymaps :
KeymapManager
- .tooltips :
TooltipManager
- .commands :
CommandRegistry
- .grammars :
GrammarRegistry
- .styles :
StyleManager
- .packages :
PackageManager
- .themes :
ThemeManager
- .menu :
MenuManager
- .contextMenu :
ContextMenuManager
- .project :
Project
- .textEditors :
TextEditorRegistry
- .workspace :
Workspace
- .history :
HistoryManager
- Messaging the User
- .clipboard :
- static
- .preloadPackages ℗
- Event Subscription
- .onDidBeep(callback) ⇒
Disposable
- .onDidBeep(callback) ⇒
- instance
atomEnvironment.clipboard : Clipboard
Kind: instance property of AtomEnvironment
atomEnvironment.deserializers : DeserializerManager
Kind: instance property of AtomEnvironment
atomEnvironment.views : ViewRegistry
Kind: instance property of AtomEnvironment
atomEnvironment.notifications : NotificationManager
Kind: instance property of AtomEnvironment
atomEnvironment.config : Config
Kind: instance property of AtomEnvironment
atomEnvironment.keymaps : KeymapManager
Kind: instance property of AtomEnvironment
atomEnvironment.tooltips : TooltipManager
Kind: instance property of AtomEnvironment
atomEnvironment.commands : CommandRegistry
Kind: instance property of AtomEnvironment
atomEnvironment.grammars : GrammarRegistry
Kind: instance property of AtomEnvironment
atomEnvironment.styles : StyleManager
Kind: instance property of AtomEnvironment
atomEnvironment.packages : PackageManager
Kind: instance property of AtomEnvironment
atomEnvironment.themes : ThemeManager
Kind: instance property of AtomEnvironment
atomEnvironment.menu : MenuManager
Kind: instance property of AtomEnvironment
atomEnvironment.contextMenu : ContextMenuManager
Kind: instance property of AtomEnvironment
atomEnvironment.project : Project
Kind: instance property of AtomEnvironment
atomEnvironment.textEditors : TextEditorRegistry
Kind: instance property of AtomEnvironment
atomEnvironment.workspace : Workspace
Kind: instance property of AtomEnvironment
atomEnvironment.history : HistoryManager
Kind: instance property of AtomEnvironment
atomEnvironment.beep()
Visually and audibly trigger a beep.
Kind: instance method of AtomEnvironment
Category: Messaging the User
Emits: event:beep
AtomEnvironment.preloadPackages ℗
Returns output of preloadPackages()
for this Classes Instance of Packages
.
Kind: static property of AtomEnvironment
Access: private
AtomEnvironment.onDidBeep(callback) ⇒ Disposable
Invoke the given callback whenever ::beep is called.
Kind: static method of 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 is called. |
Clipboard
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
// 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.
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.
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.
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:
<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 accepttrue
orfalse
flag: For attributes that don't require or accept values. eg autoplay cssId: Exclusively used for theid
attribute color: Exclusively used for thebgcolor
attribute style: Exclusively used for thestyle
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()
fs
dalek
assert
path
path
path
_
path
beforeEach()
beforeEach()
conditionPromise()
conditionPromise()
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()
beforeEach()
beforeEach()
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.
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()
beforeEach()
beforeEach()
conditionPromise()
beforeEach()
Kind: global function
Babel: