Add readme.md to the 18 demo folders that had none

Every demo folder now carries one, 49 of 49. Each was written from the demo's
actual source and, where the demo runs, from its real output: the commands and
the sample output in these files were executed, not composed. 21 documented
-Dexec.mainClass values were checked against the source tree, and 13 demos were
run end to end to confirm the output shown matches.

Two of the new files report that the demo does not work, rather than inventing
a usage example:

  events   ProcessSQLStatement reads a hardcoded
           C:\Users\DELL\Downloads\20240311110800487_mssql_sql\data.sql left
           behind by whoever wrote it. processTokenList stops with
           "syntax error ... near: $" -- its whole purpose is merging ${var}
           placeholders into one identifier token so templated SQL parses, and
           that is not taking effect against this parser build. The
           setTokenListHandle wiring is still worth reading; the result is not.
  snowflake Evaluates JavaScript with Nashorn, removed from the JDK in 15, so
           it needs Java 8-14. Its snowflake.js is the repository's only
           classpath resource and had been sitting in src/main/java where
           nothing copies it, which is why the demo had never run; that was
           fixed separately.

Two folders are not demos and say so: removeSpecialConditions has no main() and
is exercised through its test, and utils holds shared helpers behind the sqlenv
demo.

Where a demo has a near neighbour the reader probably wants instead, the file
says which: removeCondition vs removeSpecialConditions vs sqlrefactor,
scriptwriter as the round-trip that modifysql depends on, sqlenv vs
gettablecolumns' JDBC-backed runGetTableColumn, findproceduralsql as triage
ahead of analyzesp and callgraph.

mvn clean test: 144 tests, the same 3 known analyzespTest failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012qPRpoD8exYRrUmbfXXWXj

Author: 2 people

src/main/java/gudusoft/gsqlparser/demos/callgraph/readme.md

