forked from CoatiSoftware/SourcetrailDB
-
Notifications
You must be signed in to change notification settings - Fork 0
/
SourcetrailDBWriter.h
524 lines (484 loc) · 20.6 KB
/
SourcetrailDBWriter.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
/*
* Copyright 2018 Coati Software KG
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef SOURCETRAIL_SRCTRLDB_WRITER_H
#define SOURCETRAIL_SRCTRLDB_WRITER_H
#include <memory>
#include <string>
#include "DefinitionKind.h"
#include "EdgeKind.h"
#include "ElementComponentKind.h"
#include "LocationKind.h"
#include "NameHierarchy.h"
#include "ReferenceKind.h"
#include "SourceRange.h"
#include "SymbolKind.h"
namespace sourcetrail
{
class DatabaseStorage;
/**
* SourcetrailDBWriter
*
* This class is the main interface for writing data to a Sourcetrail project database.
* It be used to manage a Sourcetrail database file and to write information to it.
*
* The following code snippet illustrates a very basic usage of the SourcetrailDBWriter class:
*
* sourcetrail::SourcetrailDBWriter writer;
* writer.open("MyProject.srctrldb");
* writer.recordSymbol({ "::",{ { "void", "foo", "()" } } });
* writer.close();
*/
class SourcetrailDBWriter
{
public:
SourcetrailDBWriter();
~SourcetrailDBWriter();
/**
* Provides the version of the SourcetrailDB Core as string with format "vXX.dbYY.pZZ"
*
* - XX: interface version. This version increases on every change that breaks backwards
* compatibility.
* - YY: Sourcetrail database version. This version needs to match the database version
* of the used Sourcetrail instance. You can find the database version of Sourcetrail
* in its About dialog.
* - ZZ: patch number of the build. It will increase with every release that publishes
* bugfixes and features that don't break any compatibility.
*
* return: version string
*/
std::string getVersionString() const;
/**
* Provides the supported database version as integer
*
* return: supported database version
*
* see: getVersionString() for details
*/
int getSupportedDatabaseVersion() const;
/**
* Provides the last error that occurred while using the SourcetrailDBWriter
*
* The last error is empty if no error occurred since instantiation of the class or since the
* error has last been cleared.
*
* return: error message of last error that occured
*
* see: clearLastError()
*/
const std::string& getLastError() const;
/**
* Modifies the stored error message
*
* param: error - the new error message
*
* see: getLastError()
*/
void setLastError(const std::string& error) const;
/**
* Clears the stored error message
*
* see: getLastError()
*/
void clearLastError();
/**
* Opens a Sourcetrail database
*
* Call this method to open a Sourcetrail database file. If the database does not have any
* related .srctrlprj project file, a minimal project file will be created that allows for
* opening the database with Sourcetrail.
*
* param: databaseFilePath - absolute file path of the database file, including file extension
*
* return: true if successful. false on failure. getLastError() provides the error message.
*/
bool open(const std::string& databaseFilePath);
/**
* Closes the currently open Sourcetrail database
*
* return: Returns true if the operation was successful. Otherwise false is returned and getLastError()
* can be checked for more detailed information.
*
* see: open(const std::string& databaseFilePath)
*/
bool close();
/**
* Clears the currently open Sourcetrail database
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: open(const std::string& databaseFilePath)
*/
bool clear();
/**
* Checks if the currently open database file contains any data
*
* return: true after opening a non-existing database file or clearing the open database
*/
bool isEmpty() const;
/**
* Checks if the currently open database is compatible with the SourcetrailDBWriter version.
*
* return: true for an empty database or a database that has been created with the same
* database version.
*
* see: getSupportedDatabaseVersion()
* see: getLoadedDatabaseVersion()
*/
bool isCompatible() const;
/**
* Provides the database version of the loaded database file as an integer
*
* return: database version of loaded database
*/
int getLoadedDatabaseVersion() const;
/**
* Starts a database transaction on the currently open database
*
* Apart from allowing to restore the database to the state it was in before this method has
* been called, wrapping multiple calls that record data with one transaction significantly
* increases the performance of these database operations.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: commitTransaction()
* see: rollbackTransaction()
*/
bool beginTransaction();
/**
* Ends the current transaction and writes all of its changes persistently to the database
*
* return: true if successful. false on failure. getLastError() provides the error message.
*/
bool commitTransaction();
/**
* Reverts the database to the state it was in before the current transaction was started
*
* return: true if successful. false on failure. getLastError() provides the error message.
*/
bool rollbackTransaction();
/**
* Reduces the on disk memory consumption of the open database to a minimum
*
* return: true if successful. false on failure. getLastError() provides the error message.
*/
bool optimizeDatabaseMemory();
/**
* Stores a symbol to the database
*
* note: Calling this method multiple times with the same input on the same Sourcetrail
* database will always return the same id.
*
* param: nameHierarchy - the name of the symbol to store.
*
* return: symbolId - integer id of the stored symbol. 0 on failure. getLastError()
* provides the error message.
*
* see: NameHierarchy
*/
int recordSymbol(const NameHierarchy& nameHierarchy);
/**
* Stores a definition kind for a specific symbol to the database
*
* Calling this method allows to store a DefinitionKind (e.g. explicitly defined, implicitly
* defined) for a symbol referenced by id to the database. Calling this method with the same
* symbolId multiple times overwrites the symbol's previously recorded DefinitionKind. If no
* DefinitionKind is recorded for a symbol, Sourcetrail treats this symbol as "non-indexed".
* This may be desired while recording a reference to a symbol with a definition that is located
* outside of the indexed source files.
*
* param: symbolId - the id of the symbol for which a DefinitionKind shall be recorded.
* param: definitionKind - the DefinitionKind that shall be recorded for the respective symbol.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: DefinitionKind
*/
bool recordSymbolDefinitionKind(int symbolId, DefinitionKind definitionKind);
/**
* Stores a symbol kind for a specific symbol to the database
*
* Calling this method allows to store a SymbolKind (e.g. "class", "function", etc.) for a
* symbol referenced by id to the database. Calling this method with the same symbolId multiple
* times overwrites the symbol's previously recorded SymbolKind. If no SymbolKind is recorded
* for a symbol, Sourcetrail displays the type of this symbol as "symbol".
*
* param: symbolId - the id of the symbol for which a SymbolKind shall be recorded.
* param: symbolKind - the SymbolKind that shall be recorded for the respective symbol.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SymbolKind
*/
bool recordSymbolKind(int symbolId, SymbolKind symbolKind);
/**
* Stores a location for a specific symbol to the database
*
* This method allows to store a location for a symbol referenced by id to the database.
* Calling this method with the same symbolId multiple times adds multiple locations for the
* respective symbol. The stored location will be clickable and displayable. When clicked
* Sourcetrail will activate the symbol with the specified id. When the symbol with the specified
* id is activated, this location will be displayed and highlighted by Sourcetrail.
*
* param: symbolId - the id of the symbol for which a location shall be recorded.
* param: location - the SourceRange that shall be recorded as location for the respective symbol.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordSymbolLocation(int symbolId, const SourceRange& location);
/**
* Stores a scope location for a specific symbol to the database
*
* This method allows to store a scope location for a symbol referenced by id to the database.
* Calling this method with the same symbolId multiple times adds multiple scope locations for the
* respective symbol. The stored location will only be displayable and not clickable. When the
* symbol with the specified id is activated, this location will be fully displayed but not
* highlighted by Sourcetrail.
*
* param: symbolId - the id of the symbol for which a scope location shall be recorded.
* param: location - the SourceRange that shall be recorded as scope location for the respective
* symbol.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordSymbolScopeLocation(int symbolId, const SourceRange& location);
/**
* Stores a signature location for a specific symbol to the database
*
* This method allows to store a signature location for a symbol referenced by id to the
* database. If a signature location is recorded for a symbol, Sourcetrail will display the
* respective source code in a tooltip whenever the symbol with the referenced id or any of
* that symbol's locations gets hovered.
* If no signature location is recorded for a symbol, Sourcetrail will show its name hierarchy.
*
* note: Calling this method with the same symbolId multiple times adds multiple signature
* locations for the respective symbol. It is not guaranteed which one will be used, so it is
* advised to call it only once per symbol.
*
* param: symbolId - the id of the symbol for which a signature location shall be recorded.
* param: location - the SourceRange that shall be recorded as signature location for the
* respective symbol.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordSymbolSignatureLocation(int symbolId, const SourceRange& location);
/**
* Stores a reference between two symbols to the database
*
* This method allows to store the information of symbols referencing one another to the database.
* For each recorded reference Sourcetrail's graph view will display an edge that originates at
* the reference's recorded context symbol and points to the recorded referenced symbol. The
* recorded ReferenceKind is used to determine the type of the displayed edge and to generate a
* description in the hover tooltip of the edge.
*
* note: Calling this method multiple times with the same input on the same Sourcetrail database
* will always return the same id.
*
* param: contextSymbolId - the id of the source of the recorded reference edge
* param: referencedSymbolId - the id of the target of the recorded reference edge
* param: referenceKind - kind of the recorded reference edge
*
* return: referenceId - integer id of the stored reference. 0 on failure. getLastError()
* provides the error message.
*
* see: ReferenceKind
*/
int recordReference(int contextSymbolId, int referencedSymbolId, ReferenceKind referenceKind);
/**
* Stores a location for a specific reference to the database
*
* This method allows to store a location for a reference to the database.
* Calling this method with the same referenceId multiple times adds multiple locations for the
* respective reference. The stored location will be clickable and displayable. When the reference
* location is clicked Sourcetrail will activate the symbol referenced by the respective reference.
* When the reference with the specified id is activated, this location will be displayed and
* highlighted by Sourcetrail.
*
* param: referenceId - the id of the reference for which a location shall be recorded.
* param: location - the SourceRange that shall be recorded as location for the respective
* reference.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordReferenceLocation(int referenceId, const SourceRange& location);
/**
* Marks a reference that is stored in the database as "ambiguous"
*
* This method allows to additional information for a reference to the database. Sourcetrail will
* display an "ambiguous" reference with a special style to emphasize that the existance of the
* reference is questionable. This method is intended to be called in situations when an indexed
* token may have meanings, all of which shall be recorded.
*
* param: referenceId - the id of the reference that shall be marked as ambiguous.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*/
bool recordReferenceIsAmbiguous(int referenceId);
/**
* Stores a location between a specific context and an "unsolved" symbol to the database
*
* This method allows to store all available information to the database in the case that a symbol
* is referenced in a certain context but the referenced symbol could not be resolved to a concrete
* name. For each reference recorded by this method, Sourcetrail's graph view will display an edge
* that originates at the recorded context symbol and points to a node called "unsolved symbol".
* Furthermore Sourcetrail's code view will use a different highlight when the provided source range
* gets hovered.
*
* param: contextSymbolId - the id of the source of the recorded reference edge
* param: referenceKind - kind of the recorded reference edge
* param: location - the SourceRange that shall be recorded as location for the respective
* reference.
*
* return: referenceId - integer id of the stored reference. 0 on failure. getLastError()
* provides the error message.
*
* see: SourceRange
*/
int recordReferenceToUnsolvedSymhol(int contextSymbolId, ReferenceKind referenceKind, const SourceRange& location);
/**
* Stores a location for the usage of a symbol's name as qualifier to the database
*
* This method allows to store a location where a specific symbol is used as a qualifier to the
* database. Calling this method with the same referencedSymbolId multiple times adds multiple locations
* for the respective reference. The stored location will be clickable but not displayable: When the
* reference location is clicked Sourcetrail will activate the symbol referenced by the respective
* reference. When the symbol with the specified id is activated, this location will NOT be displayed and
* highlighted by Sourcetrail.
*
* param: referencedSymbolId - the id of the symbol that is used as qualifier at the current location.
* param: location - the SourceRange that shall be recorded as location for the symbol's occurrence as
* qualifier
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordQualifierLocation(int referencedSymbolId, const SourceRange& location);
/**
* Stores a file to the database
*
* note: Calling this method multiple times with the same input on the same Sourcetrail database
* will always return the same id.
*
* param: filePath - the absolute path to the file to store.
*
* return: fileId - integer id of the stored file. 0 on failure. getLastError() provides the
* error message.
*/
int recordFile(const std::string& filePath);
/**
* Stores language information for a specific file to the database
*
* This method allows to store language information for a file to the database. Language information
* is passed and stored as string (e.g. "cpp", "java", etc.) and allows Sourcetrail to pick the
* correct syntax highlighting rules when displaying the respective source file.
*
* param: fileId - the id of the file for which language information shall be recorded.
* param: languageIdentifier - a string that denotes the programming language the respective file
* is written in.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*/
bool recordFileLanguage(int fileId, const std::string& languageIdentifier);
/**
* Stores a local symbol to the database
*
* note: Calling this method multiple times with the same input on the same Sourcetrail database
* will always return the same id.
*
* param: name - a name that is unique for this local symbol (e.g. the string encoded location
* of the local symbol's definition).
*
* return: localSymbolId - integer id of the stored local symbol. 0 on failure. getLastError()
* provides the error message.
*/
int recordLocalSymbol(const std::string& name);
/**
* Stores a location for a specific local symbol to the database
*
* This method allows to store a location for a local symbol symbol referenced by id to the database.
* Calling this method with the same symbolId multiple times adds multiple locations for the
* respective local symbol. The stored location will be clickable and displayable. When clicked
* Sourcetrail will activate this and all other local symbol locations that share the same local
* symbol id.
*
* param: localSymbolId - the id of the local symbol for which a location shall be recorded.
* param: location - the SourceRange that shall be recorded as location for the respective
* local symbol.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordLocalSymbolLocation(int localSymbolId, const SourceRange& location);
/**
* Stores an atomic SourceRange to the database
*
* This method allows to store an atomic SourceRange to the database. These ranges will
* be used by Sourcetrail to prevent the code view from displaying only a part of the range. Thus,
* if any line that lies within one of the project's atomic ranges is dispayed, the remaining
* lines will be displayed as well. This may be useful for dealing with multi-line comments or
* multi-line strings.
*
* param: sourceRange - the SourceRange to record.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordAtomicSourceRange(const SourceRange& sourceRange);
/**
* Stores an indexing error to the database
*
* This method allows to store an indexing error to the database. Errors will be shown by
* Sourcetrail's error view. When clicking the error in Sourcetrail's error list, the code view
* will display this location.
*
* param: message - an error message that will be displayed in Sourcetrail's error list.
* param: fatal - boolean fatal indicates whether parsing/indexing was aborted at this point.
* param: location - the SourceRange of the error encountered.
*
* return: true if successful. false on failure. getLastError() provides the error message.
*
* see: SourceRange
*/
bool recordError(const std::string& message, bool fatal, const SourceRange& location);
private:
void openDatabase();
void closeDatabase();
void setupDatabaseTables();
void clearDatabaseTables();
void createOrResetProjectFile();
void updateProjectSettingsText();
int addNodeHierarchy(const NameHierarchy& nameHierarchy);
int addFile(const std::string& filePath);
int addEdge(int sourceId, int targetId, EdgeKind edgeKind);
void addSourceLocation(int elementId, const SourceRange& location, LocationKind kind);
void addElementComponent(int elementId, ElementComponentKind kind, const std::string& data);
std::string m_projectFilePath;
std::string m_databaseFilePath;
std::unique_ptr<DatabaseStorage> m_storage;
mutable std::string m_lastError;
};
} // namespace sourcetrail
#endif // SOURCETRAIL_SRCTRLDB_WRITER_H