LuaShell.ru.hlf

.Language=Russian,Russian (Русский)
.PluginContents=LuaShell
.Options CtrlStartPosChar=§¦


@Contents
$ #LuaShell#

 Назначение данной утилиты — реализовать запуск #~lua~@https://www.lua.org/manual/5.1/manual.html@/~moon~@https://moonscript.org/reference/@/~yue~@https://yuescript.org/doc/@# скриптов из командной строки
максимально ~естественным образом~@Purpose@, наподобие команд оболочки, и наравне с ними.

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

 Скрипты удобно не только запускать вручную, но и использовать в ~ассоциациях~@:FileAssoc@,
~меню пользователя~@:UserMenu@, диалоге “~Применить команду~@:ApplyCmd@” и т. п.

 Область действия не ограничена панелями: командная строка ~доступна~@ExecDlg@ в любой области
Far’а, с автодополнением и историей.

 Также возможно непосредственно исполнять набранные в строке ввода #lua(/moon/yue)#-~выражения~@LuaExpr@,
и ~просматривать возвращаемые значения~@ShowRet@.

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

 #Макросам#: предоставляется модуль ~sh~@sh@ для доступа к скриптам.

@=

 Обсуждение на форуме: ~https://forum.farmanager.com/viewtopic.php?f=15&t=10907~@https://forum.farmanager.com/viewtopic.php?f=15&t=10907@

