doc: migration guide

README.md

@@ -18,14 +18,14 @@ SELECT 1 FROM dual WHERE a = b
 ```
 
 ```text
- SQL Text
-   └─Statements: net.sf.jsqlparser.statement.select.Select
-       ├─selectItems -> Collection<SelectItem>
-       │  └─LongValue: 1
-       ├─Table: dual
-       └─where: net.sf.jsqlparser.expression.operators.relational.EqualsTo
-          ├─Column: a
-          └─Column: b
+SQL Text
+ └─Statements: statement.select.PlainSelect
+    ├─selectItems: statement.select.SelectItem
+    │  └─LongValue: 1
+    ├─Table: dual
+    └─where: expression.operators.relational.EqualsTo
+       ├─Column: a
+       └─Column: b
 ```
 
 ```java
@@ -61,9 +61,6 @@ Assertions.assertEquals("b", b.getColumnName());
 
 **JSqlParser** can also be used to create SQL Statements from Java Code with a fluent API (see [Samples](https://jsqlparser.github.io/JSqlParser/usage.html#build-a-sql-statements)).
 
-## Alternatives to JSqlParser?
-[**General SQL Parser**](http://www.sqlparser.com/features/introduce.php?utm_source=github-jsqlparser&utm_medium=text-general) looks pretty good, with extended SQL syntax (like PL/SQL and T-SQL) and java + .NET APIs. The tool is commercial (license available online), with a free download option.
-
 ## [Documentation](https://jsqlparser.github.io/JSqlParser)
 
 ### [Samples](https://jsqlparser.github.io/JSqlParser/usage.html#parse-a-sql-statements)

src/site/sphinx/index.rst

@@ -12,6 +12,7 @@ Java SQL Parser Library
 
    usage
    contribution
+   migration
    syntax_stable
    syntax_snapshot
    javadoc_stable

src/site/sphinx/migration.rst

@@ -1,21 +1,146 @@
 *********************************
-Migration to JSQLParser Version 5
+Migration to 5.0
 *********************************
 
-* ``ValueListExpression`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`
-* ``ValuesStatement`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`
-* ``ItemsList`` has been removed and ``ExpressionList`` is used instead
-* ``MultiExpressionList`` has been removed and ``ExpressionList`` is used instead (with ``ExpressionList`` elements)
-* ``SelectBody`` has been removed and `PlainSelect` can be used directly
-* ``SubJoin`` has been removed, using normal ```ParenthesedFromItem`` instead
-* ``SubSelect`` has been removed and any instance of ``Select`` (`PlainSelect`, `Values` or `SetOperationList`) can be used instead
-*
+`Values` Clause
+---------------------------------
+The ``ValueListExpression`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`.
 
-* `hasBrackets()`, 'isUsingBrackets()' and similar methods have been removed, instead the Parser will return ``ParenthesedExpressionList`` or ``ParenthesedSelect`` or ```ParenthesedFromItem`` or ``Parenthesis`` wrapping the object within brackets
+The ``ValuesStatement`` has been replaced by ``Values``, which implements ``Select`` `Statement` and `Expression`.
 
-* any instance of `List<Expression>` is considered an Anti Pattern and `ExpressionList<?>` shall be used instead
+.. tab:: Statement
 
-* ``List<UpdateSet>`` is used for any `Set` clause within `Insert`, `Update`, `Upsert` or `Merge` statements
+    .. code-block:: SQL
+        :caption: `VALUES` examples
 
-* ``Statements`` extends `List<Statement>` directly and so ``Statements.getStatements()`` is obsolete
+        VALUES ( 1, 2, 3 )
+        ;
+
+
+    .. code-block:: TEXT
+        :caption: AST for the `VALUES` examples
+
+        SQL Text
+         └─Statements: statement.select.Values
+            └─ParenthesedExpressionList: (1, 2, 3)
+
+    .. raw:: html
+
+        <pre>
+        SQL Text
+         └─<span style="color: #000080;">Statements</span>: <span style="color: #808000;">statement.select.PlainSelect</span>
+            ├─<span style="color: #000080;">selectItems</span>: <span style="color: #808000;">statement.select.SelectItem</span>
+            │  └─<span style="color: #000080;">AllColumns</span>: <span style="color: #808000;">*</span>
+            ├─<span style="color: #000080;">Table</span>: <span style="color: #808000;">cfe.test</span>
+            └─<span style="color: #000080;">where</span>: <span style="color: #808000;">expression.operators.relational.EqualsTo</span>
+               ├─<span style="color: #000080;">Column</span>: <span style="color: #808000;">a</span>
+               └─<span style="color: #000080;">Column</span>: <span style="color: #808000;">b</span>
+
+        </pre>
+
+
+
+.. tab:: Sub-query
+
+    .. code-block:: SQL
+        :caption: `VALUES` examples
+
+        SELECT *
+        FROM ( VALUES 1, 2, 3 )
+        ;
+
+
+    .. code-block:: TEXT
+        :caption: AST for the `VALUES` examples
+
+        SQL Text
+         └─Statements: statement.select.PlainSelect
+            ├─selectItems: statement.select.SelectItem
+            │  └─AllColumns: *
+            └─fromItem: statement.select.ParenthesedSelect
+               └─select: statement.select.Values
+                  └─ExpressionList: 1, 2, 3
+
+.. tab:: Expression
+
+    .. code-block:: SQL
+        :caption: `VALUES` examples
+
+        UPDATE test
+        SET (   a
+                , b
+                , c ) = ( VALUES 1, 2, 3 )
+        ;
+
+
+    .. code-block:: TEXT
+        :caption: AST for the `VALUES` examples
+
+        SQL Text
+         └─Statements: statement.update.Update
+            ├─Table: test
+            └─updateSets: statement.update.UpdateSet
+               ├─ParenthesedExpressionList: (a, b, c)
+               └─ExpressionList: (VALUES 1, 2, 3)
+
+.. tab:: Clause
+
+    .. code-block:: SQL
+        :caption: `VALUES` examples
+
+        INSERT INTO test
+        VALUES ( 1, 2, 3 )
+        ;
+
+    .. code-block:: TEXT
+        :caption: AST for the `VALUES` examples
+
+        SQL Text
+         └─Statements: statement.insert.Insert
+            ├─Table: test
+            └─select: statement.select.Values
+               └─ParenthesedExpressionList: (1, 2, 3)
+
+`Expression` Lists
+---------------------------------
+
+The class ``ExpressionList`` extends ``List<Expression>`` directly and so ``ExpressionList.getExpressions()`` is obsolete.
+
+Any instance of `List<Expression>` is considered an Anti Pattern and the class ``ExpressionList<T extends Expression>`` shall be used instead.
+
+``ItemsList`` has been removed and ``ExpressionList`` is used instead.
+
+``MultiExpressionList`` has been removed and ``ExpressionList`` is used instead (with ``ExpressionList`` elements).
+
+Generic `SelectItem`
+---------------------------------
+
+The class ``SelectItem<T extends Expression>`` is now generic and various derivatives (e. |_| g. ``SelectExpressionItem``, ``FunctionItem``, ``ExpressionListItem``) have been removed.
+
+
+`Select` Statement
+---------------------------------
+
+``SelectBody`` has been removed and `PlainSelect` can be used directly
+
+``SubJoin`` has been replaced by `ParenthesedFromItem`` (implementing a ``FromItem`` with a regular list of ``Join``)
+
+``SubSelect`` has been removed and any instance of ``Select`` (`PlainSelect`, `Values` or `SetOperationList`) can be used instead
+
+Brackets
+---------------------------------
+
+Any `hasBrackets()`, `isUsingBrackets()` and similar methods have been removed; instead the Parser will return a ``ParenthesedExpressionList`` or ``ParenthesedSelect`` or ```ParenthesedFromItem`` or ``Parenthesis`` wrapping the object within brackets.
+
+This allows for much better bracket handling.
+
+`UpdateSet` clause
+---------------------------------
+
+A ``List<UpdateSet>`` is used for any `Set` clause within `Insert`, `Update`, `Upsert` or `Merge` statements.
+
+`Statements` collection
+---------------------------------
+
+The ``Statements`` class extends `List<Statement>` directly and so ``Statements.getStatements()`` is obsolete.