package gudusoft.gsqlparser.parser;

import gudusoft.gsqlparser.EDbVendor;

/**
 * Strategy interface for vendor-specific SQL parsing.
 *
 * <p>This interface defines the contract for all database vendor-specific parsers.
 * Each vendor (Oracle, MySQL, PostgreSQL, etc.) provides its own implementation
 * that handles the vendor-specific tokenization, parsing, and semantic analysis.
 *
 * <p><b>Design Pattern:</b> Strategy Pattern
 * <ul>
 *   <li>The strategy (SqlParser) is selected at runtime based on database vendor</li>
 *   <li>All inputs come from {@link ParserContext} (immutable)</li>
 *   <li>All outputs go to {@link SqlParseResult} (immutable)</li>
 * </ul>
 *
 * <p><b>Usage Example:</b>
 * <pre>
 * // Get parser for specific vendor
 * SqlParser parser = SqlParserFactory.get(EDbVendor.dbvoracle);
 *
 * // Build context with inputs
 * ParserContext context = new ParserContext.Builder(EDbVendor.dbvoracle)
 *     .sqlText("SELECT * FROM employees")
 *     .build();
 *
 * // Parse and get result
 * SqlParseResult result = parser.parse(context);
 *
 * // Access outputs
 * TStatementList statements = result.getSqlStatements();
 * </pre>
 *
 * @see ParserContext
 * @see SqlParseResult
 * @see AbstractSqlParser
 * @since 3.2.0.0
 */
public interface SqlParser {

    /**
     * Get the database vendor this parser handles.
     *
     * @return the database vendor (e.g., dbvoracle, dbvmysql)
     */
    EDbVendor getVendor();

    /**
     * Parse SQL from the given context.
     *
     * <p>This method performs full parsing including:
     * <ul>
     *   <li>Tokenization (lexical analysis)</li>
     *   <li>Syntax analysis (building parse tree)</li>
     *   <li>Semantic analysis (resolving references)</li>
     * </ul>
     *
     * <p>All inputs come from the context parameter, all outputs go to the result.
     * This ensures clean separation of concerns and thread-safety.
     *
     * @param context immutable context containing all parser inputs
     *                (SQL text, options, callbacks, etc.)
     * @return immutable result containing all parser outputs
     *         (statements, tokens, errors, etc.)
     */
    SqlParseResult parse(ParserContext context);

    /**
     * Tokenize SQL without parsing or statement extraction.
     *
     * <p>This method performs only tokenization (lexical analysis):
     * <ul>
     *   <li>Tokenization (lexical analysis)</li>
     * </ul>
     *
     * <p>The result contains tokens but NO statements. Use this when you only
     * need the token stream (e.g., for syntax highlighting, token analysis).
     *
     * <p>For statement boundaries without full parsing, use {@link #getrawsqlstatements(ParserContext)}.
     *
     * @param context immutable context containing all parser inputs
     * @return immutable result containing tokens only (no statements)
     */
    SqlParseResult tokenize(ParserContext context);

    /**
     * Vendor policy validation, run by {@code TGSqlParser} AFTER every statement
     * has been parsed ("recognize then reject", Sybase family decomposition).
     *
     * <p>Runs post-parse on purpose: some statement objects are REPLACED during
     * parsing (the refined statement is built from the parse-tree node), so an
     * error attached at raw-extraction time can silently vanish with the old
     * object. Post-parse, the statements are final.
     *
     * <p>Default is a no-op returning {@code null} — behaviour of every vendor
     * that does not override this is untouched.
     *
     * @param statements the fully parsed statement list
     * @return statements this vendor rejects (errors already attached), or null
     */
    default java.util.List<gudusoft.gsqlparser.TCustomSqlStatement>
            validateRecognizedStatements(gudusoft.gsqlparser.TStatementList statements) {
        return null;
    }

    /**
     * Extract raw SQL statements without full parsing.
     *
     * <p>This method performs:
     * <ul>
     *   <li>Tokenization (lexical analysis)</li>
     *   <li>Raw statement extraction (statement boundary detection)</li>
     * </ul>
     *
     * <p>This is faster than {@link #parse(ParserContext)} because it skips
     * detailed syntax checking and semantic analysis. The statements returned
     * have their tokens grouped correctly but no AST (parse tree) is built.
     *
     * <p><b>Use cases:</b>
     * <ul>
     *   <li>Split a script into individual statements</li>
     *   <li>Determine statement types without full parsing</li>
     *   <li>Quick validation of statement boundaries</li>
     *   <li>Pre-processing before selective parsing</li>
     * </ul>
     *
     * <p><b>Equivalent to legacy API:</b> {@code TGSqlParser.getrawsqlstatements()}
     *
     * <p><b>Default implementation:</b> For parsers still in delegation phase,
     * this default implementation falls back to {@link #tokenize(ParserContext)}.
     * Parsers extending AbstractSqlParser override this with proper implementation.
     *
     * @param context immutable context containing all parser inputs
     * @return immutable result containing tokens and raw statements (no AST)
     */
    default SqlParseResult getrawsqlstatements(ParserContext context) {
        // Default implementation for parsers in delegation phase
        // Just tokenize - subclasses should override with proper implementation
        return tokenize(context);
    }

    /**
     * Extract raw statements from already-tokenized source without re-tokenization.
     *
     * <p>This method is used when tokens are already available from a previous
     * tokenization step (e.g., via {@code dosqltexttotokenlist()}). It performs
     * only raw statement extraction without repeating tokenization.
     *
     * <p><b>Default implementation:</b> Falls back to tokenize() method for vendors
     * that haven't implemented this optimization yet.
     *
     * @param context immutable context containing all parser inputs
     * @param tokens already-tokenized source token list
     * @return statement list containing extracted raw statements
     * @since 3.2.0.0
     * @deprecated As of 3.2.0.0, replaced by {@link #getrawsqlstatements(ParserContext)}
     *             which returns a richer {@link SqlParseResult} object containing statements,
     *             tokens, errors, timing information, and more. This method only returns
     *             {@link gudusoft.gsqlparser.TStatementList} without error information.
     *             <p>
     *             <b>Migration:</b> Use {@code vendorParser.getrawsqlstatements(context)}
     *             instead, which performs both tokenization and extraction in a single call
     *             and returns complete result information via {@link SqlParseResult}.
     *             <p>
     *             This method will be removed in a future major version.
     */
    @Deprecated
    default gudusoft.gsqlparser.TStatementList doExtractRawStatements(ParserContext context, gudusoft.gsqlparser.TSourceTokenList tokens) {
        // Default implementation: fall back to tokenize() which does both tokenization and extraction
        // Vendors that extend AbstractSqlParser will override this via the doExtractRawStatements() implementation
//        SqlParseResult result = tokenize(context);
//        return result.getSqlStatements();
        return null; // To be implemented by vendors, this method must be orerridden
    }
}