|
SciTE Lua Scripting Extension |
| Документация FAQ Регулярные выражения SciTE Extension LUA SciTE Director Команды SciTE и Scintilla Сборка Ru-Board Ядро SciTE-Ru Shell SciTE Helper История |
Lua is Copyright (C) 1994-2007 Lua.org, PUC-Rio. Полная лицензия на Lua находиться в luaCOPYRIGHT в папке с установленным SciTE. Информация о Lua, включая документацию о самом языке находиться на www.lua.org.
О возможностях Lua, вы можете узнать посетив портал сообщества lua-users.org, использование Lua со SciTE и несколько примеров скриптов.
Свойства ext.lua.startup.script и extension.filepattern можно использовать для объявления команд и обработчиков событий которые будут вызываться SciTE. Другие свойства начинающиеся с ext.lua также влияют на поведение Lua. Смотрите документацию по SciTE для получения большей информации об этом.
Объявляя функции в сценарии загрузки или в сценарии активного расширения, вы можете подогнать SciTE под ваши потребности, добавляя новое поведение и функциональность.
Вы можете обрабатывать любые из событий объявленных в интерфейсе расширений Scite (SciTE Extension Interface). Вы просто объявляете функции с теми же именами как и у событий. Сейчас поддерживаются: OnOpen, OnClose, OnSwitchFile, OnSave, OnBeforeSave, OnChar, OnKey, OnSavePointReached, OnSavePointLeft, OnDwellStart, OnDoubleClick, OnMarginClick, и OnUserListSelection.
Для некоторых из этих событий, SciTE помещает один или более аргументов в функцию обработки событий: в обработчики событий OnOpen, OnClose, OnSwitchFile, OnSave, и OnBeforeSave будет передано имя файла выбранного буфера как первый аргумент. Обработчик OnChar должен ожидать односимвольный строковый аргумент. An OnKey handler should expect an integer keycode and boolean shift, control, and alt arguments. The keycode is currently a platform specific value but this may change in future. OnDwellStart will receive the position of the mouse and the word under the mouse as arguments and the word will be empty when the mouse starts moving. Обработчик OnUserListSelection принимает два аргумента: номер показывающий на тип списка и строку показывающую выбранное значение. Другие обработчики не принимают аргументов.
Обработчики событий возвращают логическое значение, показывающее как SciTE должен продолжать обработку события. Возврат значения "истина" показывает что событие полностью обработано и другие обработчики не будут вызываться. Возврат значения "ложь" позволяет другим расширениям обработать тоже событие. В большинстве случаев (но не во всех) обработчик должен вернуть "ложь". Помните что в Lua "not true" = "false" = "nil". Не как в C++, Python и многих других языках, где "true" = 0.
Есть дополнительный обработчик события OnClear, он явно не объявлен в Интрефейсе Расширений, но доступен для Lua. Когда SciTE перечитывает свойства (что случается каждый раз когда вы переключаете буферы или открываете новый файл, а также в некоторых других случаях), Расширение Lua удаляет все глобальные свойства, созданные с тех пор когда последний раз перечитывались свойства и востанавливает все глобальные свойства которые были изменены. Затем, если в сценарии загрузки объявлен обработчик OnClear, эта функция будет вызвана, так сценарии могут очистить другие изменения, которые могли быть сделаны за рамками Lua (т.е. динамические свойства измененные через объект props; смотрите далее) и/или подогнать окружение Lua соответствующее локальным свойствам для данного буфера.
После этого, SciTE читает свойства и в итоге загружает сценарий расширения , если он объявлен. Однако, во время когда событие OnClear срабатывает, сценарий расширения еще не загружен. Так обработчик OnClear может быть объявлен в сценарии загрузки, но не в сценарии расширения.
В добавок к обработчикам событий вы можете объявить новые команды, которые доступны через меню Tools или клавиатуру. Для указания того что команда, что будет обработана Lua, укажите подсистему 3 для команды. Затем, объявите глобальную функцию с именем команды.
Вы также можете использовать предопределённые функции как dofile and dostring.
Что либо указанное после имени команды помещается в функцию Lua как одиночный строковый аргумент. Пример команды использующий встроенную команду dofile:
Примечание: командная строка напрямую не распознается как сценарий Lua.
Если нет функции совпадающей с именем команды, ошибка не возникнет. Это потому что Lua предполагает что команда есть значение для какого-то другого расширения, например, такого как интерфейс SciTE Director. Однако, если функция команды найдена, но произошел сбой во время выполнения, об ошибке будет сообщено.
Scite Ext Man может помочь в более сложных приложениях, где вам необходимо иметь много скриптов для обработки событий.
Вместе со сценариями Lua вы можете использовать следующие функции и объекты:
trace(s) - записывает s в выходную панель (без префиксов, без перевода строки) dostring(s) - выполняет s как сценарий Lua, как Lua 4's dostring editor - панель редактора output - выходная панель props - псевдотаблица представляющая свойства SciTE buffer - таблица связанная с с текущим буфером или документом scite - пространство имен для функций которые контролируют SciTE.
Все константы объявленные в Scintilla.iface доступны как глобальные переменные Lua. Они доступны если их имена записаны заглавными буквами с префиксом SCI_.(прим. переводчика - Что выделено синим цветом здесь и ниже, необходимо проверить на корректность, кем нибудь кто разбирается в этом больше)
Все функции и объекты объявленные в стандартных библиотеках Lua также доступны. Однако dostring была отключена в Lua 5, она восстановлена так как она может полезна в командах меню Tools.
Функция _ALERT() объявлена как синоним встроенной print(), которая печатает предупреждающие сообщения (с переводом строки) в окно. Это предоставляет корректный способ для Lua выводить сообщения об ошибках пользователю. Вы свободно можете перекрыть объявление _ALERT отличающимся объявлением.
Псевдотаблица свойств позволяет вам читать и записывать свойства по имени используя нормальную семантику Lua для доступа к таблицам. т.е. props["property.name"]. Как с таблицами Lua, вы можете сбрасывать параметр присваивая nil его ключу.
Когда вы присваиваете значение параметру через Lua, это перекрывает все значения указаные в конфигурационных файлах для данного параметра. Параметры в файлах при этом не меняются. Если вы позже присвоите nil этому параметру через Lua, это сбросит параметр во время исполнения сценария, позволяя любому параметру из файла настроек восстановить значение.
Панели редактора и вывода поддерживают следующие параметры и методы:
textrange(startPos, endPos) - получает текст из указаного диапазона
findtext(text, [flags], [startPos, [endPos]])
- возвращает начало и конец первого совпадения или nil если нет совпадений
- флаг может быть 0 (по умолчанию) или комбинация констант SCFIND
таких как SCFIND_WHOLEWORD, SCFIND_MATCHCASE и SCFIND_REGEXP
match(text, [flags], [startPos])
- возвращает генератор который позволяет перебрать все совпадения
т.е. for m in editor:match(text, flags) do ... end
- совпавший объект (т.е. счетчик m в предыдущем примере)
поддерживает параметры только для чтения pos, len и text
и также поддерживает метод replace(replaceText) для
поддержки поиска и замены.
- если, пока перебирая совпадения, документ был изменен
другим способом, не через метод replace,
это может быть причиной того что генератор потеряет
позиции найденых совпадений.
- также, не пытайтесь сохранить совпавший объект для
доступа вне цикла; он не будет пригоден к использованию.
append(text) - добавляет текст в конец документа
insert(pos, text) - вставляет текст в указанную позицию
remove(startPos, endPos) - удаляет текст в диапазоне
Большинство функций объявленных в Scintilla.iface также доступны как методы панелей. Функции имеющие параметры простых типов (string, boolean, и numeric) полностью поддерживаются. Например, editor:InsertText(pos, text) делает то же самое что и editor:insert(pos, text). Функция имеющая аргумент возвращающий строку, также включает строку в возвращаемое значение. Для обоих строк в аргументе и во возвращаемом значении, если функция документирована как предполагающая длину в первом параметре, вы не должны помещать длину в Lua. Это будет сделано в контексте.
Параметры имеющие тип keymod имеют частичную поддержку. Когда функция iface объявлена как получающая keymod, эквивалент Lua предполагает два числа: первое - код клавиши (например SCK_LEFT или string.byte("'") и второй - модификатор (например SCMOD_CTRL).
Функции имеющие более сложные параметры не поддерживаются.
Функции которые объявлены возвращать числовой тип добавляют результат к возвращаемому значению. Если функция также имеет строковый результат, он приходит первым, затем числовое значение.
Несколько функций объявлено как 'get' или 'set' в файле iface. Это в основном доступно Lua как свойства, например editor.TabSize = 8. Некоторые из getters и setters также имеют параметры. Где возможно, они доступны Lua как индексированные параметры, например editor.StyleBold[SCE_PROPS_DEFAULT] = true. Однако, если функция iface объявлена как get / set но неможет быть преобразована в свойство Lua, она доступна как функция Lua.
Перечень доступных функций Scintilla перечислен в данном API-файле. Интерфейс Scintilla API описан в ScintillaDoc
Пространство имен scite включает следующие функции:
scite.Open(filename)
- открывает файл в новом буфере
- активирует файловый буфер если уже открыт.
scite.SendEditor(SCI_constant, ...)
- посылает сообщение панели редактора
- эквивалент соответствующей функции или свойства iface
scite.SendOutput(SCI_constant, ...)
- посылает сообщение панели вывода
scite.ConstantName(number)
- возвращает символьное имя константы Scintilla / SciTE
Функция Open требует особого внимания. Когда меняется буфер в SciTE, глобальное пространство имен Lua сбрасывается в начальное состояние и загружаются все сценарии расширений связанные с новым буфером. Так, когда вы вызываете Open, это может изменить окружение в котором выполняется ваш текущий сценарий. Когда возможно вы можете избежать конфликтов просто возвращаясь после вызова scite.Open, но когда нет возможности просто держите в уме, что могут быть посторонние эффекты. Локальные переменные, в отличие от глобальные, будут сохранены после смены буфера пока ваш сценарий возвращается.
Функции SendEditor и SendOuput повторяют функциональность объектов редактора и вывода, предоставляя доступ к ним через интерфейс более привычный для разработчиков Scintilla C++. Это может полезно для создания прототипов кода C++ используя Lua. Внутри, SendEditor и SendOutput передаются в соответствующие функции или свойства iface, так типы их аргументов и возвращаемых значений индентичны. (Однако правила вызова для свойств естественно отличаются.)
Функция ConstantName может быть полезна для генерирования отладочных сообщений или для поддержки записи макросов.
The MenuCommand function enables usage of SciTE's menu commands as defined in SciTE.h.
Despite some of the big changes in Lua 5.1 dealing with changes in the language, most of the compatibility options have been turned on. Compatibilities: - table.getn still works, but the '#' operator should be used - Lua 5.0's varargs are still available - Lua 5.0's math.mod is still available, as well as 5.1's math.fmod - Lua 5.0's string.gfind is still available, as well as 5.1's string.gmatch - [C API] Lua 5.0's luaL_openlib behavior is still available Changes: - table.setn was deprecated - loadlib was moved into the package table (package.loadlib) - Lua 5.0's long string nesting throws an error
Сейчас Lua загружается по требованию перед первым использованием. Lua может быть загружен через параметр ext.lua.startup.script, указанием файла lua в параметре extension.filepattern или через использование механизма расширений для объявления команд в меню Tools (т.е. подсистема 3). Если не использовали эти вещи, движок сценариев Lua не загрузиться и для всех практических целей SciTE будет вынужден вести себя также когда Lua не был добавлен.
Не смотря на это, все еще есть возможность собрать SciTE без поддержки Lua. Чтобы сделать это просто объявите переменную NO_LUA при сборке, т.е. для MSVC nmake -f scite.mak -DNO_LUA или с инструментарием GNU make NO_LUA=1.