easy.database.qsp v. 0.2

Система управления базой данных "easy.database" — это модуль (библиотека), предназначенный для простого редактирования нереляционной базы данных на QSP.

Существует модуль Олегуса, реализующий то же самое, но через другие механизмы: https://forum.ifiction.ru/viewtopic.php?id=1522.

Исходный код "easy.database" всегда доступен по адресу: https://github.com/AleksVersus/easy.nrBD

Подключение

"easy.database" подключается как любой другой модуль QSP, то есть с использованием команды inclib. Скачайте архив со страницы релизов, распакуйте и скопируйте папку "lib" в папку с вашей игрой. Тогда на самой первой локации в игре достаточно будет прописать такую команду подключения:

Для работы модуля требуется так же подключить и библиотеку "easy.math". Она поставляется вместе с модулем. Подключение аналогичное:

Если вы уже используете библиотеку "easy.math" в своей игре, убедитесь, что версия "easy.math" совместима с "easy.database". Для этого в любом месте вашей игры используйте команду:

При запуске игры вы увидите на экране текущую и необходимую версии модуля "easy.math".

Работа с исходниками

Если вы пишете игру, используя Sublime Text с подключённым пакетом QSP, у вас есть возможность самостоятельно собирать модуль из исходников.

В папке " [source] " размещены исходные тексты модуля, а так же файл " project.json ", отредактировав который вы наладите сборку модуля в папку с вашей игрой.

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

В исходниках предусмотрены два режима сборки: без обработки препроцессором и с обработкой препроцессором.

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

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

Вы также можете включить препроцессор, но сохранить блоки предохранителей в конечной сборке модуля. Для этого в исходном файле " 00_edb.start.qsps " в любом месте пропишите строку:

Обратите внимание! Исходники библиотеки "easy.math" необходимо скачивать отдельно: easy.math на github

Подключение встроенного отладчика

Вы можете подключить отладочные команды модуля к командной строке (полю ввода), прописав в самом начале игры следующую команду:

Это добавит новый обработчик строки ввода к уже работающим. Обратите внимание на квадратные скобки. Если вы используете свой собственный обработчик строки ввода и хотите, чтобы обработчик модуля работал совместно (параллельно) с вашим, обязательно ставьте квадратные скобки после $usercom.

Все команды модуля должны начинаться с ключевого слова edb. Для вывода списка всех доступных команд, введите в строке ввода edb help.

Также список всех доступных команд для поля ввода представлен в разделе данной документации "Команды отладки".

Особенности работы

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

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

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

Также при создании таблицы данных автоматически генерируется колонка первичных ключей. Она является служебной, и с ней нельзя напрямую взаимодействовать, хотя технически это такой же массив, как и все прочие, поэтому при желании вы можете изменять колонку первичных ключей, используя чистый QSP. Колонка первичных ключей всегда представляет собой массив, название которого состоит из идентификатора таблицы данных и слова ' _id '.

Примеры имён массивов, представляющих колонки первичных ключей для разных таблиц данных:

Основные функции, реализующие работу с базой данных, представленны в виде локаций-функций. Названия всех таких локаций начинаются с edb. Для удобства чтения кода названия локаций содержат точки, это не мешает использовать их при неявном вызове func :

Также для улучшения семантики в названиях локаций-функций указывается сущность, с которой они работают, и только затем непосредственно названия функций. Исключение составляют функции, работающие непосредственно с сущностью базы данных:

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

Сущности

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

База данных. Data Base

QSP не позволяет организовать полноценную базу данных, но в большинстве игр она и не нужна. Тем не менее можно реализовать некий аналог базы данных, чтобы облегчить себе работу с различными игровыми объектами.

Технически База данных в QSP — это набор массивов, которым мы можем тем или иным образом управлять через специальные механизмы Системы Управления Базой Данных. Последнее воплощено в данном модуле.

Непосредственно База Данных, как сущность, представлена в виде глобального массива $EASY_DATABASE[], в котором хранятся некоторые настройки, позволяющие Базой Данных управлять.

Чтобы использовать Базу Данных в своей игре, её необходимо инициализировать, то есть создать. А в дальнейшем применять методы для управления составляющими этой базы данных.

Методы

Методы Базы Данных представлены в виде соответствующих функций. С подробным описанием можно ознакомиться в разделе "Функции модуля".

• init - инициализация базы данных. Требуется в самом начале игры, чтобы заполнить массив $EASY_DATABASE[] исходными значениями. ( edb.init).
• print — вывод на экран, или в виде возвращаемого результата, человекочитаемой информации о базе данных. ( edb.print).
• new_table — создание таблицы данных с указанным идентификатором в базе данных. ( edb.new_table).
• del_table — удаление таблицы данных с указанным идентификатором из базы данных. ( edb.del_table).

Свойства

Свойства базы данных соответствуют значениям в массиве $EASY_DATABASE. См. функцию edb.init .

Таблица Данных. Data Table

Таблица данных — это наибольшая структурная единица базы данных. Именно из множества таблиц данных состоит вся база данных игры.

