easy.database.qsp v. 0.2

Функции модуля

Функции для работы с базой данных. База данных, Таблица данных, Колонка, Строка

Большинство функций автоматически перемещают указатель на указанные таблицу, колонку и/или строку.

edb.init

Данная функция служит для инициализации базы данных.

Инициализация должна проводиться в самом начале игры, после чего больше повторяться не может. На всю игру создаётся только одна база данных. При этом инициализируются следующие значения в массиве $EASY_DATABASE :

• ID - идентификатор базы данных в виде псевдо-UUID. Нужен для проверки инициализации базы данных.
• data_tables_counter - счётчик созданных таблиц данных, включая удалённые.
• data_tables_number - счётчик существующих в настоящий момент таблиц данных.
• data_tables_ids - список существующих таблиц данных.
• last_data_table - указатель на предыдущую активную таблицу данных.
• current_data_table - указатель на текущую активную таблицу данных.

Вызов функции:

edb.print

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

Аргументы:

• $args[0] — управляющие конструкции:
  • [inmain] — выведет информацию напрямую в окно основного описания.
  • [instat] — выведет информацию напрямую в окно дополнительного описания.
  • если ни одна из двух предыдущих конструкций не указана, вернёт информацию в виде результата.
  • [all arrays] — к информации добавится список всех массивов, занятых базой данных.

Примеры вызова функции:

edb.new_table

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

Аргументы:

• $args[0] — обязательный аргумент, идентификатор таблицы данных.
• $args[1] — название таблицы данных. Можно не указывать, или указать пустое значение.
• $args[2] — тип первичных ключей (по умолчанию [rstr:16]):
  • [msecscount] - первичные ключи будут генерироваться на основе данных из функции msecscount.
  • [uuid] - первичные ключи генерируются в формате UUID
  • [hex:N] - первичные ключи генерируются, как порядковое шестнадцатерияное число из N символов. Это ограничит высоту таблицы данных максимальным возможным в этой таблице данных числом.
  • [num:N] - первичные ключи генерируются в виде N-значного десятеричного числа. Это ограничит высоту таблицы данных максимальным возможным в такой таблице числом.
  • [rhex:N] - первичным ключом будет назначаться случайное шестнадцатеричное число, состоящее из не менее, чем 8 символов.
  • [rnum:N] - первичным ключом будет назначаться случайное десятерично число, состоящее из не менее, чем 16 символов.
  • [uid] - первичный ключ будет генерироваться из строки случайных букв и цифр плюс текущее абсолютное значение от msecscount
  • [rstr:N] - первичный ключ генерируется, как случайный набор букв и цифр из N символов, но не менее 16 символов.

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

• ID — идентификатор таблицы данных.
• NAME — название таблицы данных.
• columns — список колонок таблицы данных.
• current_col — идентификатор текущей колонки (указатель).
• current_row — идентификатор текущей строки (указатель).
• primary_keys_type — тип первичных ключей.
• free_keys — список освободившихся первичных ключей (только для порядковых первичных ключей).

Также при создании таблицы данных изменяются соответствующие значения в $EASY_DATABASE, и инициализируется массив для колонки первичных ключей.

Примеры:

edb.del_table

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

Аргументы:

• $args[0] — идентификатор таблицы данных (по умолчанию используется идентификатор из указателя).

При удалении таблицы данных уничтожаются массивы, соответствующие колонкам, а также одноимённый с идентификатором массив, описывающий свойства таблицы данных. Помимо этого изменяются соответствующие значения в массиве $EASY_DATABASE.

Примеры:

edb.dt.set_cur

Устанавливает указанную таблицу данных текущей.

Аргументы:

• $args[0] — идентификатор таблицы данных.

Идентификатор текущей таблицы данных записывается в $EASY_DATABASE['last_data_table'], а идентификатор указанной таблицы данных записывается в $EASY_DATABASE['current_data_table'].

Пример:

edb.dt.print

Выводит на печать или возвращает человекочитаемое описание таблицы данных.

Аргументы:

• $args[0] — идентификатор таблицы данных. Если не указывать, используется текущий.
• $args[1] — управление:
  • [oi], [only info] — будет возвращена только информация о таблице данных
  • [ot], [only table] — будет возвращёна только html-таблица с содержимым таблицы данных.
    • [range:N-M] — будут возвращены только строки с N по M включительно.
  • если предыдущие опции не указаны, возвращается и информация и html-таблица с содержимым.
  • [inmain] — выведет информацию напрямую в окно основного описания.
  • [instat] — выведет информацию напрямую в окно дополнительного описания.
  • если ни одна из двух предыдущих конструкций не указана, вернёт информацию в виде результата.

Примеры вызова:

