diff --git a/types/atom-keymap/atom-keymap-tests.ts b/types/atom-keymap/atom-keymap-tests.ts index ad886ae22a..ac013b07eb 100644 --- a/types/atom-keymap/atom-keymap-tests.ts +++ b/types/atom-keymap/atom-keymap-tests.ts @@ -1,8 +1,9 @@ +import { Disposable } from "event-kit"; import KeymapManager = require("atom-keymap"); import * as ImportTest from "atom-keymap"; declare const element: HTMLElement; -declare let sub: EventKit.Disposable; +declare let sub: Disposable; declare const event: KeyboardEvent; // NPM Examples =============================================================== diff --git a/types/atom-keymap/index.d.ts b/types/atom-keymap/index.d.ts index 69dcf8de4e..1d67a20ba2 100644 --- a/types/atom-keymap/index.d.ts +++ b/types/atom-keymap/index.d.ts @@ -4,7 +4,7 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.2 -/// +import { Disposable } from "event-kit"; declare global { namespace AtomKeymap { @@ -156,27 +156,25 @@ declare global { * key binding. */ onDidMatchBinding(callback: (event: Events.FullKeybindingMatch) => void): - EventKit.Disposable; + Disposable; /** Invoke the given callback when one or more keystrokes partially match a binding. */ onDidPartiallyMatchBindings(callback: (event: Events.PartialKeybindingMatch) => - void): EventKit.Disposable; + void): Disposable; /** Invoke the given callback when one or more keystrokes fail to match any bindings. */ onDidFailToMatchBinding(callback: (event: Events.FailedKeybindingMatch) => - void): EventKit.Disposable; + void): Disposable; /** Invoke the given callback when a keymap file is reloaded. */ - onDidReloadKeymap(callback: (event: Events.KeymapLoaded) => void): - EventKit.Disposable; + onDidReloadKeymap(callback: (event: Events.KeymapLoaded) => void): Disposable; /** Invoke the given callback when a keymap file is unloaded. */ - onDidUnloadKeymap(callback: (event: Events.KeymapLoaded) => void): - EventKit.Disposable; + onDidUnloadKeymap(callback: (event: Events.KeymapLoaded) => void): Disposable; /** Invoke the given callback when a keymap file not able to be loaded. */ onDidFailToReadFile(callback: (error: Events.FailedKeymapFileRead) => void): - EventKit.Disposable; + Disposable; // Adding and Removing Bindings /** Construct KeyBindings from an object grouping them by CSS selector. */ @@ -185,7 +183,7 @@ declare global { /** Add sets of key bindings grouped by CSS selector. */ add(source: string, bindings: { [key: string]: { [key: string]: string }}, - priority?: number): EventKit.Disposable; + priority?: number): Disposable; // Accessing Bindings /** Get all current key bindings. */ @@ -221,7 +219,7 @@ declare global { /** Customize translation of raw keyboard events to keystroke strings. */ addKeystrokeResolver(resolver: (event: Events.AddedKeystrokeResolver) => string): - EventKit.Disposable; + Disposable; /** * Get the number of milliseconds allowed before pending states caused by diff --git a/types/event-kit/event-kit-tests.ts b/types/event-kit/event-kit-tests.ts index 9507290244..bad636aee2 100644 --- a/types/event-kit/event-kit-tests.ts +++ b/types/event-kit/event-kit-tests.ts @@ -1,13 +1,13 @@ import { Disposable, CompositeDisposable, Emitter } from "event-kit"; declare let bool: boolean; -declare let subscription: EventKit.Disposable; -declare let subscriptions: EventKit.CompositeDisposable; -declare let emitter: EventKit.Emitter; +declare let subscription: Disposable; +declare let subscriptions: CompositeDisposable; +declare let emitter: Emitter; // NPM Usage Tests ============================================================ class User { - private readonly emitter: EventKit.Emitter; + private readonly emitter: Emitter; name: string; constructor() { diff --git a/types/event-kit/index.d.ts b/types/event-kit/index.d.ts index 2a40b0468f..e08c980977 100644 --- a/types/event-kit/index.d.ts +++ b/types/event-kit/index.d.ts @@ -4,131 +4,104 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.2 -declare global { - namespace EventKit { - interface DisposableLike { - dispose(): void; - } - - /** A handle to a resource that can be disposed. */ - interface Disposable extends DisposableLike { - disposed: boolean; - - /** A callback which will be called within dispose(). */ - disposalAction?(): void; - - /** - * Perform the disposal action, indicating that the resource associated - * with this disposable is no longer needed. - */ - dispose(): void; - } - - interface DisposableStatic { - /** Ensure that Object correctly implements the Disposable contract. */ - isDisposable(object: object): boolean; - - /** Construct a Disposable. */ - new (disposableAction?: () => void): Disposable; - } - - /** - * An object that aggregates multiple Disposable instances together into a - * single disposable, so they can all be disposed as a group. - */ - interface CompositeDisposable extends DisposableLike { - disposed: boolean; - - /** - * Dispose all disposables added to this composite disposable. - * If this object has already been disposed, this method has no effect. - */ - dispose(): void; - - // Managing Disposables - /** - * Add disposables to be disposed when the composite is disposed. - * If this object has already been disposed, this method has no effect. - */ - add(...disposables: DisposableLike[]): void; - - /** Remove a previously added disposable. */ - remove(disposable: DisposableLike): void; - - /** Alias to CompositeDisposable::remove. */ - delete(disposable: DisposableLike): void; - - /** - * Clear all disposables. They will not be disposed by the next call to - * dispose. - */ - clear(): void; - } - - /** The static side to the CompositeDisposable class. */ - interface CompositeDisposableStatic { - /** Construct an instance, optionally with one or more disposables. */ - new (...disposables: DisposableLike[]): CompositeDisposable; - } - - /** - * Utility class to be used when implementing event-based APIs that allows - * for handlers registered via ::on to be invoked with calls to ::emit. - */ - interface Emitter extends DisposableLike { - disposed: boolean; - - /** Clear out any existing subscribers. */ - clear(): void; - - /** Unsubscribe all handlers. */ - dispose(): boolean; - - // Event Subscription - /** Registers a handler to be invoked whenever the given event is emitted. */ - // tslint:disable-next-line:no-any - on(eventName: string, handler: (value: any) => void): Disposable; - - /** - * Register the given handler function to be invoked the next time an event - * with the given name is emitted via ::emit. - */ - // tslint:disable-next-line:no-any - once(eventName: string, handler: (value: any) => void): Disposable; - - /** - * Register the given handler function to be invoked before all other - * handlers existing at the time of subscription whenever events by the - * given name are emitted via ::emit. - */ - // tslint:disable-next-line:no-any - preempt(eventName: string, handler: (value: any) => void): Disposable; - - // Event Emission - /** Invoke handlers registered via ::on for the given event name. */ - // tslint:disable-next-line:no-any - emit(eventName: string, value?: any): void; - } - - /** The static side to the Emitter class. */ - interface EmitterStatic { - /** Construct an emitter. */ - new (): Emitter; - } - } +export interface DisposableLike { + dispose(): void; } /** A handle to a resource that can be disposed. */ -export const Disposable: EventKit.DisposableStatic; +export class Disposable implements DisposableLike { + disposed: boolean; + + /** Ensure that Object correctly implements the Disposable contract. */ + static isDisposable(object: object): boolean; + + /** Construct a Disposable. */ + constructor(disposableAction?: () => void); + + /** A callback which will be called within dispose(). */ + disposalAction?: () => void; + + /** + * Perform the disposal action, indicating that the resource associated + * with this disposable is no longer needed. + */ + dispose(): void; +} /** * An object that aggregates multiple Disposable instances together into a * single disposable, so they can all be disposed as a group. */ -export const CompositeDisposable: EventKit.CompositeDisposableStatic; +export class CompositeDisposable implements DisposableLike { + disposed: boolean; + + /** Construct an instance, optionally with one or more disposables. */ + constructor(...disposables: DisposableLike[]); + + /** + * Dispose all disposables added to this composite disposable. + * If this object has already been disposed, this method has no effect. + */ + dispose(): void; + + // Managing Disposables + /** + * Add disposables to be disposed when the composite is disposed. + * If this object has already been disposed, this method has no effect. + */ + add(...disposables: DisposableLike[]): void; + + /** Remove a previously added disposable. */ + remove(disposable: DisposableLike): void; + + /** Alias to CompositeDisposable::remove. */ + delete(disposable: DisposableLike): void; + + /** + * Clear all disposables. They will not be disposed by the next call to + * dispose. + */ + clear(): void; +} /** * Utility class to be used when implementing event-based APIs that allows * for handlers registered via ::on to be invoked with calls to ::emit. */ -export const Emitter: EventKit.EmitterStatic; +export class Emitter implements DisposableLike { + disposed: boolean; + + /** Clear out any existing subscribers. */ + clear(): void; + + /** Unsubscribe all handlers. */ + dispose(): boolean; + + /** Construct an emitter. */ + constructor(); + + // Event Subscription + /** Registers a handler to be invoked whenever the given event is emitted. */ + // tslint:disable-next-line:no-any + on(eventName: string, handler: (value: any) => void): Disposable; + + /** + * Register the given handler function to be invoked the next time an event + * with the given name is emitted via ::emit. + */ + // tslint:disable-next-line:no-any + once(eventName: string, handler: (value: any) => void): Disposable; + + /** + * Register the given handler function to be invoked before all other + * handlers existing at the time of subscription whenever events by the + * given name are emitted via ::emit. + */ + // tslint:disable-next-line:no-any + preempt(eventName: string, handler: (value: any) => void): Disposable; + + // Event Emission + /** Invoke the handlers registered via ::on for the given event name. */ + // tslint:disable-next-line:no-any + emit(eventName: string, value?: any): void; +} diff --git a/types/first-mate/first-mate-tests.ts b/types/first-mate/first-mate-tests.ts index b348cd1758..3d3be512a1 100644 --- a/types/first-mate/first-mate-tests.ts +++ b/types/first-mate/first-mate-tests.ts @@ -1,8 +1,9 @@ +import { Disposable } from "event-kit"; import { GrammarRegistry, Grammar, ScopeSelector } from "first-mate"; -declare let subscription: EventKit.Disposable; -declare let grammar: FirstMate.Grammar; -declare let grammars: FirstMate.Grammar[]; +declare let subscription: Disposable; +declare let grammar: Grammar; +declare let grammars: Grammar[]; // NPM Examples =============================================================== const selector = new ScopeSelector("a | b"); diff --git a/types/first-mate/index.d.ts b/types/first-mate/index.d.ts index ca96e5814e..c7df2365c3 100644 --- a/types/first-mate/index.d.ts +++ b/types/first-mate/index.d.ts @@ -4,275 +4,249 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.2 -/// - -declare global { - /** TextMate helpers. */ - namespace FirstMate { - /** - * The option objects that the user is expected to fill out and provide to - * specific API calls. - */ - namespace Options { - interface Grammar { - name?: string; - fileTypes?: ReadonlyArray; - scopeName?: string; - foldingStopMarker?: string; - maxTokensPerLine?: number; - maxLineLength?: number; - - injections?: object; - injectionSelector?: ScopeSelector; - patterns?: ReadonlyArray; - repository?: object; - firstLineMatch?: boolean; - } - } - - /** The structures that are passed to the user by Atom following specific API calls. */ - namespace Structures { - interface GrammarToken { - value: string; - scopes: string[]; - } - - /** Result returned by `Grammar.tokenizeLine`. */ - interface TokenizeLineResult { - /** The string of text that was tokenized. */ - line: string; - - /** - * An array of integer scope ids and strings. Positive ids indicate the - * beginning of a scope, and negative tags indicate the end. To resolve ids - * to scope names, call GrammarRegistry::scopeForId with the absolute - * value of the id. - */ - tags: Array; - - /** - * This is a dynamic property. Invoking it will incur additional overhead, - * but will automatically translate the `tags` into token objects with `value` - * and `scopes` properties. - */ - tokens: GrammarToken[]; - - /** - * An array of rules representing the tokenized state at the end of the line. - * These should be passed back into this method when tokenizing the next line - * in the file. - */ - ruleStack: GrammarRule[]; - } - - interface GrammarRule { - // https://github.com/atom/first-mate/blob/v7.0.7/src/rule.coffee - // This is private. Don't go down the rabbit hole. - rule: object; - scopeName: string; - contentScopeName: string; - } - } - - /** Grammar that tokenizes lines of text. */ - interface Grammar { - name: string; - fileTypes: string[]; - scopeName: string; - maxTokensPerLine: number; - maxLineLength: number; - - // Event Subscription - onDidUpdate(callback: () => void): EventKit.Disposable; - - // Tokenizing - /** - * Tokenize all lines in the given text. - * @param text A string containing one or more lines. - * @return An array of token arrays for each line tokenized. - */ - tokenizeLines(text: string): Structures.GrammarToken[][]; - - /** - * Tokenizes the line of text. - * @param line A string of text to tokenize. - * @param ruleStack An optional array of rules previously returned from this - * method. This should be null when tokenizing the first line in the file. - * @param firstLine A optional boolean denoting whether this is the first line - * in the file which defaults to `false`. - * @return An object representing the result of the tokenize. - */ - tokenizeLine(line: string, ruleStack?: null, firstLine?: boolean): - Structures.TokenizeLineResult; - /** - * Tokenizes the line of text. - * @param line A string of text to tokenize. - * @param ruleStack An optional array of rules previously returned from this - * method. This should be null when tokenizing the first line in the file. - * @param firstLine A optional boolean denoting whether this is the first line - * in the file which defaults to `false`. - * @return An object representing the result of the tokenize. - */ - tokenizeLine(line: string, ruleStack: Structures.GrammarRule[], firstLine?: false): - Structures.TokenizeLineResult; - } - - /** The static side to the Grammar class. */ - interface GrammarStatic { - new (registry: GrammarRegistry, options?: Options.Grammar): Grammar; - } - - /** Instance side of GrammarRegistry class. */ - interface GrammarRegistry { - maxTokensPerLine: number; - maxLineLength: number; - - // Event Subscription - /** - * Invoke the given callback when a grammar is added to the registry. - * @param callback The callback to be invoked whenever a grammar is added. - * @return A Disposable on which `.dispose()` can be called to unsubscribe. - */ - onDidAddGrammar(callback: (grammar: Grammar) => void): EventKit.Disposable; - - /** - * Invoke the given callback when a grammar is updated due to a grammar it - * depends on being added or removed from the registry. - * @param callback The callback to be invoked whenever a grammar is updated. - * @return A Disposable on which `.dispose()` can be called to unsubscribe. - */ - onDidUpdateGrammar(callback: (grammar: Grammar) => void): EventKit.Disposable; - - // Managing Grammars - /** - * Get all the grammars in this registry. - * @return A non-empty array of Grammar instances. - */ - getGrammars(): Grammar[]; - - /** - * Get a grammar with the given scope name. - * @param scopeName A string such as `source.js`. - * @return A Grammar or undefined. - */ - grammarForScopeName(scopeName: string): Grammar|undefined; - - /** - * Add a grammar to this registry. - * A 'grammar-added' event is emitted after the grammar is added. - * @param grammar The Grammar to add. This should be a value previously returned - * from ::readGrammar or ::readGrammarSync. - * @return Returns a Disposable on which `.dispose()` can be called to remove - * the grammar. - */ - addGrammar(grammar: Grammar): EventKit.Disposable; - - /** - * Remove the given grammar from this registry. - * @param grammar The grammar to remove. This should be a grammar previously - * added to the registry from ::addGrammar. - */ - removeGrammar(grammar: Grammar): void; - - /** - * Remove the grammar with the given scope name. - * @param scopeName A string such as `source.js`. - * @return Returns the removed Grammar or undefined. - */ - removeGrammarForScopeName(scopeName: string): Grammar|undefined; - - /** - * Read a grammar synchronously but don't add it to the registry. - * @param grammarPath The absolute file path to a grammar. - * @return The newly loaded Grammar. - */ - readGrammarSync(grammarPath: string): Grammar; - - /** - * Read a grammar asynchronously but don't add it to the registry. - * @param grammarPath The absolute file path to the grammar. - * @param callback The function to be invoked once the Grammar has been read in. - */ - readGrammar(grammarPath: string, callback: (error: Error|null, grammar?: Grammar) => - void): void; - - /** - * Read a grammar synchronously and add it to this registry. - * @param grammarPath The absolute file path to the grammar. - * @return The newly loaded Grammar. - */ - loadGrammarSync(grammarPath: string): Grammar; - - /** - * Read a grammar asynchronously and add it to the registry. - * @param grammarPath The absolute file path to the grammar. - * @param callback The function to be invoked once the Grammar has been read in - * and added to the registry. - */ - loadGrammar(grammarPath: string, callback: (error: Error|null, grammar?: Grammar) => - void): void; - - /** - * Convert compact tags representation into convenient, space-inefficient tokens. - * @param lineText The text of the tokenized line. - * @param tags The tags returned from a call to Grammar::tokenizeLine(). - * @return An array of Token instances decoded from the given tags. - */ - decodeTokens(lineText: string, tags: Array): Structures.GrammarToken[]; - } - - /** The static side to the GrammarRegistry class. */ - interface GrammarRegistryStatic { - new (options?: { maxTokensPerLine?: number, maxLineLength?: number }): - GrammarRegistry; - } - - interface ScopeSelector { - /** - * Check if this scope selector matches the scopes. - * @param scopes A single scope or an array of them to be compared against. - * @return A boolean indicating whether or not this ScopeSelector matched. - */ - matches(scopes: string|ReadonlyArray): boolean; - - /** - * Gets the prefix of this scope selector. - * @param scopes The scopes to match a prefix against. - * @return The matching prefix, if there is one. - */ - getPrefix(scopes: string|ReadonlyArray): string|undefined; - - /** - * Convert this TextMate scope selector to a CSS selector. - * @return A string with the CSSSelector representation of this ScopeSelector. - */ - toCssSelector(): string; - - /** - * Convert this TextMate scope selector to a CSS selector, prefixing scopes - * with `syntax--`. - * @return A string with the syntax-specific CSSSelector representation of this - * ScopeSelector. - */ - toCssSyntaxSelector(): string; - } - - /** The static side to the ScopeSelector class. */ - interface ScopeSelectorStatic { - /** - * Create a new scope selector. - * @param source The string to parse as a scope selector. - * @return A newly constructed ScopeSelector. - */ - new (source: string): ScopeSelector; - } - } -} - -/** Registry containing one or more grammars. */ -export const GrammarRegistry: FirstMate.GrammarRegistryStatic; - -export const ScopeSelector: FirstMate.ScopeSelectorStatic; +import { Disposable } from "event-kit"; /** Grammar that tokenizes lines of text. */ -export const Grammar: FirstMate.GrammarStatic; +export class Grammar { + name: string; + fileTypes: string[]; + scopeName: string; + maxTokensPerLine: number; + maxLineLength: number; + + constructor(registry: GrammarRegistry, options?: GrammarOptions); + + // Event Subscription + onDidUpdate(callback: () => void): Disposable; + + // Tokenizing + /** + * Tokenize all lines in the given text. + * @param text A string containing one or more lines. + * @return An array of token arrays for each line tokenized. + */ + tokenizeLines(text: string): GrammarToken[][]; + + /** + * Tokenizes the line of text. + * @param line A string of text to tokenize. + * @param ruleStack An optional array of rules previously returned from this + * method. This should be null when tokenizing the first line in the file. + * @param firstLine A optional boolean denoting whether this is the first line + * in the file which defaults to `false`. + * @return An object representing the result of the tokenize. + */ + tokenizeLine(line: string, ruleStack?: null, firstLine?: boolean): TokenizeLineResult; + /** + * Tokenizes the line of text. + * @param line A string of text to tokenize. + * @param ruleStack An optional array of rules previously returned from this + * method. This should be null when tokenizing the first line in the file. + * @param firstLine A optional boolean denoting whether this is the first line + * in the file which defaults to `false`. + * @return An object representing the result of the tokenize. + */ + tokenizeLine(line: string, ruleStack: GrammarRule[], firstLine?: false): + TokenizeLineResult; +} + +/** Instance side of GrammarRegistry class. */ +export class GrammarRegistry { + maxTokensPerLine: number; + maxLineLength: number; + + constructor(options?: { maxTokensPerLine?: number, maxLineLength?: number }); + + // Event Subscription + /** + * Invoke the given callback when a grammar is added to the registry. + * @param callback The callback to be invoked whenever a grammar is added. + * @return A Disposable on which `.dispose()` can be called to unsubscribe. + */ + onDidAddGrammar(callback: (grammar: Grammar) => void): Disposable; + + /** + * Invoke the given callback when a grammar is updated due to a grammar it + * depends on being added or removed from the registry. + * @param callback The callback to be invoked whenever a grammar is updated. + * @return A Disposable on which `.dispose()` can be called to unsubscribe. + */ + onDidUpdateGrammar(callback: (grammar: Grammar) => void): Disposable; + + // Managing Grammars + /** + * Get all the grammars in this registry. + * @return A non-empty array of Grammar instances. + */ + getGrammars(): Grammar[]; + + /** + * Get a grammar with the given scope name. + * @param scopeName A string such as `source.js`. + * @return A Grammar or undefined. + */ + grammarForScopeName(scopeName: string): Grammar|undefined; + + /** + * Add a grammar to this registry. + * A 'grammar-added' event is emitted after the grammar is added. + * @param grammar The Grammar to add. This should be a value previously returned + * from ::readGrammar or ::readGrammarSync. + * @return Returns a Disposable on which `.dispose()` can be called to remove + * the grammar. + */ + addGrammar(grammar: Grammar): Disposable; + + /** + * Remove the given grammar from this registry. + * @param grammar The grammar to remove. This should be a grammar previously + * added to the registry from ::addGrammar. + */ + removeGrammar(grammar: Grammar): void; + + /** + * Remove the grammar with the given scope name. + * @param scopeName A string such as `source.js`. + * @return Returns the removed Grammar or undefined. + */ + removeGrammarForScopeName(scopeName: string): Grammar|undefined; + + /** + * Read a grammar synchronously but don't add it to the registry. + * @param grammarPath The absolute file path to a grammar. + * @return The newly loaded Grammar. + */ + readGrammarSync(grammarPath: string): Grammar; + + /** + * Read a grammar asynchronously but don't add it to the registry. + * @param grammarPath The absolute file path to the grammar. + * @param callback The function to be invoked once the Grammar has been read in. + */ + readGrammar(grammarPath: string, callback: (error: Error|null, grammar?: Grammar) => + void): void; + + /** + * Read a grammar synchronously and add it to this registry. + * @param grammarPath The absolute file path to the grammar. + * @return The newly loaded Grammar. + */ + loadGrammarSync(grammarPath: string): Grammar; + + /** + * Read a grammar asynchronously and add it to the registry. + * @param grammarPath The absolute file path to the grammar. + * @param callback The function to be invoked once the Grammar has been read in + * and added to the registry. + */ + loadGrammar(grammarPath: string, callback: (error: Error|null, grammar?: Grammar) => + void): void; + + /** + * Convert compact tags representation into convenient, space-inefficient tokens. + * @param lineText The text of the tokenized line. + * @param tags The tags returned from a call to Grammar::tokenizeLine(). + * @return An array of Token instances decoded from the given tags. + */ + decodeTokens(lineText: string, tags: Array): GrammarToken[]; +} + +export class ScopeSelector { + /** + * Create a new scope selector. + * @param source The string to parse as a scope selector. + * @return A newly constructed ScopeSelector. + */ + constructor(source: string); + + /** + * Check if this scope selector matches the scopes. + * @param scopes A single scope or an array of them to be compared against. + * @return A boolean indicating whether or not this ScopeSelector matched. + */ + matches(scopes: string|ReadonlyArray): boolean; + + /** + * Gets the prefix of this scope selector. + * @param scopes The scopes to match a prefix against. + * @return The matching prefix, if there is one. + */ + getPrefix(scopes: string|ReadonlyArray): string|undefined; + + /** + * Convert this TextMate scope selector to a CSS selector. + * @return A string with the CSSSelector representation of this ScopeSelector. + */ + toCssSelector(): string; + + /** + * Convert this TextMate scope selector to a CSS selector, prefixing scopes + * with `syntax--`. + * @return A string with the syntax-specific CSSSelector representation of this + * ScopeSelector. + */ + toCssSyntaxSelector(): string; +} + +// Options ==================================================================== +// The option objects that the user is expected to fill out and provide to +// specific API calls. + +export interface GrammarOptions { + name?: string; + fileTypes?: ReadonlyArray; + scopeName?: string; + foldingStopMarker?: string; + maxTokensPerLine?: number; + maxLineLength?: number; + + injections?: object; + injectionSelector?: ScopeSelector; + patterns?: ReadonlyArray; + repository?: object; + firstLineMatch?: boolean; +} + +// Structures ================================================================= +// The structures that are passed to the user by Atom following specific API calls. + +export interface GrammarToken { + value: string; + scopes: string[]; +} + +/** Result returned by `Grammar.tokenizeLine`. */ +export interface TokenizeLineResult { + /** The string of text that was tokenized. */ + line: string; + + /** + * An array of integer scope ids and strings. Positive ids indicate the + * beginning of a scope, and negative tags indicate the end. To resolve ids + * to scope names, call GrammarRegistry::scopeForId with the absolute + * value of the id. + */ + tags: Array; + + /** + * This is a dynamic property. Invoking it will incur additional overhead, + * but will automatically translate the `tags` into token objects with `value` + * and `scopes` properties. + */ + tokens: GrammarToken[]; + + /** + * An array of rules representing the tokenized state at the end of the line. + * These should be passed back into this method when tokenizing the next line + * in the file. + */ + ruleStack: GrammarRule[]; +} + +export interface GrammarRule { + // https://github.com/atom/first-mate/blob/v7.0.7/src/rule.coffee + // This is private. Don't go down the rabbit hole. + rule: object; + scopeName: string; + contentScopeName: string; +} diff --git a/types/pathwatcher/index.d.ts b/types/pathwatcher/index.d.ts index 6775d1f7cd..0ff5427913 100644 --- a/types/pathwatcher/index.d.ts +++ b/types/pathwatcher/index.d.ts @@ -5,250 +5,237 @@ // TypeScript Version: 2.2 /// -/// +import { Disposable } from "event-kit"; import { ReadStream, WriteStream } from "fs"; -declare global { - namespace PathWatcher { - /** - * The event objects that are passed into the callbacks which the user provides to - * specific API calls. - */ - namespace Events { - interface PathWatchErrorThrown { - /** The error object. */ - error: Error; - - /** - * Call this function to indicate you have handled the error. - * The error will not be thrown if this function is called. - */ - handle(): void; - } - - interface WatchedFilePathChangedEvent { - event: string; - newFilePath: string; - } - } - - /** Represents an individual file that can be watched, read from, and written to. */ - interface File { - // Properties - realPath: string|null; - path: string; - symlink: boolean; - - // Construction - /** - * Creates the file on disk that corresponds to ::getPath() if no such file - * already exists. - */ - create(): Promise; - - // Event Subscription - /** Invoke the given callback when the file's contents change. */ - onDidChange(callback: () => void): EventKit.Disposable; - - /** Invoke the given callback when the file's path changes. */ - onDidRename(callback: () => void): EventKit.Disposable; - - /** Invoke the given callback when the file is deleted. */ - onDidDelete(callback: () => void): EventKit.Disposable; - - /** - * Invoke the given callback when there is an error with the watch. When - * your callback has been invoked, the file will have unsubscribed from the - * file watches. - */ - onWillThrowWatchError(callback: (errorObject: Events.PathWatchErrorThrown) => - void): EventKit.Disposable; - - // File Metadata - /** Returns a boolean, always true. */ - isFile(): boolean; - - /** Returns a boolean, always false. */ - isDirectory(): boolean; - - /** Returns a boolean indicating whether or not this is a symbolic link. */ - isSymbolicLink(): boolean; - - /** - * Returns a promise that resolves to a boolean, true if the file exists, - * false otherwise. - */ - exists(): Promise; - - /** Returns a boolean, true if the file exists, false otherwise. */ - existsSync(): boolean; - - /** Get the SHA-1 digest of this file. */ - getDigest(): Promise; - - /** Get the SHA-1 digest of this file. */ - getDigestSync(): string; - - /** Sets the file's character set encoding name. */ - setEncoding(encoding: string): void; - - /** Returns the string encoding name for this file (default: "utf8"). */ - getEncoding(): string; - - // Managing Paths - /** Returns the string path for the file. */ - getPath(): string; - - /** Returns this file's completely resolved string path. */ - getRealPathSync(): string; - - /** - * Returns a promise that resolves to the file's completely resolved - * string path. - */ - getRealPath(): Promise; - - /** Return the string filename without any directory information. */ - getBaseName(): string; - - // Traversing - /** Return the Directory that contains this file. */ - getParent(): Directory; - - // Reading and Writing - /** Reads the contents of the file. */ - read(flushCache?: boolean): Promise; - - /** Returns a stream to read the content of the file. */ - createReadStream(): ReadStream; - - /** Overwrites the file with the given text. */ - write(text: string): Promise; - - /** Returns a stream to write content to the file. */ - createWriteStream(): WriteStream; - - /** Overwrites the file with the given text. */ - writeSync(text: string): undefined; - } - - /** The static side to the File class. */ - interface FileStatic { - /** Configures a new File instance, no files are accessed. */ - new (filePath: string, symlink?: boolean): File; - } - - /** Represents a directory on disk that can be watched for changes. */ - interface Directory { - // Properties - realPath: string|null; - path: string; - symlink: boolean; - - // Construction - /** - * Creates the directory on disk that corresponds to ::getPath() if no such - * directory already exists. - */ - create(mode?: number): Promise; - - // Event Subscription - /** Invoke the given callback when the directory's contents change. */ - onDidChange(callback: () => void): EventKit.Disposable; - - // Directory Metadata - /** Returns a boolean, always false. */ - isFile(): boolean; - - /** Returns a roolean, always true. */ - isDirectory(): boolean; - - /** Returns a boolean indicating whether or not this is a symbolic link. */ - isSymbolicLink(): boolean; - - /** - * Returns a promise that resolves to a boolean, true if the directory - * exists, false otherwise. - */ - exists(): Promise; - - /** Returns a boolean, true if the directory exists, false otherwise. */ - existsSync(): boolean; - - /** - * Return a boolean, true if this Directory is the root directory of the - * filesystem, or false if it isn't. - */ - isRoot(): boolean; - - // Managing Paths - /** - * This may include unfollowed symlinks or relative directory entries. - * Or it may be fully resolved, it depends on what you give it. - */ - getPath(): string; - - /** - * All relative directory entries are removed and symlinks are resolved to - * their final destination. - */ - getRealPathSync(): string; - - /** Returns the string basename of the directory. */ - getBaseName(): string; - - /** Returns the relative string path to the given path from this directory. */ - relativize(fullPath: string): string; - - // Traversing - /** Traverse to the parent directory. */ - getParent(): Directory; - - /** - * Traverse within this Directory to a child File. This method doesn't actually - * check to see if the File exists, it just creates the File object. - */ - getFile(filename: string): File; - - /** - * Traverse within this a Directory to a child Directory. This method doesn't actually - * check to see if the Directory exists, it just creates the Directory object. - */ - getSubdirectory(dirname: string): Directory; - - /** Reads file entries in this directory from disk synchronously. */ - getEntriesSync(): Array; - - /** Reads file entries in this directory from disk asynchronously. */ - getEntries(callback: (error: Error, entries: Array) => void): void; - - /** - * Determines if the given path (real or symbolic) is inside this directory. This - * method does not actually check if the path exists, it just checks if the path - * is under this directory. - */ - contains(pathToCheck: string): boolean; - } - - /** The static side to the Directory class. */ - interface DirectoryStatic { - /** Configures a new Directory instance, no files are accessed. */ - new (directoryPath: string, symlink?: boolean): Directory; - } - - interface PathWatcher { - onDidChange(callback: (change: Events.WatchedFilePathChangedEvent) => void): - EventKit.Disposable; - - close(): void; - } - } -} - -export let File: PathWatcher.FileStatic; -export let Directory: PathWatcher.DirectoryStatic; - -export function watch(): PathWatcher.PathWatcher; +export function watch(): PathWatcher; export function closeAllWatchers(): void; export function getWatchedPaths(): string[]; + +/** Represents an individual file that can be watched, read from, and written to. */ +export class File { + // Properties + realPath: string|null; + path: string; + symlink: boolean; + + // Construction + /** Configures a new File instance, no files are accessed. */ + constructor(filePath: string, symlink?: boolean); + + /** + * Creates the file on disk that corresponds to ::getPath() if no such file + * already exists. + */ + create(): Promise; + + // Event Subscription + /** Invoke the given callback when the file's contents change. */ + onDidChange(callback: () => void): Disposable; + + /** Invoke the given callback when the file's path changes. */ + onDidRename(callback: () => void): Disposable; + + /** Invoke the given callback when the file is deleted. */ + onDidDelete(callback: () => void): Disposable; + + /** + * Invoke the given callback when there is an error with the watch. When + * your callback has been invoked, the file will have unsubscribed from the + * file watches. + */ + onWillThrowWatchError(callback: (errorObject: PathWatchErrorThrownEvent) => + void): Disposable; + + // File Metadata + /** Returns a boolean, always true. */ + isFile(): boolean; + + /** Returns a boolean, always false. */ + isDirectory(): boolean; + + /** Returns a boolean indicating whether or not this is a symbolic link. */ + isSymbolicLink(): boolean; + + /** + * Returns a promise that resolves to a boolean, true if the file exists, + * false otherwise. + */ + exists(): Promise; + + /** Returns a boolean, true if the file exists, false otherwise. */ + existsSync(): boolean; + + /** Get the SHA-1 digest of this file. */ + getDigest(): Promise; + + /** Get the SHA-1 digest of this file. */ + getDigestSync(): string; + + /** Sets the file's character set encoding name. */ + setEncoding(encoding: string): void; + + /** Returns the string encoding name for this file (default: "utf8"). */ + getEncoding(): string; + + // Managing Paths + /** Returns the string path for the file. */ + getPath(): string; + + /** Returns this file's completely resolved string path. */ + getRealPathSync(): string; + + /** + * Returns a promise that resolves to the file's completely resolved + * string path. + */ + getRealPath(): Promise; + + /** Return the string filename without any directory information. */ + getBaseName(): string; + + // Traversing + /** Return the Directory that contains this file. */ + getParent(): Directory; + + // Reading and Writing + /** Reads the contents of the file. */ + read(flushCache?: boolean): Promise; + + /** Returns a stream to read the content of the file. */ + createReadStream(): ReadStream; + + /** Overwrites the file with the given text. */ + write(text: string): Promise; + + /** Returns a stream to write content to the file. */ + createWriteStream(): WriteStream; + + /** Overwrites the file with the given text. */ + writeSync(text: string): undefined; +} + +/** Represents a directory on disk that can be watched for changes. */ +export class Directory { + // Properties + realPath: string|null; + path: string; + symlink: boolean; + + // Construction + /** Configures a new Directory instance, no files are accessed. */ + constructor(directoryPath: string, symlink?: boolean); + + /** + * Creates the directory on disk that corresponds to ::getPath() if no such + * directory already exists. + */ + create(mode?: number): Promise; + + // Event Subscription + /** Invoke the given callback when the directory's contents change. */ + onDidChange(callback: () => void): Disposable; + + // Directory Metadata + /** Returns a boolean, always false. */ + isFile(): boolean; + + /** Returns a roolean, always true. */ + isDirectory(): boolean; + + /** Returns a boolean indicating whether or not this is a symbolic link. */ + isSymbolicLink(): boolean; + + /** + * Returns a promise that resolves to a boolean, true if the directory + * exists, false otherwise. + */ + exists(): Promise; + + /** Returns a boolean, true if the directory exists, false otherwise. */ + existsSync(): boolean; + + /** + * Return a boolean, true if this Directory is the root directory of the + * filesystem, or false if it isn't. + */ + isRoot(): boolean; + + // Managing Paths + /** + * This may include unfollowed symlinks or relative directory entries. + * Or it may be fully resolved, it depends on what you give it. + */ + getPath(): string; + + /** + * All relative directory entries are removed and symlinks are resolved to + * their final destination. + */ + getRealPathSync(): string; + + /** Returns the string basename of the directory. */ + getBaseName(): string; + + /** Returns the relative string path to the given path from this directory. */ + relativize(fullPath: string): string; + + // Traversing + /** Traverse to the parent directory. */ + getParent(): Directory; + + /** + * Traverse within this Directory to a child File. This method doesn't actually + * check to see if the File exists, it just creates the File object. + */ + getFile(filename: string): File; + + /** + * Traverse within this a Directory to a child Directory. This method doesn't actually + * check to see if the Directory exists, it just creates the Directory object. + */ + getSubdirectory(dirname: string): Directory; + + /** Reads file entries in this directory from disk synchronously. */ + getEntriesSync(): Array; + + /** Reads file entries in this directory from disk asynchronously. */ + getEntries(callback: (error: Error, entries: Array) => void): void; + + /** + * Determines if the given path (real or symbolic) is inside this directory. This + * method does not actually check if the path exists, it just checks if the path + * is under this directory. + */ + contains(pathToCheck: string): boolean; +} + +// Events ===================================================================== +// The event objects that are passed into the callbacks which the user provides +// to specific API calls. + +export interface PathWatchErrorThrownEvent { + /** The error object. */ + error: Error; + + /** + * Call this function to indicate you have handled the error. + * The error will not be thrown if this function is called. + */ + handle(): void; +} + +export interface WatchedFilePathChangedEvent { + event: string; + newFilePath: string; +} + +// Structures ================================================================= +// The structures that are passed to the user by Atom following specific API calls. + +export interface PathWatcher { + onDidChange(callback: (change: WatchedFilePathChangedEvent) => void): Disposable; + + close(): void; +} diff --git a/types/pathwatcher/pathwatcher-tests.ts b/types/pathwatcher/pathwatcher-tests.ts index 20f3d797a3..55cba4ac33 100644 --- a/types/pathwatcher/pathwatcher-tests.ts +++ b/types/pathwatcher/pathwatcher-tests.ts @@ -1,11 +1,12 @@ +import { Disposable } from "event-kit"; import { File, Directory } from "pathwatcher"; let bool: boolean; let str: string; -let sub: EventKit.Disposable; +let sub: Disposable; -let file: PathWatcher.File; -let dir: PathWatcher.Directory; +let file: File; +let dir: Directory; // File ======================================================================= // Construction diff --git a/types/text-buffer/text-buffer-tests.ts b/types/text-buffer/text-buffer-tests.ts index 593bd0e2e2..c21c1a0ef5 100644 --- a/types/text-buffer/text-buffer-tests.ts +++ b/types/text-buffer/text-buffer-tests.ts @@ -1,3 +1,4 @@ +import { Disposable } from "event-kit"; import TextBuffer = require("text-buffer"); declare let obj: object; @@ -14,7 +15,7 @@ declare let displayMarkerLayer: TextBuffer.DisplayMarkerLayer; declare let marker: TextBuffer.Marker; declare let markers: TextBuffer.Marker[]; declare let markerLayer: TextBuffer.MarkerLayer; -declare let sub: EventKit.Disposable; +declare let sub: Disposable; // Point ====================================================================== let point = new TextBuffer.Point(42, 42);