QSP: Модуль работы с таблицами данных

Версия: 1.3.1

О модуле

Несмотря на тот факт, что внутренний язык платформы QSP поддерживает работу с массивами со строковыми ключами, позволяющими в теории реализовывать и таблицы, и многомерные массивы, и деревья и т.п., на деле работать со всем этим… неудобно. Всегда приходится вокруг массива, содержащего структуры данных, дополнительно лепить некую "инфраструктуру": переменные-счетчики, вспомогательные массивы и т.п. А отсутствие в QSP (в версии 5.7.0) операторов цикла делает код для обработки всего этого хозяйства еще более громоздким.

Данный модуль предназначен для работы с таблицами данных (далее — просто "таблицами"), состоящих из именованных колонок и строк, в которых хранятся значения по каждой колонке. Типа такой:

Перечень того, что позволяет делать модуль:

• Создавать таблицу с произвольным числом колонок.
• Добавлять, находить и удалять строки в таблице.
• Получать и устанавливать значения произвольных ячеек в таблице.
• Сортировать строки таблицы как по одной, так и по нескольким колонкам в порядке возрастания и убывания.
• Для доступа к отдельным строкам (чтение или запись значений ячеек) использовать не только номера строк, но и уникальные значения из какой-либо колонки (работа с индексом).
• Выгружать строку таблицы в ассоциативный массив.
• Перебирать таблицу в любом направлении: от первой строки до последней и наоборот.
• Выбирать, копировать и удалять строки таблицы (как все, так и по заданному фильтру).
• Получать число строк в таблице (как всех, так и по заданному фильтру).

Варианты модуля

Поскольку для большинства программистов привычнее работать с англоязычными командами, существует соответствующая версия модуля, в которой все операторы и функции даны в англоязычном варианте. Далее по тексту англязычная версия будет обозначаться для краткости как "Версия E".

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

Входящие в пакет файлы

Подключение модуля

Первым делом необходимо подключить к своему проекту сам модуль. Для этого файл модуля нужно скопировать в тот же каталог, в котором находится основной проект, после чего в начало кода проекта добавить команду "ADDQST" (для QSP версии 5.7.0):

Подключение модуля с командами на русском языке:

ADDQST 'otg_lib_tables.qsp'

Подключение модуля с командами на английском языке:

ADDQST 'otg_lib_tables_eng.qsp'

Все локации модуля начинаются с префикса "Таб." ("Table." в версии E), а переменные — с префикса "otg_", поэтому пересечения с данными основного проекта быть не должно.

Перечень команд

Описание команд

Таб.Создать · Table.Create

Создает новую таблицу.

Синтаксис:

GS 'Таб.Создать', <Имя таблицы>, <Перечень колонок>, <Текущая>

Параметры:

Пример:

GS 'Таб.Создать', 'Персонажи', 'Имя,Здоровье,Раса', 1

Таб.Текущая · Table.Current

GS 'Таб.Текущая', <Имя таблицы>

GS 'Таб.Текущая', 'Персонажи'
GS 'Таб.ДобавитьКолонку', '', 'Сила'

Таб.ДобавитьКолонку · Table.NewColumn

Добавляет колонку к указанной таблице.

Синтаксис:

GS 'Таб.ДобавитьКолонку', <Имя таблицы>, <Имя колонки>

Параметры:

Пример:

GS 'Таб.ДобавитьКолонку', 'Персонажи', 'Сила'

Таб.СоздатьИндекс · Table.CreateIndex

Создает индекс к указанной колонке таблицы.

Синтаксис:

GS 'Таб.СоздатьИндекс', <Имя таблицы>, <Имя колонки>

Параметры:

Пример:

GS 'Таб.СоздатьИндекс', 'Персонажи', 'Имя'

Таб.УдалитьИндекс · Table.DestroyIndex

Удаляет существующий индекс.

Синтаксис:

GS 'Таб.УдалитьИндекс', <Имя таблицы>

Параметры:

Пример:

GS 'Таб.УдалитьИндекс', 'Персонажи'

Таб.ДобавитьСтроку · Table.NewLine

Добавляет строку к указанной таблице.

Синтаксис:

GS 'Таб.СоздатьИндекс', <Имя таблицы>, <Значение колонки 1>, <Значение колонки 2> …

Параметры:

Пример:

Если у нас есть таблица "Персонажи" с колонками "Имя", "Здоровье" и "Раса", то следующая команда:

GS 'Таб.ДобавитьСтроку', 'Персонажи', 'Арабелла', 75, 'Амазонка'

Добавит в таблицу строку:

Имя: Арабелла
Здоровье: 75
Раса: Амазонка.

Таб.Установить · Table.SetValue

