001package gudusoft.gsqlparser.resolver2.format;
002
003/**
004 * Controls how identifier names are rendered for display output.
005 *
006 * <p>This mode determines the "visual style" of the output - whether to show
007 * raw SQL form with quotes, clean display form without quotes, or canonical form.</p>
008 *
009 * <p>Note: This is separate from {@link DisplayNamePolicy} which determines
010 * "which occurrence to use" when the same object appears multiple times with
011 * different spellings.</p>
012 *
013 * <h3>Example with SQL Server:</h3>
014 * <pre>
015 * SQL: SELECT [OrderID] FROM [dbo].[SalesOrder]
016 *
017 * DISPLAY:    dbo.SalesOrder, OrderID (quotes stripped, case preserved)
018 * SQL_RENDER: [dbo].[SalesOrder], [OrderID] (quotes preserved)
019 * CANONICAL:  dbo.SalesOrder, OrderID (SQL Server stores names as written,
020 *             so its canonical form folds nothing and matches DISPLAY here)
021 *
022 * The same names under Oracle, where unquoted identifiers DO fold:
023 *
024 * SQL: SELECT OrderID, "Order Date" FROM SalesOrder
025 *
026 * DISPLAY:    SalesOrder, OrderID, Order Date
027 * CANONICAL:  SALESORDER, ORDERID, Order Date   ("Order Date" was quoted, so it keeps its case)
028 * </pre>
029 *
030 * @see DisplayNamePolicy
031 * @see DisplayNameNormalizer
032 */
033public enum DisplayNameMode {
034
035    /**
036     * Display mode: strip delimiters, preserve original case.
037     *
038     * <p>Recommended for debugging and test output. Produces clean, readable
039     * output that reflects what the user wrote (minus the quote noise).</p>
040     *
041     * <p>Examples:</p>
042     * <ul>
043     *   <li>{@code [OrderID]} → {@code OrderID}</li>
044     *   <li>{@code `kalyan-DB`} → {@code kalyan-DB}</li>
045     *   <li>{@code "MyTable"} → {@code MyTable}</li>
046     * </ul>
047     */
048    DISPLAY,
049
050    /**
051     * SQL render mode: the name written as valid SQL for the vendor.
052     *
053     * <p>"Valid SQL that names this object" is a constraint, not a value: {@code dbo},
054     * {@code [dbo]} and {@code "dbo"} all satisfy it. The spelling is therefore GENERATED by
055     * rule rather than echoed from whichever reference was read, and
056     * {@code SqlNameGenerator.QuotePolicy} is the parameter that makes it unique:</p>
057     * <ul>
058     *   <li>{@code WHEN_NEEDED} (default): delimit only where the bare word would be invalid,
059     *       would denote another object, or is a keyword.
060     *       {@code [dbo].[Sales Order]} → {@code dbo.[Sales Order]};
061     *       MySQL {@code `t`.`date`} → {@code t.`date`}</li>
062     *   <li>{@code ALWAYS}: delimit every segment. {@code dbo.T} → {@code [dbo].[T]}</li>
063     * </ul>
064     *
065     * <p>A name written without delimiters is returned as written: it is already valid SQL for
066     * that object, and folding its case would need the catalog's stored case, which SQL text
067     * does not reveal. One object written several ways still yields ONE listing row, chosen by
068     * {@link DisplayNamePolicy}.</p>
069     */
070    SQL_RENDER,
071
072    /**
073     * Canonical mode: apply vendor-specific case folding.
074     *
075     * <p>Produces output matching the database's internal canonical form.
076     * Useful for comparing against metadata or catalog information.</p>
077     *
078     * <p>Examples (vendor-dependent):</p>
079     * <ul>
080     *   <li>Oracle: {@code MyTable} → {@code MYTABLE} (unquoted folds to upper)</li>
081     *   <li>PostgreSQL: {@code MyTable} → {@code mytable} (unquoted folds to lower)</li>
082     *   <li>BigQuery: {@code MyTable} → {@code MyTable} (case-sensitive)</li>
083     * </ul>
084     */
085    CANONICAL
086}