docs: Add comprehensive Godoc examples for pkg/gosqlx (closes #59) (#100)

ajitpratap0 · Ajit Pratap Singh · claude · web-flow · commit e0f5a4dafedc · 2025-11-16T23:11:36.000+05:30
* feat: add stdin/stdout pipeline support (closes #65) Implement comprehensive stdin/stdout pipeline support for all CLI commands (validate, format, analyze, parse) with Unix pipeline conventions and cross-platform compatibility. Features: - Auto-detection: Commands automatically detect piped input - Explicit stdin: Support "-" as stdin marker for all commands - Input redirection: Full support for "< file.sql" syntax - Broken pipe handling: Graceful handling of Unix EPIPE errors - Security: 10MB input limit to prevent DoS attacks - Cross-platform: Works on Unix/Linux/macOS and Windows PowerShell Implementation: - Created stdin_utils.go with pipeline utilities: - IsStdinPipe(): Detects piped input using golang.org/x/term - ReadFromStdin(): Reads from stdin with size limits - GetInputSource(): Unified input detection (stdin/file/direct SQL) - WriteOutput(): Handles stdout and file output with broken pipe detection - DetectInputMode(): Determines input mode based on args and stdin state - ValidateStdinInput(): Security validation for stdin content - Updated all commands with stdin support: - validate.go: Stdin validation with temp file approach - format.go: Stdin formatting (blocks -i flag appropriately) - analyze.go: Stdin analysis with direct content processing - parse.go: Stdin parsing with direct content processing - Dependencies: - Added golang.org/x/term for stdin detection - Testing: - Unit tests: stdin_utils_test.go with comprehensive coverage - Integration tests: pipeline_integration_test.go for real pipeline testing - Manual testing: Validated echo, cat, and redirect operations - Documentation: - Updated README.md with comprehensive pipeline examples - Unix/Linux/macOS and Windows PowerShell examples - Git hooks integration examples Usage Examples: echo "SELECT * FROM users" | gosqlx validate cat query.sql | gosqlx format gosqlx validate - gosqlx format < query.sql cat query.sql | gosqlx format | gosqlx validate Cross-platform: # Unix/Linux/macOS cat query.sql | gosqlx format | tee formatted.sql | gosqlx validate # Windows PowerShell Get-Content query.sql | gosqlx format | Set-Content formatted.sql "SELECT * FROM users" | gosqlx validate Security: - 10MB stdin size limit (MaxStdinSize constant) - Binary data detection (null byte check) - Input validation before processing - Temporary file cleanup in validate command 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: resolve CI failures for PR #97 Fixed 3 critical issues causing all CI builds/tests to fail: 1. Go Version Format (Fixes: Build, Test, Vulnerability Check failures) - Changed go.mod from 'go 1.24.0' (three-part) to 'go 1.24' (two-part) - Three-part format not supported by Go 1.19/1.20 toolchains in CI - Error: 'invalid go version 1.24.0: must match format 1.23' 2. Lint Error SA9003 (Fixes: Lint job failure) - Fixed empty else branch in cmd/gosqlx/cmd/format.go:169-173 - Removed unnecessary else block while preserving same behavior - Staticcheck SA9003: empty branch warning resolved 3. Workflow Go Version Mismatch (Fixes: Security scan failures) - Updated .github/workflows/security.yml to use Go 1.24 - Both GoSec and GovulnCheck jobs now use Go 1.24 - Matches project requirements for golang.org/x/term v0.37.0 All changes maintain backward compatibility and functionality. Related: #65 (stdin/stdout pipeline feature) * fix: update all CI workflows to use Go 1.24 Updated Go version across all GitHub Actions workflows to match go.mod requirements: - .github/workflows/go.yml: Changed build matrix from [1.19, 1.20, 1.21] to [1.24] - .github/workflows/test.yml: Changed test matrix from [1.19, 1.20, 1.21] to [1.24] - .github/workflows/test.yml: Changed benchmark job from 1.21 to 1.24 - .github/workflows/lint.yml: Changed from 1.21 to 1.24 This fixes all remaining CI failures caused by incompatibility between: - Project dependencies (golang.org/x/term v0.37.0) requiring Go 1.24 - Old workflow configurations using Go 1.19-1.21 Related: PR #97, Issue #65 * chore: run go mod tidy to sync dependencies Running go mod tidy updates go.mod format to go 1.24.0 (three-part) which is the standard format for Go 1.24+. This resolves build failures caused by out-of-sync go.mod and go.sum files. Note: Go 1.24 supports both two-part (1.24) and three-part (1.24.0) formats, but go mod tidy standardizes on three-part format. * fix: remove empty if block in validate.go (SA9003) * fix: update staticcheck to latest version for Go 1.24 compatibility * fix: use os.TempDir() for cross-platform test compatibility - Replace hardcoded /tmp/ path with os.TempDir() - Add path/filepath import for filepath.Join - Fixes Windows test failure in TestWriteOutput * docs: add comprehensive Godoc examples for pkg/gosqlx package - Add 15 function-specific examples (ExampleParse, ExampleValidate, etc.) that appear directly in pkg.go.dev function documentation - Examples cover all major functions: Parse, Validate, Format, Extract* - All examples include proper Output comments for go test verification - Examples demonstrate real-world use cases and best practices - Improves pkg.go.dev discoverability and developer onboarding Issue: #59 --------- Co-authored-by: Ajit Pratap Singh <ajitpratapsingh@Ajits-Mac-mini.local> Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/pkg/gosqlx/example_test.go b/pkg/gosqlx/example_test.go
@@ -1,12 +1,227 @@
 package gosqlx_test
 
 import (
+	"context"
 	"fmt"
 	"log"
+	"time"
 
 	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
 )
 
+// ExampleParse demonstrates basic SQL parsing.
+func ExampleParse() {
+	sql := "SELECT * FROM users WHERE active = true"
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Parsed %d statement(s)\n", len(ast.Statements))
+	// Output: Parsed 1 statement(s)
+}
+
+// ExampleValidate demonstrates SQL validation.
+func ExampleValidate() {
+	sql := "SELECT * FROM users"
+	if err := gosqlx.Validate(sql); err != nil {
+		fmt.Printf("Invalid SQL: %v\n", err)
+		return
+	}
+
+	fmt.Println("Valid SQL")
+	// Output: Valid SQL
+}
+
+// ExampleParseMultiple demonstrates parsing multiple SQL statements efficiently.
+func ExampleParseMultiple() {
+	queries := []string{
+		"SELECT * FROM users",
+		"SELECT * FROM orders",
+		"SELECT * FROM products",
+	}
+
+	asts, err := gosqlx.ParseMultiple(queries)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Parsed %d queries\n", len(asts))
+	// Output: Parsed 3 queries
+}
+
+// ExampleFormat demonstrates SQL formatting with options.
+func ExampleFormat() {
+	sql := "SELECT * FROM users WHERE active = true"
+
+	opts := gosqlx.DefaultFormatOptions()
+	opts.AddSemicolon = true
+
+	formatted, err := gosqlx.Format(sql, opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Formatted SQL ends with semicolon: %v\n", formatted[len(formatted)-1] == ';')
+	// Output: Formatted SQL ends with semicolon: true
+}
+
+// ExampleParseWithContext demonstrates parsing with context for cancellation.
+func ExampleParseWithContext() {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	sql := "SELECT * FROM users"
+	ast, err := gosqlx.ParseWithContext(ctx, sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Parsed with context: %d statement(s)\n", len(ast.Statements))
+	// Output: Parsed with context: 1 statement(s)
+}
+
+// ExampleParseWithTimeout demonstrates parsing with a timeout.
+func ExampleParseWithTimeout() {
+	sql := "SELECT * FROM users"
+	ast, err := gosqlx.ParseWithTimeout(sql, 5*time.Second)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Parsed with timeout: %d statement(s)\n", len(ast.Statements))
+	// Output: Parsed with timeout: 1 statement(s)
+}
+
+// ExampleMustParse demonstrates MustParse for SQL literals.
+func ExampleMustParse() {
+	// Use MustParse only with SQL literals you control
+	ast := gosqlx.MustParse("SELECT 1")
+
+	fmt.Printf("Type: %T\n", ast)
+	// Output: Type: *ast.AST
+}
+
+// ExampleParseBytes demonstrates parsing from a byte slice.
+func ExampleParseBytes() {
+	sqlBytes := []byte("SELECT * FROM users")
+
+	ast, err := gosqlx.ParseBytes(sqlBytes)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Printf("Parsed from bytes: %d statement(s)\n", len(ast.Statements))
+	// Output: Parsed from bytes: 1 statement(s)
+}
+
+// ExampleValidateMultiple demonstrates validating multiple SQL statements.
+func ExampleValidateMultiple() {
+	queries := []string{
+		"SELECT * FROM users",
+		"INSERT INTO users (name) VALUES ('test')",
+		"UPDATE users SET active = true WHERE id = 1",
+	}
+
+	if err := gosqlx.ValidateMultiple(queries); err != nil {
+		fmt.Printf("Validation failed: %v\n", err)
+		return
+	}
+
+	fmt.Println("All queries valid")
+	// Output: All queries valid
+}
+
+// ExampleExtractTables demonstrates extracting table names from a query.
+func ExampleExtractTables() {
+	sql := "SELECT * FROM users u JOIN orders o ON u.id = o.user_id"
+
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tables := gosqlx.ExtractTables(ast)
+	fmt.Printf("Found %d tables\n", len(tables))
+	// Output: Found 2 tables
+}
+
+// ExampleExtractColumns demonstrates extracting column names from a query.
+func ExampleExtractColumns() {
+	sql := "SELECT u.name, u.email FROM users u WHERE u.active = true ORDER BY u.created_at"
+
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	columns := gosqlx.ExtractColumns(ast)
+	fmt.Printf("Found %d columns\n", len(columns))
+	// Output: Found 4 columns
+}
+
+// ExampleExtractFunctions demonstrates extracting function names from a query.
+func ExampleExtractFunctions() {
+	sql := "SELECT COUNT(*), AVG(salary), UPPER(name) FROM employees"
+
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	functions := gosqlx.ExtractFunctions(ast)
+	fmt.Printf("Found %d functions\n", len(functions))
+	// Output: Found 3 functions
+}
+
+// ExampleExtractMetadata demonstrates extracting comprehensive metadata from a query.
+func ExampleExtractMetadata() {
+	sql := `SELECT u.name, COUNT(o.id) as order_count
+		FROM users u
+		LEFT JOIN orders o ON u.id = o.user_id
+		WHERE u.active = true
+		GROUP BY u.name
+		HAVING COUNT(o.id) > 5`
+
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	metadata := gosqlx.ExtractMetadata(ast)
+	fmt.Printf("Tables: %d, Columns: %d, Functions: %d\n",
+		len(metadata.Tables), len(metadata.Columns), len(metadata.Functions))
+	// Output: Tables: 2, Columns: 4, Functions: 1
+}
+
+// ExampleExtractTablesQualified demonstrates extracting qualified table names.
+func ExampleExtractTablesQualified() {
+	sql := "SELECT * FROM users JOIN orders ON users.id = orders.user_id"
+
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	tables := gosqlx.ExtractTablesQualified(ast)
+	fmt.Printf("Found %d tables\n", len(tables))
+	// Output: Found 2 tables
+}
+
+// ExampleExtractColumnsQualified demonstrates extracting qualified column names.
+func ExampleExtractColumnsQualified() {
+	sql := "SELECT u.name, u.email FROM users u WHERE u.active = true"
+
+	ast, err := gosqlx.Parse(sql)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	columns := gosqlx.ExtractColumnsQualified(ast)
+	fmt.Printf("Found %d qualified columns\n", len(columns))
+	// Output: Found 3 qualified columns
+}
+
 // Example_simple demonstrates the simplest way to parse SQL.
 func Example_simple() {
 	sql := "SELECT * FROM users"
