PTTJS — формат текстового хранения комплексных таблиц

PTTJS — plain text table javascript, формат разработанный из личной необходимости и острой нужды.

Публикую в народ, потому что уверен, что не меня одного волнуют ограничения и проблемы текущих форматов для табличных данных.

Уже написаны JS библиотека с парсером и сериализатором, а также Obsidian плагин.

Цель

Главная цель формата PTTJS — получить текстовый формат таблиц, который позволяет хранить более сложные таблицы, нежели существующие форматы (CSV, MD), но при этом сохранять читаемость и текстовую основу.

Мотивация

Мотивация для разработки копилась в течении долгого времени, ведь Я как и все нормальные люди готов мириться с некоторыми неудобствами. Но недавно терпение кончилось и пришлось взяться за проработку и разработку.

Решающими стали факторы:

1. Необходимость передавать в LLM более сложные таблицы нежели обычные CSV или MD форматы. Очень часто в документах встречаются сложносоставные таблицы, которые невозможно перевести в текстовый формат. Из-за чего приходится использовать более сложные и тяжелые мультимодальные модели.

2. Необходимость распознавать сложносоставные таблицы с помощью CV возвращая простой текст, а ни какой-нибудь многовложенный JSON, который ещё нормально не перепроверишь, пока не отрендеришь.

3. Необходимость обучать LLM работе целиком с таблицей, а не через костыли внутри Google Shets или Microsoft Excel. Дать возможность LLM-ке самой крутить стобцы, строки, формулы, как ей понадобится.

4. Невозможность открыть большинство, даже простых таблиц, которые, за неимением аналогов, все хранят в XLS(X) или ODT, без специального ПО.

5. Желание работать с более сложными таблицами в текстовых редакторах и ПО по типу Obsidian.

6. Личная неприязнь к Google Shets и Microsoft Excel (надеюсь Я не один такой).

Описание формата

Первая строка всегда отдана под аннотацию:
|PTTJS 1.0|encoding=UTF‑8|\n

Страницы

Каждая таблица лежит на странице:

|(@P1|Название страницы){\n — начало страницы, в скобках: id страницы начинается с символа «@» и название страницы.

}|\n — конец страницы.

Обозначения страницы опциональны, если их нет, вся таблица на одной странице.

Ячейки

Вся таблица состоит из ячеек и обозначения конца строки:

|H([1|1]1|1|@C1)> — начало ячейки, H — пометка, что это заголовок, в круглых скобках: индекс ячейки по X и Y в квадратных скобках, масштаб (scale) ячейки по X и Y и id ячейки (начинается с символа «@»).

<|\n — конец строки.

H — опциональная пометка, что ячейка — это заголовок.

Индекс ячейки по X и Y — опционален, при обработке просто заполняется итеративно по ячейкам и строкам, начиная с [0|0]. Можно выгрузить при необходимости не визуальной обработки (в скрипте или c помощью AI).

Масштаб (scale) ячейки по X и Y — опционален и по умолчанию равен 1|1.
Масштаб всегда указывается в верхней левой ячейке.

Id ячейки — опционален, нужен для ссылок и направленных формул.

Даже если в строке нет значений, но после неё есть строки, надо указать в строке хотя бы одну пустую ячейку |><|.

Данные внутри ячеек не должны содержать символов ответственных за указание новой ячейки, конца строки, фигурных скобочек и переноса строки («\n«, «|«, «>«, «<«, «{«, «}«).

Все эти символы должны быть заменены на URL Encode аналоги:

Новая строка (\n) -> %5Cn
Вертикальная черта (|) -> %7C
> -> %3E,
< -> %3C,
{ -> %7B,
} -> %7D,

чтобы парсер валидно воспринимал данные.

В библиотеке в serializer.js есть функция escapeValue, которая может заменить символы на URL Encode вариант.

В библиотеке в parser.js есть функция unescapeValue, которая может заменить символы обратно из URL Encode варианта в обычный вид.

Скрипты

>>>SCRIPT\n — начало блока скриптов

<<<SCRIPT\n — конец блока скриптов

Блок скриптов всегда находится после всех данных и может работать с данными на разных листах.

Скрипты хранят формулы и форматирование, которые срабатывают при инициализации или изменении таблицы в совместимом редакторе.

Обработка ячеек делается с помощью JS кода и специально заготовленных JS функций.

Можно определять свои функции в редакторе.

Стили присваиваются с помощью символа «<=» и описываются в CSS подобном формате (тут также будут срабатывать JS функции для стилизации).

Форматы ячеек присваиваются символом «=>» и указывают на формат данных в ячейках (это тоже JS функции).
Например NUMBER(2,’ ‘), первый параметр это decimals — количество цифр после запятой, а второй — разделитель тысяч, в нашем случае пробел ‘ ‘.