Внимание!!! В описании таблицы данных указывается её высота, эта высота определяется размером массива первичных ключей, однако поскольку нулевая ячейка каждого массива используется под служебную информацию, полезная высота таблицы данных на единицу меньше обозначенной при выводе. Учитывайте это при работе с базой данных.

edb.dt.new_col

Создаёт колонку в таблице данных.

Аргументы:

• $args[0] — идентификатор колонки. Обязательный аргумент.
• $args[1] — тип колонки. По умолчанию, тип 'str'.
• $args[2] — идентификатор таблицы данных. Если не указан, используется текущий.

Примеры вызова:

При создании колонки в таблице данных инициализируется массив с именем, состоящим из идентификатора таблицы данных и идентификатора колонки данных, поэтому к идентификатору колонки применяются те же требования, что и к названиям массивов в QSP. Например, если идентификатор таблицы данных objects, а идентификатор колонки body, будет инициализирован массив $objects_body. При этом в нулевую ячейку такого массива записывается тип колонки:

• 'str' - это колонка, которая может содержать только простую строку
• 'dict' - это колонка, содержащая словарь значений. Словарь составляется из тегов типа "[tag:строка текста:tag]".
• 'list' - это строка, содержащая перечисленные через | значения
• 'tuple' - колонка со значениями кортежами
• 'num' - колонка с числовыми значениями
• 'ids' - колонка первичных ключей (нельзя указывать этот тип, так как колонка первичных ключей создаётся автоматически)

edb.dt.del_col

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

Аргументы:

• $args[0] - идентификатор колонки. Если не указан, используется идентификатор из указателя текущей колонки.
• $args[1] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Пример:

Удаление колонки приводит к уничтожению соответствующего массива. Восстановить удалённую колонку нельзя.

edb.dt.new_row

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

Аргументы:

• $args[0] - идентификатор таблицы данных. Если не указан, используется идентификатор из указтеля текущей колонки.

Функция возвращает идентификатор созданной строки, для дальнейшего использования.

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

Пример:

edb.dt.del_row

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

Аргументы:

• $args[0] - идентификатор строки. Если не указан, используется идентификатор из указателя текущей строки.
• $args[1] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Примеры:

Удаление строки — это уничтожение ячеек в массивах, соответствующих колонкам таблицы данных, по индексу, совпадающему с первичным ключом.

edb.dt.height

Функция для получения высоты таблицы данных.

Аргументы:

• $args[0] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Возвращает высоту таблицы данных (число).

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

Пример:

edb.dt.width

Функция для получения ширины таблицы данных.

Аргументы:

• $args[0] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Возвращает ширину таблицы данных (число), которое соответствует числу колонок. Работа этой функции основана на цикле.

Пример:

edb.dt.find

Поиск значения по таблице данных.

Аргументы:

• $args[0] - регулярное выражение по которому производится поиск. Поиск ведётся на точное совпадение с регулярным выражением. Невозможно производить поиск по регулярному выражению, если тип колонки, по которой производится поиск, 'num'.
• $args[1] - идентификатор колонки, по которой производится поиск. Если не указан, используется идентификатор из указателя текущей колонки.
• $args[2] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы данных.
• $args[3] - размер чанка. Чанк - это фрагмент таблицы данных, по которому будет производиться поиск. Разбиение на чанки ускоряет поиск, если искомая информация находится где-то в начале таблицы данных.
• $args[4]... $args[18] — дополнительные фильтры в виде кортежей:
  • (колонка, значение, управление) - управление:
    • [regexp] - регулярка. Точное соответствие. Не работает для колонок типа 'num'
    • [callback] - функция колбэк принимающая, как аргумент, значение элемента, и возвращающая 1 или 0, в зависимости от результатов фильтрации
    • [strict] (или не указанное значение) - проверяем на точное соответствие.

Функция возвращает идентификатор строки, в которой найдено искомое значение.

Примеры:

edb.dt.clear

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

Аргументы:

• $args[0] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Пример:

edb.dt.clone

Создаёт копию таблицы данных, или указанной части таблицы данных.

Аргументы:

• $args[0] - идентификатор новой таблицы данных. Обязательный аргумент.
• $args[1] - идентификатор исходной таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.
• $args[2] или args[2] - идентификатор строки, от которой нужно производить клонирование, или номер этой строки. Если не указано, копирование таблицы данных будет производиться с первой строки. Технически нулевые ячейки массивов, соответствующих колонкам, отведены под хранение служебной информации, поэтому нумерация строк таблицы данных ведётся с 1.
• args[3] - число строк, которые необходимо скопировать. По-умолчанию: все оставшиеся строки.

Технически функция делает то, что указано. Создаёт точную копию уже существующей таблицы данных, либо некоторого количества её строк. При этом копируются все колонки, в т.ч. и колонка первичных ключей. В новой таблице данных снимаются все указатели, однако указатель текущей таблицы данных переводится на неё.

