added README to examples and improved database version check when used from Sourcetrail

CMakeLists.txt

@@ -80,7 +80,7 @@ if (BUILD_EXAMPLES)
 	add_subdirectory("${CMAKE_SOURCE_DIR}/examples/cpp_poetry_indexer")
 
 	if (BUILD_BINDINGS_PYTHON)
-		add_subdirectory("${CMAKE_SOURCE_DIR}/examples/python_binding_example")
+		add_subdirectory("${CMAKE_SOURCE_DIR}/examples/python_api_example")
 	else()
 		message(STATUS "Skip python binding sample. You can enable building it by setting 'BUILD_BINDINGS_PYTHON' to 'ON'.")
 	endif()

core/src/StorageTypes.cpp

@@ -1,70 +0,0 @@
-/*
-* 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.
-*/
-
-#include "SymbolKind.h"
-
-#include "NodeKind.h"
-
-namespace sourcetrail
-{
-	NodeKind symbolKindToNodeKind(SymbolKind v)
-	{
-		switch (v)
-		{
-		case SYMBOL_TYPE:
-			return NODE_TYPE;
-		case SYMBOL_BUILTIN_TYPE:
-			return NODE_BUILTIN_TYPE;
-		case SYMBOL_MODULE:
-			return NODE_MODULE;
-		case SYMBOL_NAMESPACE:
-			return NODE_NAMESPACE;
-		case SYMBOL_PACKAGE:
-			return NODE_PACKAGE;
-		case SYMBOL_STRUCT:
-			return NODE_STRUCT;
-		case SYMBOL_CLASS:
-			return NODE_CLASS;
-		case SYMBOL_INTERFACE:
-			return NODE_INTERFACE;
-		case SYMBOL_ANNOTATION:
-			return NODE_ANNOTATION;
-		case SYMBOL_GLOBAL_VARIABLE:
-			return NODE_GLOBAL_VARIABLE;
-		case SYMBOL_FIELD:
-			return NODE_FIELD;
-		case SYMBOL_FUNCTION:
-			return NODE_FUNCTION;
-		case SYMBOL_METHOD:
-			return NODE_METHOD;
-		case SYMBOL_ENUM:
-			return NODE_ENUM;
-		case SYMBOL_ENUM_CONSTANT:
-			return NODE_ENUM_CONSTANT;
-		case SYMBOL_TYPEDEF:
-			return NODE_TYPEDEF;
-		case SYMBOL_TEMPLATE_PARAMETER:
-			return NODE_TEMPLATE_PARAMETER;
-		case SYMBOL_TYPE_PARAMETER:
-			return NODE_TYPE_PARAMETER;
-		case SYMBOL_MACRO:
-			return NODE_MACRO;
-		case SYMBOL_UNION:
-			return NODE_UNION;
-		}
-		return NODE_UNKNOWN;
-	}
-}

examples/cpp_api_example/README.md

@@ -0,0 +1,24 @@
+
+## C++ API Example
+
+### Requirements
+
+* CMake
+* C++ Compiler
+
+### Building
+
+* Run cmake with `BUILD_EXAMPLES=ON`
+* Build target `cpp_api_example`
+
+### Running from Command Line
+
+Invoke binary located in the build directory:
+
+```
+$ cpp_api_example path/to/database_file.srctrldb path/to/examples/cpp_api_example/data/example.cpp
+```
+
+### Running with Sourcetrail
+
+Open `cpp_api_example.srctrlprj` located in the build directory with Sourcetrail and index the project.

examples/cpp_api_example/cpp_api_example.srctrlprj.in

@@ -2,7 +2,7 @@
 <config>
     <source_groups>
         <source_group_78efd997-84bf-4db6-9736-f5ddd702053c>
-            <custom_command>./cpp_api_example $DB_PATH $DB_VERSION $SOURCE_PATH</custom_command>
+            <custom_command>./cpp_api_example $DB_PATH $SOURCE_PATH $DB_VERSION</custom_command>
             <name>Custom Command Source Group</name>
             <source_extensions>
                 <source_extension>.cpp</source_extension>

examples/cpp_api_example/src/main.cpp

@@ -1,3 +1,4 @@
+#include <cstdlib>
 #include <fstream>
 #include <iostream>
 