Технически Таблица Данных — это набор массивов, каждый из которых является столбцом такой таблицы. Соответственно строкой можно считать ряд записей во все массивы Таблицы Данных под одним индексом.

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

Методы

Методы Таблицы Данных представлены в виде соответствующих функций. С подробным описанием можно ознакомиться в разделе "Функции модуля".

• set_cur - устанавливает указанную таблицу данных в качестве текущей. ( edb.dt.set_cur).
• print - выводит на экран, или возвращает в виде результата, человекочитаемую информацию об указанной таблице данных. ( edb.dt.).
• new_col - создаёт в таблице данных колонку с указанным идентификатором. ( edb.dt.new_col).
• del_col - удаляет из таблицы данных колонку с указанным идентификатором. ( edb.dt.del_col).
• new_row - создаёт в таблице данных строку и возвращает её идентификатор. ( edb.dt.new_row).
• del_row - удаляет из таблицы данных строку с указанным идентификатором. ( edb.dt.del_row).
• height - возвращает высоту таблицы данных, то есть число строк. ( edb.dt.height).
• width - возвращает ширину таблицы данных, то есть число колонок. ( edb.dt.width).
• find - возвращает идентификатор строки, в которой найдено указанное значение. Данный метод позволяет использовать дополнительные фильтры для более точного поиска информации в таблице данных. ( edb.dt.find).
• clear - удаляет все строки в указанной таблице данных. ( edb.dt.clear).
• clone - копирует таблицу данных, или её часть, в новую таблицу данных. ( edb.dt.clone).

Свойства

Свойства таблицы данных соответствуют значениям в массиве, имя которого совпадает с идентификатором таблицы данных. См. функцию edb.new_table. Помимо этого механизмы "easy.database" используют не обозначенные в данном массиве свойства:

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

Колонка. Column

Таблица данных разбивается на колонки для удобства размещения информации. Как правило, колонка используется для хранения неких однотипных данных, реализующих какое-либо свойство для хранимой записи. Например, в таблице предметов может быть создана отдельная колонка для хранения названия, отдельная — для хранения веса, для хранения количества, и так далее.

Технически колонка представляет собой массив, название которого состоит из идентификатора таблицы данных и идентификатора колонки, разделённых символом нижнего подчёркивания. В нулевой ячейке такого массива прописывается тип данных, которые можно хранить в колонке (тип колонки). Возможные типы колонок можно посмотреть в описании функции edb.dt.new_col.

Примеры массивов, реализующих колонки:

• $objects_sid - колонка таблицы данных objects под именем sid.
• $objects_body - колонка таблицы данных objects под именем body

Колонки в данном руководстве могут называться столбцами.

Методы

• set_cur - устанавливает указанную колонку в качестве текущей. ( edb.col.set_cur).
• print - выводит на экран, или возвращает в виде результата, содержимое колонки или части колонки. ( edb.col.print).
• set_next - в указанной колонке присваивает значение ячейке текущей строки, затем перемещает указатель на следующую строку. ( edb.col.set_next).

Свойства

У любой колонки есть всего два свойства:

• высота — совпадает с размером массива, описывающего колонку.
• тип данных, хранящихся в колонке.

Строка. Row

Таблица данных разбивается на отдельные записи — строки — для удобства размещения информации. Как правило, строка используется для хранения отдельных сложных записей. Например, в таблице предметов каждая отдельная запись соответствует одному предмету.

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

Например, наша таблица данных objects состоит из трёх колонок id, body, position, это означает, что строки в такой таблице можно сформировать следующим образом:

Методы

• set_cur — устанавливает указанную строку в качестве текущей. ( edb.row.set_cur).
• fill — заполняет строку группой значений. ( edb.row.fill). Значения могут быть перечисленны по порядку в соответствующих аргументах (и таким образом будут размещены в колонках соответственно порядку идентификаторов колонок в списке колонок таблицы данных), либо в качестве аргументов можно указывать кортежи, состоящие из значения и идентификатора колонки. В последнем случае значения не обязательно передавать в порядке, соответствующем списку колонок. Если будут переданы одновременно аргументы в виде кортежей и отдельных значений, это может привести к ошибкам заполнения вроде перезаписи только что внесённых значений.
• print — выводит на экран, или возвращает в виде результата, содержимое строки, которое оформляется в виде списка. ( edb.row.print). Данный метод подходит только для контроля содержимого строк со стороны разработчика, и его нельзя использовать для получения содержимого строки в механизмах игры, т.к. многие ячейки могут содержать в себе списки.
• set_next — присваивает ячейке (в текущей колонке и указнной строке) значение, а затем сдвигает указатель на следующую строку. Когда указатель достигает последнего столбца, он больше не сдвигается. Таким образом при постоянном обращении к этой функции происходит выход за пределы таблицы данных, а значит значение будет присваиваться всегда последней ячейке в строке.. ( edb.row.set_next).
• exchange — обменивает содержимое строк, но сами строки позициями не меняются. Т.е. их идентификаторы в таблице данных не перемещаются. ( edb.row.exchange).
• extract — извлекает из строки содержимое, помещая значения в указанный массив, при этом индексами элементов массива выступают названия колонок. ( edb.row.extract).
• inject — вводит в указанную строку данные из указанного массива. При этом предполагается, что данные лежат в ячейках, индексы которых соответствуют названиям колонок таблицы данных. ( edb.row.inject).
• clone — дублирует строку в таблице данных. То есть создаётся новая строка, идентичная указанной, но с отличающимся идентификатором. ( edb.row.clone).

