work on documentation for new release

TODO

@@ -1,10 +1,5 @@
 task right now: get a 0.5.0 release
-check generated documentation
-  fix docs on index of website for cabal v2
-  add notes on non query supported sql
-add note about the release being not a milestone but just checkpoint
 test with different ghcs
-maybe add something to the docs about bug reports and feature requests
 fix these two bugs
   https://github.com/JakeWheat/simple-sql-parser/issues/7
   https://github.com/JakeWheat/simple-sql-parser/issues/8
@@ -15,7 +10,7 @@ is this one fixed now?
 review alters, and think about adding rename versions
   https://github.com/JakeWheat/simple-sql-parser/issues/20
 update changelog
-
+do release
 
 
 

tools/SimpleSQLParserExample.hs

@@ -0,0 +1,43 @@
+
+-- Simple example to show parsing some SQL then pretty printing the AST
+
+import System.Environment
+import Text.Show.Pretty
+import System.IO
+
+import Language.SQL.SimpleSQL.Parse (parseStatements,peFormattedError)
+
+import Language.SQL.SimpleSQL.Syntax (ansi2011)
+
+
+main :: IO ()
+main = do
+    args <- getArgs
+    case args of
+        [] -> do
+              -- read from stdin
+              c <- getContents
+              doIt c
+        ["-s", sql] -> do
+              -- parse arg given
+              doIt sql
+        [f] ->
+              -- read file
+              withFile f ReadMode (\h -> do
+                  x <- hGetContents h
+                  doIt x)
+        _ -> do
+            putStrLn "use no arguments to stream sql from stdin, e.g.:\n\
+                     \  cat some.sql | SimpleSQLParserExample\n\
+                     \n\
+                     \use -s to parse sql on command line, e.g.:\n\
+                     \  SimpleSQLParserExample -s \"select * from t\"\n\
+                     \use a single arg to parse a file, e.g.\n\
+                     \  SimpleSQLParserExample some.sql"
+
+doIt :: String -> IO ()
+doIt src = do
+    let parsed = parseStatements ansi2011 "" Nothing src
+    either (error . peFormattedError)
+           (putStrLn . ppShow)
+           parsed

website/index.asciidoc

@@ -22,7 +22,10 @@ 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 7.10.2, 7.8.4 and 7.6.3.
+Release 0.5.0 is a checkpoint release since there hasn't been a
+release for a while.
+
+Tested with GHC 8.6.5.
 
 == Links
 
@@ -57,14 +60,23 @@ link:https://github.com/JakeWheat/intro_to_parsing/blob/master/SimpleSQLQueryPar
 ** set operators
 ** common table expressions
 ** wide range of scalar expressions
-* DDL
+* DDL (ansi dialect)
-** TODO
+** create,drop schema
+** create, alter, drop table
+** create, drop view
+** create, alter, drop domain
+** create, drop assertion
+** create, alter, drop sequence
 * non-query DML
-** TODO
+** delete
+** truncate
+** insert
+** update
 * Access control
-** TODO
+** grant, revoke - permissions and roles
+** create, drop role
 * Transaction management
-** TODO
+** begin, commit, rollback, savepoints
 
 See the link:supported_sql.html[] page for details on
 the supported SQL.
@@ -277,12 +289,61 @@ order by numwait desc, s_name
 fetch first 100 rows only;
 ----
 