@@ -7,39 +8,48 @@ int main(int argc, const char *argv[])
 {
 	sourcetrail::SourcetrailDBWriter dbWriter;
 
-	std::cout << "SourcetrailDB Poetry Indexer" << std::endl;
+	std::cout << "\nSourcetrailDB C++ API Example" << std::endl;
 	std::cout << std::endl;
 	std::cout << "SourcetrailDB version: " << dbWriter.getVersionString() << std::endl;
 	std::cout << "Supported database version: " << dbWriter.getSupportedDatabaseVersion() << std::endl;
 	std::cout << std::endl;
 
-	if (argc != 4)
+	if (argc < 3 || argc > 4)
 	{
-		std::cout << "usage: poetry_indexer <database_path> <database_version> <source_path>";
+		std::cout << "usage: cpp_api_example <database_path> <source_path> <optional:database_version>";
 	}
 
 	std::string dbPath = argv[1];
-	int dbVersion = std::stoi(argv[2]);
+	std::string sourcePath = argv[2];
-	std::string sourcePath = argv[3];
 
-	if (dbVersion != dbWriter.getSupportedDatabaseVersion())
+	int dbVersion = 0;
+	if (argc == 4)
 	{
-		std::cout << "error: binary only supports database version: " << dbWriter.getSupportedDatabaseVersion()
+		char* end;
+		dbVersion = strtol(argv[3], &end, 10);
+	}
+
+	if (dbVersion && dbVersion != dbWriter.getSupportedDatabaseVersion())
+	{
+		std::cerr << "error: binary only supports database version: " << dbWriter.getSupportedDatabaseVersion()
 			<< ". Requested version: " << dbVersion << std::endl;
 		return 1;
 	}
 
 	// open database by passing .srctrldb or .srctrldb_tmp path
+	std::cout << "Opening Database: " << dbPath << std::endl;
 	if (!dbWriter.open(dbPath))
 	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
+	std::cout << "Starting Indexing..." << std::endl;
+
 	// start recording with faster speed
 	if (!dbWriter.beginTransaction())
 	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
@@ -108,22 +118,24 @@ int main(int argc, const char *argv[])
 
 
 	// record error
-	dbWriter.recordError("Really? You missed that \";\" again?", false, { fileId, 22, 1, 22, 1 });
+	dbWriter.recordError("Really? You missed that \";\" again? (intentional error)", false, { fileId, 22, 1, 22, 1 });
 
 
 	// end recording
 	if (!dbWriter.commitTransaction())
 	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
 	// check for errors before finishing
 	if (dbWriter.getLastError().size())
 	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
+	std::cout << "done!" << std::endl;
+
 	return 0;
 }

examples/cpp_poetry_indexer/README.md

@@ -0,0 +1,24 @@
+
+## Poetry Indexer Example
+
+### Requirements
+
+* CMake
+* C++ Compiler
+
+### Building
+
+* Run cmake with `BUILD_EXAMPLES=ON`
+* Build target `poetry_indexer`
+
+### Running from Command Line
+
+Invoke binary located in the build directory:
+
+```
+$ poetry_indexer path/to/database_file.srctrldb path/to/examples/cpp_poetry_indexer/data/e_e_cummings_-_in_just-.txt
+```
+
+### Running with Sourcetrail
+
+Open `poetry_indexer.srctrlprj` located in the build directory with Sourcetrail and index the project.

examples/cpp_poetry_indexer/poetry_indexer.srctrlprj.in

@@ -2,7 +2,7 @@
 <config>
     <source_groups>
         <source_group_78efd997-84bf-4db6-9736-f5ddd702053c>
-            <custom_command>./poetry_indexer $DB_PATH $DB_VERSION $SOURCE_PATH</custom_command>
+            <custom_command>./poetry_indexer $DB_PATH $SOURCE_PATH $DB_VERSION</custom_command>
             <exclude_filters>
                 <exclude_filter>@POETRY_INDEXER_DATA_PATH@/COPYRIGHT.txt</exclude_filter>
             </exclude_filters>

examples/cpp_poetry_indexer/src/main.cpp

@@ -1,3 +1,4 @@
+#include <cstdlib>
 #include <fstream>
 #include <iostream>
 #include <regex>
