LuaShell

LuaShell

Назначение данной утилиты — реализовать запуск lua/moon скриптов из командной строки максимально естественным образом, наподобие команд оболочки, и наравне с ними.

Точно так же скрипты можно запускать просто по имени, не задумываясь где именно они расположены (в текущей папке, или где-то в PATH). И по тем же правилам им можно передавать аргументы в командной строке.

Скрипты удобно не только запускать вручную, но и использовать в ассоциациях, меню пользователя, диалоге "Применить команду" и т.п.

Область действия не ограничена панелями, командная строка доступна в любой области фара, с автодополнением и историей.

Скриптам: предоставляется ряд средств, в числе которых — простое обращение к другим скриптам, доступным в PATH, что позволяет сформировать собственную экосистему, в некотором роде альтернативную модулям Lua.

Макросам: предоставляется модуль sh для доступа к скриптам (см. [API]).

Установка

Для установки содержимое архива (директории scripts и utils) достаточно распаковать в %FARPROFILE%\Macros\ и перезагрузить макросы.

Это обеспечит запуск скриптов по префиксу (luash:) из разных мест (панели, ассоциации, меню пользователя, диалог "Применить команду"), а из собственного диалога (Ctrl-G, в панелях - с удержанием) - без префикса.

Чтобы свободно запускать скрипты без префикса отовсюду (что конечно удобнее) необходимы некоторые дополнительные действия:

1. В редакторе конфигурации (far:config) активировать параметр System.Executor.UseAssociations

2. Добавить ассоциацию:

  *.lua,*.moon,*.yue | luash:"!\!.!"

Примечания

a. При старте в переменную среды PATHEXT добавляются расширения .lua;.moon (если отсутствуют).

Это необходимо для работы автодополнения, и для запуска скриптов без префикса (см. выше)

b. Для удобства к значению переменной PATH добавляется путь к директории Macros\utils (настраиваемо) и рекурсивно ко всем её поддиректориям (исключая скрытые).

c. Для более комфортной работы рекомендуется установить следующие модули: - 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/MoonScript

Опции

• prefix, path, pathext позволяют переопределить значения, описанные в разделе Установка

• Значение result определяет имя глобальной переменной, в которой сохраняются возвращаемые значения последнего запущенного скрипта.

• В LastResultKey задаётся шорткат, по которому эти значения можно просмотреть (Ctrl-Shift-L по умолчанию).

Опции можно изменить в начале скрипта.

А чтобы после каждого обновления не приходилось вручную восстанавливать изменённые значения опций рекомендуется использовать возможности cfgscript из пакета ScriptsBrowser.

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

Скрипты можно запускать из командной строки фара по имени, как исполняемые файлы. Кроме того, по Ctrl[-Shift]-G доступен Диалог запуска скрипта, предоставляющий дополнительные возможности (см.), такие как работу во всех макрообластям (с раздельной историей), запуск с просмотром возвращаемых значений, а также непосредственное исполнение набранных в строке ввода lua-выражений.

Для создания нового скрипта необязательно переходить в целевую директорию, достаточно в том же диалоге набрать его имя и нажать F4 - скрипт будет создан в директории заднанной по умолчанию. Таким же образом можно открыть и существующий скрипт на редактирование.

Альтернативно: запустить в командной строке edit <scriptname>.

Это лишь краткий обзор возможностей, подробнее см. в соответствующих разделах.

Скрипты

Аргументы командной строки скриптам передавать можно обычным образом, разделяя пробелами, и заключая (при необходимости) в кавычки. При этом скрипты получают как список аргументов-строк в ..., так и изначальную строку _cmdline, которую (например) можно преобразовать в выражение: _cmdline:eval()

Скрипты могут быть исполнены как напрямую (из командной строки или диалога), так и вызваны из других скриптов (см. ниже), при этом переменной _cmdline в окружении не будет. Чтобы различить способ запуска, и выполнить соответствующие действия можно использовать такой паттерн:

if _cmdline=="" then
  print "Скрипт запущен без аргументов, выводим подсказку"
  return
elseif _cmdline then
  print("Командная строка:",_cmdline)
  print("Аргументы:",...)
else
  -- скрипт вызван другим скриптом, возвращаем функцию
  return some_function
end

Запуск скриптов предусмотрен двумя способами (см. [API]): 1. sh "scriptname"(...) 2. sh.scriptname(...)

sh.scriptname == "scriptname"(scriptname), соответственно sh.scriptname(...) == "scriptname"(scriptname)(...)

Первый способ выполняет код (и возвращает значения), второй же подходит для обращения к возвращаемому значению непосредственно (по типу модуля).

Проще всего разобраться используя прилагаемые примеры.

Диалог запуска скрипта

Запуск скриптов возможен как из штатной командной строки Фара, так и из собственного диалога, доступного отовсюду по шорткату Ctrl[-Shift]-G (в панелях CtrlG:Hold, требует MacroEx).

Строка ввода сохраняет историю команд (по макрообластям)

По Enter Запускать можно как lua/moon скрипты с параметрами (см. Командная строка), так и непосредственно lua/moon выражения.

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) Допустимо как 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) чтобы передать собственное окружение) Возвращает функцию. Примеры:

~~~
sh"anyname"(arg1,arg2,...)

sh("anyname", gefenv(1))(arg1,arg2,...)
~~~

Кроме того, в директории utilsstdcore можно найти некоторые "внутренние" скрипты, которые (как и все прочие) можно адресовать через sh.

Командная строка

<filename[.ext]> [<arg1> <arg2> ...]

• Аргументы указываются традиционным для командной строки образом, т.е. как строки, отделяемые друг от друга пробелами. Чтобы передать строку с пробелами необходимо заключить её в двойные кавычки. Сами кавычки не являются частью строки (кавычку можно передать только экранировав её с помощью обратного слэша).
• Если не указан путь, то скрипт будет также искаться в %PATH%. Если не указано расширение, то сначала ищется ".lua", затем ".moon".

luash:[=][*|@]
luashs:[=][*|@]

Модификаторы, используемые с префиксом: * Символ @ используется для запрета отображения выполняемой команды на экране (полезно для "Применить команду"). Если не указан, то команда отображается только если скрипт использовал "print". * Символ * используется для того, чтобы отобразить выполняемую команду в любом случае. * Символ = позволяет отобразить возвращаемые значения скрипта в виде списка. Таблицы можно просматривать (опционально: рекомендуются модули "le" и "inspect") * Если после = в командной строке не указан файл, то отображаются значения, возвращённые последним выполненным скриптом. * Опционально, эти значения также сохраняются и в глобальной переменной с указанным именем, по умолчанию "LastCmdLineResult". * Опционально, для просмотра этих значений предусмотрен макрос, по умолчанию назначенный на Ctrl-Shift-L (см. Просмотр возвращаемых значений).