package gudusoft.gsqlparser.nodes;


import java.util.ArrayList;

/**
 * Represents indirection elements in SQL expressions, supporting both array access and qualified name syntax.
 * This class handles two distinct syntactic patterns found in PostgreSQL and other SQL dialects.
 * 
 * <h3>Array Access Syntax (ARRAY_ACCESS)</h3>
 * Used for accessing array elements and slicing operations:
 * <ul>
 *   <li><code>array_column[5]</code> - Single element access</li>
 *   <li><code>array_column[2:4]</code> - Array slice from index 2 to 4</li>
 *   <li><code>array_column[:3]</code> - Array slice from start to index 3</li>
 *   <li><code>array_column[2:]</code> - Array slice from index 2 to end</li>
 *   <li><code>array_column[:]</code> - Full array slice</li>
 * </ul>
 * 
 * <h3>Qualified Name Syntax (QUALIFIED_NAME)</h3>
 * Used for accessing object fields and properties:
 * <ul>
 *   <li><code>json_column.field_name</code> - Access specific field</li>
 *   <li><code>record_column.*</code> - Access all fields</li>
 *   <li><code>composite_type.attribute</code> - Access composite type attribute</li>
 * </ul>
 * 
 * <h3>Usage Examples</h3>
 * <pre>{@code
 * // Example SQL: SELECT users[1].name FROM user_array;
 * // This creates two TIndices:
 * // 1. TIndices for [1] with type ARRAY_ACCESS
 * // 2. TIndices for .name with type QUALIFIED_NAME
 * 
 * TIndices arrayAccess = ...; // represents [1]
 * if (arrayAccess.isArrayAccess()) {
 *     TExpression index = arrayAccess.getLowerSubscript(); // gets "1"
 *     // Process array index...
 * }
 * 
 * TIndices fieldAccess = ...; // represents .name  
 * if (fieldAccess.isQualifiedName()) {
 *     TObjectName fieldName = fieldAccess.getAttributeName(); // gets "name"
 *     // Process field access...
 * }
 * }</pre>
 * 
 * <h3>SQL Examples by Database</h3>
 * <table border="1">
 * <tr><th>Database</th><th>Array Access</th><th>Field Access</th></tr>
 * <tr><td>PostgreSQL</td><td><code>arr[1], arr[1:3]</code></td><td><code>json_col.field, record.*</code></td></tr>
 * <tr><td>Databricks</td><td><code>array_col[0]</code></td><td><code>struct_col.attr, json.key</code></td></tr>
 * <tr><td>Snowflake</td><td><code>array_col[0]</code></td><td><code>variant_col.field, object.*</code></td></tr>
 * </table>
 * 
 * <h3>Type Safety and Backward Compatibility</h3>
 * This class maintains backward compatibility with existing code while providing type-safe access:
 * <ul>
 *   <li>{@link #isRealIndices()} - Legacy method, still works as before</li>
 *   <li>{@link #isArrayAccess()} - New type-safe method for array access</li>
 *   <li>{@link #isQualifiedName()} - New type-safe method for field access</li>
 *   <li>{@link #getIndicesType()} - Get explicit type information</li>
 * </ul>
 * 
 * <h3>Complete Usage Example</h3>
 * <pre>{@code
 * // Processing SQL: SELECT data[1:3].users.name FROM complex_table;
 * // This would create a chain of TIndices in TIndirection
 * 
 * public void processIndirection(TIndirection indirection) {
 *     for (TIndices indices : indirection.getIndices()) {
 *         switch (indices.getIndicesType()) {
 *             case ARRAY_ACCESS:
 *                 System.out.println("Array access detected:");
 *                 TExpression lower = indices.getLowerSubscript();
 *                 TExpression upper = indices.getUpperSubscript();
 *                 
 *                 if (lower != null && upper != null) {
 *                     System.out.println("  Slice: [" + lower + ":" + upper + "]");
 *                 } else if (lower != null) {
 *                     System.out.println("  Single element: [" + lower + "]");
 *                 }
 *                 break;
 *                 
 *             case QUALIFIED_NAME:
 *                 System.out.println("Field access detected:");
 *                 TObjectName field = indices.getAttributeName();
 *                 System.out.println("  Field: ." + field.toString());
 *                 break;
 *         }
 *     }
 * }
 * 
 * // Legacy compatibility - existing code still works
 * if (indices.isRealIndices()) {
 *     // Handle as array access (legacy approach)
 * } else {
 *     // Handle as field access (legacy approach)  
 * }
 * }</pre>
 * 
 * @see TIndirection
 * @see TExpression
 * @see TObjectName
 * @since PostgreSQL parser support
 */

