LuaShell.ru.text

<!--HLF:
     Language = Russian,Russian (Русский);
     PluginContents = LuaShell;
    TopicHeading = h6;
    Margin = 1;
    IndentCode = 4;
     IndentList = 0;
    IndentPara = 0;
    IndentQuote = 4;
    PlainCode = false;
    PlainHeading = false;
    CenterHeading = false;
     EmptyLinesBeforeTopic = 2;
    EmptyLinesAfterHeading = 1;
     EmptyLinesBeforeHeading = 2;
    HighlightListBullet = true;
    HighlightListNumber = true;
-->

LuaShell {#Contents refsTitle=Описание}
========

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

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

Скрипты удобно не только запускать вручную, но и использовать в [ассоциациях](:FileAssoc),
[меню пользователя](:UserMenu), диалоге "[Применить команду](:ApplyCmd)" и т. п.

Область действия не ограничена панелями: командная строка [доступна][Диалог запуска скрипта] в любой области
Far'а, с автодополнением и историей.

Также возможно непосредственно исполнять набранные в строке ввода *lua(/moon/yue)*-[выражения],
и [просматривать возвращаемые значения][Просмотр возвращаемых значений].

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

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

- - -

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


Назначение {#Purpose}
----------

Данный скрипт возник в ответ на штатную возможность запускать [lua-скрипты][cmdline], появившуюся ещё в LuaMacro 198.
В штатной реализации аргументы представляли собой *lua*-выражения, разделённые _запятыми_:

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

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

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

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

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

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


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

* Запуск скриптов без необходимости указывать полный путь, и даже [без специального префикса][Установка];
  как обычные утилиты, доступные в `%PATH%`, но с полным доступом к _FAR API_.

* Доступ к "командной строке" не только из панелей, но [также][Диалог] из редактора и прочих областей.

* Помимо "строкового" интерфейса командной строки, скрипты могут "экспортировать" свои функции непосредственно,
  что позволяет обращаться из скрипта к скрипту наиболее прямым образом, см. [sh].

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

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

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

[cmdline]: mk:@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/92.html


Утилиты {#Utils}
=======

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


Набор **3rd-party**
-------------------

Набор [3rd-party], распространяемый отдельно, это скрипты и макросы других авторов,
приспособленные для использования в LuaShell.  
Обычное место размещения - `Macros\utils\3rd-party`.

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

[3rd-party]: https://github.com/FarManagerLegacy/LuaShell.3rd-party


Набор **std**
-------------

В наборе [std] представлены как полезные утилиты, которыми я регулярно пользуюсь, так и экспериментальные,
а также скрипты написанные для тестирования и/или иллюстрации возможностей системы.  
Набор предполагается размещать в директории `Macros\utils\std`.

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

- filesmenu: поиск/выбор файла из меню
- files/apply: Универсальный выбор/обработка файлов, удовлетворяющих заданному условию
- [lineup]\: Вертикальное выравнивание строк по разделителям
- [lorem]\: _Lorem ipsum generator_
- RunMacro: исполнять макросы из макрофайлов, не устанавливая их
- plugins: утилиты для загрузки/выгрузки плагинов, как с выбором через меню, так и массово
- venv: работа с _Python virtual environments_
- ...

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


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

Часть утилит написаны так, что могут быть использованы и без LuaShell:
либо как макросы (если в них содержатся определения `Macro` или `MenuItem`),
либо исполняться штатными средствами LuaMacro: из [командной строки][cmdline],
или с помощью [mf.eval].

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

[std]: https://github.com/FarManagerLegacy/LuaShell.std
[mf.eval]: mk:@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/79.html
[lineup]: https://forum.farmanager.com/viewtopic.php?t=12582
[lorem]: https://forum.farmanager.com/viewtopic.php?t=13230


Установка {#Install}
=========

Для базовой установки можно воспользоваться командой меню пользователя (по `F2`),
или сделать это вручную как описано в [README.md].

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

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

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

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

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

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


Примечания:

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

b. Для удобства к значению переменной `PATH` добавляется путь к директории `Macros\utils`
   и рекурсивно ко всем её поддиректориям (исключая скрытые).  
   Содержимое `Macros\utils\core` является неотъемлемой частью LuaShell,
   [остальные][Утилиты] директории и их содержимое — опциональны.

c. *Префикс*, *путь к директории по-умолчанию*, *расширения*,
   и некоторые другие параметры при необходимости можно переопределить через [опции].

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

   - *Lua explorer* (le): https://forum.farmanager.com/viewtopic.php?f=60&t=7988
   - *Inspect*:           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=60&t=8008) скрипта в редакторе + выполнение
   - [Luacheck FAR scripts](https://forum.farmanager.com/viewtopic.php?f=60&t=9650) — статический анализатор для *Lua/Moon-/Yuescript*

[README.md]: https://github.com/FarManagerLegacy/LuaShell.core/README.md
[MacroEx]: https://forum.farmanager.com/viewtopic.php?f=15&t=8764 "MacroEx — запуск макросов нетрадиционными способами"


Опции {#Config}
-----

- `prefix`,  `path`,  `pathext` (string) позволяют переопределить значения, описанные в разделе [Установка].

- В `LastResultKey` (string) задаётся шорткат, по которому можно [просмотреть][Просмотр возвращаемых значений] возвращаемые значения
  последнего запущенного скрипта (подробнее в разделе [Использование]).  
  По умолчанию: `Ctrl-Shift-L`.

- С помощью функции `initEval(env)` можно изменить окружение, доступное при исполнении через [`eval`][API]
  при исполнении *lua(/moon/yue)*-[выражений][Выражения].  
  По умолчанию: `F=far.Flags`; `sh.autoload=true` (см. [sh].)

- `execDlgOptions` (table) — настройки [диалога запуска скрипта][Диалог запуска скрипта] (см.)

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

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

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


Использование {#Usage}
=============

Скрипты можно запускать из [командной строки][Командная строка] Far по имени, как исполняемые файлы
(при правильной [установке][Установка]), указывая при необходимости и аргументы.

Повторить запуск скрипта можно нажатием `Ctrl-Alt-G` или `CtrlG:Double`  
(Внимание: шорткаты с ":Double" и ":Hold" предполагают наличие [MacroEx]).

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

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

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

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

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

- - -

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

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

Если скрипт/выражение возвращают значения, то в нижней части экрана отображается
нотификация с предложением [просмотреть][Просмотр возвращаемых значений] их, нажав `Enter`.  
Или же можно сразу при запуске указать, что после выполнения требуется отобразить результат
(см. справку [командной строки][Командная строка] / [диалога][Диалог запуска скрипта]).  
Кроме того, значения можно просмотреть и позже в любой момент, с помощью макроса на `Ctrl-Shift-L` ([настраивается][Опции]).

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

- - -

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


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

LuaShell позволяет не только запускать скрипты, но и непосредственно исполнять *lua(/moon-/yuescript)*-выражения,
и [получать возвращаемые значения][Просмотр возвращаемых значений]:

- В [диалоге запуска скрипта][Диалог запуска скрипта]
- В [командной строке][Командная строка] (при использовании с префиксом, или через другой скрипт, см. ниже)
- Через API — `sh.eval` (см. [sh] и *utils\core\eval\README*)

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

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

* Допустимы как *[lua]-*, так и *[moon]-/[yuescript]-* выражения.  
  Перед *lua*-выражением сначала делается попытка подставить `"return "`.

* Выражения могут обращаться к скриптам, используя модуль [sh], и даже просто по имени  
  (зависит от значения `sh.autoload`, для выражений по умолчанию разрешено, см. [Опции]).

* Окружение можно предварительно инициализировать функцией `initEval` (см. [Опции]).

* При запуске из [Диалога][Диалог] окружение можно предварительно инициализировать
  заданным скриптом (см.)

[lua]: https://www.lua.org/manual/5.1/manual.html
[moon]: https://moonscript.org/reference/
[yuescript]: https://yuescript.org/doc/

[Выражения]: #LuaExpr


Командная строка {#Cmdline}
----------------

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

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

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

- - -

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

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

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

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

* Удвоенный символ `":"` однозначно указывает, что в командной строке имя файла, и не следует пытаться выполнить её как _выражение_,
  если скрипт не найден.
* Просмотр возвращаемых значений:
  - Символ `?` позволяет отобразить [список возвращаемых значений][Просмотр возвращаемых значений] сразу, если они есть.
  - Символ `=` аналогично, но если возвращаемых значений нет, то об этом выводится сообщение.  
    Если после `=` в командной строке ничего не указано, то отображаются значения, возвращённые последним выполненным скриптом.
    
* В обычном режиме сама выполняемая команда отображается на экране только если скрипт использовал "`print`".
  - Символ `*` используется для того, чтобы отобразить команду в любом случае.
  - Символ `@` используется для запрета отображения команды.


Диалог запуска скрипта {#ExecDlg}
----------------------

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

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

По `Enter` запускать можно как *lua(/moon/yue)*-скрипты с параметрами (см. [Командная строка]),
так и непосредственно *lua(/moon/yue)*-[выражения].

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

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

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

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

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

[Диалог]: #ExecDlg


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

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

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

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

- На верхней рамке слева находится кнопка `...`, позволяющая выбрать скрипт предварительной
  настройки окружения для [выражений][Выражения].  
  Таким образом можно _например_ добавить любые пользовательские функции, или реализовать обращение
  к функциям `math` напрямую без префикса, или запретить *autoload* (обращение к сприптам без [sh].)  
  См. прилагаемые примеры `_eval_extra`, `_eval_noauto`, ...

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

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

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


Опции
-----

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

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

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

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

`[ ] Show result` - отобразить [возвращаемые значения][Просмотр возвращаемых значений]
:	`[x]` соответствует символу `=`, опция `showret`
:	`[?]` соответствует символу `?`, опция `showret_ifany`

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

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

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

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

Кроме того, есть несколько параметров, которые можно задать только вручную, через [`execDlgOptions`][Опции]:

- `initenv` (string)  и `autostatus` (boolean) описаны выше.
- `small` (boolean) отображает диалог [без полей][FDLG_SMALLDIALOG].

[FDLG_SMALLDIALOG]: https://api.farmanager.com/ru/service_functions/dialoginit.html#FDLG_SMALLDIALOG


Просмотр возвращаемых значений {#ShowRet}
------------------------------

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

Таблицы можно просматривать в виде списка (рекомендуются модули "`le`" и "`inspect`", см. раздел [Установка]).

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

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

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

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


API {#API}
===

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

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

`_filename` (string)
:	Полное имя скрипта.

`_cmdline` (string)
:	Переменная, в которую помещаются неразделённые аргументы скрипта в виде строки (исключая имя скрипта),
	в случае когда скрипт исполняется напрямую (из [командной строки][Командная строка] или [диалога][Диалог запуска скрипта]).

	- Если скрипт вызван без параметров, то `_cmdline==""`
	- Если скрипт запущен не из командной строки, а вызван другим скриптом (см. ниже `sh`),
	  то переменной `_cmdline` в окружении не будет.  

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

	~~~ lua
	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`, а все последующие — используют кэшированное значение.
	- [Опция][Опции] `debug` также отключает кэширование.

`print` (function)
:	То же что и `sh.print` (см.)

`sh` (table)
:	[API для обращения к другим скриптам][sh] + дополнительные сервисные функции.


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


API для обращения к другим скриптам — `sh` {#sh}
------------------------------------------

Модуль `sh` доступен из скрипта непосредственно, а в обычном макросе — через [`require`][require].

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

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

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

	Примеры:

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

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

	- Не исполняет скрипт непосредственно, а возвращает функцию, аналогично [`loadfile`][loadfile].  
	  Таким образом скрипту можно передать параметры, как и при обычном запуске из [командной строки][Командная строка].  

	  Примеры:

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

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

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

	- Позволяет (опционально) задать окружение.  
	  Например если скрипт используется как короткий алиас другого скрипта, для работы которого может требоваться
	  передать не только аргументы, но и служебное _окружение_ ([`_filename`, `_cmdline`][API]).

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

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

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

[require]: https://www.lua.org/manual/5.1/manual.html#pdf-require
[loadfile]: https://www.lua.org/manual/5.2/manual.html#pdf-loadfile
[sh]: #sh

- - -

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

`sh.print(...)`
:	Аналог стандартной Lua-функции [`print`][print], реализован на основе [`win.WriteConsole`][win.WriteConsole].  
	Выводит текст в буфер под панелями (панели гасятся, а после завершения скрипта восстанавливаются автоматически).  
	Скриптам LuaShell данная функция доступна и просто как `print`, без префикса.  
	(Это не мешает использовать штатную `_G.print` / [`mf.print`][mf.print] там где нужна именно она.)
	
	**Примечание:** по функциональности `sh.print` похожа на [`mf.printconsole`][mf.printconsole], однако последняя
	гасит/восстанавливает панели ([`Get`][panel.GetUserScreen]/[`SetUserScreen`][panel.SetUserScreen]) при каждом
	вызове, что не всегда удобно, и ограничивает производительность.

`sh.eval(expr, env, ...)` (реализовано отдельным скриптом)
:	Вычисляет строку как *lua*-[выражение][Выражения] (опционально, передавая таблицу с окружением, и аргументы).  
	Полезно как для собственно вычислений (`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`,
	подробнее в разделе [Использование]).  
	Там же скрипты могут сохранять свои данные между запусками (в рамках одной сессии).  
	Один из вариантов обеспечения уникальности используемого ключа, это использовать путь к скрипту:
	
	~~~lua
	local mydata = sh._shared[_filename]
	if not mydata then
	  mydata = {}
	  sh._shared[_filename] = mydata
	end
	~~~

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

	Примечания:

	- Для [выражений][Выражения] окружение предустановлено (см. [Опции]), и значение по умолчанию истинно.
	- Если в качестве значения задана функция, и будучи вызванной с искомым именем в качестве аргумента она вернёт значение,
	  то будет использованно именно оно (см. *core\eval\eval.lua*).  
	  Только если функция не вернула значений, искомое имя будет использовано для загрузки скрипта.

[print]: https://www.lua.org/manual/5.1/manual.html#pdf-print
[win.WriteConsole]: mk:@MSITStore:%FARHOME%\Encyclopedia\luafar_manual.chm::/534.html
[mf.printconsole]: mk:@MSITStore:%FARHOME%\Encyclopedia\macroapi_manual.ru.chm::/101.html
[mf.print]: https://api.farmanager.com/ru/macro/macrocmd/prop_func/general.html#print
[panel.GetUserScreen]: mk:@MSITStore:%FARHOME%\Encyclopedia\luafar_manual.chm::/228.html
[panel.SetUserScreen]: mk:@MSITStore:%FARHOME%\Encyclopedia\luafar_manual.chm::/15.html


---
refsTemplate: refsBottom
links: |
  - [core](https://github.com/FarManagerLegacy/LuaShell.core) | [Скачать](https://github.com/FarManagerLegacy/LuaShell.core/zipball/master)
  - [std](https://github.com/FarManagerLegacy/LuaShell.std) | [Скачать](https://github.com/FarManagerLegacy/LuaShell.std/zipball/master)
  - [3rd-party](https://github.com/FarManagerLegacy/LuaShell.3rd-party) | [Скачать](https://github.com/FarManagerLegacy/LuaShell.3rd-party/zipball/master)
...