Merge pull request #160 from j-tr/j-tr/docs

README: integrate missing blog post
This commit is contained in:
mrks 2020-10-08 10:37:21 +02:00 committed by GitHub
commit 1e9f6b50f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 72 additions and 4 deletions

View File

@ -11,7 +11,7 @@ In March 2015 we've also written a short paper outlining discussing some develop
## Usage
**Note:** You can also find a detailed usage description at this [blog post](http://torpedro.github.io/tech/c++/sql/parser/2016/02/27/c++-sql-parser.html).
**Note:** You can also find a detailed usage description [here](docs/basic-usage.md).
**Requirements:**
* gcc 5+ (or clang 5+)

View File

@ -6,11 +6,9 @@ Internal Links:
* [Developer Documentation](dev-docs.md)
* [Supported SQL Queries](syntax-support.md)
* [Known Limitations & Missing Features](known-limitations.md)
* [Basic Usage](basic-usage.md)
External Resources:
* [Original Dev-Paper (2015)](http://torpedro.com/paper/HyriseSQL-03-2015.pdf)
* [Blog Post about Basic Usage](http://torpedro.github.io/tech/c++/sql/parser/2016/02/27/c++-sql-parser.html)

70
docs/basic-usage.md Executable file
View File

@ -0,0 +1,70 @@
Using the Library
=======================
Using the SQL parser library is very simple. First step will be to download and build the library. Either get the latest sources from the repository or download the latest release. The only requirement is a modern C++ compiler. Versions that are definitely working are gcc 4.8 and clang 3.4, but older versions might work also or only need small modifications. To build it simply go into the directory and run
```
make # creates libsqlparser.so
make install # copies the library to /usr/local/lib/
```
To include it in your own code you only need to include one header file: SQLParser.h. The entire framework is wrapped in the namespace hsql. To parse a SQL string you have to call the static method `hsql::SQLParser::parseSQLString(std::string query)`.
The `parseSQLString` method will return an object of type `SQLParserResult*`. When the query was valid SQL the result will contain a list of `SQLStatement` objects that represent the statements in your query. To check whether the query was valid, you can check the `result->isValid` flag. The successfully parsed statements are stored at `result->statements` which is of type `std::vector<SQLStatement*>`.
This is a list of the currently available statement types, each being a subclass of `SQLStatement`:
```
CreateStatement
DeleteStatement
DropStatement
ExecuteStatement
ImportStatement
PrepareStatement
SelectStatement
UpdateStatement
```
To find out what type of statement a certain `SQLStatement` is, you can check the `stmt->type()`, which will return an enum value. This `enum StatementType` is defined in `SQLStatement.h`. There you can see all the available values. Some of these do not match to statement classes though, because they are not implemented yet.
Probably the best way to get familiar with the properties is to look at the class definitions itself in the repository here. The statement definitions are simply structs holding the data from the query. You could also take a look at the utility code in `sqlhelper.cpp` which contains code that prints information about statements to the console.
## Example Code
example.cpp
```
// include the sql parser
#include "SQLParser.h"
int main(int argc, char *argv[]) {
if (argc <= 1) {
fprintf(stderr, "Usage: ./example \"SELECT * FROM test;\"\n");
return -1;
}
std::string query = argv[1];
// parse a given query
hsql::SQLParserResult* result = hsql::SQLParser::parseSQLString(query);
// check whether the parsing was successful
if (result->isValid) {
printf("Parsed successfully!\n");
printf("Number of statements: %lu\n", result->size());
// process the statements...
} else {
printf("The SQL string is invalid!\n");
return -1;
}
return 0;
}
```
Makefile
```
CFLAGS = -std=c++11 -lstdc++ -Wall -I../src/ -L../
all:
$(CXX) $(CFLAGS) example.cpp -o example -lsqlparser
```