Примеры:

edb.col.set_cur

Устанавливает указанную колонку в качестве текущей.

Аргументы:

• $args[0] — идентификатор колонки.
• $args[1] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Технически присваивает ячейке одноименного с идентификатором таблицы данных массива под индексом 'current_col' указанный идентификатор колонки.

Примеры:

edb.col.print

Вывод содержимого указанной колонки.

Аргументы:

• $args[0] — идентификатор колонки. Если не указан, используется идентификатор из указателя текущей колонки.
• $args[1] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.
• $args[2] — управление:
  • [inmain] — выведет информацию напрямую в окно основного описания.
  • [instat] — выведет информацию напрямую в окно дополнительного описания.
  • если ни одна из двух предыдущих конструкций не указана, вернёт информацию в виде результата.
  • [range:N-M] — вывод значений от элемента N до M включительно в колонке.

Примеры:

edb.col.set_next

Присваивает значение ячейке текущей строки, затем перемещает указатель на следующую строку.

Аргументы:

• $args[0] - значение, присваиваемое ячейке.
• $args[1] - идентификатор колонки. Если не указан, используется идентификатор из указателя текущей колонки.
• $args[2] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

ВНИМАНИЕ!!! Данная функция использует arrpos для поиска элементов. Для баз больших объёмов это может существенно подвешивать игру. Не используйте данную функцию без необходимости.

Примеры:

edb.row.set_cur

Устанавливает указанную строку в качестве текущей.

Аргументы:

• $args[0] — идентификатор строки.
• $args[1] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Технически присваивает ячейке одноименного с идентификатором таблицы данных массива под индексом 'current_row' указанный идентификатор строки. Сделать текущей строку, которой нет в таблице данных нельзя, однако ошибку в игре это не вызовет.

Примеры:

edb.row.fill

Заполняет строку значениями.

Аргументы:

• $args[0]... $args[18] — значения, или кортежи типа (идентификатор колонки, значение), с помощью которых заполняются ячейки в строке.
• $args[18]... $args[0] — кортеж типа (идентификатор строки, идентификатор таблицы данных), либо только идентификатор строки.

Внимание! При использовании данной функции не происходит переключения текущей колонки.

Примеры:

edb.row.print

Вывод содержимого указанной строки.

Аргументы:

• $args[0] - идентификатор строки. Если не указан, используется идентификатор из указателя текущей строки.
• $args[1] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.
• $args[2] - управление:
  • [inmain] — выведет информацию напрямую в окно основного описания.
  • [instat] — выведет информацию напрямую в окно дополнительного описания.
  • если ни одна из двух предыдущих конструкций не указана, вернёт информацию в виде результата

Пример:

edb.row.set_next

Присваивает значение ячейке текущей колонки, затем перемещает указатель на следующую колонку.

• $args[0] - значение.
• $args[1] - идентификатор строки. Если не указан, используется идентификатор из указателя текущей строки.
• $args[2] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Примеры:

edb.row.exchange

Функция меняет содержимое двух строк местами. Внимание!!! Меняется именно содержимое строк. Идентификаторы не перемещаются, т.е. фактически строки остаются на своих местах, но обмениваются содержимым !

• $args[0] - идентификатор одной строки.
• $args[1] - идентификатор другой строки.
• $args[2] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Обменять ошибку несуществующих строк нельзя, однако ошибку в игре это не вызовет.

Строка, идентификатор которой передан в $args[0], становится текущей.

Пример:

edb.row.extract

Извлекает из строки содержимое, помещая значения в указанный массив, при этом индексами элементов массива выступают названия колонок.

Концепция функции взята из модуля Олегуса.

Аргументы:

• $args[0] - название массива. Обязательный аргумент.
• $args[1] - идентификатор строки. Если не указан, используется идентификатор из указателя текущей строки.
• $args[2] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Пример:

edb.row.inject

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

Внимание!!! Новые данные затирают уже существующие в строке данные.

Аргументы:

• $args[0] - название массива. Обязательный аргумент.
• $args[1] - идентификатор строки. Если не указан, используется идентификатор из указателя текущей строки.
• $args[2] - идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Пример:

edb.row.clone

Копирует строку внутри таблицы данных.

Аргументы:

• $args[0] — идентификатор клонируемой строки. Если не указан, клонируется текущая строка (идентификатор которой находится в указателе текущей строки).
• $args[1] — идентификатор таблицы данных. Если не указан, используется идентификатор из указателя текущей таблицы.

Возвращает идентификатор новой строки.

Технически в таблице данных создаётся новая строка с новым первичным ключом. Все остальные значения в ячейках этой строки идентичны значениям в исходной строке.

Пример: