---
name: tql_helpers
kind: function
lang: cpp
domain: core
version: "1.0.0"
purity: pure
signature: "namespace data_table { const char* op_label(Op); const char* view_mode_token(ViewMode); const char* agg_fn_token(AggFn); const char* join_strategy_token(JoinStrategy); std::string aggregation_alias(const Aggregation&); std::string lua_string_literal(const std::string&); std::string color_to_hex(unsigned int); unsigned int hex_to_color(const std::string&); ... }"
description: "Pure token conversion helpers for TQL (Table Query Language): Op/ColumnType/AggFn/ViewMode/JoinStrategy/DateGranularity enum-to-string and back, aggregation_alias, lua_string_literal escaping, and color hex encoding. Used internally by tql_emit and tql_apply."
tags: [tables, tql, cpp-tables]
uses_functions: []
uses_types:
  - data_table_types_cpp_core
returns: []
returns_optional: false
error_type: ""
imports:
  - "core/tql_helpers.h"
tested: true
tests:
  - "lua_string_literal escaping"
  - "color roundtrip"
test_file_path: "cpp/functions/core/tql_emit_test.cpp"
file_path: "cpp/functions/core/tql_helpers.cpp"
params:
  - name: various
    desc: "Token conversion functions operating on data_table enum values and std::string. All are pure — no side effects, no global state."
output: "String tokens or enum values corresponding to TQL wire format. Used by tql_emit (serialization) and tql_apply (parsing)."
---

## Ejemplo

```cpp
#include "core/tql_helpers.h"

// Op token
const char* t = data_table::op_label(data_table::Op::Gte); // ">="

// ViewMode token
const char* vm = data_table::view_mode_token(data_table::ViewMode::Bar); // "bar"
data_table::ViewMode m = data_table::view_mode_from_token("scatter"); // ViewMode::Scatter

// Aggregation alias
data_table::Aggregation a;
a.fn = data_table::AggFn::Sum; a.col = "revenue";
std::string alias = data_table::aggregation_alias(a); // "sum_revenue"

// Lua string escaping (used in emit)
std::string lit = data_table::lua_string_literal("say \"hi\""); // "\"say \\\"hi\\\"\""

// Color hex roundtrip
std::string hex = data_table::color_to_hex(0xFF0000FFu); // "#ff0000"
unsigned int c  = data_table::hex_to_color("#ff0000");   // 0xFF0000FF
```

## Cuando usarla

Cuando necesites convertir entre valores internos del stack TQL (Op, ViewMode, AggFn, etc.) y sus representaciones textuales en el formato Lua TQL. Directamente usado por `tql_emit` y `tql_apply`; rara vez se llama desde código externo.

## Notas

- Todas las funciones son puras (no I/O, no estado global).
- `view_mode_from_token(nullptr)` y `op_from_label(nullptr)` retornan valores por defecto seguros (Table / Eq).
- Promoted from `cpp/apps/primitives_gallery/playground/tables/data_table_logic.cpp`, issue 0081-C.
