Экспорт функций

Руководство по экспорту функций из вашего плагина для использования другими языковыми модулями в Plugify.

В экосистеме Plugify плагины на Lua могут экспортировать функции, чтобы сделать их доступными для других плагинов. Это руководство объясняет, как определять и экспортировать функции в Lua, и предоставляет примеры, которые помогут вам беспрепятственно интегрировать ваши плагины.

Базовое сопоставление типов

В следующей таблице перечислены способы представления типов в Python API:

Тип C++Тип LuaПсевдоним PlugifyПоддержка ссылок ?
voidnilvoid❌
boolbooleanbool✅
charstringchar8✅
char16_tstringchar16✅
int8_tintegerint8✅
int16_tintegerint16✅
int32_tintegerint32✅
int64_tintegerint64✅
uint8_tintegeruint8✅
uint16_tintegeruint16✅
uint32_tintegeruint32✅
uint64_tintegeruint64✅
uintptr_tintegerptr64✅
uintptr_tintegerptr32✅
floatnumberfloat✅
doublenumberdouble✅
void*functionfunction❌
plg::stringstringstring✅
plg::anyanyany✅
plg::vector<bool>tablebool[]✅
plg::vector<char>tablechar8[]✅
plg::vector<char16_t>tablechar16[]✅
plg::vector<int8_t>tableint8[]✅
plg::vector<int16_t>tableint16[]✅
plg::vector<int32_t>tableint32[]✅
plg::vector<int64_t>tableint64[]✅
plg::vector<uint8_t>tableuint8[]✅
plg::vector<uint16_t>tableuint16[]✅
plg::vector<uint32_t>tableuint32[]✅
plg::vector<uint64_t>tableuint64[]✅
plg::vector<uintptr_t>tableptr64[]✅
plg::vector<uintptr_t>tableptr32[]✅
plg::vector<float>tablefloat[]✅
plg::vector<double>tabledouble[]✅
plg::vector<plg::string>tablestring[]✅
plg::vector<plg::any>tableany[]✅
plg::vector<plg::vec2>tablevec2[]✅
plg::vector<plg::vec3>tablevec3[]✅
plg::vector<plg::vec4>tablevec4[]✅
plg::vector<plg::mat4x4>tablemat4x4[]✅
plg::vec2Vector2vec2✅
plg::vec3Vector3vec3✅
plg::vec4Vector4vec4✅
plg::mat4x4Matrix4x4mat4x4✅

Экспорт функций в Lua

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

Простой пример

Вот простой пример экспорта функции в плагине на Lua:

Определение функции

plugin.lua
function addNumbers_exported(a, b)
    -- Складывает два целых числа
    return a + b
end

Манифест плагина

Чтобы экспортировать функцию, опишите ее в манифесте плагина в разделе methods:

plugin_name.pplugin
{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "addNumbers",
      "funcName": "addNumbers_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "a"
        },
        {
          "type": "int32",
          "name": "b"
        }
      ],
      "retType": {
        "type": "int32"
      }
    }
  ]
}

Сложный пример: Экспорт сложных функций

Вот пример экспорта функции со сложными типами параметров и возвращаемого значения:

Определение функции

plugin.lua
function processData_exported(data, prefix)
    local result = {}
    for i = 1, #data do
        result[i] = prefix .. tostring(data[i])
    end
    return result
end

Манифест плагина

plugin_name.pplugin
{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "processData",
      "funcName": "processData_exported",
      "paramTypes": [
        {
          "type": "float[]",
          "name": "data"
        },
        {
          "type": "string",
          "name": "prefix"
        }
      ],
      "retType": {
        "type": "string[]"
      }
    }
  ]
}

Экспорт функций с параметрами по ссылке

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

  1. Первый элемент: Возвращаемое значение функции (используйте nil, если функция возвращает void)
  2. Остальные элементы: Измененные значения для всех ссылочных параметров в порядке их объявления

Определение функции с параметрами по ссылке

plugin.lua
function incrementValue_exported(value)
    -- Увеличить значение
    -- Возврат: (возвращаемое_значение, измененное_значение)
    return nil, value + 1
end

function calculate_exported(a, b, sum, product)
    -- Вычислить сумму и произведение
    -- Возврат: (возвращаемое_значение, sum, product)
    local calculatedSum = a + b
    local calculatedProduct = a * b
    return nil, calculatedSum, calculatedProduct
