using System.Text; using Strata.SqlTools.SqlBreakdown.Expressions; using Strata.SqlTools.Visitors.SqlServer; namespace Strata.SqlTools.Markdown.Expressions; /// /// Generates simplified markdown documentation for Expression trees focused on readability. /// public class SimpleExpressionGenerator { private readonly CommandVisitor _sqlVisitor = new(); /// /// Generates a simple markdown document from an Expression. /// /// The expression to document. /// Optional title for the documentation. /// A markdown formatted string documenting the expression. public string GenerateMarkdown(Expression expression, string? title = null) { var sb = new StringBuilder(); if (!string.IsNullOrWhiteSpace(title)) { sb.AppendLine($"# {title}"); sb.AppendLine(); } sb.AppendLine("## Expression"); sb.AppendLine(); sb.AppendLine("```sql"); sb.AppendLine(expression.Accept(_sqlVisitor)); sb.AppendLine("```"); sb.AppendLine(); sb.AppendLine("## Type Information"); sb.AppendLine(); sb.AppendLine($"- **Expression Type:** `{expression.GetType().Name}`"); sb.AppendLine($"- **Namespace:** `{expression.GetType().Namespace}`"); sb.AppendLine(); sb.AppendLine("## Description"); sb.AppendLine(); sb.AppendLine(GetExpressionDescription(expression)); sb.AppendLine(); return sb.ToString(); } /// /// Generates a comparison table for multiple expressions. /// /// Dictionary of expression names to expressions. /// Optional title for the table. /// A markdown formatted comparison table. public string GenerateComparisonTable(Dictionary expressions, string? title = null) { var sb = new StringBuilder(); if (!string.IsNullOrWhiteSpace(title)) { sb.AppendLine($"# {title}"); sb.AppendLine(); } sb.AppendLine("| Name | Expression | Type |"); sb.AppendLine("|------|------------|------|"); foreach (var (name, expr) in expressions) { var sql = expr.Accept(_sqlVisitor).Replace("|", "\\|").Replace("\n", " "); var type = expr.GetType().Name; sb.AppendLine($"| {name} | `{sql}` | `{type}` |"); } sb.AppendLine(); return sb.ToString(); } /// /// Generates a bulleted list of expressions. /// /// List of expressions to document. /// Optional title for the list. /// A markdown formatted bulleted list. public string GenerateBulletList(IEnumerable expressions, string? title = null) { var sb = new StringBuilder(); if (!string.IsNullOrWhiteSpace(title)) { sb.AppendLine($"## {title}"); sb.AppendLine(); } foreach (var expr in expressions) { var sql = expr.Accept(_sqlVisitor).Replace("\n", " "); sb.AppendLine($"- `{sql}` - *{expr.GetType().Name}*"); } sb.AppendLine(); return sb.ToString(); } private static string GetExpressionDescription(Expression expression) { var typeName = expression.GetType().Name; return typeName switch { "AndExpression" => "A logical AND expression that combines two boolean expressions. Both expressions must evaluate to true for the result to be true.", "OrExpression" => "A logical OR expression that combines two boolean expressions. Either expression can evaluate to true for the result to be true.", "NotExpression" => "A logical NOT expression that negates a boolean expression.", "ComparisonOperatorExpression" => "A comparison expression that compares two values using an operator (=, <>, <, >, <=, >=).", "ArithmeticExpression" => "An arithmetic expression that performs mathematical operations (+, -, *, /) on numeric values.", "FunctionExpression" => "A SQL function call expression that invokes a database function with arguments.", "AggregateFunctionExpression" => "An aggregate function expression (SUM, COUNT, AVG, MIN, MAX) that operates on sets of values.", "CaseExpression" => "A CASE expression that provides conditional logic similar to if-then-else statements.", "InExpression" => "An IN expression that checks if a value exists in a set of values.", "BetweenExpression" => "A BETWEEN expression that checks if a value falls within a range.", "LikeExpression" => "A LIKE expression that performs pattern matching on strings using wildcards.", "NumberLiteralExpression" => "A numeric literal value.", "StringLiteralExpression" => "A string literal value enclosed in quotes.", "DateTimeLiteralExpression" => "A date/time literal value.", "BooleanLiteralExpression" => "A boolean literal value (true/false).", "NullLiteralExpression" => "A NULL literal value representing absence of data.", "ParameterExpression" => "A parameterized value placeholder that will be substituted at runtime.", "ColumnExpression" => "A reference to a database column from a table or view.", _ => $"A {typeName} expression." }; } }