Присваивает указанное значение заданной ячейке таблицы.

Синтаксис:

GS 'Таб.Установить', <Имя таблицы>, <Номер строки>, <Название/номер колонки>, <Значение>
GS 'Таб.Установить', <Имя таблицы>, 'id:<ID строки>', <Название/номер колонки>, <Значение>
GS 'Таб.Установить', <Имя таблицы>, <Значение индексного поля>, <Название/номер колонки>, <Значение>

Параметры:

Пример:

GS 'Таб.Установить', 'Персонажи', 2, 'Здоровье', 15
GS 'Таб.Установить', 'Персонажи', 'id:15', 'Здоровье', 13
GS 'Таб.Установить', 'Персонажи', 'index:7', 'Здоровье', 28
GS 'Таб.Установить', 'Персонажи', 'Арабелла', 'Здоровье', 25

Таб.Получить · Table.GetValue

Возвращает значение из определенной ячейки таблицы.

Синтаксис:

func('Таб.Получить', <Имя таблицы>, <Номер строки>, <Название/номер колонки>)
func('Таб.Получить', <Имя таблицы>, 'id:<ID строки>', <Название/номер колонки>)
func('Таб.Получить', <Имя таблицы>, <Значение индексного поля>, <Название/номер колонки>)

Параметры:

Пример:

рЗдоровье=func('Таб.Получить', 'Персонажи', 2, 'Здоровье')
рЗдоровье=func('Таб.Получить', 'Персонажи', 'id:15', 'Здоровье')
рЗдоровье=func('Таб.Получить', 'Персонажи', 'index:7', 'Здоровье')
$рРаса=func('Таб.Получить', 'Персонажи', 'Арабелла', 'Раса')

Таб.УдалитьСтроку · Table.DeleteLine

Удаляет строку из таблицы.

Синтаксис:

GS 'Таб.УдалитьСтроку', <Имя таблицы>, <Номер строки>
GS 'Таб.УдалитьСтроку', <Имя таблицы>, 'id:<ID строки>'
GS 'Таб.УдалитьСтроку', <Имя таблицы>, <Значение индексного поля>

Параметры:

Пример:

GS 'Таб.УдалитьСтроку', 'Персонажи', 3
GS 'Таб.УдалитьСтроку', 'Персонажи', 'id:7'
GS 'Таб.УдалитьСтроку', 'Персонажи', 'index:9'
GS 'Таб.УдалитьСтроку', 'Персонажи', 'Арабелла'

Таб.Сортировать · Table.Sort

Сортирует таблицу по одной или нескольким колонкам.

Синтаксис:

GS 'Таб.Сортировать', <Имя таблицы>, <Имя колонки>
GS 'Таб.Сортировать', <Имя таблицы>, <Имя колонки 1, Имя колонки 2…>

Параметры:

Пример:

GS 'Таб.Сортировать', 'Персонажи', 'Имя'
GS 'Таб.Сортировать', 'Персонажи', 'Раса, Здоровье-'

Таб.НайтиСтроку · Table.FindValue

Возвращает номер первой найденной по определенному условию строки из таблицы.

Синтаксис:

func('Таб.НайтиСтроку', <Имя таблицы>, <Название/Номер колонки>, <Операция сравнения>, <Параметр 1>, <Параметр 2>)

Параметры:

Пример:

рНомерСтроки=func('Таб.НайтиСтроку','Персонажи','Имя','=','Арабелла')

Таб.СлучайнаяСтрока · Table.RandomLine

Возвращает номер случайной строки из таблицы.

Синтаксис:

func('Таб.СлучайнаяСтрока', <Имя таблицы>)

Параметры:

Пример:

рНомерСтроки=func('Таб.СлучайнаяСтрока', 'Персонажи')
GS 'Таб.УдалитьСтроку', 'Персонажи', func('Таб.СлучайнаяСтрока', 'Персонажи')

Таб.СтрокуВМассив · Table.LineToArray

Создает массив с указанным именем и заполняет его значениями из указанной строки таблицы. При этом ключи массива будут соответствовать названиям колонок.

Синтаксис:

GS 'Таб.УдалитьСтроку', <Имя таблицы>, <Номер строки>, <Имя массива>
GS 'Таб.УдалитьСтроку', <Имя таблицы>, 'id:<ID строки>', <Имя массива>
GS 'Таб.Получить', <Имя таблицы>, <Значение индексного поля>, <Имя массива>

Параметры:

Пример:

GS 'Таб.СтрокуВМассив', 'Персонажи', 2, 'Герой'
GS 'Таб.СтрокуВМассив', 'Персонажи', 'id:5', 'Герой'
GS 'Таб.СтрокуВМассив', 'Персонажи', 'index:17', 'Герой'
GS 'Таб.СтрокуВМассив', 'Персонажи', 'Арабелла', 'Герой'