@=

 Другие разделы справки: [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@Purpose
$ #Назначение#

 Данный скрипт возник в ответ на штатную возможность запускать ~lua-скрипты~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/92.html@, появившуюся ещё в LuaMacro 198.
В штатной реализации аргументы представляли собой #lua#-выражения, разделённые #запятыми#:

 #    lua:@@filename arg1, arg2, ...#

 Из этого также следовало, что передать простую строку можно только заключив её #в кавычки#.

 Всё это плохо совмещается с тем, как используются в командной строке обычные утилиты.
Соответственно, довольно проблематично использовать таким образом lua-скрипты в ~ассоциациях~@:FileAssoc@,
~меню пользователя~@:UserMenu@, диалоге “~Применить команду~@:ApplyCmd@” и т. п.

 Поэтому #основная цель# данного скрипта (первоначально довольно простого) — реализовать передачу аргументов
#общепринятым# способом, т.е. как ~список строк~@Cmdline@, разделяемых пробелами, с учётом кавычек:

 #    luash:filename arg1 "arg 2" ...#

     Примечание: в то же время есть возможность и аналогично LuaMacro, интерпретировать командную строку как список выражений,
см. ~sh~@sh@#.eval#.

 К #основной фунциональности# относятся также:

 #•# §¦Запуск скриптов без необходимости указывать полный путь, и даже ~без специального префикса~@Install@;
как обычные утилиты, доступные в #%PATH%#, но с полным доступом к #FAR API#.

 #•# §¦Доступ к “командной строке” не только из панелей, но ~также~@ExecDlg@ из редактора и прочих областей.

 #•# §¦Помимо “строкового” интерфейса командной строки, скрипты могут “экспортировать” свои функции непосредственно,
что позволяет обращаться из скрипта к скрипту наиболее прямым образом, см. ~sh~@sh@.

   §¦Один и тот же скрипт может предусматривать как вызов из командной строки пользователем, так и обращение к
его функциям из другого скрипта, см. ~_cmdline~@API@.

 В процессе разработки возникали и другие идеи, которые в итоге воплотились в ряд дополнительных функций,
задокументированных в разных разделах данной справки.

 Также вокруг основного скрипта возник ряд вспомогательных, которые сначала приводились как пример применения #LuaShell#,
а впоследствии образовали своеобразную экосистему, см. раздел ~Утилиты~@Utils@.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@Utils
$ #Утилиты#

 Помимо скриптов, входящих в комплект поставки LuaShell и являющихся его неотъемлемой частью,
доступны также дополнительные наборы скриптов/утилит, спонтанно развившихся со временем в его экосистеме.


 #Набор 3rd-party#

 Набор ~3rd-party~@https://github.com/FarManagerLegacy/LuaShell.3rd-party@, распространяемый отдельно, это скрипты и макросы других авторов,
приспособленные для использования в LuaShell.
 Обычное место размещения - #Macros\utils\3rd-party#.

 Информацию о составе пакета можно получить в репозитории по ссылке выше.
 Кроме того, большинство файлов снабжено описаниями (#descript.ion#).


 #Набор std#

 В наборе ~std~@https://github.com/FarManagerLegacy/LuaShell.std@ представлены как полезные утилиты, которыми я регулярно пользуюсь, так и экспериментальные,
а также скрипты написанные для тестирования и/или иллюстрации возможностей системы.
 Набор предполагается размещать в директории #Macros\utils\std#.

 Вот лишь несколько примеров:

 #•# §¦filesmenu: поиск/выбор файла из меню
 #•# §¦files/apply: Универсальный выбор/обработка файлов, удовлетворяющих заданному условию
 #•# §¦~lineup~@https://forum.farmanager.com/viewtopic.php?t=12582@: Вертикальное выравнивание строк по разделителям
 #•# §¦~lorem~@https://forum.farmanager.com/viewtopic.php?t=13230@: #Lorem ipsum generator#
 #•# §¦RunMacro: исполнять макросы из макрофайлов, не устанавливая их
 #•# §¦plugins: утилиты для загрузки/выгрузки плагинов, как с выбором через меню, так и массово
 #•# §¦venv: работа с #Python virtual environments#
 #•# §¦…

 Помимо перечисленных выше в наборе присутствуют десятки скриптов-утилит,
и для получения более подробной информации следует смотреть их непосредственно —
как правило они снабжены подсказкой, отображаемой при их запуске без аргументов.
 Также дополнительная информация содержится в файлах #README#, расположенных в некоторых поддиректориях.


 #Возможность использования отдельно от LuaShell#

 Часть утилит написаны так, что могут быть использованы и без LuaShell:
либо как макросы (если в них содержатся определения #Macro# или #MenuItem#),
либо исполняться штатными средствами LuaMacro: из ~командной строки~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/92.html@,
или с помощью ~mf.eval~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/79.html@.

 И конечно любой скрипт можно исполнить из макроса используя ~sh~@sh@,
см. например #indent_macro.lua.sample#.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@Install
$ #Установка#

 Для базовой установки можно воспользоваться командой меню пользователя (по #F2#),
или сделать это вручную как описано в ~README.md~@https://github.com/FarManagerLegacy/LuaShell.core/README.md@.

 Это обеспечит запуск скриптов по префиксу (#luash:#) из разных мест
(~панели~@:Panels@, ~ассоциации~@:FileAssoc@, ~меню пользователя~@:UserMenu@, диалог “~Применить команду~@:ApplyCmd@”).
 И без префикса из ~собственного~@ExecDlg@ диалога,
доступного по #Ctrl-G# (в панелях — с удержанием, или #Ctrl-Shift-G#).

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

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

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

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

 Рекомендуются установить также ~дополнительные~@Utils@ наборы готовых скриптов/утилит: #std#, #3rd-party#.

 Примечания:

 #1.# §¦При старте в переменную среды #PATHEXT# добавляются расширения #.lua;.moon;.yue# (если отсутствуют).
    §¦Это необходимо для работы автодополнения, и для запуска скриптов без префикса (см. выше).

 #2.# §¦Для удобства к значению переменной #PATH# добавляется путь к директории #Macros\utils#
и рекурсивно ко всем её поддиректориям (исключая скрытые).
    §¦Содержимое #Macros\utils\core# является неотъемлемой частью LuaShell,
~остальные~@Utils@ директории и их содержимое — опциональны.

 #3.# §¦#Префикс#, #путь к директории по-умолчанию#, #расширения#,
и некоторые другие параметры при необходимости можно переопределить через ~опции~@Config@.

 #4.# §¦Следующие модули, при их наличии, будут обеспечивать просмотр и форматирование lua-значений
(подробнее см. #utils\core\README#):

     #•# §¦#Lua explorer# (le): ~https://forum.farmanager.com/viewtopic.php?f=60&t=7988~@https://forum.farmanager.com/viewtopic.php?f=60&t=7988@
     #•# §¦#Inspect#: ~https://github.com/kikito/inspect.lua~@https://github.com/kikito/inspect.lua@

    §¦Кроме того, для комфортной работы рекомендуются следующие скрипты:

     #•# §¦~Ctrl-O~@https://forum.farmanager.com/viewtopic.php?f=15&t=10983@: просмотр пользовательского экрана из любой области
     #•# §¦~Макросы~@https://forum.farmanager.com/viewtopic.php?f=60&t=8675@ для работы с большим буфером консоли
     #•# §¦~MacroEx~@https://forum.farmanager.com/viewtopic.php?f=15&t=8764@ — запуск макросов нетрадиционными способами
     #•# §¦~Проверка корректности~@https://forum.farmanager.com/viewtopic.php?f=60&t=8008@ скрипта в редакторе + выполнение
     #•# §¦~Luacheck FAR scripts~@https://forum.farmanager.com/viewtopic.php?f=60&t=9650@ — статический анализатор для #Lua/Moon-/Yuescript#

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@Config
$ #Опции#

 #•# §¦#prefix#, #path#, #pathext# (string) позволяют переопределить значения, описанные в разделе ~Установка~@Install@.

 #•# §¦В #LastResultKey# (string) задаётся шорткат, по которому можно ~просмотреть~@ShowRet@ возвращаемые значения
последнего запущенного скрипта (подробнее в разделе ~Использование~@Usage@).
   §¦По умолчанию: #Ctrl-Shift-L#.

 #•# §¦С помощью функции #initEval(env)# можно изменить окружение, доступное при исполнении через ~eval~@API@
при исполнении #lua(/moon/yue)#-~выражений~@LuaExpr@.
   §¦По умолчанию: #F=far.Flags#; #sh.autoload=true# (см. ~sh~@sh@.)

 #•# §¦#execDlgOptions# (table) — настройки ~диалога запуска скрипта~@ExecDlg@ (см.)

 #•# §¦#debug# (boolean) используется для отладки.
   §¦В частности, отключает кэширование скриптов.

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

 Но чтобы после каждого обновления скрипта не приходилось вручную восстанавливать
изменённые значения, рекомендуется использовать возможности #cfgscript# из пакета
~ScriptsBrowser~@https://forum.farmanager.com/viewtopic.php?f=15&t=10418@.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@Usage
$ #Использование#

 Скрипты можно запускать из ~командной строки~@Cmdline@ Far по имени, как исполняемые файлы
(при правильной ~установке~@Install@), указывая при необходимости и аргументы.

 Повторить запуск скрипта можно нажатием #Ctrl-Alt-G# или #CtrlG:Double#
 (Внимание: шорткаты с “:Double” и “:Hold” предполагают наличие ~MacroEx~@https://forum.farmanager.com/viewtopic.php?f=15&t=8764@).

 По #Ctrl-Shift-G# доступен ~Диалог запуска скрипта~@ExecDlg@, работающий во всех макрообластях (с раздельной историей).
Кроме того, он вызывается и следующими шорткатами:

 #•# §¦#Ctrl-G# (кроме панелей);
 #•# §¦в панелях: #CtrlG:Hold#;
 #•# §¦в редакторе #CtrlG:Hold# подхватывает выделенный текст или текущую строку.

 Для создания нового скрипта необязательно переходить в целевую директорию, достаточно в том же диалоге
набрать его имя и нажать #F4# — скрипт будет создан в директории ~заданной~@Config@ по умолчанию.
 Таким же образом можно открыть и существующий скрипт на редактирование (а с помощью #F3# — на просмотр).

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

 При редактировании скрипта может встретиться обращение к другому скрипту (см. ~sh~@sh@),
установив курсор на его имени и нажав #F4# можно открыть этот скрипт в редакторе.

@=


 #Возвращаемые значения#

 LuaShell позволяет не только запускать скрипты, но и непосредственно исполнять #lua(/moon/yue)#-~выражения~@LuaExpr@,
и получать #возвращаемые значения#.

 Если скрипт/выражение возвращают значения, то в нижней части экрана отображается
нотификация с предложением ~просмотреть~@ShowRet@ их, нажав #Enter#.
 Или же можно сразу при запуске указать, что после выполнения требуется отобразить результат
(см. справку ~командной строки~@Cmdline@ / ~диалога~@ExecDlg@).
 Кроме того, значения можно просмотреть и позже в любой момент, с помощью макроса на #Ctrl-Shift-L# (~настраивается~@Config@).

 #Примечаниe:# массив значений также сохраняются в общую переменную #sh._shared.LastCmdLineResult# (см. ~sh~@sh@),
по аналогии с ~CmdLine.Result~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/92.html@.

@=

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

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~API~@API@], [~i~@index@]


@LuaExpr
$ #Выполнение Lua-выражений#

 LuaShell позволяет не только запускать скрипты, но и непосредственно исполнять #lua(/moon-/yuescript)#-выражения,
и ~получать возвращаемые значения~@ShowRet@:

 #•# §¦В ~диалоге запуска скрипта~@ExecDlg@
 #•# §¦В ~командной строке~@Cmdline@ (при использовании с префиксом, или через другой скрипт, см. ниже)
 #•# §¦Через API — #sh.eval# (см. ~sh~@sh@ и #utils\core\eval\README#)

 При запуске из Диалога или командной строки сначала делается попытка найти скрипт по имени,
и только после неудачи введённая строка рассматривается как #выражение#.
 (Зависит от опции ~диалога~@ExecDlg@ #[?] Expr.#)

 #Примечания:#

 #•# §¦Допустимы как #~lua~@https://www.lua.org/manual/5.1/manual.html@-#, так и #~moon~@https://moonscript.org/reference/@-/~yuescript~@https://yuescript.org/doc/@-# выражения.
   §¦Перед #lua#-выражением сначала делается попытка подставить #"return "#.

 #•# §¦Выражения могут обращаться к скриптам, используя модуль ~sh~@sh@, и даже просто по имени
   §¦(зависит от значения #sh.autoload#, для выражений по умолчанию разрешено, см. ~Опции~@Config@).

 #•# §¦Окружение можно предварительно инициализировать функцией #initEval# (см. ~Опции~@Config@).

 #•# §¦При запуске из ~Диалога~@ExecDlg@ окружение можно предварительно инициализировать
заданным скриптом (см.)

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@Cmdline
$ #Командная строка#

 Запуск скрипта как “исполняемого файла”:

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

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

@=

 Запуск скрипта через префикс плагина позволяет настроить ряд параметров, что может понадобиться при запуске
по ~ассоциации~@:FileAssoc@, из ~меню пользователя~@:UserMenu@, или диалога “~Применить команду~@:ApplyCmd@”.
 Кроме того, при запуске через префикс можно выполнять не только скрипты, но и непосредственно #lua(/moon/yue)#-~выражения~@LuaExpr@,
и просматривать возвращаемые значения (см. ниже).

 #     luash:[:][=|?][@@|*]...#
 #    luashs:[:][=|?][@@|*]...#

 При использовании префикса #luashs:# команда исполняется синхронно, а не в режиме макроса.

 Модификаторы, используемые с префиксом:

 #•# §¦Удвоенный символ #":"# однозначно указывает, что в командной строке имя файла, и не следует пытаться выполнить её как #выражение#,
если скрипт не найден.
 #•# §¦Просмотр возвращаемых значений:
     #•# §¦Символ #?# позволяет отобразить ~список возвращаемых значений~@ShowRet@ сразу, если они есть.
     #•# §¦Символ #=# аналогично, но если возвращаемых значений нет, то об этом выводится сообщение.
       §¦Если после #=# в командной строке ничего не указано, то отображаются значения, возвращённые последним выполненным скриптом.
 #•# §¦В обычном режиме сама выполняемая команда отображается на экране только если скрипт использовал “#print#”.
     #•# §¦Символ #*# используется для того, чтобы отобразить команду в любом случае.
     #•# §¦Символ #@@# используется для запрета отображения команды.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@ExecDlg
$ #Диалог запуска скрипта#

 Запуск скриптов возможен как из штатной командной строки Far’а,
так и из собственного диалога, доступного отовсюду по заданным макросам (см. ~Использование~@Usage@).

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

 По #Enter# запускать можно как #lua(/moon/yue)#-скрипты с параметрами (см. ~Командная строка~@Cmdline@),
так и непосредственно #lua(/moon/yue)#-~выражения~@LuaExpr@.

 #Ctrl-Enter# запускает скрипт на исполнение, выставив опции #[x] Reuse env# и #[x] Reopen#.

 #Shift-Enter# после исполнения показывает ~возвращённые значения~@ShowRet@, через опцию #[x] Show ret.#
 (также они всегда доступны по #Ctrl-Shift-L#, подробнее в разделе ~Использование~@Usage@).

 #F4# открывает редактор со скриптом, имя которого содержится в строке ввода.
И например чтобы создать новый скрипт, достаточно ввести желаемое имя и нажать #F4#.

 #F3# открывает скрипт во вьювере.

 Также в диалоге работают кнопки #PgUp# / #PgDn# / #Home#.


 #Дополнительные возможности#

 #•# §¦На нижней рамке диалога отображается результат(ы) предыдущего выполнения скрипта/выражения,
просмотреть подробнее их можно нажав #Ctrl-L#, или воспользовавшись кнопкой.
   §¦#Ctrl-Ins# на кнопке — копирует строку в буфер обмена.

   §¦В выражениях на предыдущий результат можно сослаться, использовав имя #ans# (используется только первое значение).
   §¦А с помощью функции #last(i)# можно получить все значения (опционально: начиная с #i#).
   §¦Примечание: #ans# и #last()# реализованы внешними скриптами (см. #utils\core\eval\#).

 #•# §¦На верхнем поле диалога располагается #строка статуса#, в которой может отображаться
результат выражения, вычисляемый динамически по мере ввода.
   §¦С помощью #Ctrl-E# можно просмотреть его подробно.
   §¦По умолчанию функция динамического обновление статуса активируется при включённом #ScrollLock#.
   §¦С помощью опции #autostatus=true# можно её включить безусловно,
а с помощью #autostatus=false# наоборот, полностью отключить.

 #•# §¦На верхней рамке слева находится кнопка #...#, позволяющая выбрать скрипт предварительной
настройки окружения для ~выражений~@LuaExpr@.
   §¦Таким образом можно #например# добавить любые пользовательские функции, или реализовать обращение
к функциям #math# напрямую без префикса, или запретить #autoload# (обращение к сприптам без ~sh~@sh@.)
   §¦См. прилагаемые примеры #_eval_extra#, #_eval_noauto#, …

   §¦При выборе скрипта его имя отображается на кнопке. #F4# позволяет открыть его в редакторе.
Сбросить выбор можно с помощью #Del# или указав пустую строку.

   §¦Выбор сохраняется в течении сессии, если же нужно иметь какой-либо скрипт всегда по умолчанию,
его имя можно указать в опции #initenv# (см. ниже).

   §¦#Примечание:#

   §¦При использовании опции #[x] Keep env# повторный запуск не приведёт к запуску скрипта инициализации.
   §¦Если скрипт требуется выполнять каждый раз, надо в нём установить #_inited = false#, см. #_eval_noauto.lua#.


 #Опции#

 Допустимо предварять строку ввода теми же символами-модификаторами, что предусмотрены для использования с ~префиксом~@Cmdline@,
или же можно задать требуемые опции с помощью чекбоксов:

 #[ ] Synchro# - синхронный режим запуска
   §¦#[x]# соответствует префиксу #luashs:#, опция #synchro#

 #[?] Expr.# - рассматривать текст как выражение, если скрипт с соответствующим именем не найден
   §¦#[ ]# только запуск скриптов, соответствует удвоенному символу #:#, опция #noexpr#
   §¦#[x]# только выполнение выражений, соответствует опции #expr_only#

 #[?] echo# - печать выполняемой команды
   §¦#[x]# соответствует символу #*#, опция #echo_force#
   §¦#[ ]# соответствует символу #@@#, опция #echo_off#

 #[ ] Show result# - отобразить ~возвращаемые значения~@ShowRet@
   §¦#[x]# соответствует символу #=#, опция #showret#
   §¦#[?]# соответствует символу #?#, опция #showret_ifany#

 Кроме того, есть опции специально для диалога запуска:

 #[ ] Keep env# - сохранять окружение между запусками
   §¦#[x]# соответствует опции #keepenv#
   §¦Окружение можно просмотреть нажав #Ctrl-K#, удалить — #Ctrl-Shift-K# (или #Del#, когда курсор на опции).

 #[ ] Reopen# - после выполнения команды заново открыть диалог запуска
   §¦#[x]# соответствует опции #reopen#

 Состояние опций “по-умолчанию” можно сохранить для текущей сессиии кнопкой #[ Save options ]#.
 Изменить опции перманентно можно в ~Опциях~@Config@, имена ключей см. выше, состояние #[?]# кодируется числом #2#.

 Кроме того, есть несколько параметров, которые можно задать только вручную, через ~execDlgOptions~@Config@:

 #•# §¦#initenv# (string) и #autostatus# (boolean) описаны выше.
 #•# §¦#small# (boolean) отображает диалог ~без полей~@https://api.farmanager.com/ru/service_functions/dialoginit.html##FDLG_SMALLDIALOG@.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@ShowRet
$ #Просмотр возвращаемых значений#

 Для просмотра возвращаемых значений можно воспользоваться соответствующей опцией
в ~диалоге запуска скрипта~@ExecDlg@ или же шорткатом #Shift-Enter#;
 аналогичная возможность предусмотрена и в ~командной строке~@Cmdline@, указанием специального символа #=#.

 Таблицы можно просматривать в виде списка (рекомендуются модули “#le#” и “#inspect#”, см. раздел ~Установка~@Install@).

 Кроме того, когда скрипт (или #lua(/moon/yue)#-~выражение~@LuaExpr@) возвращает значения —
в нижней части экрана кратковременно выводится нотификация с предложением просмотреть их, нажав #Enter#.

 Эта же функция доступна и позже в любой момент по #Ctrl-Shift-L# (подробнее в разделе ~Использование~@Usage@).

 В списке значений доступны следующие действия:

 #•# §¦#Enter# - просмотреть значение в диалоге
 #•# §¦#Ctrl-Ins# - скопировать дамп значения
 #•# §¦#Ctrl-E# - заново открыть диалог с командой

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@API
$ #API#

 #API, предоставляемый скрипту#

 #...# (#vararg#)
   §¦Аргументы командной строки.

 #_filename# (string)
   §¦Полное имя скрипта.

 #_cmdline# (string)
   §¦Переменная, в которую помещаются неразделённые аргументы скрипта в виде строки (исключая имя скрипта),
в случае когда скрипт исполняется напрямую (из ~командной строки~@Cmdline@ или ~диалога~@ExecDlg@).

     #•# §¦Если скрипт вызван без параметров, то #_cmdline==""#

     #•# §¦Если скрипт запущен не из командной строки, а вызван другим скриптом (см. ниже #sh#),
то переменной #_cmdline# в окружении не будет.

       §¦Таким образом возможно различить как запущен скрипт, и в зависимости от этого
либо вернуть значение (в том числе функцию, таблицу), либо непосредственно выполнить
соответствующие действия, оперируя аргументами, переданными в командной строке.
       §¦Например, можно использовать такой паттерн:

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

   §¦Для того чтобы рассмотреть командную строку как выражение — можно использовать #sh.eval(_cmdline)# (см.)

 #nocache# (boolean)
   §¦Параметр, позволяющий запретить кэширование результата исполнения скрипта.
   §¦См. примеры использования в #utils\core\eval\ans.lua#/#last.lua# и #utils\std\far\api\*.lua#

   §¦Примечания:

     #•# §¦По умолчанию возвращаемое скриптом значение кэшируется, т.е. скрипт исполняется только при первом обращении
к #sh.somefile#, а все последующие — используют кэшированное значение.
     #•# §¦~Опция~@Config@ #debug# также отключает кэширование.

 #print# (function)
   §¦То же что и #sh.print# (см.)

 #sh# (table)
   §¦~API для обращения к другим скриптам~@sh@ + дополнительные сервисные функции.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~i~@index@]


@sh
$ #API для обращения к другим скриптам — sh#

 Модуль #sh# доступен из скрипта непосредственно, а в обычном макросе — через ~require~@https://www.lua.org/manual/5.1/manual.html##pdf-require@.

 Загрузить скрипт по его имени можно двумя способами:

 #sh.<name># (т.е. индексируя нэймспейс #sh#, используя в качестве ключа имя скрипта)
   §¦Рекомендуется к использованию в большинстве случаев.
   §¦Позволяет обратиться непосредственно к возвращаемому значению скрипта.

   §¦Примечание:
   §¦При исполнении скрипту в качестве аргумента передаётся собственное имя (для совместимости с модулями).

   §¦Примеры:

 #      local ret = sh.name    -- исполняет скрипт, возвращая результат#
 #      sh.name(arg1,arg2,...) -- если экспортируется функция#
 #      sh.name.somefunc(...)  -- если возвращается таблица содержащая функцию somefunc#

 #sh(name,env)#
   §¦Даёт больше контроля при загрузке скрипта:

     #•# §¦Не исполняет скрипт непосредственно, а возвращает функцию, аналогично ~loadfile~@https://www.lua.org/manual/5.2/manual.html##pdf-loadfile@.
       §¦Таким образом скрипту можно передать параметры, как и при обычном запуске из ~командной строки~@Cmdline@.

       §¦Примеры:

 #      local fn = sh"name"                  -- загружает скрипт (но не исполняет)#
 #      local ret = fn(arg1,arg2,...)        -- исполняет ранее загруженный скрипт, передавая аргументы#

 #      local ret = sh"name"(arg1,arg2,...)  -- то же самое но за один шаг#

 #      sh"name"("name")                     -- то же что и `sh.name`#

     #•# §¦Позволяет (опционально) задать окружение.
       §¦Например если скрипт используется как короткий алиас другого скрипта, для работы которого может требоваться
передать не только аргументы, но и служебное #окружение# (~_filename, _cmdline~@API@).

 #      sh("name", {_cmdline=_cmdline})(...) -- можно передать собственный _cmdline#
 #      sh("name", getfenv())(...)           -- или собственное окружение целиком#

 #Примечание:#

 В директории #utils\core\# можно найти некоторые “внутренние” скрипты, которые
(как и все прочие) можно адресовать через #sh.#

@=


 #Дополнительные сервисные функции#

 #sh.print(...)#
   §¦Аналог стандартной Lua-функции ~print~@https://www.lua.org/manual/5.1/manual.html##pdf-print@, реализован на основе ~win.WriteConsole~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\luafar_manual.chm::/534.html@.
   §¦Выводит текст в буфер под панелями (панели гасятся, а после завершения скрипта восстанавливаются автоматически).
   §¦Скриптам LuaShell данная функция доступна и просто как #print#, без префикса.
   §¦(Это не мешает использовать штатную #_G.print# / ~mf.print~@https://api.farmanager.com/ru/macro/macrocmd/prop_func/general.html##print@ там где нужна именно она.)

   §¦#Примечание:# по функциональности #sh.print# похожа на ~mf.printconsole~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/101.html@, однако последняя
гасит/восстанавливает панели (~Get~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\luafar_manual.chm::/228.html@/~SetUserScreen~@start hh mk:@@MSITStore:%FARHOME%\Encyclopedia\luafar_manual.chm::/15.html@) при каждом
вызове, что не всегда удобно, и ограничивает производительность.

 #sh.eval(expr, env, ...)# (реализовано отдельным скриптом)
   §¦Вычисляет строку как #lua#-~выражение~@LuaExpr@ (опционально, передавая таблицу с окружением, и аргументы).
   §¦Полезно как для собственно вычислений (#1+math.sin(2)#), так и для передачи любых lua-значений
(#_G, Far, 123, "abc", {k="v"}, function() print"hello" end, ...#).

   §¦Типичный случай использования: #sh.eval(_cmdline)#.
   §¦Другие примеры использования в #utils\core\eval\README#.

 #sh._shared# (table)
   §¦Доступ к некоторым внутренним параметрам, таким как мета-информация о скрипте #LuaShell.lua#,
и его таблица #options#.
   §¦Может служить для обмена информацией между скриптами (в частности содержит поле #LastCmdLineResult#,
подробнее в разделе ~Использование~@Usage@).
   §¦Там же скрипты могут сохранять свои данные между запусками (в рамках одной сессии).
   §¦Один из вариантов обеспечения уникальности используемого ключа, это использовать путь к скрипту:

 #      local mydata = sh._shared[_filename]#
 #      if not mydata then#
 #        mydata = {}#
 #        sh._shared[_filename] = mydata#
 #      end#

 #sh.autoload# (boolean/function)
   §¦Параметр, дающий возможность загружать скрипты не используя #sh.#, а просто по имени, как глобальную переменную.
   §¦Если значение истинно, то при обращении к любому необъявленному идентификатору будет произведена
попытка загрузить одноимённый скрипт, и использовать возвращённое им значение.
   §¦По умолчанию: нет.
   §¦Предполагается что задать значение может понадобиться в каком-либо скрипте локально, для его собственных нужд.

   §¦Примечания:

     #•# §¦Для ~выражений~@LuaExpr@ окружение предустановлено (см. ~Опции~@Config@), и значение по умолчанию истинно.
     #•# §¦Если в качестве значения задана функция, и будучи вызванной с искомым именем в качестве аргумента она вернёт значение,
то будет использованно именно оно (см. #core\eval\eval.lua#).
       §¦Только если функция не вернула значений, искомое имя будет использовано для загрузки скрипта.

@=

 Другие разделы справки: [~Описание~@Contents@], [~Утилиты~@Utils@], [~Установка~@Install@], [~Использование~@Usage@], [~API~@API@], [~i~@index@]


@index
$ #Index#

 #•# §¦~LuaShell~@Contents@
     #•# §¦~Назначение~@Purpose@
 #•# §¦~Утилиты~@Utils@
     #•# §¦Набор #3rd-party#
     #•# §¦Набор #std#
     #•# §¦Возможность использования отдельно от LuaShell
 #•# §¦~Установка~@Install@
     #•# §¦~Опции~@Config@
 #•# §¦~Использование~@Usage@
     #•# §¦Возвращаемые значения
     #•# §¦~Выполнение Lua-выражений~@LuaExpr@
     #•# §¦~Командная строка~@Cmdline@
     #•# §¦~Диалог запуска скрипта~@ExecDlg@
         #•# §¦Дополнительные возможности
         #•# §¦Опции
     #•# §¦~Просмотр возвращаемых значений~@ShowRet@
 #•# §¦~API~@API@
     #•# §¦API, предоставляемый скрипту
     #•# §¦~API для обращения к другим скриптам — sh~@sh@
         #•# §¦Дополнительные сервисные функции