Модуль:WDBackend/doc

Модуль предназначен для получения информации из Викиданных по задаваемой схеме. Схема описывается в формате таблицы Lua.

Модуль используется в модуле Модуль:CiteGost/WDSource для получения информации об источниках информации. Модуль WDSource, в свою очередь, используется в модуле Модуль:CiteGost для оформления библиографических записей.

Использование

Создать экземпляр объекта форматирования можно функцией модуля new() с указанием языка получения данных. Для получения данных по схеме можно использовать методы полученного объекта:

• fetchEntity(таблица, элемент, схема) — получить данных по схеме из указанного элемента Викиданных.
• fetch(таблица, схема) — получить данных по схеме (элементы Викиданных уже указаны в схеме).
• ensureLang() — ассерт на то, что язык точно выбран.

Формат схемы

Формат схемы в общем виде:

{
  -- Поле с указаным элементом Викиданных:
  {
    name = 'Имя поля с QID',
    -- Получить из элемента данные:
    get = {
      -- 1-е поле
      {
        name = 'Имя получаемого поля',

        property = 'P-идентификатор свойства',

        match = Значение, по которому будут обрабатываться квалификаторы (работает совместно с qualifiers),

        getValue = Опциональная функция получения значения (должна возвращать два аргумента: текст и язык текста),

        getData = Опциональная функция получения данных о значении (помимо значения, например, может возвращать его язык и флаг fromLabel получения данных из метки элемента),

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

        max = Опциональное максимальное количество обрабатываемых значений,

        -- Подмена элементов Викиданных согласно отображению (ключ заменяется на значение):
        mapEntities = { QID 1 = 'QID 2', ... },

        -- Фильтрация по разрешённых элементам Викиданных:
        allowedEntities = { QID 1, QID 2, ... },

        defaultUnit = QID единицы измерения по умолчанию,

        -- Фильтрация по разрешённым единицам измерения:
        allowedUnits = { QID единицы измерения 1, QID единицы измерения 2, ... },

        -- Перезаписать поле, если у него уже задано значение:
        overwrite = true,

        -- Перезаписать идентификатор элемента Викиданных родительского поля (для безымянных полей):
        overwriteEntity = true,

        -- Перезаписать значение родительского поля (для безымянных полей):
        overwriteValue = true,

        -- Сделать поле вложенным полем для родительского (поместить в components):
        isLocal = true,

        -- Пометить значение как точное (например, как указано в источнике):
        exact = true,

        -- Принудительно делать из поля массив:
        isArray = true,

        -- Подставить значение текущего поля в другое по шаблону, заданному ещё одним полем:
        substInto = {
          name = 'Целевое поле (куда записываем)',
          template = {
            name = 'Имя поля, в значении которого записан шаблон',
          },
        }

        -- Получить другие поля из элемента Викиданных данного поля:
        get = {
          -- ...
        },

        -- Если текущее поле не удалось получить, то получить другие поля:
        elseGet = {
          -- ...
        },
      },
      -- ...
    },
  },
  -- ...
}

Общий формат отдельного поля:

{
  value = Значение (в случае даты — таблица)
  entity = Идентификатор элемента Викиданных
  unitEntity = Идентификатор элемента Викиданных единицы измерения, соответствующей значению value
  retrieved = Флаг, обозначающий, что поле было получено из Викиданных (а не заполнено вручную)
  exact = Флаг, обозначающий, что получено уточнённое значение поля
  lang = Язык, соответствующий значению
  components = {
    -- Вложенные поля
    -- ...
  },
}

Принцип работы

При обходе полей схемы, если в поле уже есть значение, то второй раз оно уже не будет получено, если только не указано overwrite=true, что подразумевает перезапись ранее заданного или полученного значения. Таким образом, можно в одно и то же поле пытаться получать значение по очереди из разных свойств. Получено будет первое попавшееся значение. По этому принципу (порядок получения) можно выстраивать приоритет получения данных из разных ствойств.

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

Если в поле не задано имя, то полученное значение никуда не записывается. Если же задан параметр overwriteEntity, перезаписывается идентификатор родительского элемента. Если задан параметр overwriteValue, — значение родительского элемента. Безымянные поля удобны для перезаписи значений родительских полей из квалификаторов, либо же для получения свойств из полученного в безымянном поле элемента через get.

Внесение изменений

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

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

Тесты

См. также: Модуль:WDBackend/testcases

N26 tests failed.

	Name	Expected	Actual
N	test_fetchEntity_array	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_baseTypes	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_components	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_defaultUnit	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_elseGet_exists	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_elseGet_in_inLocal_with_overwriteEntity	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_elseGet_notExists	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_forceGet	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_forceGet_predefined_value	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_get	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_getValue	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_has	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_isArray	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_isLocal_in_array	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_isLocal_in_unnamed	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_isLocal_with_qualifiers_and_get_by_entity_with_isLocal	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_map	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_max	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_noOverwrite	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_overwrite	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_overwriteByQualifier	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_overwriteEntity	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_overwriteValue	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_overwriteValueByQualifier	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_qualifiers	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)
N	test_fetchEntity_substInto	Lua error -- Модуль:WDBase:29: attempt to index field 'wikibase' (a nil value)