// tql_apply — Parse TQL Lua text and populate data_table::State.
// TQL (Table Query Language): canonical Lua chunk format for State round-trips.
// Promoted from primitives_gallery playground to registry, issue 0081-C.
//
// Depends on: Lua 5.4 C API (vendored at cpp/vendor/lua/), tql_helpers.h.
// Does NOT call lua_engine — formulas are stored verbatim in DerivedColumn.formula.
// Formula evaluation (Lua engine) is the caller's responsibility.
//
// Pure in the registry sense: no global state, no I/O, no side effects beyond
// populating the output State. The only external requirement is that Lua 5.4
// is available to parse the text chunk.
#pragma once

#include "core/data_table_types.h"
#include <string>
#include <vector>

namespace tql {

struct ApplyResult {
    bool                     ok       = false;
    std::string              error;           // non-empty on hard failure
    std::vector<std::string> warnings;        // soft issues (unknown col, etc.)
    data_table::State        state;           // populated on ok=true
};

// apply — Parse a TQL Lua chunk and return the resulting State.
//
// Parameters:
//   lua_text          — the TQL Lua chunk (output of tql_emit, or hand-written).
//   available_headers — original column names used to validate filter/sort col refs.
//                       Pass empty to skip col-name validation (warnings only).
//
// Returns ApplyResult:
//   ok=true  — state populated; warnings may still be non-empty (unknown cols, etc.)
//   ok=false — error is set; state is partially populated / undefined.
//
// DerivedColumn.formula is stored verbatim; lua_id is set to -1 (not compiled).
// The caller must compile formulas via a Lua engine after receiving the result.
ApplyResult apply(const std::string& lua_text,
                  const std::vector<std::string>& available_headers);

// apply (extended overload) — Playground-compatible signature used by data_table render.
//
// Wraps the base apply(), writes the parsed State into `st` in-place, and returns bool.
// Parameters cells/rows/orig_cols are accepted for API compatibility with the playground
// caller but are not used by the parser itself (they are provided for future validation).
//
//   lua_text     — TQL Lua chunk.
//   st           — output State (populated on ok=true).
//   orig_headers — column names for validation (may be empty).
//   orig_types   — column types matching orig_headers (unused by parser, kept for compat).
//   cells        — row-major cell array (unused by parser; accepted for caller compat).
//   rows         — row count (unused by parser; accepted for caller compat).
//   orig_cols    — number of original columns (unused by parser; accepted for compat).
//   err          — if non-null, receives the error message on failure.
//
// Returns true on success, false on parse error.
bool apply(const std::string& lua_text,
           data_table::State& st,
           const std::vector<std::string>& orig_headers,
           const std::vector<data_table::ColumnType>& orig_types,
           const char* const* cells,
           int rows,
           int orig_cols,
           std::string* err);

} // namespace tql
