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), falls back to
040     * catalog metadata when the object resolved to a catalog entry, and only then to first
041     * occurrence. Metadata sits in the middle because without a definition site the remaining
042     * spellings are arbitrary references, and "first occurrence" alone would make the printed
043     * name depend on statement order — inserting an unrelated statement at the top of a
044     * script would rename the table in the output.</p>
045     *
046     * <p>A policy chooses AMONG spellings: an object that is only ever written one way is
047     * printed as written, whatever the catalog says.</p>
048     */
049    PREFER_DEFINITION_SITE,
050
051    /**
052     * Prefer the first occurrence in the SQL text.
053     *
054     * <p>Uses the spelling from the earliest position (by offset/line/column)
055     * in the source SQL. This provides deterministic output based purely on
056     * source order.</p>
057     *
058     * <p>Example:</p>
059     * <pre>
060     * SELECT * FROM Emp WHERE emp.id = 1;
061     * -- First occurrence is "Emp", so output: Tables: Emp
062     * </pre>
063     */
064    PREFER_FIRST_OCCURRENCE,
065
066    /**
067     * Prefer the spelling from database metadata.
068     *
069     * <p>Uses the canonical name stored in the database catalog/metadata.
070     * Requires that the resolver has access to metadata (via SQLEnv) and
071     * that the object was successfully resolved to a catalog entry.</p>
072     *
073     * <p>Useful when output should match the "official" database names,
074     * especially for databases where table names are case-sensitive
075     * (like BigQuery).</p>
076     *
077     * <p>If metadata is unavailable, falls back to PREFER_DEFINITION_SITE.</p>
078     */
079    PREFER_METADATA
080}