InnerCore/Библиотеки - История изменений

80LK в 17:47, 4 июля 2018

2018-07-04T17:47:23Z

Admin в 21:10, 10 марта 2018

2018-03-10T21:10:20Z

Admin: Created page with " Библиотеки — это дополнительные исполняемые файлы, нужные, чтобы дополнить и расширить сущест..."

2018-03-10T21:09:48Z

Created page with " Библиотеки — это дополнительные исполняемые файлы, нужные, чтобы дополнить и расширить сущест..."

Новая страница

Библиотеки — это дополнительные исполняемые файлы, нужные, чтобы дополнить и расширить существующий API и упростить выполнение каких-либо задач.  

== Добавление библиотек в моды ==

Библиотеки представлены одиночным файлом с кодом. Чтобы добавить библиотеку в мод, ее нужно переместить в директорию библиотек мода (обычно она называется lib, название директории задается параметром libraryDir в разделе defaultConfig файла построения).

== Принцип работы библиотек ==

Библиотека регистрирует новые объекты API, которые можно импортировать в пространство имен любого исполняемого файла для их последующего использования. Имя библиотеки и имена объектов API, которые она добавляет можно посмотреть в документации к ней.

Чтобы импортировать библиотеку используется команда IMPORT:

''IMPORT'' (''"имя библиотеки") - импортирует все объекты API из указанной библиотеки''

''IMPORT ("имя библиотеки", "имя объекта API") - импортирует конкретный объект API из указанной библиотеки''

== Область видимости библиотек ==

Библиотеки бывают двух типов - локальные и глобальные.  

Локальные могут быть импортированы только в пределах одного мода, и, если одна и та же библиотека присутствует в двух разных модах, она будет загружена для каждого из них отдельно. Локальные библиотеки используются в случае, когда API, которое она добавляет не нуждается в совместимости. К примеру, библиотека ToolType просто добавляет упрощенные типы инструментов.

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

== Версии библиотек ==

Каждая библиотека имеет свой собственный код версии, он нужен для определения самой новой версии библиотеки, если одновременно используется несколько одинаковых библиотек. Особенно это касается глобальных.

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

== Обратная совместимость ==

Новые версии библиотек могут изменять старый API, при этом правило с загрузкой максимальной версии может вызвать некорректную работу какого-то мода, использующего старую версию библиотеки.

Для этого в команде импорта существует возможность импортировать библиотеку с указанием целевой версии. Формат команды импорта с указанием целевой версии:

''IMPORT ("имя библиотеки:целевая версия", ...) - в первом параметре указывается через двоеточие код целевой версии библиотеки, второй параметр остается неизменным.''

Советуется использовать именно этот вариант импорта, чтобы минимизировать шанс того, что полученный API не будет соответствовать ожидаемому (Произойдет это только в том случае, если разработчик библиотеки не позаботился об обратной совместимости).

= Разработка библиотек =

Как было сказано выше библиотека — это одиночный файл с кодом. Далее будут рассмотрены особенности разработки библиотек.

== Заголовок ==

Заголовок библиотеки полностью описывает ее параметры и представлен вызовом команды LIBRARY перед всем остальным кодом. 

Использование команды LIBRARY:''
<syntaxhighlight lang="Javascript">LIBRARY({
name: "имя библиотеки", // по этому имени библиотека будет импортирована
version: код версии, // код версии должен быть целым числом больше 0, при каждом обновлении библиотеки его надо увеличивать и указывать в документации к ней
shared: false, // если true, то библиотека будет глобальной api: "CoreEngine", // название API, которое использует библиотека
dependencies: [ "name1:version1",
//...
]
/* список зависимостей от других библиотек в том же формате, что и первый параметр команды IMPORT (Импортировать эти библиотеки надо отдельно, этот параметр гарантирует их загрузку до загрузки этой библиотеки)*/
});
</syntaxhighlight>

== Импорт библиотек ==

Импорт других библиотек происходит по тем же принципам, что и в обычных файлах модов, однако все импортируемые библиотеки нужно задекларировать в загловке в параметре dependencies с учетом версий.

== Экспорт объектов API ==

Экспорт объектов API является самой важной частью библиотек, без которой они теряют свой смысл. Экспорт позволяет передать какой-либо объект под данным именем для его последующего импорта из этой библиотеки.

Использование команды EXPORT:

''EXPORT("имя объекта API", объект API) - делает данный объект доступным для экспорта под данным именем''

== Обратная совместимость экспортируемых объектов ==

При изменении объекта API и его несовместимости с прошлыми версиями (к примеру при удалении или изменении названия метода) стоит сделать дополнительный экспорт для обратной совместимости.

Использование команды EXPORT для добавления объекта обратной совместимости:

''EXPORT("имя объекта API:код версии", объект API) - экспортирует данный объект для версий <код версии> и ниже, может присутствовать экспорт с таким же именем и без версии, а так же другие импорты для совместимости с более низкими версиями.''

Пример (Версия библиотеки, в которой это происходит больше 3):''
<syntaxhighlight lang="Javascript">EXPORT("print", function() {
alert("new version print");
});

EXPORT("print:3", function() {
alert("older print");
});

EXPORT("print:1", function() {
alert("first version print");
});</syntaxhighlight>

При импорте библиотеки с указанием разных версий, всегда будет присутствовать print, однако для новых версий это будет первый вариант, для версии 3 и ниже - второй, а для версии 1 - третий.

@@ Строка 46: / Строка 46: @@
 Как было сказано выше библиотека — это одиночный файл с кодом. Далее будут рассмотрены особенности разработки библиотек.
 == Заголовок ==
@@ Строка 54: / Строка 55: @@
      name: "имя библиотеки", // по этому имени библиотека будет импортирована
      version: код версии, // код версии должен быть целым числом больше 0, при каждом обновлении библиотеки его надо увеличивать и указывать в документации к ней
-     shared: false, // если true, то библиотека будет глобальной api: "CoreEngine", // название API, которое использует библиотека
+     shared: false, // если true, то библиотека будет глобальной
      dependencies: [  "name1:version1",
          //...
@@ Строка 61: / Строка 63: @@
 });
 </syntaxhighlight>
 == Импорт библиотек ==

@@ Строка 1: / Строка 1: @@
 Библиотеки — это дополнительные исполняемые файлы, нужные, чтобы дополнить и расширить существующий API и упростить выполнение каких-либо задач. &nbsp;
@@ Строка 48: / Строка 50: @@
 Заголовок библиотеки полностью описывает ее параметры и представлен вызовом команды LIBRARY <u>перед всем остальным кодом</u>.&nbsp;
-Использование команды LIBRARY:''
+Использование команды LIBRARY:
 <syntaxhighlight lang="Javascript">LIBRARY({
      name: "имя библиотеки", // по этому имени библиотека будет импортирована
@@ Строка 80: / Строка 82: @@
 ''EXPORT("имя объекта API:код версии", объект API) - экспортирует данный объект для версий <код версии> и ниже, может присутствовать экспорт с таким же именем и без версии, а так же другие импорты для совместимости с более низкими версиями.''
-<u>Пример (Версия библиотеки, в которой это происходит больше 3):</u>''
+<u>Пример (Версия библиотеки, в которой это происходит больше 3):</u>
 <syntaxhighlight lang="Javascript">EXPORT("print", function() {
      alert("new version print");