package gudusoft.gsqlparser.pp2.token;

import gudusoft.gsqlparser.TSourceToken;
import gudusoft.gsqlparser.TSourceTokenList;

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

/**
 * Immutable, indexed view of a {@link TSourceTokenList} as a sequence of
 * {@link Pp2Token}s.
 *
 * <p>The constructor copies token <i>references</i> from the input
 * {@code TSourceTokenList} into a private {@link ArrayList} — the source
 * list is never mutated, and the resulting stream cannot be structurally
 * mutated (no add/remove/clear). Per-token role bookkeeping on individual
 * {@link Pp2Token}s remains writable because pp2 stages annotate roles
 * incrementally (see {@code TokenRole}).
 *
 * <p>Two factory paths are supported:
 * <ul>
 *   <li>{@link #fromSourceTokenList(TSourceTokenList)} — basic wrap with
 *       zero {@code precedingBlanks}/{@code precedingLinebreaks}. Used by
 *       early Phase-1 callers and tests.</li>
 *   <li>{@link #ofTokens(List)} — internal entry point used by
 *       {@code Pp2TokenStreamBuilder} (S7), which folds whitespace into the
 *       next solid token's preceding-whitespace counts before constructing
 *       the stream.</li>
 * </ul>
 *
 * <p>Probe A7 (slice S1) established that {@code TGSqlParser} reuses the
 * same {@code TSourceTokenList} reference across calls. This stream's
 * copy-on-construct contract is the reason that finding is not a footgun:
 * the next re-tokenization cannot invalidate an already-built stream's
 * <i>structure</i>.
 *
 * <h2>Two-tier stability contract</h2>
 *
 * <ul>
 *   <li><b>Structural stability</b> (guaranteed): after a stream is built,
 *       {@link #size()} and the per-index {@link Pp2Token} wrapper
 *       references are stable. Re-tokenizing the source parser does not
 *       grow, shrink, or re-shuffle the stream, and never replaces a
 *       wrapper reference at a given index. {@link #toReadOnlyList()}
 *       returns this stable structure.</li>
 *   <li><b>Text stability</b> (NOT guaranteed): {@code Pp2Token.getText()}
 *       delegates live to the wrapped {@code TSourceToken}. If the parser
 *       re-tokenizes a different SQL and re-uses the underlying
 *       {@code TSourceToken} fields, the live text returned by an existing
 *       wrapper changes. Neither {@link #toReadOnlyList()} nor any other
 *       method in this class snapshots text. Callers that must outlive a
 *       parser re-tokenization MUST snapshot text into their own
 *       {@code List<String>} before the second tokenize call (see
 *       {@code Pp2TokenStreamTest#textSnapshotSurvivesParserReuse}).</li>
 * </ul>
 */
public final class Pp2TokenStream implements Iterable<Pp2Token> {

    private final List<Pp2Token> tokens;

    /** Internal constructor. Use {@link #ofTokens(List)} or factories. */
    private Pp2TokenStream(List<Pp2Token> tokens) {
        // Defensive copy into a fresh ArrayList so the caller cannot
        // structurally mutate the stream after construction.
        this.tokens = new ArrayList<Pp2Token>(tokens);
    }

    /**
     * Build a stream from a previously-prepared list of {@link Pp2Token}s.
     * The supplied list is copied; subsequent caller mutations do not leak.
     *
     * @throws NullPointerException if {@code tokens} or any element is null
     */
    public static Pp2TokenStream ofTokens(List<Pp2Token> tokens) {
        if (tokens == null) throw new NullPointerException("tokens");
        for (int i = 0; i < tokens.size(); i++) {
            if (tokens.get(i) == null) {
                throw new NullPointerException("tokens[" + i + "]");
            }
        }
        return new Pp2TokenStream(tokens);
    }

    /**
     * Build a stream by wrapping each {@link TSourceToken} in the input
     * list as a {@link Pp2Token} with zero preceding whitespace.
     *
     * <p>Smarter folding of whitespace into {@code precedingBlanks}/
     * {@code precedingLinebreaks} is the job of
     * {@code Pp2TokenStreamBuilder} (S7); this factory is the minimal
     * Phase-1 wrap.
     *
     * <p>Contract: the input {@code TSourceTokenList} is not mutated. The
     * stream holds the same {@code TSourceToken} references as the input,
     * verifiable in tests by reference + text equality before vs after
     * construction.
     *
     * <p>A null element in the source list is treated as a parser-side bug
     * and triggers a {@link NullPointerException} — silently skipping would
     * shift the per-index mapping and hide corruption.
     *
     * @throws NullPointerException if {@code source} is null or contains a
     *     null element
     */
    public static Pp2TokenStream fromSourceTokenList(TSourceTokenList source) {
        if (source == null) throw new NullPointerException("source");
        List<Pp2Token> wrapped = new ArrayList<Pp2Token>(source.size());
        for (int i = 0; i < source.size(); i++) {
            TSourceToken t = source.get(i);
            if (t == null) {
                throw new NullPointerException("source[" + i + "] — "
                    + "null entry in TSourceTokenList; pp2 treats this as "
                    + "parser corruption rather than silently shrinking the stream");
            }
            wrapped.add(new Pp2Token(t));
        }
        return new Pp2TokenStream(wrapped);
    }

    public int size() {
        return tokens.size();
    }

    public boolean isEmpty() {
        return tokens.isEmpty();
    }

    /**
     * @throws IndexOutOfBoundsException if {@code index} is out of range
     */
    public Pp2Token get(int index) {
        return tokens.get(index);
    }

    /** Unmodifiable view of the underlying token list. */
    public List<Pp2Token> toReadOnlyList() {
        return Collections.unmodifiableList(tokens);
    }

    @Override
    public Iterator<Pp2Token> iterator() {
        return new Iterator<Pp2Token>() {
            int idx = 0;
            @Override public boolean hasNext() { return idx < tokens.size(); }
            @Override public Pp2Token next() {
                if (idx >= tokens.size()) throw new NoSuchElementException();
                return tokens.get(idx++);
            }
            @Override public void remove() {
                throw new UnsupportedOperationException("Pp2TokenStream is immutable");
            }
        };
    }

    @Override
    public String toString() {
        return "Pp2TokenStream{size=" + tokens.size() + "}";
    }
}