public class TIndices extends TParseTreeNode {
    
    /**
     * Enum to distinguish between array access syntax and qualified name syntax.
     * 
     * <p><strong>ARRAY_ACCESS</strong> - Represents bracket notation for array/list operations:
     * <ul>
     *   <li><code>[5]</code> - Single element at index 5</li>
     *   <li><code>[2:4]</code> - Slice from index 2 to 4 (inclusive)</li>
     *   <li><code>[:3]</code> - Slice from start to index 3</li>
     *   <li><code>[2:]</code> - Slice from index 2 to end</li>
     *   <li><code>[:]</code> - Full array/list slice</li>
     * </ul>
     * 
     * <p><strong>QUALIFIED_NAME</strong> - Represents dot notation for field/property access:
     * <ul>
     *   <li><code>.field_name</code> - Access specific field or property</li>
     *   <li><code>.*</code> - Access all fields (wildcard expansion)</li>
     * </ul>
     * 
     * @since 1.0
     */
    public enum IndicesType {
        /** Array/list access using bracket notation: [expr], [expr:expr], etc. */
        ARRAY_ACCESS,
        /** Field/property access using dot notation: .field, .* */
        QUALIFIED_NAME,
        /** Function call via dot notation: .func(), .func(args) */
        FUNCTION_CALL
    }
    private TExpression lowerSubscript;
    private TExpression upperSubscript;

    private TObjectName attributeName;
    
    private IndicesType indicesType;
    
    /**
     * Flag indicating whether this array access represents a slice operation (contains colon syntax).
     * 
     * <h3>Purpose and Rationale</h3>
     * <p>This property was introduced to solve a fundamental ambiguity problem in SQL text generation.
     * The core issue was distinguishing between two syntactically different but internally identical
     * array access patterns:
     * 
     * <table border="1">
     * <tr><th>Original SQL</th><th>Internal Representation</th><th>Expected Output</th></tr>
     * <tr><td><code>array[5]</code></td><td>lower=5, upper=null</td><td><code>array[5]</code></td></tr>
     * <tr><td><code>array[5:]</code></td><td>lower=5, upper=null</td><td><code>array[5:]</code></td></tr>
     * </table>
     * 
     * <p>Without this flag, both patterns would have identical field values (lowerSubscript=5, upperSubscript=null),
     * making it impossible for the script generator to determine whether to include the colon in the output.
     * 
     * <h3>How It Works</h3>
     * <p>The parser sets this flag based on the presence of colon syntax in the original BNF rule:
     * <ul>
     *   <li><strong>Single Element Access</strong>: <code>[expr]</code> → isSlice = false</li>
     *   <li><strong>Slice Operations</strong>: <code>[expr:expr]</code>, <code>[:expr]</code>, <code>[expr:]</code>, <code>[:]</code> → isSlice = true</li>
     * </ul>
     * 
     * <h3>Usage in Script Generation</h3>
     * <p>The {@link gudusoft.gsqlparser.scriptWriter.TScriptGeneratorVisitor#preVisit(TIndices)} method
     * uses this flag to determine whether to include a colon in the generated SQL:
     * 
     * <pre>{@code
     * if (node.isSlice()) {
     *     // Output: [lower:upper] or [lower:] or [:upper] or [:]
     *     acceptSymbol(":");
     * } else {
     *     // Output: [lower] (no colon)
     * }
     * }</pre>
     * 
     * <h3>Impact on Accuracy</h3>
     * <p>This property ensures that the generated SQL text exactly matches the original input:
     * <ul>
     *   <li><code>SELECT array[5] FROM table</code> → regenerates as <code>SELECT array[5] FROM table</code></li>
     *   <li><code>SELECT array[5:] FROM table</code> → regenerates as <code>SELECT array[5:] FROM table</code></li>
     * </ul>
     * 
     * <p>This level of accuracy is crucial for SQL formatting tools, query analysis, and any application
     * that needs to preserve the exact semantic meaning of array access operations.
     * 
     * @see #isSlice()
     * @see #setSlice(boolean)
     * @see gudusoft.gsqlparser.scriptWriter.TScriptGeneratorVisitor#preVisit(TIndices)
     * @since Introduction of enhanced array slice support
     */
    private boolean isSlice;

    /**
     * Gets the attribute name for qualified name access patterns.
     * This is only populated for QUALIFIED_NAME type indices (e.g., .field, .*).
     * 
     * <p>Examples:
     * <ul>
     *   <li>For <code>json_col.user_name</code> → returns "user_name"</li>
     *   <li>For <code>record.*</code> → returns "*"</li>
     *   <li>For <code>array[5]</code> → returns null (not a qualified name)</li>
     * </ul>
     * 
     * @return the attribute/field name for qualified access, or null for array access
     * @see #isQualifiedName()
     */
    public TObjectName getAttributeName() {
        return attributeName;
    }

    /**
     * Gets the lower bound expression for array access patterns.
     * This represents the starting index or single index in array access operations.
     * 
     * <p>Examples:
     * <ul>
     *   <li>For <code>arr[5]</code> → returns expression "5"</li>
     *   <li>For <code>arr[2:8]</code> → returns expression "2"</li>
     *   <li>For <code>arr[:3]</code> → returns null (no lower bound)</li>
     *   <li>For <code>obj.field</code> → returns null (not array access)</li>
     * </ul>
     * 
     * @return the lower bound expression, or null if not applicable
     * @see #getUpperSubscript()
     * @see #isArrayAccess()
     */
    public TExpression getLowerSubscript() {
        return lowerSubscript;
    }

    /**
     * Gets the upper bound expression for array slice patterns.
     * This represents the ending index in array slice operations (e.g., [start:end]).
     * 
     * <p>Examples:
     * <ul>
     *   <li>For <code>arr[2:8]</code> → returns expression "8"</li>
     *   <li>For <code>arr[:3]</code> → returns expression "3"</li>
     *   <li>For <code>arr[5]</code> → returns null (single element, not slice)</li>
     *   <li>For <code>arr[2:]</code> → returns null (no upper bound)</li>
     * </ul>
     * 
     * @return the upper bound expression for slices, or null if not a slice or no upper bound
     * @see #getLowerSubscript()
     * @see #isArrayAccess()
     */
    public TExpression getUpperSubscript() {
        return upperSubscript;
    }

    /**
     * Legacy method to check if this represents "real" array indices.
     * 
     * <p><strong>Note:</strong> This method is maintained for backward compatibility.
     * For new code, prefer using {@link #isArrayAccess()} and {@link #isQualifiedName()}
     * for clearer semantic meaning.
     * 
     * <p>Returns true for array access patterns and false for qualified name patterns:
     * <ul>
     *   <li><code>arr[5]</code> → true (real array indices)</li>
     *   <li><code>arr[2:4]</code> → true (real array slice)</li>
     *   <li><code>obj.field</code> → false (not real indices, just field access)</li>
     * </ul>
     * 
     * @return true if this represents array access, false for qualified name access
     * @deprecated Use {@link #isArrayAccess()} for better code clarity
     */
    public  boolean isRealIndices(){
        return (this.attributeName == null);
    }

    /**
     * Gets the explicit type of this indices element.
     * 
     * <p>This method returns the semantic type of the indirection, helping distinguish
     * between array access operations and qualified name field access. The method
     * includes fallback logic for backward compatibility with legacy code.
     * 
     * <p>Type determination logic:
     * <ol>
     *   <li>If explicit type was set via {@link #setIndicesType(IndicesType)}, return that</li>
     *   <li>Otherwise, infer from legacy fields: attributeName present → QUALIFIED_NAME, absent → ARRAY_ACCESS</li>
     * </ol>
     * 
     * @return {@link IndicesType#ARRAY_ACCESS} for bracket notation or {@link IndicesType#QUALIFIED_NAME} for dot notation
     * @see #isArrayAccess()
     * @see #isQualifiedName()
     */
    public IndicesType getIndicesType() {
        if (indicesType != null) {
            return indicesType;
        }
        // Fallback to legacy logic for backward compatibility
        return (attributeName != null) ? IndicesType.QUALIFIED_NAME : IndicesType.ARRAY_ACCESS;
    }
    
    /**
     * Sets the explicit type of this indices element.
     * 
     * <p>This method is typically called by the parser to explicitly mark whether
     * an indices element represents array access or qualified name access.
     * 
     * @param indicesType the semantic type to set - {@link IndicesType#ARRAY_ACCESS} 
     *                   for bracket notation or {@link IndicesType#QUALIFIED_NAME} for dot notation
     * @see #getIndicesType()
     */
    public void setIndicesType(IndicesType indicesType) {
        this.indicesType = indicesType;
    }
    
    /**
     * Checks if this represents an array slice operation (contains colon syntax).
     * 
     * <p>Returns true for slice patterns that contain a colon:
     * <ul>
     *   <li><code>arr[2:8]</code> - Slice with both bounds</li>
     *   <li><code>arr[:3]</code> - Slice with upper bound only</li>
     *   <li><code>arr[2:]</code> - Slice with lower bound only</li>
     *   <li><code>arr[:]</code> - Full slice</li>
     * </ul>
     * 
     * <p>Returns false for single element access:
     * <ul>
     *   <li><code>arr[5]</code> - Single element access (no colon)</li>
     * </ul>
     * 
     * @return true if this represents a slice operation with colon syntax
     * @see #setSlice(boolean)
     */
    public boolean isSlice() {
        return isSlice;
    }
    
    /**
     * Sets whether this represents an array slice operation.
     * 
     * <p>This method is typically called by the parser to indicate whether
     * the original syntax contained a colon (slice) or not (single element).
     * 
     * @param isSlice true if this represents slice syntax with colon, false for single element
     * @see #isSlice()
     */
    public void setSlice(boolean isSlice) {
        this.isSlice = isSlice;
    }
    
    /**
     * Checks if this represents array access syntax using bracket notation.
     * 
     * <p>Returns true for all forms of array/list access patterns:
     * <ul>
     *   <li><code>arr[5]</code> - Single element access</li>
     *   <li><code>arr[2:8]</code> - Array slice with both bounds</li>
     *   <li><code>arr[:3]</code> - Array slice to index 3</li>
     *   <li><code>arr[2:]</code> - Array slice from index 2</li>
     *   <li><code>arr[:]</code> - Full array slice</li>
     * </ul>
     * 
     * <p>This is the preferred method for type-safe checking of array access patterns.
     * 
     * @return true if this represents array access using bracket notation
     * @see #isQualifiedName()
     * @see #getLowerSubscript()
     * @see #getUpperSubscript()
     */
    public boolean isArrayAccess() {
        return getIndicesType() == IndicesType.ARRAY_ACCESS;
    }
    
    /**
     * Checks if this represents qualified name syntax using dot notation.
     * 
     * <p>Returns true for all forms of field/property access patterns:
     * <ul>
     *   <li><code>obj.field_name</code> - Access specific field</li>
     *   <li><code>json_col.key</code> - Access JSON object key</li>
     *   <li><code>record.*</code> - Access all fields (wildcard)</li>
     *   <li><code>composite_type.attribute</code> - Access composite type attribute</li>
     * </ul>
     * 
     * <p>This is the preferred method for type-safe checking of qualified name patterns.
     * 
     * @return true if this represents qualified name access using dot notation
     * @see #isArrayAccess()
     * @see #getAttributeName()
     */
    public boolean isQualifiedName() {
        return getIndicesType() == IndicesType.QUALIFIED_NAME;
    }

