001package gudusoft.gsqlparser.resolver2.format;
002
003/**
004 * Policy for choosing the representative display name when the same object
005 * appears multiple times with different spellings (e.g., different case).
006 *
007 * <p>This policy determines "which occurrence to use" for deduplicated output
008 * like Tables/Fields lists. It is separate from {@link DisplayNameMode} which
009 * controls the visual rendering style.</p>
010 *
011 * <h3>Example:</h3>
012 * <pre>
013 * SQL (Oracle): SELECT * FROM Emp; SELECT * FROM EMP;
014 *
015 * Both "Emp" and "EMP" refer to the same table (Oracle is case-insensitive for unquoted).
016 * When outputting the deduplicated Tables: list, which name do we use?
017 *
018 * PREFER_DEFINITION_SITE:    Use the definition site spelling (if available)
019 * PREFER_FIRST_OCCURRENCE:   Use "Emp" (first occurrence in SQL)
020 * PREFER_METADATA:           Use whatever is stored in the database catalog
021 * </pre>
022 *
023 * @see DisplayNameMode
024 * @see DisplayNameNormalizer
025 */
026public enum DisplayNamePolicy {
027
028    /**
029     * Prefer the spelling from the definition site.
030     *
031     * <p>This is the recommended default. It uses the name as written at the
032     * object's definition location:</p>
033     * <ul>
034     *   <li>CTE name: use the spelling in {@code WITH cte_name AS (...)}</li>
035     *   <li>Table alias: use the spelling in {@code FROM table AS alias}</li>
036     *   <li>CTAS target: use the spelling in {@code CREATE TABLE target AS ...}</li>
037     * </ul>
038     *
039     * <p>If no definition site exists (e.g., external table reference),
040     * falls back to first occurrence.</p>
041     */
042    PREFER_DEFINITION_SITE,
043
044    /**
045     * Prefer the first occurrence in the SQL text.
046     *
047     * <p>Uses the spelling from the earliest position (by offset/line/column)
048     * in the source SQL. This provides deterministic output based purely on
049     * source order.</p>
050     *
051     * <p>Example:</p>
052     * <pre>
053     * SELECT * FROM Emp WHERE emp.id = 1;
054     * -- First occurrence is "Emp", so output: Tables: Emp
055     * </pre>
056     */
057    PREFER_FIRST_OCCURRENCE,
058
059    /**
060     * Prefer the spelling from database metadata.
061     *
062     * <p>Uses the canonical name stored in the database catalog/metadata.
063     * Requires that the resolver has access to metadata (via SQLEnv) and
064     * that the object was successfully resolved to a catalog entry.</p>
065     *
066     * <p>Useful when output should match the "official" database names,
067     * especially for databases where table names are case-sensitive
068     * (like BigQuery).</p>
069     *
070     * <p>If metadata is unavailable, falls back to PREFER_DEFINITION_SITE.</p>
071     */
072    PREFER_METADATA
073}