+Parsing some SQL and printing the AST:
+
+[source,haskell]
+----
+
+import System.Environment
+import Text.Show.Pretty
+import System.IO
+
+import Language.SQL.SimpleSQL.Parse (parseStatements,peFormattedError)
+
+import Language.SQL.SimpleSQL.Syntax (ansi2011)
+
+
+main :: IO ()
+main = do
+    args <- getArgs
+    case args of
+        [] -> do
+              -- read from stdin
+              c <- getContents
+              doIt c
+        ["-s", sql] -> do
+              -- parse arg given
+              doIt sql
+        [f] ->
+              -- read file
+              withFile f ReadMode (\h -> do
+                  x <- hGetContents h
+                  doIt x)
+        _ -> do
+            putStrLn "use no arguments to stream sql from stdin, e.g.:\n\
+                     \  cat some.sql | SimpleSQLParserExample\n\
+                     \n\
+                     \use -s to parse sql on command line, e.g.:\n\
+                     \  SimpleSQLParserExample -s \"select * from t\"\n\
+                     \use a single arg to parse a file, e.g.\n\
+                     \  SimpleSQLParserExample some.sql"
+
+doIt :: String -> IO ()
+doIt src = do
+    let parsed = parseStatements ansi2011 "" Nothing src
+    either (error . peFormattedError)
+           (putStrLn . ppShow)
+           parsed
+----
+
+
+
 == Installation
 
 Installing the latest release from Hackage.
 
 ----
-cabal update && cabal install simple-sql-parser
+cabal v2-update && cabal v2-install simple-sql-parser
 ----
 
 Working with the latest development version:
@@ -290,9 +351,7 @@ Working with the latest development version:
 ----
 git clone https://github.com/JakeWheat/simple-sql-parser.git
 cd simple-sql-parser
-cabal sandbox init
+cabal v2-build
-cabal install --only-dependencies
-cabal build
 ----
 
 === Running the tests
@@ -303,25 +362,38 @@ source directory.
 You can run the tests using cabal:
 
 ----
-cabal sandbox init
+cabal v2-test
-cabal install --only-dependencies --enable-tests
-cabal configure --enable-tests
-cabal test
 ----
 
 Or you can run them directly which gives more options. The tests use
 tasty, which provides the command line options.
 
 ----
-cabal sandbox init
+cabal v2-build --enable-tests
-cabal install --only-dependencies --enable-tests
+dist-newstyle/build/x86_64-linux/ghc-8.6.5/simple-sql-parser-0.5.0/t/Tests/build/Tests/Tests
-cabal configure --enable-tests
-cabal build
-dist/build/Tests/Tests
 ----
 
 --hide-successes is a good option to use:
 
 ----
-dist/build/Tests/Tests --hide-successes
+dist-newstyle/build/x86_64-linux/ghc-8.6.5/simple-sql-parser-0.5.0/t/Tests/build/Tests/Tests --hide-successes
 ----
+
+Right now this option doesn't seem to be working for me - it still
+outputs a huge amount of text when all the tests pass.
+
+== Reporting bugs
+
+Please report bugs here:
+
+https://github.com/JakeWheat/simple-sql-parser/issues
+
+A good bug report (or feature request) should have an example of the
+SQL which is failing.
+
+Feature requests are welcome, but please note that there is no-one
+generally available to work on these, so you should either make a pull
+request, or find someone willing to write the fixes and make a pull
+request.
+
+

website/supported_sql.asciidoc

@@ -141,16 +141,45 @@ The supported scalar expressions include:
 
 == DDL
 
-todo
+* schemas
+** create, drop + drop restrict
+
+* tables
+** create table
+*** constraints: named, null, unique, primary key, foreign key (matches, on update/delete)
+*** identity (the weird ansi version), defaults
+*** defaults
+** alter table
+*** defaults, null, set data type, drop column, constraints
+** drop table + restrict
+** create, drop view
+
+** create, alter, drop domain
+*** defaults, constraints
+** create, drop assertion
+** create, alter, drop sequence
 
 == Non-query DML
 
-todo
+** delete
+*** delete from
+*** as alias
+*** where
+** truncate
+*** with identity options
+** insert
+*** values, general queries, defaults
+** update
+*** including row updates
 
 == Access Control
 
-todo
+** grant privileges
+*** all, grant option, table, domain, type, sequence, role, etc.
+** revoke
+** create role, drop role
 
 == Transaction management
 
-todo
+* begin, commit, rollback
+* savepoints