From 32e738f050d0fec654185e00072ac4efdcab36e0 Mon Sep 17 00:00:00 2001 From: Jake Wheat Date: Wed, 10 Jan 2024 16:18:05 +0000 Subject: [PATCH] fix rendering of test case examples for website, other small fixes to website --- Makefile | 12 ++++- tools/Language/SQL/SimpleSQL/LexerTests.hs | 4 +- website/AddLinks.hs | 2 +- website/contributing.asciidoc | 45 ++++++++++++++++ website/index.asciidoc | 60 +++++++++++----------- website/release_checklist.asciidoc | 36 +++++++++++++ 6 files changed, 125 insertions(+), 34 deletions(-) create mode 100644 website/contributing.asciidoc create mode 100644 website/release_checklist.asciidoc diff --git a/Makefile b/Makefile index 83f3e84..c768e75 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ website : website-non-haddock build-haddock .PHONY : website-non-haddock website-non-haddock : build/main.css build/ocean.css build/index.html build/supported_sql.html \ - build/test_cases.html + build/test_cases.html build/contributing.html build/release_checklist.html build/main.css : website/main.css @@ -56,6 +56,13 @@ build/index.html : website/index.asciidoc website/AddLinks.hs build/supported_sql.html : website/supported_sql.asciidoc website/AddLinks.hs asciidoctor website/supported_sql.asciidoc -o - | cabal -v0 exec runhaskell website/AddLinks.hs > build/supported_sql.html +build/contributing.html : website/contributing.asciidoc website/AddLinks.hs + asciidoctor website/contributing.asciidoc -o - | cabal -v0 exec runhaskell website/AddLinks.hs > build/contributing.html + +build/release_checklist.html : website/release_checklist.asciidoc website/AddLinks.hs + asciidoctor website/release_checklist.asciidoc -o - | cabal -v0 exec runhaskell website/AddLinks.hs > build/release_checklist.html + + build/test_cases.html : website/RenderTestCases.hs cabal -v0 exec runhaskell -- --ghc-arg=-package=pretty-show -itools website/RenderTestCases.hs > build/test_cases.asciidoc asciidoctor build/test_cases.asciidoc -o - | \ @@ -65,6 +72,9 @@ build/test_cases.html : website/RenderTestCases.hs # TODO: make the tables autowidth # -e "s/(code.*)font-size:1em/\1font-size:0.8em/g" rm build/test_cases.asciidoc + # the tests don't render right if the TestCases aren't all at the same level + # of group nesting, which should be fixed - if this isn't the case, it + # will silently not render some of the tests # works here, but not in a recipe. amazing # GHC_VER="$(shell ghc --numeric-version)" diff --git a/tools/Language/SQL/SimpleSQL/LexerTests.hs b/tools/Language/SQL/SimpleSQL/LexerTests.hs index 6fa36fb..22c9b12 100644 --- a/tools/Language/SQL/SimpleSQL/LexerTests.hs +++ b/tools/Language/SQL/SimpleSQL/LexerTests.hs @@ -43,7 +43,7 @@ lexerTests = Group "lexerTests" $ -- quick sanity tests to see something working bootstrapTests :: TestItem -bootstrapTests = Group "bootstrap tests" $ +bootstrapTests = Group "bootstrap tests" [Group "bootstrap tests" $ map (uncurry (LexTest ansi2011)) ( [("iden", [Identifier Nothing "iden"]) ,("'string'", [SqlString "'" "'" "string"]) @@ -82,7 +82,7 @@ bootstrapTests = Group "bootstrap tests" $ ] ++ map (\a -> (a, [Symbol a])) ( ["!=", "<>", ">=", "<=", "||"] - ++ map T.singleton ("(),-+*/<>=." :: [Char]))) + ++ map T.singleton ("(),-+*/<>=." :: [Char])))] ansiLexerTable :: [(Text,[Token])] diff --git a/website/AddLinks.hs b/website/AddLinks.hs index f7ba98e..22771f6 100644 --- a/website/AddLinks.hs +++ b/website/AddLinks.hs @@ -30,5 +30,5 @@ linkSection = \
  • Changes
    • \n\ \
  • Other versions
    • \n\ \
  • Parent project\n\ - \
  • jakewheatmail@gmail.com
    • \n\ + \
  • jakewheat@tutanota.com
    • \n\ \\n" diff --git a/website/contributing.asciidoc b/website/contributing.asciidoc new file mode 100644 index 0000000..4129a76 --- /dev/null +++ b/website/contributing.asciidoc @@ -0,0 +1,45 @@ + +:toc: right +:sectnums: +:toclevels: 10 +:source-highlighter: pygments + += Contributing + +== Contributing to simple sql parser + +Contributions are welcome. It's preferred if they follow some guidelines: + +If you add something to the public api, follow the pattern already set for haddock. + +If something isn't ansi sql, add it under a dialect flag which isn't enabled in the ansi dialect. + +If you add dialect flags, add them to the appropriate dialects, create a new one if it's a system which doesn't already have a dialect. + +Testing + +Run all the preexisting tests and make sure they continue to pass. + +Add tests for anything you add, negative tests are a good idea too - check something that's behind a dialect flag doesn't parse when disabled. + +It's ideal if tests for something set with a dialect flag go in a test file for that dialect flag, unless it's an ansi feature that's disabled in other dialects. It's also an option to put tests in a test file dedicated to the dialect that the dialect flag was introduced for. But the current testing doesn't quite stick to this approach at the moment, it's not the worse thing about the codebase. + +== Key design notes + +The parsing is done using the megaparsec library. + +The parser uses a separate lexer. I think this makes the code a lot simpler. It used to be a big speed boost over naively not using a separate lexer with parsec, I'm not sure this is still the case with megaparsec. + +SQL comes in a huge variety of annoyingly different dialects. The aspirational goal is to have a dialect flag for each dialect that you pass to the parser and it parses that dialect and rejects things not in that dialect. This is a bit of a stretch since most major SQL systems have huge numbers of dialect options. One think you learn when writing a non toy SQL parser is you cannot hope to comprehensively support anything, you just have to do enough, and add bits you missed when you need them. + +A big tradeoff here is all code needs to be prepared to deal with the abstract syntax which supports all features from all dialects. I think the least unreasonable way you could fix this would be to have a system which generates dialect specific simple-sql-parser packages, which is still very unreasonable. + +The system probably doesn't always pretty print in the right dialect from correct syntax. This might need some changes if it causes a problem. + +TODO: tests overview in addition to the above + +TODO: how the website works, what it contains + +== Releasing + +See the link:release_checklist.html[] for things that should be done before each release. diff --git a/website/index.asciidoc b/website/index.asciidoc index 4a60862..e42a902 100644 --- a/website/index.asciidoc +++ b/website/index.asciidoc @@ -22,27 +22,7 @@ probably not very stable, since adding support for all the not-yet-supported ANSI SQL syntax, then other dialects of SQL is likely to change the abstract syntax types considerably. -Tested with GHC 9.8.1, 9.6.3, and 9.4.8. - -== Links - -* Haddock: link:haddock/index.html[] -* Supported SQL: link:supported_sql.html[] -* Test cases: link:test_cases.html[simple-sql-parser test cases] -* Homepage: http://jakewheat.github.io/simple-sql-parser/latest -* Hackage: http://hackage.haskell.org/package/simple-sql-parser -* Repository: https://github.com/JakeWheat/simple-sql-parser -* Bug tracker: https://github.com/JakeWheat/simple-sql-parser/issues -* Changes: https://github.com/JakeWheat/simple-sql-parser/blob/master/changelog -* Other versions: http://jakewheat.github.io/simple-sql-parser/ -* Parent project: http://jakewheat.github.io/ -* Contact: +++jakewheatmail@gmail.com+++ - -The simple-sql-parser is a lot less simple than it used to be. If you -just need to parse much simpler SQL than this, or want to start with a -simpler parser and modify it slightly, you could also look at the -basic query parser in the intro_to_parsing project, the code is here: -link:https://github.com/JakeWheat/intro_to_parsing/blob/master/SimpleSQLQueryParser0.lhs[SimpleSQLQueryParser]. +Tested with GHC 9.8.1, 9.6.4, and 9.4.8. == Feature support @@ -388,18 +368,14 @@ doIt src = do == Installation -Installing the latest release from Hackage. - ----- -cabal v2-update && cabal v2-install simple-sql-parser ----- +Use cabal, stack or your usual system to work with the released package. Working with the latest development version: ---- git clone https://github.com/JakeWheat/simple-sql-parser.git cd simple-sql-parser -cabal v2-build +cabal build ---- === Running the tests @@ -410,7 +386,7 @@ source directory. You can run the tests using cabal: ---- -cabal v2-test +cabal test ---- Or you can run them directly which gives more options. The tests use @@ -419,7 +395,7 @@ with --ansi-tricks=false so it works is a good option to use: ---- -cabal v2-run test:Tests -- --hide-successes --ansi-tricks=false +cabal run test:Tests -- --hide-successes --ansi-tricks=false ---- == Reporting bugs @@ -437,4 +413,28 @@ request, or find someone willing to write the fixes and make a pull request. There is a related tutorial on implementing a SQL parser here: -http://jakewheat.github.io/intro_to_parsing/ +http://jakewheat.github.io/intro_to_parsing/ (TODO: this is out of date, hopefully it will be updated at some point) + +== Contributing + +Contributions are welcome, there are some notes on these pages: link:contributing.html[], link:release_checklist.html[]. + +== Links + +* Haddock: link:haddock/index.html[] +* Supported SQL: link:supported_sql.html[] +* Test cases: link:test_cases.html[simple-sql-parser test cases] +* Homepage: http://jakewheat.github.io/simple-sql-parser/latest +* Hackage: http://hackage.haskell.org/package/simple-sql-parser +* Repository: https://github.com/JakeWheat/simple-sql-parser +* Bug tracker: https://github.com/JakeWheat/simple-sql-parser/issues +* Changes: https://github.com/JakeWheat/simple-sql-parser/blob/master/changelog +* Other versions: http://jakewheat.github.io/simple-sql-parser/ +* Parent project: http://jakewheat.github.io/ +* Contact: +++jakewheat@tutanota.com+++ + +The simple-sql-parser is a lot less simple than it used to be. If you +just need to parse much simpler SQL than this, or want to start with a +simpler parser and modify it slightly, you could also look at the +basic query parser in the intro_to_parsing project, the code is here: +link:https://github.com/JakeWheat/intro_to_parsing/blob/master/SimpleSQLQueryParser0.lhs[SimpleSQLQueryParser]. diff --git a/website/release_checklist.asciidoc b/website/release_checklist.asciidoc new file mode 100644 index 0000000..e352592 --- /dev/null +++ b/website/release_checklist.asciidoc @@ -0,0 +1,36 @@ +:toc: right +:sectnums: +:toclevels: 10 +:source-highlighter: pygments + += Release checklist + +Check the version in the cabal file - update it if it hasn't already been updated + +Update the changelog, use git diff or similar to try to avoid missing anything important + +run the tests + +generate the website: + +check the webpages appear nicely + +check all the tests are rendered on the example page + +check the examples on the main page to check if they need updating + +run cabal update, cabal outdated. cabal check + +update stack.yaml to latest lts, install latest stack, run stack build + +run the tests on the previous 2 ghcs' latest point releases, and the latest ghc, each with the latest cabal-install they support + +build the release tarball, run a test with an example using this tarball + +if there are any non trivial changes, upload a new wesbite + +upload candidate to hackage, run a test with example using this package + +if all good, release the candidate + +Todo: try to turn as much of this into a script, with a nice report as possible, order this list properly, say what you need to check in more detail, say what else you need to redo if any steps need actions