Ячейка. Cell

Ячейка — наименьшая структурная единица таблицы данных. Ячейки создаются в пересечениях строк и столбцов.

Технически Ячейка Таблицы Данных представляет собой ячейку массива, соответствующего колонке, под указанным индексом, являющимся идентификатором строки. Каждая ячейка содержит лишь одно значение.

Методы

• set_value — устанавливает значение ячейки. Если в ячейке уже было значение, оно затирается. При этом не важно, какой тип имеет столбец, в ячейку технически записываются либо число (для столбцов типа 'num'), либо строка (для столбцов всех остальных типов). ( edb.cell.set_value).
• get_value — извлекает значение из ячейки. ( edb.cell.get_value).
• add — добавляет значение к значению ячейки. Результат работы данной функции будет отличаться в зависимости от типа колонки. ( edb.cell.add).
• del — вычитает значение из значения ячейки. Результат работы данной функции будет отличаться в зависимости от типа колонки. ( edb.cell.del).

Список. List

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

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

Примеры списков:

Методы

• remove - заменяет указанное значение в списке на новое значение. Позволяет заменить самое первое указанное значение в списке, либо сразу все значения в списке. ( edb.list.remove).
• is_el - проверяет, является ли указанное значение элементом списка. ( edb.list.is_el).
• first - получает первое значение в списке. ( edb.list.first).
• last - получает последнее значение в списке. ( edb.list.last).
• append - добавляет элемент в конец списка. ( edb.list.append).
• diff - возвращает разницу двух списков. ( edb.list.diff).
• for_each - перебирает элементы списка, и для каждого вызывает переданный в качестве аргумента код. В этот код нулевым аргументом передаётся значение элемента списка. Таким образом можно довольно гибко обрабатывать любые списки. ( edb.list.for_each)
• length - возвращает длину списка. ( edb.list.length).

Свойства

Единственным свойством списка является его длина.

Команды отладки

Внимание!!! Отладчик ещё не доработан. Команды могут отличаться от версии к версии. Если вы вводите команду, а она не работает, или работает некорректно, проверьте локацию edb.usercom, чтобы убедиться, что ваша версия модуля поддерживает данную команду.

Все команды отладки начинаются с ключевого слова edb. Без этого ключевого слова отладчик просто не сработает. Ниже команды отладки приводятся без этого ключевого слова. Пример правильно введённой команды к отладчику:

• help - вывод справки по модулю easy.database.
• run - выполнить следующий после run текст, как строку кода QSP.
• verison — текущая версия модуля.
• required em — информация по используемому и необходимому easy.math.
• gen id - генерирует uuid.
• init - инициализирует базу данных.
• > - выводит информацию о базе данных.

Последняя команда может быть расширена через доп инструкции, идентификаторы сущностей и инструкции к ним. Большинство инструкций к сущностям совпадают с названиями методов для этих сущностей. Однако не все методы можно использовать. Ниже приводится список, соответствующий расширениям команды. Идентификаторы сущностей и инструкций должны разделяться символом >. Пример:

• new_table - создать новую таблицу данных. Идентификатор указывается далее через >.
• del_table - удалить таблицу данных. Идентификатор указывается далее через >.
• идентификатор таблицы данных - работа с указанной таблицей данных. Через > указывается:
  • set_cur — установить таблицу данных текущей.
  • print - распечатать информацию по таблице данных в основном описании.
  • new_col - создать новую колонку в таблице данных. Идентификатор колонки указывается далее через >.
  • del_col - удалить колонку из таблицы данных. Идентификатор колонки указывается далее через >.
  • new_row - создать новую строку в таблице данных. Идентификатор строки указывается далее через >.
  • del_row - удалить строку из таблицы данных. Идентификатор строки указывается далее через >.
  • height - получить высоту таблицы данных.
  • width - получить ширину таблицы данных.
  • clear - очистить таблицу данных от строк.
  • clone - полное клонирование таблицы данных в новую таблицу данных. Идентификатор новой таблицы данных указывается далее через >.
  • идентификатор строки - работа с указанной строкой в таблице данных. Через > указывается:
    • set_cur — установить строку текущей.
    • print — вывести на экран содержимое строки в виде списка.
  • идентификатор колонки - работа с указанной колонкой в таблице данных. Через > указывается:
    • set_cur — установить колонку текущей.
    • print — вывести на экран содержимое колонки. идентификатор строки - работа с ячейкой в указанных колонке и строке. Через > указывается:
      • set_value - установить значение ячейки. Значение указывается через > без пробелов. Все последующие символы > считаются относящимися к значению.
      • get_value - вывести на экран значение ячейки. Значение можно сразу записать в глобальную переменную, для этого через > указывается название переменной.

Подробнее: