package gudusoft.gsqlparser.resolver2.model;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
 * Represents a field path for deep/record field access in structured types.
 *
 * <p>In BigQuery, Snowflake, and other databases with STRUCT/RECORD types,
 * column references can include field paths like {@code customer.address.city}.
 * This class captures the field path portion (segments beyond the base column).</p>
 *
 * <p>Design principles:</p>
 * <ul>
 *   <li>Immutable - once created, cannot be modified</li>
 *   <li>Only stores segments beyond the base column (e.g., for {@code customer.address.city},
 *       if base column is {@code customer}, fieldPath stores {@code ["address", "city"]})</li>
 *   <li>Empty fieldPath means no field access (regular column reference)</li>
 * </ul>
 *
 * <p>Example:</p>
 * <pre>
 * -- SQL: SELECT customer.address.city FROM orders
 * -- base column: customer
 * -- fieldPath: ["address", "city"]
 * </pre>
 *
 * @see ColumnSource#getFieldPath()
 */
public class FieldPath {

    /** Empty field path singleton for regular column references */
    public static final FieldPath EMPTY = new FieldPath(Collections.emptyList());

    /** The field path segments (beyond the base column) */
    private final List<String> segments;

    /**
     * Create a FieldPath from a list of segments.
     *
     * @param segments The field path segments (will be copied)
     */
    public FieldPath(List<String> segments) {
        if (segments == null || segments.isEmpty()) {
            this.segments = Collections.emptyList();
        } else {
            this.segments = Collections.unmodifiableList(new ArrayList<>(segments));
        }
    }

    /**
     * Create a FieldPath from a single segment.
     *
     * @param segment The single field segment
     * @return A new FieldPath with one segment
     */
    public static FieldPath of(String segment) {
        if (segment == null || segment.isEmpty()) {
            return EMPTY;
        }
        return new FieldPath(Collections.singletonList(segment));
    }

    /**
     * Create a FieldPath from multiple segments.
     *
     * @param segments The field segments
     * @return A new FieldPath
     */
    public static FieldPath of(String... segments) {
        if (segments == null || segments.length == 0) {
            return EMPTY;
        }
        List<String> list = new ArrayList<>(segments.length);
        for (String s : segments) {
            if (s != null && !s.isEmpty()) {
                list.add(s);
            }
        }
        return list.isEmpty() ? EMPTY : new FieldPath(list);
    }

    /**
     * Create a FieldPath from a list of segments.
     *
     * @param segments The field segments
     * @return A new FieldPath, or EMPTY if null/empty
     */
    public static FieldPath of(List<String> segments) {
        if (segments == null || segments.isEmpty()) {
            return EMPTY;
        }
        return new FieldPath(segments);
    }

    /**
     * Get the field path segments.
     *
     * @return Unmodifiable list of segments
     */
    public List<String> getSegments() {
        return segments;
    }

    /**
     * Get the number of segments in this field path.
     *
     * @return Number of segments
     */
    public int size() {
        return segments.size();
    }

    /**
     * Check if this field path is empty (no field access).
     *
     * @return true if empty
     */
    public boolean isEmpty() {
        return segments.isEmpty();
    }

    /**
     * Get the first segment (immediate field).
     *
     * @return First segment, or null if empty
     */
    public String getFirst() {
        return segments.isEmpty() ? null : segments.get(0);
    }

    /**
     * Get the last segment (deepest field).
     *
     * @return Last segment, or null if empty
     */
    public String getLast() {
        return segments.isEmpty() ? null : segments.get(segments.size() - 1);
    }

    /**
     * Get a segment by index.
     *
     * @param index The index
     * @return The segment at that index
     * @throws IndexOutOfBoundsException if index is invalid
     */
    public String get(int index) {
        return segments.get(index);
    }

    /**
     * Create a new FieldPath with an additional segment appended.
     *
     * @param segment The segment to append
     * @return New FieldPath with the segment appended
     */
    public FieldPath append(String segment) {
        if (segment == null || segment.isEmpty()) {
            return this;
        }
        List<String> newSegments = new ArrayList<>(segments.size() + 1);
        newSegments.addAll(segments);
        newSegments.add(segment);
        return new FieldPath(newSegments);
    }

    /**
     * Create a new FieldPath with additional segments appended.
     *
     * @param other The FieldPath to append
     * @return New FieldPath with all segments
     */
    public FieldPath append(FieldPath other) {
        if (other == null || other.isEmpty()) {
            return this;
        }
        if (this.isEmpty()) {
            return other;
        }
        List<String> newSegments = new ArrayList<>(segments.size() + other.segments.size());
        newSegments.addAll(segments);
        newSegments.addAll(other.segments);
        return new FieldPath(newSegments);
    }

    /**
     * Create a sub-path starting from the given index.
     *
     * @param fromIndex Start index (inclusive)
     * @return New FieldPath with segments from fromIndex
     */
    public FieldPath subPath(int fromIndex) {
        if (fromIndex >= segments.size()) {
            return EMPTY;
        }
        if (fromIndex <= 0) {
            return this;
        }
        return new FieldPath(segments.subList(fromIndex, segments.size()));
    }

    /**
     * Convert to dot-separated string representation.
     *
     * @return String like "address.city", or empty string if empty
     */
    @Override
    public String toString() {
        if (segments.isEmpty()) {
            return "";
        }
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < segments.size(); i++) {
            if (i > 0) {
                sb.append('.');
            }
            sb.append(segments.get(i));
        }
        return sb.toString();
    }

    /**
     * Convert to full reference string with base column.
     *
     * @param baseColumn The base column name
     * @return String like "customer.address.city"
     */
    public String toFullReference(String baseColumn) {
        if (segments.isEmpty()) {
            return baseColumn != null ? baseColumn : "";
        }
        StringBuilder sb = new StringBuilder();
        if (baseColumn != null && !baseColumn.isEmpty()) {
            sb.append(baseColumn);
            sb.append('.');
        }
        sb.append(toString());
        return sb.toString();
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        FieldPath fieldPath = (FieldPath) o;
        return segments.equals(fieldPath.segments);
    }

    @Override
    public int hashCode() {
        return segments.hashCode();
    }
}