end

function processAndCount_exported(data, prefix)
    -- Обработать данные и вернуть как результат, так и количество
    -- Возврат: (result, count) - оба являются фактическими возвратами, не ссылками
    local result = {}
    for i = 1, #data do
        result[i] = prefix .. tostring(data[i])
    end
    local count = #data
    return result, count
end

Манифест плагина с параметрами по ссылке

В манифесте отметьте параметры, которые должны обрабатываться как ссылки, используя "ref": true:

plugin_name.pplugin
{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "incrementValue",
      "funcName": "incrementValue_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "value",
          "ref": true
        }
      ],
      "retType": {
        "type": "void"
      }
    },
    {
      "name": "calculate",
      "funcName": "calculate_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "a"
        },
        {
          "type": "int32",
          "name": "b"
        },
        {
          "type": "int32",
          "name": "sum",
          "ref": true
        },
        {
          "type": "int32",
          "name": "product",
          "ref": true
        }
      ],
      "retType": {
        "type": "void"
      }
    },
    {
      "name": "processAndCount",
      "funcName": "processAndCount_exported",
      "paramTypes": [
        {
          "type": "float[]",
          "name": "data"
        },
        {
          "type": "string",
          "name": "prefix"
        },
        {
          "type": "int32",
          "name": "count",
          "ref": true
        }
      ],
      "retType": {
        "type": "string[]"
      }
    }
  ]
}

Как это работает

  1. Порядок возврата: Первое возвращаемое значение - это фактическое возвращаемое значение функции. Последующие значения соответствуют ссылочным параметрам в порядке их объявления.
  2. Функции с void: Если функция возвращает void, первый элемент кортежа должен быть nil.
  3. Смешанные возвраты: Если функция имеет как возвращаемое значение, так и ссылочные параметры, возвращаемое значение идет первым, за ним следуют все ссылочные параметры.

Поддержка параметров по ссылке

Параметры по ссылке работают с большинством типов Plugify, как показано в столбце "Поддержка ссылок" таблицы сопоставления типов. Следующие типы не поддерживают ссылки:

  • void/nil (не может быть передан по ссылке)
  • function (типы обратных вызовов)

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

Обработка обратных вызовов (Callbacks)

Plugify позволяет экспортировать функции, которые принимают обратные вызовы в качестве параметров. Вот пример:

Определение функции

plugin.lua
function executeWithCallback_exported(value, inputStr, callback)
    local result = callback(value, inputStr)
    print("Callback result:", result)
end

Манифест плагина

plugin_name.pplugin
{
  "name": "ExampleLuaPlugin",
  "version": "1.0.0",
  "methods": [
    {
      "name": "executeWithCallback",
      "funcName": "executeWithCallback_exported",
      "paramTypes": [
        {
          "type": "int32",
          "name": "value"
        },
        {
          "type": "string",
          "name": "inputStr"
        },
        {
          "type": "function",
          "name": "callback",
          "prototype": {
            "name": "exampleCallback",
            "funcName": "exampleCallback_exported",
            "paramTypes": [
              {
                "type": "int32",
                "name": "value"
              },
              {
                "type": "string",
                "name": "inputStr"
              }
            ],
            "retType": {
              "type": "string"
            }
          }
        }
      ],
      "retType": {
        "type": "void"
      }
    }
  ]
}

Лучшие практики

  1. Определяйте функции четко: Убедитесь, что ваши функции хорошо документированы и просты для понимания.
  2. Соблюдайте соглашения о типах: Придерживайтесь соглашений о типах Plugify для параметров и возвращаемых значений.
  3. Тестируйте тщательно: Тестируйте ваши экспортированные функции, чтобы убедиться, что они работают так, как ожидается, при вызове другими плагинами.
  4. Обновляйте манифест: Всегда описывайте экспортированные функции в манифесте плагина в разделе methods.

Заключение

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

Редактировать на GitHub
Первый плагин
Узнайте, как создать свой первый плагин с помощью языкового модуля, включая основной синтаксис и настройку.
Импорт функций
Узнайте, как импортировать функции из других плагинов, написанных на разных языках, и использовать их в своем собственном.