Основы Lua#

Когда использовать Lua#

Для одного сочетания, операции с окном, URL, программы или команды используйте простое действие. Выбирайте Lua, когда жест должен ветвиться по программе, преобразовывать текст или сочетать операции. Mousetroke встраивает Lua 5.4.

Ваш первый скрипт#

1. Создайте или выберите жест в настройках.

2. В разделе Действие выберите Скрипт Lua. Замените всё текстовое поле следующим кодом.

3. Дождитесь указания о сохранении, затем запустите жест вне настроек.

function ms_action(pos, wid, pid, exe, title, mode)
  ms.log("Target: %s, mode: %s", exe, mode)
  ms.show_toast("My first Lua gesture", 1500)
end

function начинает функцию, а end завершает её. Mousetroke загружает код, затем один раз вызывает ms_action. Помещайте свою работу внутрь этой функции. Имена в скобках получают контекст; неиспользуемые аргументы можно опустить. ms.log пишет в журнал среды выполнения, а ms.show_toast показывает сообщение на 1500 миллисекунд.

Пункт редактора Основы Lua открывает эту страницу. Следуйте рецептам Lua, чтобы жест мыши выводил текст или вставлял через буфер обмена.

Аргументы точки входа#

Полная точка входа — ms_action(pos, wid, pid, exe, title, mode):

Цель фиксируется для жеста. pos может отличаться от координат начала жеста в переменных действия. Клавиатурный ввод по-прежнему идёт в активную программу, пока вы не активируете цель. На Mac ms.focus_win(wid) может активировать только целевую программу этого жеста. Текст подстановок вроде %MS_PID% в Lua не раскрывается; используйте pid напрямую.

Lua за пять минут#

local создаёт переменную. Строки используют одинарные или двойные кавычки; .. соединяет строки. -- начинает комментарий. if, elseif, else, end выбирают ветку. nil означает отсутствие значения; в условиях ложны только false и nil (0 и "" истинны).

function ms_action(pos, wid, pid, exe)
  local message = "Hello"
  if string.find(string.lower(exe), "firefox", 1, true) then
    message = "Hello, Firefox"
  else
    message = message .. " from Mousetroke"
  end
  ms.show_toast(message)
end

Здесь string.find(s, needle, 1, true) ищет буквально и возвращает позицию или nil. Значение true не даёт трактовать пунктуацию как шаблон. string.match использует шаблоны Lua, которые отличаются от регулярных выражений. Таблица может хранить именованные поля или список, чей первый индекс равен 1. Вспомогательная функция может вернуть значение:

local function app_name(identity)
  return string.match(identity, "([^/\\]+)$") or identity
end

function ms_action(pos, wid, pid, exe)
  local target = {name = app_name(exe), process = pid}
  local lines = {target.name, tostring(target.process)}
  ms.show_toast(table.concat(lines, " / "))
end

Строки Lua интерпретируют экранирование до разбора последовательности клавиш. "\\" обозначает одну обратную косую, "\n" — перевод строки. Строки в длинных скобках вроде [[text]] сохраняют обратные косые. Руководство по отправке клавиш объясняет второй слой синтаксиса.

Отладка#

Используйте ms.log("pid=%d title=%s", pid, title) и смотрите О программе → Открыть журнал:

• Windows: %APPDATA%\mousetroke\mousetroke.log.

• Mac: ~/Library/Logs/mousetroke/mousetroke.log.

Ошибки загрузки и выполнения появляются там с именем фрагмента gesture_script. ms.show_toast("Reached this step") — быстрая визуальная проверка. Необязательные результаты API могут быть nil; проверяйте их перед арифметикой или доступом к таблице. Неподдерживаемые вызовы Mac см. в справочнике API.

Среда выполнения и ограничения#

Каждое выполнение скрипта создаёт свежую VM Lua в рабочем потоке с лимитом выделения Lua 8 МиБ. Глобальные значения не сохраняются между жестами. Среда не ставит лимит числа инструкций или реального времени. Избегайте бесконечных циклов. ms.sleep(ms) блокирует рабочий поток этого скрипта, а не хук ввода или главный поток интерфейса. ms.keys ждёт завершения своей последовательности; на Mac ввод продвигается таймером главного потока, пока рабочий поток Lua ждёт.

Доступные стандартные библиотеки — базовые функции, coroutine, table, io, os, string, utf8, math и package. debug не загружается; загрузка собственных модулей C отключена безопасным режимом mlua. os.date доступна. Это не песочница безопасности операционной системы: io, os и API процессов могут обращаться к файлам или запускать команды с вашими правами пользователя. Запускайте только те скрипты и конфигурации, которым доверяете.

Далее: справочник API, рецепты копирования и вставки, устранение неполадок.