"""Minimal Text Tables reader for agents: python3 read_txtab.py FILE prints a summary.

Reads inline tables by row count. Not a validator: no recovery when rows= is wrong, no per-table
encoding for inline data, single-character delimiters only (Python's csv module). For
reference= tables, open the referenced file yourself with the table's dialect and encoding.
"""
import csv, io, re, sys

BOMS = [(b'\x00\x00\xfe\xff', 'utf-32-be'), (b'\xff\xfe\x00\x00', 'utf-32-le'),
        (b'\xfe\xff', 'utf-16-be'), (b'\xff\xfe', 'utf-16-le'), (b'\xef\xbb\xbf', 'utf-8')]
DELIMS = {'comma': ',', 'tab': '\t', 'pipe': '|', 'semicolon': ';'}
QUOTES = {'none': None, 'double': '"', 'single': "'"}


def kv(s):
    """key=value tokens; quoted values may contain spaces, "" is a literal quote."""
    return {k: (v[1:-1].replace('""', '"') if v.startswith('"') else v)
            for k, v in re.findall(r'(\S+?)=("(?:[^"]|"")*"|\S*)', s)}


def read_txtab(path):
    raw = open(path, 'rb').read()
    enc = next((e for b, e in BOMS if raw.startswith(b)), None)
    text = raw.decode(enc or 'ascii', errors='replace').lstrip('﻿')
    first = text.split('\n', 1)[0].rstrip('\r')
    P, rest = first.split(' ', 1)                      # the prefix and the first line's keys
    filekv = kv(rest)
    if not enc:                                        # no BOM: encoding= applies after line 1
        try:
            text = raw.decode(filekv.get('encoding', 'utf-8'))
        except LookupError:                            # unknown encoding name: fall back to UTF-8
            text = raw.decode('utf-8')
    lines = text.splitlines()[1:]
    is_sys = lambda l: l == P or l.startswith(P + ' ')
    meta, tables, i = {}, [], 0
    while i < len(lines):
        l = lines[i]
        if is_sys(l):
            word, _, payload = l[len(P) + 1:].partition(' ')
            if word == 'table':
                t = {**{k: filekv[k] for k in ('delim', 'quote', 'null', 'encoding') if k in filekv},
                     **kv(payload), 'lines': [], 'columns': [], 'meta': {}, 'agg': {}, 'sql': []}
                tables.append(t)
            elif tables:
                t = tables[-1]
                if word == 'column': t['columns'].append(kv(payload))
                elif word.startswith('agg-'): t['agg'][word[4:]] = payload
                elif word.startswith('meta-'): t['meta'][word[5:]] = payload
                elif word.startswith('sql-'): t['sql'].append((word, payload))
            elif word.startswith('meta-'):
                meta[word[5:]] = payload
            i += 1
            continue
        t = tables[-1]                                 # data section: header row + rows records
        n = 0 if 'reference' in t else int(t.get('header', '1')) + int(t['rows'])
        if n == 0:
            i += 1
            continue
        t['lines'], i = lines[i:i + n], i + n
    for t in tables:                                   # parse records in the table's own dialect
        q = QUOTES.get(t.get('quote', 'none'), t.get('quote'))
        rd = csv.reader(io.StringIO('\n'.join(t['lines'])), delimiter=DELIMS.get(t.get('delim', 'comma'), t.get('delim', ',')),
                        quotechar=q or '"', quoting=csv.QUOTE_MINIMAL if q else csv.QUOTE_NONE)
        t['records'] = list(rd)
    return P, filekv, meta, tables


if __name__ == '__main__':
    P, filekv, meta, tables = read_txtab(sys.argv[1])
    print(f'prefix {P!r}  first line {filekv}  file meta {meta}')
    for n, t in enumerate(tables):
        cols = ', '.join(f"{c.get('name')}:{c.get('type', '?')}" for c in t['columns'])
        where = t.get('reference', 'inline')
        print(f"[{n}] {t.get('name', '(unnamed)')} rows={t['rows']} data={where} columns: {cols or '(none declared)'}")
        if t['meta']: print('    meta', t['meta'])
        if t['agg']: print('    agg', t['agg'])
        if t['records']: print('    header/first records', t['records'][:3])
