1 | import { Disposable, Grammar, GrammarToken, TextBuffer } from "../index";
|
2 |
|
3 | /** Registry containing one or more grammars. */
|
4 | export 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 | }
|