@@ -23,51 +24,60 @@ int main(int argc, const char *argv[])
 {
 	sourcetrail::SourcetrailDBWriter dbWriter;
 
-	std::cout << "SourcetrailDB Poetry Indexer" << std::endl;
+	std::cout << "\nSourcetrailDB Poetry Indexer" << std::endl;
 	std::cout << std::endl;
 	std::cout << "SourcetrailDB version: " << dbWriter.getVersionString() << std::endl;
 	std::cout << "Supported database version: " << dbWriter.getSupportedDatabaseVersion() << std::endl;
 	std::cout << std::endl;
 
-	if (argc != 4)
+	if (argc < 3 || argc > 4)
 	{
-		std::cout << "usage: poetry_indexer <database_path> <database_version> <source_path>";
+		std::cout << "usage: poetry_indexer <database_path> <source_path> <optional:database_version>";
 	}
 
 	std::string dbPath = argv[1];
-	int dbVersion = std::stoi(argv[2]);
+	std::string sourcePath = argv[2];
-	std::string sourcePath = argv[3];
 
-	if (dbVersion != dbWriter.getSupportedDatabaseVersion())
+	int dbVersion = 0;
+	if (argc == 4)
 	{
-		std::cout << "error: binary only supports database version: " << dbWriter.getSupportedDatabaseVersion()
+		char* end;
+		dbVersion = strtol(argv[3], &end, 10);
+	}
+
+	if (dbVersion && dbVersion != dbWriter.getSupportedDatabaseVersion())
+	{
+		std::cerr << "error: binary only supports database version: " << dbWriter.getSupportedDatabaseVersion()
 			<< ". Requested version: " << dbVersion << std::endl;
 		return 1;
 	}
 
-	if (!dbWriter.open(dbPath))
-	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
-		return 1;
-	}
-
-	if (!dbWriter.beginTransaction())
-	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
-		return 1;
-	}
-
-	int fileId = dbWriter.recordFile(sourcePath);
-	if (fileId == 0)
-	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
-		return 1;
-	}
-
 	std::ifstream fileStream(sourcePath.c_str());
 	if (!fileStream.good())
 	{
-		std::cout << "error: opening file failed: " << sourcePath << std::endl;
+		std::cerr << "error: opening file failed: " << sourcePath << std::endl;
+		return 1;
+	}
+
+	std::cout << "Opening Database: " << dbPath << std::endl;
+	if (!dbWriter.open(dbPath))
+	{
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
+		return 1;
+	}
+
+	std::cout << "Starting Indexing: " << sourcePath << std::endl;
+
+	if (!dbWriter.beginTransaction())
+	{
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
+		return 1;
+	}
+
+	int fileId = dbWriter.recordFile(sourcePath);
+	if (fileId == 0)
+	{
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
@@ -191,15 +201,17 @@ int main(int argc, const char *argv[])
 
 	if (!dbWriter.commitTransaction())
 	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
 	if (dbWriter.getLastError().size())
 	{
-		std::cout << "error: " << dbWriter.getLastError() << std::endl;
+		std::cerr << "error: " << dbWriter.getLastError() << std::endl;
 		return 1;
 	}
 
+	std::cout << "done!" << std::endl;
+
 	return 0;
 }

examples/python_api_example/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required (VERSION 2.6)
 
-set(EXAMPLE_NAME "python_binding_example")
+set(EXAMPLE_NAME "python_api_example")
 
 # --- Configure Sourcetrail Project File ---
 
@@ -27,7 +27,7 @@ else()
 		COMMAND ${CMAKE_COMMAND} -E copy ${PYTHON_BINDING_OUTPUT_DIR}/_sourcetraildb* ${CMAKE_CURRENT_BINARY_DIR}
 		COMMAND ${CMAKE_COMMAND} -E copy ${PYTHON_BINDING_OUTPUT_DIR}/sourcetraildb.py ${CMAKE_CURRENT_BINARY_DIR}
 	)
