UNPKG

5.99 kBTypeScriptView Raw
1import { Disposable, Grammar, GrammarToken, TextBuffer } from "../index";
2
3/** Registry containing one or more grammars. */
4export interface GrammarRegistry {
5 // Event Subscription
6 /**
7 * Invoke the given callback when a grammar is added to the registry.
8 * @param callback The callback to be invoked whenever a grammar is added.
9 * @return A Disposable on which `.dispose()` can be called to unsubscribe.
10 */
11 onDidAddGrammar(callback: (grammar: Grammar) => void): Disposable;
12
13 /**
14 * Invoke the given callback when a grammar is updated due to a grammar it
15 * depends on being added or removed from the registry.
16 * @param callback The callback to be invoked whenever a grammar is updated.
17 * @return A Disposable on which `.dispose()` can be called to unsubscribe.
18 */
19 onDidUpdateGrammar(callback: (grammar: Grammar) => void): Disposable;
20
21 /**
22 * Invoke the given callback when a grammar is removed from the registry.
23 * @param callback The callback to be invoked whenever a grammar is removed.
24 * @return A Disposable on which `.dispose()` can be called to unsubscribe.
25 */
26 onDidRemoveGrammar(callback: (grammar: Grammar) => void): Disposable;
27
28 // Managing Grammars
29 /**
30 * Get all the grammars in this registry.
31 * @return A non-empty array of Grammar instances.
32 */
33 getGrammars(): Grammar[];
34
35 /**
36 * Get a grammar with the given scope name.
37 * @param scopeName A string such as `source.js`.
38 * @return A Grammar or undefined.
39 */
40 grammarForScopeName(scopeName: string): Grammar | undefined;
41
42 /**
43 * Add a grammar to this registry.
44 * A 'grammar-added' event is emitted after the grammar is added.
45 * @param grammar The Grammar to add. This should be a value previously returned
46 * from ::readGrammar or ::readGrammarSync.
47 * @return Returns a Disposable on which `.dispose()` can be called to remove
48 * the grammar.
49 */
50 addGrammar(grammar: Grammar): Disposable;
51
52 /**
53 * Remove the given grammar from this registry.
54 * @param grammar The grammar to remove. This should be a grammar previously
55 * added to the registry from ::addGrammar.
56 */
57 removeGrammar(grammar: Grammar): void;
58
59 /**
60 * Remove the grammar with the given scope name.
61 * @param scopeName A string such as `source.js`.
62 * @return Returns the removed Grammar or undefined.
63 */
64 removeGrammarForScopeName(scopeName: string): Grammar | undefined;
65
66 /**
67 * Read a grammar synchronously but don't add it to the registry.
68 * @param grammarPath The absolute file path to a grammar.
69 * @return The newly loaded Grammar.
70 */
71 readGrammarSync(grammarPath: string): Grammar;
72
73 /**
74 * Read a grammar asynchronously but don't add it to the registry.
75 * @param grammarPath The absolute file path to the grammar.
76 * @param callback The function to be invoked once the Grammar has been read in.
77 */
78 readGrammar(grammarPath: string, callback: (error: Error | null, grammar?: Grammar) => void): void;
79
80 /**
81 * Read a grammar synchronously and add it to this registry.
82 * @param grammarPath The absolute file path to the grammar.
83 * @return The newly loaded Grammar.
84 */
85 loadGrammarSync(grammarPath: string): Grammar;
86
87 /**
88 * Read a grammar asynchronously and add it to the registry.
89 * @param grammarPath The absolute file path to the grammar.
90 * @param callback The function to be invoked once the Grammar has been read in
91 * and added to the registry.
92 */
93 loadGrammar(grammarPath: string, callback: (error: Error | null, grammar?: Grammar) => void): void;
94
95 /**
96 * Convert compact tags representation into convenient, space-inefficient tokens.
97 * @param lineText The text of the tokenized line.
98 * @param tags The tags returned from a call to Grammar::tokenizeLine().
99 * @return An array of Token instances decoded from the given tags.
100 */
101 decodeTokens(lineText: string, tags: Array<number | string>): GrammarToken[];
102
103 /**
104 * Set a TextBuffer's language mode based on its path and content, and continue
105 * to update its language mode as grammars are added or updated, or the buffer's
106 * file path changes.
107 * @param buffer The buffer whose language mode will be maintained.
108 * @return A Disposable that can be used to stop updating the buffer's
109 * language mode.
110 */
111 maintainLanguageMode(buffer: TextBuffer): Disposable;
112
113 /**
114 * Force a TextBuffer to use a different grammar than the one that would otherwise
115 * be selected for it.
116 * @param buffer The buffer whose grammar will be set.
117 * @param languageId The identifier of the desired language.
118 * @return Returns a boolean that indicates whether the language was successfully
119 * found.
120 */
121 assignLanguageMode(buffer: TextBuffer, languageId: string): boolean;
122
123 /**
124 * Remove any language mode override that has been set for the given TextBuffer.
125 * This will assign to the buffer the best language mode available.
126 */
127 autoAssignLanguageMode(buffer: TextBuffer): void;
128
129 /**
130 * Select a grammar for the given file path and file contents.
131 *
132 * This picks the best match by checking the file path and contents against
133 * each grammar.
134 * @param filePath A string file path.
135 * @param fileContents A string of text for that file path.
136 */
137 selectGrammar(filePath: string, fileContents: string): Grammar;
138
139 /**
140 * Returns a number representing how well the grammar matches the
141 * `filePath` and `contents`.
142 * @param grammar The grammar to score.
143 * @param filePath A string file path.
144 * @param contents A string of text for that file path.
145 */
146 getGrammarScore(grammar: Grammar, filePath: string, contents: string): number;
147}