максимально естественным образом, наподобие команд оболочки, и наравне с ними.
Точно так же скрипты можно запускать просто по имени, не задумываясь где именно
они расположены (в текущей папке, или где-то в
%PATH%
).И по тем же правилам им можно передавать аргументы в командной строке.
Скрипты удобно не только запускать вручную, но и использовать в ассоциациях,
меню пользователя, диалоге “Применить команду” и т.п.
Область действия не ограничена панелями, командная строка доступна в любой области
фара, с автодополнением и историей.
Скриптам: предоставляется ряд средств, в числе которых — простое обращение к другим
скриптам, доступным в
%PATH%
, что позволяет сформировать собственную экосистему,в некотором роде альтернативную модулям Lua.
Макросам: предоставляется модуль
sh
для доступа к скриптам (см. API).Установка
Для установки содержимое архива (директории
scripts
и utils
) достаточно распаковать в%FARPROFILE%\Macros\
и перезагрузить макросы.Это обеспечит запуск скриптов по префиксу (
luash:
) из разных мест(панели, ассоциации, меню пользователя, диалог “Применить команду”),
а из собственного диалога (
Ctrl-G
, в панелях - с удержанием) - без префикса.Чтобы свободно запускать скрипты без префикса отовсюду (что конечно удобнее),
необходимы некоторые дополнительные действия:
- В редакторе конфигурации (
far:config
) активировать параметрSystem.Executor.UseAssociations
. - Добавить ассоциацию:
Code: Select all
*.lua,*.moon,*.yue | luash:"!\!.!"
- При старте в переменную среды
PATHEXT
добавляются расширения.lua;.moon;.yue
(если отсутствуют).
Это необходимо для работы автодополнения, и для запуска скриптов без префикса (см. выше). - Для удобства к значению переменной
PATH
добавляется путь к директорииMacros\utils
(настраиваемо) и рекурсивно ко всем её поддиректориям (исключая скрытые). - Для более комфортной работы рекомендуется установить следующие модули:
- Lua explorer (le): http://forum.farmanager.com/viewtopic.php?f=60&t=7988
- Inspect: https://github.com/kikito/inspect.lua
Первый используется утилитой Просмотр возвращаемых значений и подключается скриптомbrowse.lua
,
второй используется скриптомdump.lua
.
(Модули легко самостоятельно заменить и на альтернативные, если будет потребность).
Кроме того, рекомендуются следующие скрипты: - Ctrl-O: просмотр пользовательского экрана из любой области
- Макросы для работы с большим буфером консоли
- Проверка корректности скрипта в редакторе + выполнение
- Luacheck FAR scripts — статический анализатор для Lua/Yue-/MoonScript
Опции
В начале скрипта (
LuaShell.lua
) есть таблица с опциями, которые можно изменять редактируя файл,или используя возможности cfgscript.
prefix
,path
,pathext
позволяют переопределить значения, описанные в разделе Установка.- Значение
result
определяет имя глобальной переменной, в которой сохраняются возвращаемые значения
последнего запущенного скрипта. - В
LastResultKey
задаётся шорткат, по которому эти значения можно просмотреть (Ctrl-Shift-L
по умолчанию).
Чтобы после каждого обновления скрипта не приходилось вручную восстанавливать
изменённые значения опций рекомендуется использовать возможности cfgscript из пакета
ScriptsBrowser: http://forum.farmanager.com/viewtopic.php?f=15&t=10418
Использование
Скрипты можно запускать из командной строки фара по имени, как исполняемые файлы.
Кроме того, по
Ctrl[-Shift]-G
доступен Диалог запуска скрипта, предоставляющий дополнительные возможности (см.),такие как работу во всех макрообластях (с раздельной историей), запуск с просмотром возвращаемых значений,
а также непосредственное исполнение набранных в строке ввода lua(/moon/yue)-выражений.
Для создания нового скрипта необязательно переходить в целевую директорию, достаточно в том же диалоге
набрать его имя и нажать
F4
- скрипт будет создан в директории заданной по умолчанию.Таким же образом можно открыть и существующий скрипт на редактирование.
Альтернативно: запустить в командной строке
edit <scriptname>
.Это лишь краткий обзор возможностей, подробнее см. в соответствующих разделах.
Скрипты
Аргументы командной строки скриптам передавать можно обычным образом, разделяя пробелами, и заключая
(при необходимости) в кавычки. При этом скрипты получают как список аргументов-строк в
...
,так и изначальную строку
_cmdline
, которую (например) можно преобразовать в выражение:_cmdline:eval()
.Скрипты могут быть исполнены как напрямую (из командной строки или диалога), так и вызваны из других
скриптов (см. ниже), при этом переменной
_cmdline
в окружении не будет.Чтобы различить способ запуска, и выполнить соответствующие действия, можно использовать такой паттерн:
Code: Select all
if _cmdline=="" then
print "Скрипт запущен без аргументов, выводим подсказку"
return
elseif _cmdline then
print("Командная строка:",_cmdline)
print("Аргументы:",...)
else
-- скрипт вызван другим скриптом, возвращаем функцию
return some_function
end
sh "scriptname"(...)
sh.scriptname(...)
sh.scriptname == "scriptname"(scriptname)
, соответственноsh.scriptname(...) == "scriptname"(scriptname)(...)
Первый способ выполняет код (и возвращает значения), второй же подходит для обращения к
возвращаемому значению непосредственно (по типу модуля).
Проще всего разобраться используя прилагаемые примеры.
Диалог запуска скрипта
Запуск скриптов возможен как из штатной командной строки Фара,
так и из собственного диалога, доступного отовсюду по шорткату
Ctrl[-Shift]-G
(в панелях
CtrlG:Hold
, требует MacroEx
).Строка ввода сохраняет историю команд (по макрообластям).
По
Enter
Запускать можно как lua/moon/yue скрипты с параметрами (см. Командная строка),так и непосредственно lua/moon/yue выражения.
Ctrl-Enter
после исполнения переоткрывает диалог.Shift-Enter
после исполнения показывает возвращённые значения(также они всегда доступны по
Ctrl-Shift-L
).F4
открывает редактор со скриптом, имя которого содержится в строке ввода.И например чтобы создать новый скрипт, достаточно ввести желаемое имя и нажать
F4
.F3
открывает скрипт во вьювере.Просмотр возвращаемых значений
Чтобы увидеть возвращаемые значения можно воспользоваться
Shift-Enter
в Диалоге запуска скрипта.Кроме того когда скрипт возвращает значения - в нижней части экрана кратковременно выводится
нотификация с предложением просмотреть их нажав
Enter
.Эта же функция доступна в любой момент по
Ctrl-Shift-L
(настраиваемо).В списке значений доступны следующие действия:
Enter
- просмотреть значение в диалогеCtrl-Ins
- скопировать дамп значенияCtrl-E
- открыть диалог с командой заново.
Повторный запуск скрипта
Чтобы повторить запуск скрипта можно воспользоваться одним из шорткатов:
CtrlG:Double
, Ctrl-Alt-G
.А если запустить шорткатом
Ctrl-Alt-Shift-G
- после завершения скрипта откроетсяПросмотр возвращаемых значений.
API, предоставляемый скрипту
_filename
Полное имя скрипта...
(vararg
)
аргументы командной строки_cmdline
Переменная, в которую помещаются неразделённые аргументы в виде строки
(исключая имя скрипта, только аргументы).
- Если скрипт вызван без параметров, то
_cmdline==""
- Если скрипт запущен не из командной строки, а вызван другим скриптом, то
переменной_cmdline
в окружении не будет.
Таким образом возможно различить как запущен скрипт, и в зависимости от этого
либо вернуть значение (в том числе функцию, таблицу), либо непосредственно выполнить
соответствующие действия, оперируя аргументами переданными в командной строке.
- Если скрипт вызван без параметров, то
_cmdline:eval(env,...)
Вычисляет строку как lua-выражение (опционально, передавая таблицу с окружением, и аргументы).
Полезно как для собственно вычислений (1+math.sin(2)
), так и для передачи любых lua-значений
(_G, Far, 123, "abc", {k="v"}, function() print"hello" end, ...
).
Применимо не только к_cmdline
, но и к любым строкам (eval
добавляется в метатаблицуstring
)
Допустимо как yue-/moonscript- так и lua-выражение. Перед lua-выражением сначала делается попытка
подставить"return "
.sh
Таблица, содержащая дополнительные сервисные функции.sh._shared
Доступ к некоторым внутренним параметрам/функциям.sh.print(...)
Юникодный аналог стандартной Lua-функцииprint
.
Выводит текст в буфер под панелями (активируется автоматически,
нет необходимости в ручном вызовеGetUserScreen
/SetUserScreen
).
По умолчанию данная функция помещается прямо в окружение скрипта, поэтому можно использовать
и простоprint
без префикса.
(При этом остаются доступны и встроенные_G.print
/mf.print
).sh.<anyname>
Позволяет запускать другие скрипты (доступные в%PATH%
) по имени, и получать возвращаемые значения.sh(name,env)
Позволяет загружать другие скрипты (доступные в%PATH%
) по имени
опционально передавая таблицу-окружение
(gefenv(1)
чтобы передать собственное окружение).
Возвращает функцию.
Примеры:
Code: Select all
sh"anyname"(arg1,arg2,...) sh("anyname", gefenv(1))(arg1,arg2,...)
(как и все прочие) можно адресовать через
sh.
Командная строка
Code: Select all
<filename[.ext]> [<arg1> <arg2> ...]
- Аргументы указываются традиционным для командной строки образом, т.е. как строки,
отделяемые друг от друга пробелами.
Чтобы передать строку с пробелами необходимо заключить её в двойные кавычки.
Сами кавычки не являются частью строки (кавычку можно передать только экранировав
её с помощью обратного слэша). - Если не указан путь, то скрипт будет также искаться в
%PATH%
.
Если не указано расширение, то сначала ищется “.lua”, затем “.moon” и “.yue”.
Code: Select all
luash:[=][*|@]
luashs:[=][*|@]
- Символ
@
используется для запрета отображения выполняемой команды на
экране (полезно для “Применить команду”).
Если не указан, то команда отображается только если скрипт использовал “print
”. - Символ
*
используется для того, чтобы отобразить выполняемую команду в любом случае. - Символ
=
позволяет отобразить возвращаемые значения скрипта в виде списка.
Таблицы можно просматривать (опционально: рекомендуются модули “le
” и “inspect
”) - Если после
=
в командной строке не указан файл, то отображаются значения,
возвращённые последним выполненным скриптом. - Опционально, эти значения также сохраняются и в глобальной переменной с
указанным именем, по умолчанию “LastCmdLineResult
”. - Опционально, для просмотра этих значений предусмотрен макрос, по умолчанию
назначенный наCtrl-Shift-L
(см. Просмотр возвращаемых значений).