-	
+
 	if (APPLE)
 		add_custom_command(
 			TARGET ${EXAMPLE_NAME} POST_BUILD
@@ -37,7 +37,7 @@ else()
 endif()
 
 
-set(PYTHON_BINDING_EXAMPLE_DATA_PATH "${CMAKE_CURRENT_SOURCE_DIR}/data")
+set(PYTHON_API_EXAMPLE_DATA_PATH "${CMAKE_CURRENT_SOURCE_DIR}/data")
 
 configure_file(
 	"${CMAKE_CURRENT_SOURCE_DIR}/${EXAMPLE_NAME}.srctrlprj.in"

examples/python_api_example/README.md

@@ -0,0 +1,30 @@
+
+## Python API Example
+
+### Requirements
+
+* CMake
+* C++ Compiler
+* Python
+* SWIG
+
+### Running from Command Line
+
+* Run cmake with `BUILD_BINDINGS_PYTHON=ON`
+* Build target `_sourcetraildb`
+* Copy two files from the `bindings_python` build directory into `SourcetrailDB/examples/python_api_example/src`:
+	- `sourcetraildb.py`
+	- Windows: `_sourcetraildb.pyd`
+	- Linux: `_sourcetraildb.so`
+	- macOS: `_sourcetraildb.dylib` and rename to `_sourcetraildb.so`
+* Run example from the directory `SourcetrailDB/examples/python_api_example/src` with:
+
+```
+$ python example.py --database-file-path=absolute/path/to/SourcetrailDB/examples/python_api_example/src/example.srctrldb --source-file-path=absolute/path/to/SourcetrailDB/examples/python_api_example/data/file.py
+```
+
+### Running with Sourcetrail
+
+* Run cmake with `BUILD_EXAMPLES=ON` and `BUILD_BINDINGS_PYTHON=ON`
+* Build target `_sourcetraildb` and `python_api_example`.
+* Open `python_api_exampl.srctrlprj` located in the build directory of `python_api_example` with Sourcetrail and index the project.

examples/python_api_example/python_api_example.srctrlprj.in

@@ -2,13 +2,13 @@
 <config>
     <source_groups>
         <source_group_78efd997-84bf-4db6-9736-f5ddd702053c>
-            <custom_command>python3 example.py --database-file-path=$DB_PATH --source-file-path=$SOURCE_PATH</custom_command>
+            <custom_command>python example.py --database-file-path=$DB_PATH --source-file-path=$SOURCE_PATH</custom_command>
             <name>Custom Command Source Group</name>
             <source_extensions>
                 <source_extension>.py</source_extension>
             </source_extensions>
             <source_paths>
-                <source_path>@PYTHON_BINDING_EXAMPLE_DATA_PATH@/file.py</source_path>
+                <source_path>@PYTHON_API_EXAMPLE_DATA_PATH@/file.py</source_path>
             </source_paths>
             <status>enabled</status>
             <type>Custom Command Source Group</type>

examples/python_api_example/src/example.py

@@ -3,23 +3,37 @@ import os
 import sourcetraildb as srctrl
 
 def main():
-	parser = argparse.ArgumentParser(description="Index a Python source file and store the indexed data to a Sourcetrail database file.")
+	parser = argparse.ArgumentParser(description="SourcetrailDB Python API Example")
-	parser.add_argument("--database-file-path", help="path to the generated Sourcetrail database file", type=str, required=True)
+	parser.add_argument("--database-file-path", help="path to the generated Sourcetrail database file",
-	parser.add_argument("--source-file-path", help="path to the source file to index", type=str, required=True)
+		type=str, required=True)
+	parser.add_argument("--source-file-path", help="path to the source file to index",
+		type=str, required=True)
+	parser.add_argument("--database-version", help="database version of the invoking Sourcetrail binary",
+		type=int, required=False, default=0)
 
 	args = parser.parse_args()
 	databaseFilePath = args.database_file_path
 	sourceFilePath = args.source_file_path
+	dbVersion = args.database_version
+
+	print("SourcetrailDB Python API Example")
+	print("Supported database version: " + str(srctrl.getSupportedDatabaseVersion()))
+
+	if dbVersion > 0 and dbVersion != srctrl.getSupportedDatabaseVersion():
+		print("ERROR: Only supports database version: " + str(srctrl.getSupportedDatabaseVersion()) +
+			". Requested version: " + str(dbVersion))
+		return 1
 
 	if not srctrl.open(databaseFilePath):
 		print("ERROR: " + srctrl.getLastError())
+		return 1
 
 	if srctrl.isEmpty():
 		print("Loaded database is empty.")
 	else:
 		print("Loaded database contains data.")
 
-	print("start all")
+	print("start indexing")
 	srctrl.beginTransaction()
 
 	fileId = srctrl.recordFile(sourceFilePath)
@@ -27,45 +41,49 @@ def main():
 
 	if len(srctrl.getLastError()) > 0:
 		print("ERROR: " + srctrl.getLastError())
+		return 1
 
-	symbolId = srctrl.recordSymbol('{ "name_delimiter": ".", "name_elements": [ { "prefix": "", "name": "MyType", "postfix": "" } ] }')
+	symbolId = srctrl.recordSymbol(
+		'{ "name_delimiter": ".", "name_elements": [ '
+			'{ "prefix": "", "name": "MyType", "postfix": "" } '
+		'] }')
 	srctrl.recordSymbolDefinitionKind(symbolId, srctrl.DEFINITION_EXPLICIT)
 	srctrl.recordSymbolKind(symbolId, srctrl.SYMBOL_CLASS)
 	srctrl.recordSymbolLocation(symbolId, fileId, 2, 7, 2, 12)
 	srctrl.recordSymbolScopeLocation(symbolId, fileId, 2, 1, 7, 1)
 
-	if len(srctrl.getLastError()) > 0:
+	memberId = srctrl.recordSymbol(
-		print("ERROR: " + srctrl.getLastError())
+		'{ "name_delimiter": ".", "name_elements": [ '
-
+			'{ "prefix": "", "name": "MyType", "postfix": "" }, '
-	memberId = srctrl.recordSymbol('{ "name_delimiter": ".", "name_elements": [ { "prefix": "", "name": "MyType", "postfix": "" }, { "prefix": "", "name": "my_member", "postfix": "" } ] }')
+			'{ "prefix": "", "name": "my_member", "postfix": "" } '
+		'] }')
 	srctrl.recordSymbolDefinitionKind(memberId, srctrl.DEFINITION_EXPLICIT)
 	srctrl.recordSymbolKind(memberId, srctrl.SYMBOL_FIELD)
 	srctrl.recordSymbolLocation(memberId, fileId, 4, 2, 4, 10)
 
-	if len(srctrl.getLastError()) > 0:
+	methodId = srctrl.recordSymbol(
-		print("ERROR: " + srctrl.getLastError())
+		'{ "name_delimiter": ".", "name_elements": [ '
-
+			'{ "prefix": "", "name": "MyType", "postfix": "" }, '
-	methodId = srctrl.recordSymbol('{ "name_delimiter": ".", "name_elements": [ { "prefix": "", "name": "MyType", "postfix": "" }, { "prefix": "", "name": "my_method", "postfix": "" } ] }')
+			'{ "prefix": "", "name": "my_method", "postfix": "" } '
+		'] }')
 	srctrl.recordSymbolDefinitionKind(methodId, srctrl.DEFINITION_EXPLICIT)
 	srctrl.recordSymbolKind(methodId, srctrl.SYMBOL_METHOD)
 	srctrl.recordSymbolLocation(methodId, fileId, 6, 6, 6, 14)
 	srctrl.recordSymbolScopeLocation(methodId, fileId, 6, 1, 7, 1)
 
-	if len(srctrl.getLastError()) > 0:
-		print("ERROR: " + srctrl.getLastError())
-
 	useageId = srctrl.recordReference(methodId, memberId, srctrl.REFERENCE_USAGE)
 	srctrl.recordReferenceLocation(useageId, fileId, 7, 10, 7, 18)
 
+	srctrl.commitTransaction()
+
 	if len(srctrl.getLastError()) > 0:
 		print("ERROR: " + srctrl.getLastError())
-
+		return 1
-	srctrl.commitTransaction()
-	print("end all")
 
 	if not srctrl.close():
 		print("ERROR: " + srctrl.getLastError())
+		return 1
 
-	if len(srctrl.getLastError()) > 0:
+	print("done")
-		print("ERROR: " + srctrl.getLastError())
+	return 0
 main()