Можно добавлять скрипты для всей строки или столбца или вообще всего диапазона с помощью двойного указания индекса через двоеточие «:», например вся первая строка (0:0|0), или весь первый столбец (0|0:0) и т.д.

Скрипты это опциональный блок.

В ячейках всегда хранится актуальная информация. Когда мы добавляем скрипт, он пересчитывает данные таблицы и складывает по ячейкам актуальную информацию.

При выгрузке — скрипты можно сохранять отдельным файлом, например с суффиксом «.script».

Примеры

Пример простой таблицы, например для хранения данных о машинах:

|PTTJS 1.0| |H>Номер машины|H>Год выпуска|H>Марка модель<| |>080XXX02|>2005|>LEXUS RX 350<| |>787XXX16|>2015|>GEELY GC7<| |>871XXX05|>1997|>TOYOTA IPSUM<| |>A602XXX|>1996|>MITSUBISHI PAJERO<| |>890XXX02|>1997|>TOYOTA LAND CRUISER PRADO<| |>216XXX13|>2007|>DAEWOO NEXIA<|

Пример простой таблицы, c индексами:

|PTTJS 1.0|encoding=UTF‑8| |H([0|0])>Номер машины|H([1|0])>Год выпуска|H([2|0])>Марка модель<| |([0|1])>080XXX02|([1|1])>2007|([2|1])>LEXUS RX 350<| |([0|2])>787XXX16|([1|2])>2015|([2|2])>GEELY GC7<| |([0|3])>871XXX05|([1|3])>1997|([2|3])>TOYOTA IPSUM<| |([0|4])>A602XXX|([1|4])>1996|([2|4])>MITSUBISHI PAJERO<| |([0|5])>890XXX02|([1|5])>1997|([2|5])>TOYOTA LAND CRUISER PRADO<| |([0|6])>216XXX13|([1|6])>2007|([2|6])>DAEWOO NEXIA<|

Пример таблицы cо «сложным» заголовком:

|PTTJS 1.0|encoding=UTF‑8| |H(1|2)>Номер машины|H(2|1)>Данные о машине|H><| |H>|H>Год выпуска|H>Марка модель<| |>080XXX02|>2007|>LEXUS RX 350<| |>787XXX16|>2015|>GEELY GC7<| |>871XXX05|>1997|>TOYOTA IPSUM<| |>A602XXX|>1996|>MITSUBISHI PAJERO<| |>890XXX02|>1997|>TOYOTA LAND CRUISER PRADO<| |>216XXX13|>2007|>DAEWOO NEXIA<|

В этом примере объединены первые ячейки первых двух строк, с заголовком «номер машины» и объединены вторая и третья ячейки первой строки с заголовком «Данные о машине».

Объединенные ячейки остаются. Это нужно чтобы не потерять позиционную информацию.

Пример простой таблицы, c индексами и скриптами:

|PTTJS 1.0|encoding=UTF‑8| |H([0|0])>Номер машины|H([1|0])>Год выпуска|H([2|0])>Марка модель<| |([0|1])>080XXX02|([1|1])>2007|([2|1])>LEXUS RX 350<| |([0|2])>787XXX16|([1|2])>2015|([2|2])>GEELY GC7<| |([0|3])>871XXX05|([1|3])>1997|([2|3])>TOYOTA IPSUM<| |([0|4])>A602XXX|([1|4])>1996|([2|4])>MITSUBISHI PAJERO<| |([0|5])>890XXX02|([1|5])>1997|([2|5])>TOYOTA LAND CRUISER PRADO<| |([0|6])>216XXX13|([1|6])>2007|([2|6])>DAEWOO NEXIA<| |([0|7])><| |([0|8])>Средний год выпуска|([1|8])>2003<|  >>>SCRIPT (1|1,1|6)=>NUMBER(2,' ') (1|8)=DIV(SUM(1|1,1|6),COUNT(1|1,1|6)) (0|8:8)<=BORDER(each,2,solid,#000) <<<SCRIPT

В этом примере у нас есть девятая строка, во второй ячейке которой лежит формула среднего значения диапазона ячеек.

Ещё указаны форматы ячеек во втором столбце со 2 по 7 строках, это числовой формат.

Также мы присвоили CSS стили диапазону ячеек, а именно обводку каждой ячейки черного цвета и толщиной 2.

Планы

1. Предстоит доделать срабатывание функций из блока скриптов на объекте Store, который получается после парсинга.

2. Добавить функции преобразования форматов (XSL(S), ODT, CSV, MD <-> PTTJS)

3. Добавить библиотеки для других языков.

4. Сделать легкий веб интерфейс для работы с PTTJS.

Сотрудничество (контрибьютинг)

GitHub репозиторий открыт, можете предлагать изменения.

Заключение

На этом всё, спасибо что уделили время, надеюсь смог помочь решить чьи-то аналогичные проблемы.