Skip to content

Commit ee2294a

Browse files
committed
update the README
1 parent a931377 commit ee2294a

File tree

1 file changed

+20
-13
lines changed

1 file changed

+20
-13
lines changed

README.md

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,41 +22,48 @@ Also, my wife said I'm not allowed to build a robot, so this project will have t
2222

2323
### SQL Grammar
2424

25-
I've chosen to re-use an existing SQL grammar for parsing; even at my most ambitious, I can't hope to implement all the features of the grammar, but it seems better than struggling along with subsets of the grammar itself while I try to implement features.
25+
I've chosen to re-use an existing SQL grammar for parsing; even at my most ambitious, I can't hope to implement even half the features of the grammar, but it seems better than struggling along writing and fixing subsets of the grammar itself while I try to implement features.
2626

27-
Remarkably, I'll want to extend the grammar to support features unique to JankSQL.
27+
On the other hand, we can expect that I'll want to extend the grammar to support features unique to JankSQL.
2828

2929
### Storage
3030

31-
I'll expect to implement my own binary file format, but that will take time. For now, there's a simpler mechanism for storage which just uses CSV files. This means I'll eventually have pluggable engines; maybe something works against CSV files, maybe I'll have different binary implementations and formats.
31+
The storage engine is based on the [CSharpTest.Net](https://github.com/csharptest/CSharpTest.Net.Collections) B-Tree implementation. The engines are pluggable through the `IEngine` and `IEngineTable` interfaces. Implementations for in-memory and on-disk storage against the CSharpTest B-Tree are supplied. A limited implementation against a CSV flat-file is also supplied.
3232

3333
### Tests
3434

35-
I'd like to be test-driven in development of the server, so I'll have a variety of unit tests. Strictly, the "unit" tests are a bit stretched -- they're probably a bit more integration tests, since they'll exercise multiple components in concert.
35+
There are more than 750 tests now, though that's a bit multiplicative due to tests running against each engine. Strictly, the "unit" tests are a bit stretched -- they're probably a bit more integration tests, since they'll exercise multiple components in concert.
36+
37+
Tests are implemented with [NUnit](https://github.com/nunit/nunit).
38+
39+
### Style
40+
41+
The project uses [StyleCop](https://github.com/StyleCop) for static analysis. I've tweaked away some of the rules that I find more annoying or counter-productive
3642

3743
# Setup
3844

3945
This project uses .Net 6.0 and therefore requires Visual Studio 2022.
4046

41-
After that, the project has just two prerequisites: the Antlr tool and an external T-SQL grammar for Antlr.
47+
After that, the project has just two prerequisites: the Antlr tool and the external T-SQL grammar for Antlr.
4248

4349
## Installing Antlr
44-
The first requirement is Antlr -- which, in turn, requires the Java run-time. The [Antlr installation instructions]( https://github.com/antlr/antlr4/blob/master/doc/getting-started.md) explain how to get Antlr going, and I just added the Antlr JAR file to my `\bin` directory, which is already on my path.
50+
The first requirement is Antlr -- which, in turn, requires the Java run-time. The [Antlr installation instructions](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md) explain how to get Antlr going, and I just added the Antlr JAR file to my `\bin` directory, which is already on my path.
4551

4652
## The T-SQL Antlr Grammar
4753
Rather than write my own grammar as I go, I started with [an available Antlr grammar for T-SQL](https://github.com/antlr/grammars-v4/tree/master/sql/tsql).
4854

49-
The `grammars-v4` project on GitHub contains many grammars, including the [sql/tsql](https://github.com/antlr/grammars-v4/tree/master/sql/tsql) grammar I chose. It's more than adequate, though it's a annoyingly case-sensitive: `SELECT` is a token, but `select` is not.
55+
The `grammars-v4` project on GitHub contains many grammars, including the [sql/tsql](https://github.com/antlr/grammars-v4/tree/master/sql/tsql) grammar I chose. It's more than adequate! I may start paring-down unused features in it to make the parser a little smaller but more importantly faster.
56+
57+
The grammar's `*.g4` files live in the Parser directory, which uses the [Antlr4BuildTasks package](https://github.com/kaby76/Antlr4BuildTasks). I've added the SQL grammar files into this repository and they'll build into the `*.CS` implementation files as needed just by building the project.
5058

51-
The grammar's `*.g4` files can be copied from that project to the `$/grammar` directory. Once landed there, build the grammar with Antlr while targeting C#:
59+
## Shell
5260

53-
```
54-
antlr4 -Dlanguage=CSharp TSqlLexer.g4 TSqlParser.g4 -o ..\Parsing -visitor
55-
```
61+
The JankSh project implements an interactive shell against a local engine. It's working against the in-memory B-Tree right now, and soon I'll have it able to attach to (or create) a directory and use that with the persisted B-Tree implementation.
5662

57-
The resulting C# files end up in the `$\Parsing` directory of the project.
63+
## Status
64+
The project is buildable, and I intend that the main branch always has all of its tests passing.
5865

59-
At this point, the project is buildable. Note that the `$\Parsing` directory is checked in with existing `*.cs` files, so maybe it's not necessary to build the grammar directly. Once Antlr add-ins are available for Visual Studio 2022, I can automate the whole thing.
66+
There are lots of language features being added as I work, so the best way to see what's supported is to scan through the tests.
6067

6168

6269
# Licensing

0 commit comments

Comments
 (0)