@@ -0,0 +1,35 @@
+## Description
+
+Builds a call graph for a PL/SQL package: every routine it declares, how those
+routines call each other, and where each one sits in the source. Emitted as
+JSON so it can feed a visualiser or an impact-analysis step.
+
+## Usage
+
+```
+java CallGraphDemo /f <path_to_sql_file> [/o <output file path>]
+```
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.callgraph.CallGraphDemo \
+    -Dexec.args="/f samples/callgraph/sample_package.sql" -Dexec.classpathScope=compile
+```
+
+```json
+{
+  "boundProgram": {
+    "routines": [
+      {"routineId": "emp_pkg.log_action/NP(1)", "kind": "NESTED_PROCEDURE", "name": "log_action",
+       "package": "emp_pkg", "paramCount": 1,
+       "sourceAnchor": {"startLine": 3, "startCol": 5, "endLine": 6, "endCol": 19}},
+      ...
+    ],
+    "objectRefs": 5,
+```
+
+`routineId` encodes package, name, kind (`NP` nested procedure, `NF` nested
+function) and arity, so overloads stay distinct. `sourceAnchor` is the routine's
+span in the input file.
+
+`samples/callgraph/sample_package.sql` is a small Oracle package kept for this
+demo.

src/main/java/gudusoft/gsqlparser/demos/evaluator/readme.md

@@ -0,0 +1,29 @@
+## Description
+
+Walks the expressions in a SQL script and evaluates what it can. Columns have
+no value outside a database, so they are substituted with 0 and reported; from
+there any expression built only from constants is folded to a result.
+
+## Usage
+
+```
+java EvaluatorDemo [/f <path_to_sql_file>] [/t <database type>]
+```
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.evaluator.EvaluatorDemo \
+    -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=compile
+```
+
+```text
+Output:
+a.id is a column, set value to 0,...
+b.name is a column, set value to 0,...
+0
+0
+100
+
+DbVendor:dbvoracle, Time Escaped: 1306ms
+```
+
+The trailing `100` is the literal in the select list, folded as a constant.

src/main/java/gudusoft/gsqlparser/demos/events/readme.md

@@ -0,0 +1,32 @@
+## Description
+
+Two callbacks the parser offers, letting you intervene *during* a parse rather
+than walking the tree afterwards.
+
+| Class | Callback | Purpose |
+|-------|----------|---------|
+| `ProcessSQLStatement` | `ISQLStatementHandle` | Fires per statement as a script is parsed, so a large script can be processed incrementally instead of held whole |
+| `processTokenList` | `ITokenListHandle` | Fires on the token list before parsing, so text that is not legal SQL can be rewritten into something that is |
+
+`processTokenList` exists for templated SQL. A script full of
+`${tx_date_yyyymm}` placeholders will not parse, so the handler merges `$`, `{`,
+name, `}` into a single identifier token first.
+
+## Usage
+
+Neither takes arguments; both are configured inline.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.events.processTokenList \
+    -Dexec.classpathScope=compile
+```
+
+> **Both demos fail as shipped.**
+>
+> `ProcessSQLStatement` reads a hardcoded path,
+> `C:\Users\DELL\Downloads\20240311110800487_mssql_sql\data.sql`, left over from
+> whoever wrote it. Point `sqlfile` at something real before running it.
+>
+> `processTokenList` currently stops with `syntax error … near: $`, so its token
+> merging is not taking effect against this parser build. The callback wiring is
+> still worth reading as an example of `setTokenListHandle`; the result is not.

src/main/java/gudusoft/gsqlparser/demos/findConstants/readme.md

@@ -0,0 +1,28 @@
+## Description
+
+Lists every string literal and numeric constant in a SQL script. The kind of
+sweep you would run before parameterising hard-coded values, or to find
+embedded secrets and magic numbers.
+
+## Usage
+
+```
+java findConstants <scriptfile> [/t <database type>]
+```
+
+`/t` defaults to `oracle`.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.findConstants.findConstants \
+    -Dexec.args="q.sql /t oracle" -Dexec.classpathScope=compile
+```
+
+For `SELECT a.id, b.name, 100 AS n FROM ta a JOIN tb b ON a.id = b.id WHERE a.x > 1 AND 'k' = 'k';`
+
+```text
+string literals and numeric constants:
+100, 1, 'k', 'k'
+```
+
+Constants are reported once per occurrence, not deduplicated: `'k'` appears
+twice above because the query contains it twice.

src/main/java/gudusoft/gsqlparser/demos/findproceduralsql/readme.md

@@ -0,0 +1,26 @@
+## Description
+
+Scans a directory of `.sql` files and picks out the ones containing procedural
+SQL — stored procedures, functions, triggers, packages — copying them to a
+second directory.
+
+Useful for triaging a large dump before analysis, since procedural code is what
+tends to need the heavier tooling (`analyzesp`, `callgraph`, `tracedatalineage`).
+
+## Usage
+
+```
+java FindProceduralSqlFiles <dbvendor> <source-sql-dir> <output-sql-dir>
+```
+
+`dbvendor` is `oracle`, `mssql` or `sqlserver`. Running it with no arguments
+prints exactly that.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.findproceduralsql.FindProceduralSqlFiles \
+    -Dexec.args="oracle /path/to/scripts /path/to/procedural-only" \
+    -Dexec.classpathScope=compile
+```
+
+Both directories are filesystem paths; the output directory receives copies, so
+the source is left untouched.

src/main/java/gudusoft/gsqlparser/demos/listGSPInfo/readme.md

@@ -0,0 +1,24 @@
+## Description
+
+Prints which parser build you are actually running: version, release date,
+whether it is the full or trial edition, and every SQL dialect it supports.
+
+Useful as a first check when a demo behaves unexpectedly, since most surprises
+come down to the parser version or the trial-vs-full distinction.
+
+## Usage
+
+Takes no arguments.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.listGSPInfo.listGSPInfo \
+    -Dexec.classpathScope=compile
+```
+
+```text
+Version: 4.1.5.15,Release date: 2026-07-12, Full version:false
+Supported DBs: 40/45,[dbvathena, dbvazuresql, dbvbigquery, ... dbvvertica]
+```
+
+`Full version:false` means the trial build. `40/45` is dialects implemented out
+of dialects defined in `EDbVendor`.

src/main/java/gudusoft/gsqlparser/demos/modifySelect/readme.md

@@ -0,0 +1,24 @@
+## Description
+
+Adds conditions to an existing `SELECT`'s `WHERE` clause through the parse
+tree rather than by string concatenation: a join predicate between two tables,
+plus bind-parameter placeholders.
+
+Doing this on the AST is what keeps it correct when the original `WHERE` is
+already non-trivial, where appending ` AND ...` to the text would not be.
+
+## Usage
+
+Takes no arguments; the query is inline in `ModifySelect.java`.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.modifySelect.ModifySelect \
+    -Dexec.classpathScope=compile
+```
+
+```text
+Original SQL:
+SELECT A.COLUMN1, B.COLUMN2 from TABLE1 A, TABLE2 B where A.COLUMN1=B.COLUMN1
+Modified SQL:
+SELECT A.COLUMN1, B.COLUMN2 from TABLE1 A, TABLE2 B where A.COLUMN1=B.COLUMN1 AND A.newcolumn=B.newcolumn AND A.newcolumn=? AND B.newcolumn=?
+```

src/main/java/gudusoft/gsqlparser/demos/modifysql/readme.md

@@ -0,0 +1,35 @@
+## Description
+
+Three small demos of rewriting SQL through the parse tree instead of by string
+manipulation. Each takes no arguments; the query is inline in its source.
+
+| Class | What it rewrites |
+|-------|------------------|
+| `replaceTablename` | Swaps a table reference for a derived table, rewriting every qualified column that pointed at it |
+| `replaceConstant` | Turns literals into `?` bind parameters |
+| `add2SQL` | Adds conditions to a `WHERE` clause |
+
+## Usage
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.modifysql.replaceTablename \
+    -Dexec.classpathScope=compile
+```
+
+```text
+input sql:
+select table1.col1, table2.col2
+from table1, table2
+where table1.foo > table2.foo
+
+output sql:
+select table1.col1, table3.col2
+from table1, (tableX join tableY using (id)) as table3
+where table1.foo > table3.foo
+```
+
+Note that `table2.col2` and `table2.foo` both became `table3.…`: the aliases
+follow the substitution, which is the part that string replacement gets wrong.
+
+`replaceConstant` turns `VALUES ('arun','deep')` into `VALUES (?,?)` — the usual
+first step in retrofitting prepared statements onto generated SQL.

src/main/java/gudusoft/gsqlparser/demos/performance/readme.md

@@ -0,0 +1,35 @@
+## Description
+
+Two demos about the cost of creating parsers rather than the cost of parsing.
+
+Building a `TGSqlParser` loads the grammar tables for its dialect, which is by
+far the most expensive part of a single parse — roughly a second in the run
+below. Pooling parsers amortises that away, which matters for a service parsing
+many statements.
+
+| Class | What it does |
+|-------|--------------|
+| `ParserPoolDemo` | Walks through the pool's behaviour: initialisation cost, then reuse |
+| `ParserPoolBenchmark` | Timed comparison of pooled versus non-pooled parsing |
+
+## Usage
+
+Neither takes arguments.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.performance.ParserPoolDemo \
+    -Dexec.classpathScope=compile
+```
+
+```text
+========================================
+    SQL Parser Pool Demonstration
+========================================
+
+=== Initialization Phase ===
+Loading grammar tables (one-time cost)...
+Grammar tables loaded in 907 ms
+```
+
+`ParserPoolBenchmark` runs longer; the API it exercises is
+`TParserPoolFactory`.

src/main/java/gudusoft/gsqlparser/demos/removeCondition/readme.md

@@ -0,0 +1,30 @@
+## Description
+
+Removes conditions from a `WHERE` clause through the parse tree, leaving the
+rest of the statement, including its `GROUP BY`, intact.
+
+Useful for stripping tenant or environment filters out of a query before
+analysing it, or for producing the "unfiltered" form of a report query.
+
+Compare `removeSpecialConditions`, which targets particular condition shapes,
+and `sqlrefactor`, which cleans up redundant parentheses.
+
+## Usage
+
+Takes no arguments; the query is inline in `removeCondition.java`.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.removeCondition.removeCondition \
+    -Dexec.classpathScope=compile
+```
+
+```text
+SELECT SUM (d.amt)
+FROM summit.cntrb_detail d
+WHERE d.fund_coll_attrb IN ( 'ShanXi University' )
+AND d.fund_acct IN ( 'Eclipse.org' )
+GROUP BY d.id;
+```
+
+There is also a test covering this demo at
+`src/test/java/gudusoft/gsqlparser/removeConditionTest/`.