Получаем массив:

$Герой['Имя']='Арабелла'
Герой['Здоровье']=77
$Герой['Раса']='Амазонка'

Таб.КоличествоКолонок · Table.ColumnsCount

Возвращает число колонок в таблице.

Синтаксис:

func('Таб.КоличествоКолонок', <Имя таблицы>)

Параметры:

Пример:

рВсегоКолонок=func('Таб.КоличествоКолонок', 'Персонажи')

func('Таб.КоличествоСтрок', <Имя таблицы>)
func('Таб.КоличествоСтрок', <Имя таблицы>, <Название/Номер колонки>, <Операция сравнения>, <Параметр 1>, <Параметр 2>)

рВсегоСтрок=func('Таб.КоличествоСтрок', 'Персонажи')
рВсегоСтрок=func('Таб.КоличествоСтрок', 'Персонажи', 'Здоровье', 'между', 40, 70)
рВсегоСтрок=func('Таб.КоличествоСтрок', 'Персонажи', 'Раса', 'в списке', 'варвар, монах')

GS 'Таб.Выбрать', <Имя таблицы>
GS 'Таб.Выбрать', <Имя таблицы>, <Название/Номер колонки>, <Операция сравнения>, <Параметр 1>, <Параметр 2>

GS 'Таб.Выбрать', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи', 'Герой'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

GS 'Таб.Выбрать', 'Персонажи', 'Раса', 'в списке', 'варвар, монах')
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи', 'Герой'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

GS 'Таб.ВНачало', <Имя таблицы>

GS 'Таб.Выбрать', 'Персонажи'
GS 'Таб.ВНачало', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи', 'Герой'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

GS 'Таб.ВКонец', <Имя таблицы>

GS 'Таб.Выбрать', 'Персонажи'
GS 'Таб.ВКонец', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Предыдущая', 'Персонажи', 'Герой'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

func('Таб.Следующая', <Имя таблицы>)
func('Таб.Следующая', <Имя таблицы>, <Имя массива>)

GS 'Таб.Выбрать', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи', 'Герой'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

func('Таб.Предыдущая', <Имя таблицы>)
func('Таб.Предыдущая', <Имя таблицы>, <Имя массива>)

GS 'Таб.Выбрать', 'Персонажи'
GS 'Таб.ВКонец', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Предыдущая', 'Персонажи', 'Герой'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

func('Таб.Первая', <Имя таблицы>)

GS 'Таб.Выбрать', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи', 'Герой'):
    *NL IIF(func('Таб.Первая'),'F',IIF(func('Таб.Последняя'),'L',' '))+' | '+func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

func('Таб.Последняя', <Имя таблицы>)

GS 'Таб.Выбрать', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи', 'Герой'):
    *NL IIF(func('Таб.Первая'),'F',IIF(func('Таб.Последняя'),'L',' '))+' | '+func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+$Герой['Имя']+' ('+Герой['Здоровье']+')'
    JUMP 'перебор_строк_таблицы'
end

func('Таб.Значение', <Имя таблицы>, <Название/номер колонки>)

GS 'Таб.Выбрать', 'Персонажи'
:перебор_строк_таблицы
if func('Таб.Следующая', 'Персонажи'):
    *NL func('Таб.Значение', 'Персонажи', 'НомерСтроки')+'. '+func('Таб.Значение', 'Персонажи', 'Имя')
    JUMP 'перебор_строк_таблицы'
end

GS 'Таб.Скопировать', <Имя таблицы-источника>, <Имя таблицы-приемника>
GS 'Таб.Скопировать', <Имя таблицы-источника>, <Имя таблицы-приемника>, <Название/Номер колонки>, <Операция сравнения>, <Параметр 1>, <Параметр 2>

GS 'Таб.Скопировать', 'Персонажи', 'Головорезы'
GS 'Таб.Скопировать', 'Персонажи', 'Головорезы', 'Раса', '=', 'Варвар'

GS 'Таб.Вывести', <Имя таблицы>, <Скрыть шапку>

GS 'Таб.Вывести', 'Персонажи'

GS 'Таб.УдалитьСтроки', <Имя таблицы>
GS 'Таб.УдалитьСтроки', <Имя таблицы>, <Название/Номер колонки>, <Операция сравнения>, <Параметр 1>, <Параметр 2>

GS 'Таб.УдалитьСтроки', 'Персонажи'
GS 'Таб.УдалитьСтроки', 'Персонажи', 'Раса', '=', 'Монах'

GS 'Таб.Удалить', <Имя таблицы>

GS 'Таб.Удалить', 'Персонажи'