    /**
     * Initializes this TIndices with the specified components.
     * 
     * <p>This method is typically called by the parser during AST construction.
     * The parameters determine the type and content of the indices element:
     * 
     * <p><strong>For Array Access:</strong> arg1=null, arg2=lowerBound, arg3=upperBound
     * <p><strong>For Qualified Names:</strong> arg1=attributeName, arg2=null, arg3=null
     * 
     * @param arg1 attribute name for qualified access, or null for array access
     * @param arg2 lower bound expression for array access, or null for qualified names
     * @param arg3 upper bound expression for array slices, or null for single elements or qualified names
     */
    public  void init(Object arg1, Object arg2, Object arg3){
        this.attributeName = (TObjectName)arg1;
        this.lowerSubscript = (TExpression)arg2;
        this.upperSubscript = (TExpression)arg3;
    }

    /**
     * Sets the lower bound expression for array access operations.
     * 
     * <p>This represents the starting index in array access patterns:
     * <ul>
     *   <li>For <code>[5]</code> → set to expression "5"</li>
     *   <li>For <code>[2:8]</code> → set to expression "2"</li>
     *   <li>For <code>[:3]</code> → set to null (no lower bound)</li>
     * </ul>
     * 
     * @param lowerSubscript the expression representing the lower bound, or null
     * @see #getLowerSubscript()
     */
    public void setLowerSubscript(TExpression lowerSubscript) {
        this.lowerSubscript = lowerSubscript;
    }

    /**
     * Sets the upper bound expression for array slice operations.
     * 
     * <p>This represents the ending index in array slice patterns:
     * <ul>
     *   <li>For <code>[2:8]</code> → set to expression "8"</li>
     *   <li>For <code>[:3]</code> → set to expression "3"</li>
     *   <li>For <code>[5]</code> → set to null (single element, not a slice)</li>
     * </ul>
     * 
     * @param upperSubscript the expression representing the upper bound, or null
     * @see #getUpperSubscript()
     */
    public void setUpperSubscript(TExpression upperSubscript) {
        this.upperSubscript = upperSubscript;
    }

    /**
     * Sets the attribute name for qualified name access operations.
     * 
     * <p>This represents the field or property name in dot notation patterns:
     * <ul>
     *   <li>For <code>.field_name</code> → set to "field_name"</li>
     *   <li>For <code>.*</code> → set to "*"</li>
     *   <li>For array access → should be null</li>
     * </ul>
     * 
     * @param attributeName the object name representing the field/property, or null for array access
     * @see #getAttributeName()
     */
    public void setAttributeName(TObjectName attributeName) {
        this.attributeName = attributeName;
    }

    public TExpressionList getSubscriptList() {
        return subscriptList;
    }

    private TExpressionList subscriptList;

    private TExpressionList functionArgs;

    public TExpressionList getFunctionArgs() {
        return functionArgs;
    }

    public void setFunctionArgs(TExpressionList functionArgs) {
        this.functionArgs = functionArgs;
    }

    public void addSubscript(TExpression expr){
        if (lowerSubscript == null){
            lowerSubscript = expr;
        }else{
            if (subscriptList == null){
                subscriptList = new TExpressionList();
            }
            subscriptList.addExpression(expr);
        }
    }

    public static void addSubscript(ArrayList<TIndices> indicesArrayList,TExpression expr){
        indicesArrayList.get(indicesArrayList.size()-1).addSubscript(expr);
    }

    public void accept(TParseTreeVisitor v){
        v.preVisit(this);
        v.postVisit(this);
    }

    public void acceptChildren(TParseTreeVisitor v){
        v.preVisit(this);
        v.postVisit(this);
    }

}