Introduce FormatSQL API to allow customizing different formats

Author: git-hulk

AGENTS.md

@@ -0,0 +1,31 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `main.go` is the CLI entry point (`clickhouse-sql-parser`) for AST output and SQL formatting.
+- `parser/` contains core parser code: lexer (`lexer.go`), AST definitions (`ast.go`), traversal helpers (`walk.go`), and grammar-specific parser files (`parser_query.go`, `parser_table.go`, `parser_alter.go`, etc.).
+- Tests live next to source as `*_test.go` files, with fixtures under `parser/testdata/`.
+- Fixture groups are organized by SQL type (`basic/`, `query/`, `dml/`, `ddl/`), with generated expectations in `output/` (AST JSON) and `format/` (formatted SQL).
+
+## Build, Test, and Development Commands
+- `make` (or `go build -o clickhouse-sql-parser main.go`): build the CLI binary.
+- `make test`: run full test suite with race detection, coverage output (`coverage.out`), and compatibility tests.
+- `make update_test`: regenerate golden fixtures after intentional parser/formatter output changes.
+- `make lint`: run `golangci-lint` using the repo configuration.
+- `go test -bench=. -benchmem ./parser`: run parser benchmarks.
+
+## Coding Style & Naming Conventions
+- Use Go 1.21 conventions (`go.mod`) and keep code `gofmt`/`goimports` clean (enforced by lint).
+- Place parsing logic in the matching module by statement family (for example, query parsing in `parser/parser_query.go`).
+- Follow existing parser naming patterns such as `parseXxx` helpers and explicit AST type names.
+- Keep AST `String()` output deterministic; formatting changes must be reflected in golden files.
+
+## Testing Guidelines
+- Use Go’s `testing` package with `testify/require` assertions and `goldie` snapshot comparisons.
+- Add new SQL cases as `.sql` files under the appropriate `parser/testdata/<category>/` directory.
+- If expected outputs change, run `make update_test` and commit updated files in both `output/` and/or `format/`.
+- Prefer descriptive test names (`TestParser_*`, `TestWalk_*`) and subtests for per-fixture coverage.
+
+## Commit & Pull Request Guidelines
+- Match existing commit style: concise, imperative subjects like `Add support for ...` or `Fix parsing failure ...`, optionally with issue refs (for example `(#235)`).
+- Keep PRs focused; describe grammar/AST impact, include representative SQL examples, and note regenerated fixtures.
+- Before requesting review, run `make lint` and `make test` locally to mirror CI expectations.

CLAUDE.md

@@ -67,9 +67,9 @@ if err != nil {
     return nil, err
 }
 
-// Call the String method to unparsed AST into a SQL string
+// Format AST back into a SQL string
 for _, stmt := range statements {
-  fmt.Println(stmt.String())
+  fmt.Println(clickhouse.Format(stmt))
 }
 ```
 

README.md

@@ -12,18 +12,20 @@ import (
 
 const VERSION = "0.4.17"
 const help = `
-Usage: clickhouse-sql-parser [YOUR SQL STRING] -f [YOUR SQL FILE] -format
+Usage: clickhouse-sql-parser [YOUR SQL STRING] -f [YOUR SQL FILE] -format -beautify
 `
 
 var options struct {
-	help    bool
-	file    string
-	format  bool
-	version bool
+	help     bool
+	file     string
+	format   bool
+	beautify bool
+	version  bool
 }
 
 func init() {
-	flag.BoolVar(&options.format, "format", false, "Beautify print the ClickHouse SQL")
+	flag.BoolVar(&options.format, "format", false, "Print formatted ClickHouse SQL")
+	flag.BoolVar(&options.beautify, "beautify", false, "Beautify print the ClickHouse SQL")
 	flag.StringVar(&options.file, "f", "", "Parse SQL from file")
 	flag.BoolVar(&options.help, "h", false, "Print help message")
 	flag.BoolVar(&options.version, "v", false, "Print version")
@@ -61,12 +63,19 @@ func main() {
 		fmt.Fprintf(os.Stderr, "parse statements error: %s\n", err.Error())
 		os.Exit(1)
 	}
-	if !options.format { // print AST
+	if !options.format && !options.beautify { // print AST
 		bytes, _ := json.MarshalIndent(stmts, "", "  ") // nolint
 		fmt.Println(string(bytes))
 	} else { // format SQL
 		for _, stmt := range stmts {
-			fmt.Println(stmt.String())
+			if options.beautify {
+				formatter := clickhouse.NewFormatter()
+				formatter.WithBeautify()
+				formatter.WriteExpr(stmt)
+				fmt.Println(formatter.String())
+			} else {
+				fmt.Println(clickhouse.Format(stmt))
+			}
 		}
 	}
 }