Общие свойства и функции

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

Far.FullScreen
Far Manager работает в оконном режиме?
Far.IsUserAdmin
Far Manager запущен под Администратором?

Свойства

Far.Height
number
высота окна консоли, в которой работает Far Manager
Far.Width
number
ширина окна консоли, в которой работает Far Manager
Far.PID
number
содержит ID текущей запущенной копии Far Manager
Far.Title
string
текущий заголовок консольного окна Far Manager
Far.UpTime
number
сколько времени (в миллисекундах) работает Far Manager (своё значение для каждой запущенной копии)

Функции

Глобальные функции

Функции akey, eval, exit, Keys, mmode, msgbox, print, prompt — это глобальные ссылки на одноимённые функции из библиотеки mf (см. ниже).

Функции band, bnot, bor, bxor, lshift, rshift — это глобальные ссылки на одноимённые функции из библиотеки bit64 (см. [LuaFAR manual]).

Взаимодействие с пользователем

E=mf.beep([N])

Воспроизвести один из системных звуковых сигналов N.

0x00000040
Звук Звёздочка
0x00000030
Звук Восклицание
0x00000010
Звук Критическая ошибка
0x00000020
Звук Вопрос
0x0
Стандартный звук
0xFFFFFFFF
Стандартный звук на встроенный динамик

Функция возвращает true или false (в случае неудачи).

S=mf.key(V)

Преобразует параметр V в строковый эквивалент названия клавиши.

Если V — строка, то проверяется правильность написания клавиши и она же возвращается.

Если V — число, то происходит попытка преобразовать значение в текстовый эквивалент названия клавиши.

В случае ошибок — возвращается пустая строка.

Примечание:

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

Keys(...)

Послать один или более ключей Far Manager’у.

Параметры:

Один или больше аргументов типа string.

Каждый аргумент может содержать несколько ключей, разделённых пробельными символами.

Аргументы регистронезависимы.

Перед каждым ключом может быть указан множитель, например “3*Down” эквивалентно “Down Down Down”.

Специальные ключи:

“AKey”
послать Far Manager’у клавишу, вызвавшую данный макрос
“SelWord”
выделить слово под курсором
“XLat”
преобразовать слово под курсором (ср. mf.xlat())
“EnOut”
разрешить вывод на экран (то же, что mmode(1,0))
“DisOut”
запретить вывод на экран (то же, что mmode(1,1))

Пример:

local mykeys = "CtrlF5 Esc"
Keys("AKey A b CtrlC ShiftEnter", mykeys)

См. также:

Ограничения в использовании некоторых функций

N=mf.msgbox([Title[,Text[,Flags]]])

Показывает сообщение Text с заголовком Title.

В параметре Text строки разбиваются символом ‘\n’.

Flags может быть набором следующих значений:

0x00000001
Используются цвета “Предупреждения” (обычно белые буквы на красном фоне).
0x00000008
Использовать для строк сообщения выравнивание влево (по умолчанию строки выводятся по центру).
0x00010000
Выводится кнопка [ Ok ]
0x00020000
Выводятся кнопки [ Ok ] и [ Cancel ]
0x00030000
Выводятся кнопки [ Abort ], [ Retry ] и [ Ignore ]
0x00040000
Выводятся кнопки [ Yes ] и [ No ]
0x00050000
Выводятся кнопки [ Yes ], [ No ] и [ Cancel ]
0x00060000
Выводятся кнопки [ Retry ] и [ Cancel ]

Если параметр Flags равен 0 (или не указан), то выводится стандартный диалог с кнопкой [ Ok ]

Функция возвращает номер выбранной кнопки (начиная с 1), или 0, если пользователь отменил сообщение

mf.print(Str)

Функция предназначена для вставки произвольного текста Str в редактор, командную строку, элементы ввода в диалогах, etc.

Допускается применение следующих escape-последовательностей:

\"
Символ ‘"’
\'
Символ ‘'’
\\
Символ ‘\’
\n
Переводу строки ‘\n’
\t
Табуляции ‘\t’
\a
bell
\b
\b
\f
\f
\v
\v
\N, \NN, \NNN
8-ричный код символа
\xNN
16-ричный код символа

См. Примеры

mf.printconsole(...)

Функция выводит (“печатает”) свои аргументы в консоль.

  • Она вставляет символ табуляции между аргументами.
  • Нет необходимости вызывать panel.GetUserScreen() / panel.SetUserScreen(), так как функция делает это сама.

Параметры:

...
0 или более величин Lua
S=mf.prompt([Title[,Prompt[,Flags[,Src[,History]]]]])

Функция позволяет ввести одну строку текста.

Параметры: Title — заголовок диалога, Prompt — приглашения для ввода, Src — начальное значение строки ввода, History — имя истории ввода.

Flags может быть набором следующих значений (аналогичных константам FIB_*):

0x00000002
Используется для ввода пароля — вводимый текст на экране отрисовывается символами ‘*’.
0x00000004
После успешного ввода, в результирующем значении S идентификаторы переменных окружения заменяются на их значения, например, если пользователь ввёл ‘%TEMP%’, то результат будет содержать ‘C:\TEMP’.
0x00000008
Не использовать предыдущее значение из истории, оставить строку ввода пустой; актуален, если указан непустой параметр History.
0x00000010
Показать разделительную линию и кнопки [ Ok ] и [ Cancel ]. Диалог увеличится на 2 строки.
0x00000020
Не показывать в приглашении ввода амперсанд, использовать его для определения горячей клавиши.

Функция возвращает строку (введённое пользователем значение) или false, если пользователь нажал Esc.

Например, запросить пароль и вывести его:

local s = mf.prompt("Password","Input password:",0x02)
mf.msgbox(s)
mf.usermenu(mode,filename)

Открывает или создаёт пользовательское меню.

Параметры:

mode
number (0 по умолчанию)
filename
string или nil

Возвращает: ничего

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

Поведение функции в зависимости от величины младшего байта mode:

0
равносильно нажатию F2 в панелях; filename игнорируется.
1
выводится диалог выбора пользовательского меню; filename игнорируется.
2
файл открывается “как есть”, т.е. по заданному filename.
3
файл filename открывается в %FARPROFILE%\Menus (папка создаётся автоматически).

См. также:

Ограничения в использовании некоторых функций

V=mf.waitkey([N[,T]])

Ожидает нажатие любой клавиши и возвращает её значение.

Параметр N позволяет ограничить время ожидания нажатия, в миллисекундах. Если время истекло, функция возвращает пустую строку (T=0) или 0 (T=1).

Если N не указан или равен 0, то функция будет бесконечно ждать нажатия клавиши.

Параметр T позволяет указать, значение какого типа использовать для клавиши.

0 (по умолчанию)
возвращается строка, название клавиши
1
возвращается число, внутренний идентификатор клавиши (в настоящий момент практического смысла не имеет)
V=Menu.Show(Items,...

Создаёт и отображает на экране меню.

Параметр Items: пункты меню, разделённые Lf (“\n”) или CrLf (“\r\n”)

Могут начинаться (cимвол+пробел) со специальных символов:

(возможны некоторые комбинации)

\1
сепаратор; не участвует в автонумерации/сортировке/удалении дубликатов.
\2
пункт отмечен (возможна комбинация с \3 и \4)
\3
пункт недоступен для навигации и выбора
\4
серый, недоступен для выбора

Дополнительные параметры:

[,TitleAndFooter
[,Flags
[,SelectOrFilter
[,X
[,Y]]]]])

Необязательный параметр TitleAndFooter: заголовок и футер меню, разделённые Lf (“\n”) или CrLf (“\r\n”).

Один или оба могут отсутствовать.

Необязательный параметр Flags — набор битов, управляющих поведением и отображением меню:

0—2

Тип рамки меню: (по умолчанию:100)

001 (0x1)
без рамки
010 (0x2)
одинарная, с окружающими пробелами
011 (0x3)
одинарная, без окружающих пробелов
100 (0x4)
двойная, с окружающими пробелами
101 (0x5)
двойная, без окружающих пробелов
3 (0x8)
возвращаемый результат — индекс выбранного пункта меню
4 (0x10)
разрешена отметка нескольких пунктов и её снятие
5 (0x20)
отсортировать (производится регистронезависимая числовая сортировка)
6 (0x40)
убрать дублирующиеся пункты меню (с учётом регистра)
7 (0x80)
автоматически назначить “горячие” клавиши
8 (0x100)

как трактовать SelectOrFilter: (по умолчанию: 0)

0
позиционировать (если SelectOrFilter — число), либо найти (если SelectOrFilter — строка) пункт меню
1
установить фильтр меню
9 (0x200)
автоматически пронумеровать пункты меню
10 (0x400)
выйти из меню при изменении выбранного пункта

Необязательный параметр SelectOrFilter — на какой пункт меню позиционировать курсор, либо фильтрация пунктов.

Может быть:

числом
если бит 8 ≡ 0, то позиционировать на указанный пункт меню.
Если число отрицательное, то отсчёт ведётся с конца меню
строкой
если бит 8 ≡ 0, то найти пункт меню.
Поиск регистронезависим, возможны маски
если бит 8 ≡ 1, то установить фильтр меню

Необязательные параметры X и Y — координаты левого верхнего угла меню. Если одна (или обе) равны -1 (по умолчанию), то производится центрирование меню по этой координате.

Возвращаемый результат функции:

пустая строка
выход из меню по Esc, F10 или при клике вне меню
число ≡ 0 (если установлен бит 3)
выход из меню по Esc, F10 или при клике вне меню
число > 0
индекс выбранного пункта
число < 0
если установлен бит 10, то индекс выбранного пункта со знаком минус
строка
выбранный пункт меню.

Если установлен бит 4, то список отмеченных пунктов меню, разделённых \n. Если установлены и бит 3 и бит 4, то список индексов отмеченных пунктов меню, разделённых \n. В меню доступны следующие сочетания клавиш: (пометка возможна только при установленном бите 4)

Ins
пометка пункта
Ctrl+Add
пометка всех видимых пунктов
Ctrl+Subtract
снятие пометки со всех видимых пунктов
Ctrl+Multiply
инверсия пометки у всех видимых пунктов
Ctrl+A
подогнать меню по высоте

Пример использования — навигация по установленным закладкам редактора:

Macro {
  description="Стековые закладки";
  area="Editor"; key="AltB";
  action=function()
    local S = ""
    local N = BM.Stat(0)
    for i=1,N do
      BM.Goto(i)
      S = S..Editor.Value.."\n"
    end
    local title = "Стековые закладки\nНавигация - Up/Down, Выход - Esc, F10"
    local I = 1
    repeat
      I = Menu.Show(S,title,0x600,math.abs(I),80,Far.Height-N-5)
      if I>0 then
        BM.Goto(I)
        Keys("SelWord")
      else
        I = 0
      end
    until i==0
  end;
}

Среда исполнения

mf.AddExitHandler(handler)

Данная функция добавляет обработчик, который будет вызван по окончанию исполнения макроса.

Параметры:

handler
function

Возвращает: ничего

Примечания:

  • Обработчик будет вызван как при нормальном завершении макроса, так и в случае, если макрос был завершён по ошибке.
  • Если в процессе исполнения макроса было добавлено несколько обработчиков, то они будут вызваны в порядке, обратном порядку их добавления.

Пример применения:

local fp = assert(io.open("some file.txt"))
mf.AddExitHandler(function() fp:close() end)
-- use fp; return from multiple places; do not care about closing fp

См. также:

Ограничения в использовании некоторых функций

V=Far.Cfg_Get(Key,Name)
(устаревшая, используйте Far.GetConfig)

Функция, позволяет получить основные текущие настройки Far Manager. В случае ошибки (нет такого Key или Name или внутренняя ошибка) возвращает false.

Например,

Far.Cfg_Get("System.KnownIDs","Network")
вернёт значение “773B5051-7C5F-4920-A201-68051C4176A4”, которое соответствует ID плагина Network.
Far.Cfg_Get("Macros","DateFormat")
вернёт значение формат преобразования даты по умолчанию для функции mf.date.
Far.Cfg_Get("Macros","TimeFormat")
вернёт false, т.к. значения с именем “TimeFormat” не существует.

Внимание!

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

val,tp=Far.GetConfig(keyname)

Функция, позволяет получить основные текущие настройки Far Manager.

Параметры:

keyname
string

Возвращает:

val

boolean, string, number, or int64

Это значение запрашиваемой величины.

Преобразование типов между Far Manager и Lua осуществляются следующим образом:

  • boolean ⟶ boolean
  • 3-state ⟶ 0,1,2 преобразуются соответственно в false,true,"other"
  • string ⟶ string
  • integer ⟶ number (если возможно преобразование без потери точности) или userdata (int64) — величина, создаваемая библиотекой bit64.
tp
string ("boolean", "3-state", "string", "integer") Это тип оригинальной величины в Far Manager.

Примечание:

В случае ошибки (некорректный аргумент, или Far Manager не нашёл указанной опции) данная функция прерывает исполнение (вызывает error).

N=Far.DisableHistory([State])

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

Необязательный параметр State (набор битовых флагов):

0x1
история командной строки
0x2
история папок
0x4
история редактора/вьюера
0x8
история диалогов

Если соответствующий флаг выставлен, то история блокируется.

Если параметр не указан, то просто возвращает текущую маску.

Функция возвращает предыдущее значение.

Примечания:

При старте макроса разрешено добавление во все истории.

Блокировка истории действует только на текущий макрос.

Примеры

Far.DisableHistory()
получить текущее состояние блокировок историй
Far.DisableHistory(-1)
выключить все истории
Far.DisableHistory(5)
выключить истории командной строки и редактора/вьюера, остальные включить
...=mf.acall(func,...)

Данная функция вызывает “асинхронно” функцию func, передавая ей все последующие аргументы.

Параметры:

func
function
...
0 или более Lua-величин

Возвращает:

...
0 или более Lua-величин

mf.acall является как бы специализацией Plugin.Call для плагина LuaMacro, но, в отличие от Plugin.Call, она позволяет выполнять код в контексте вызывающей функции, а также передавать и возвращать любые Lua-величины.

Как и Plugin.Call, mf.acall является “асинхронной”: при выводе функцией func диалога или меню на экран, mf.acall сразу завершает работу и возвращает true.

Если функция func не выводит диалог или меню на экран, то имеет место “синхронный” режим работы: в этом случае mf.acall возвращает все величины, возвращённые функцией func.

См. также:

Ограничения в использовании некоторых функций

V=mf.akey(Mode[,Type])

Возвращает название или код клавиши, вызвавшей макропоследовательность.

Mode: 0 — возвращается код клавиши, 1 — возвращается наименование клавиши.

Type: 0 — возвращает реально нажатое сочетание, которым вызывался макрос, 1 — возвращает клавишу, на которую назначен макрос.

Пример см. в разделе Примеры.

Примечания:

  • В настоящий момент практическую ценность представляет только вызов mf.akey(1,1).
  • mf.akey не предназначена для использования в функции condition макроса (возвращает false). Вместо неё следует использовать аргумент функции condition: AKey (см. [macroapi manual]).
E=mf.eval(S[,Mode[,Lang]])

Выполнить или проверить макропоследовательность.

Mode:

0

Выполнить макропоследовательность, заданную строкой S.

Если S содержит синтаксические ошибки, то макропоследовательность исполняться не будет.

Far Manager компилирует последовательность S. Если нет ошибок, то состояние текущего макроса сохраняется и начинает выполняться последовательность S. После исполнения S прерванный макрос продолжает работать.

1
Проверить макропоследовательность, заданную строкой S, и вернуть код ошибки компиляции. Последовательность S исполняться не будет.
2

Выполнить макрос, назначенный на сочетание клавиш S.

Параметр S задаётся форматом “[Area/]Key”. Здесь Area — макрообласть, из которой будет исполнен макрос; / — разделитель; Key — название клавиши.

  • Если “Area/” указан, то будет вызван макрос, назначенный на Key только в указанной области Area.

    Пример: mf.eval("Shell/CtrlP",2)

  • Если в качестве “Area/” указана строка “./”, то будет вызван макрос, назначенный на Key только в текущей области.

    Пример: mf.eval("./CtrlP",2)

  • Если “Area/” не указан, то будет вызван макрос, назначенный на Key в текущей области. Если в текущей области Key не обнаружен, то будет выполнен макрос, назначенный на Key из области Common.

    Пример: eval("CtrlP",2)

Если Key не обнаружен, то функция вернёт целочисленное значение -2.

Если Key обнаружен, то состояние текущего макроса сохраняется и начинает выполняться макрос, назначенный на сочетание клавиш S. После исполнения S прерванный макрос продолжает работать.

3

Проверить макропоследовательность, заданную строкой S, и вернуть строку-сообщение с ошибкой компиляции.

Последовательность S исполняться не будет.

Строка будет пустой, если ошибок нет, или содержать сообщение, полученное от интерпретатора Lua.

Для Mode: 0, 1, 3:

  • Lang: указывает язык кода параметра S (для Mode: 0, 1, 3)

    Допустимые значения: “lua” и “moonscript”.

    Значение по умолчанию — “lua”.

  • Параметр S может обозначать скрипт-файл, если этот параметр начинается с символа ‘@’.

    В этом случае параметр S должен иметь следующий формат:

    @<имя файла-скрипта> [<параметры скрипта>]
    • В имени файла допустимо использование переменных окружения.
    • Опциональные параметры скрипта представляют список выражений, разделённых запятыми.
    • Выражения должны использовать тот же язык программирования, что и файл-скрипт.

    Пример:

    mf.eval("@%MyFarScripts%\\calc.moon 'factorial', 3+5", 0, "moonscript")

Для всех режимов, кроме Mode=3, функция возвращает следующие значения:

0
Успешная компиляции/запуск последовательности
-1
Указаны недопустимые параметры функции
-2
Для Mode=2 сочетание клавиш S не найдено или макрос заблокирован
11
Ошибка синтаксиса

Для Mode=2 дополнительно может возвращаться следующее:

  • 0 (нормальный возврат): дополняется значениями, возвращаемыми “запускаемым” макросом.
  • -3 : если было выведено меню выбора макроса, и пользователь его отменил.
  • -4 : если “запускаемый” макрос был прерван в результате ошибки времени исполнения.

Примечания:

При выполнении макропоследовательности для неё будет установлено окружение текущего исполняемого макроса, но не локальные переменные.

Режимы 0, 1, 3 существуют из соображений обратной совместимости, вместо них рациональнее использовать штатные функции языка (loadstring/loadfile/dofile/mooonscript.loadstring/etc).

mf.exit()

Завершить работу макроса.

Параметры: нет

Возвращает: ничего

См. также:

Ограничения в использовании некоторых функций

N=mf.mmode(Action[,Value])

Управление параметрами текущего макроса.

Параметр Action:

1
позволяет изменять режим перерисовки экрана во время проигрывания макропоследовательности (запрещает вывод)
2

вернуть информацию (область и флаги) об условиях запуска исполняемой в данный момент макропоследовательности. Параметр Value игнорируется.

Функция возвращает в младшем байте номер макрообласти, из которой стартовал макрос:

1
Shell — Файловые панели
2
Viewer — Внутренняя программа просмотра
3
Editor — Редактор
4
Dialog — Диалоги
5
Search — Быстрый поиск в панелях
6
Disks — Меню выбора дисков
7
MainMenu — Основное меню
8
Menu — Прочие меню
9
Help — Система помощи
10
Info — Информационная панель
11
QView — Панель быстрого просмотра
12
Tree — Панель дерева папок
13
FindFolder — Поиск папок
14
UserMenu — Меню пользователя
15
ShellAutoCompletion — список автодополнения в панелях
16
DialogAutoCompletion — список автодополнения в диалогах
17
Grabber — Режим копирования текста с экрана
18
Desktop — Пользовательский экран (под панелями)
255
Common — Общая область
0
Other — Зарезервировано

Остальные значения — флаги условий запуска (в т.ч. некоторые служебные флаги).

Условия запуска:

0x00000200
НЕ передавать плагинам клавиши во время записи/воспроизведения макроса
0x00000800
этот макрос запускается при старте ФАРа
0x00001000
запускать, если командная линия пуста
0x00002000
запускать, если командная линия не пуста
0x00004000
запускать, если есть выделение в редакторе
0x00008000
запускать, если есть нет выделения в редакторе
0x00010000
панель активная: запускать, если есть выделение
0x00020000
панель пассивная: запускать, если есть выделение
0x00040000
панель активная: запускать, если есть нет выделения
0x00080000
панель пассивная: запускать, если есть нет выделения
0x00100000
панель активная: запускать, если это плагиновая панель
0x00200000
панель пассивная: запускать, если это плагиновая панель
0x00400000
панель активная: запускать, если это файловая панель
0x00800000
панель пассивная: запускать, если это файловая панель
0x01000000
панель активная: запускать, если текущий объект “файл”
0x02000000
панель пассивная: запускать, если текущий объект “файл”
0x04000000
панель активная: запускать, если текущий объект “папка”
0x08000000
панель пассивная: запускать, если текущий объект “папка”

Дополнительная информация:

0x00000100
подавить обновление экрана во время выполнения макроса
0x40000000
этот макрос необходимо запомнить при сохранении макросов

Параметр Value:

-1
получить текущее значение
0
выключить значение Action
1
включить значение Action
2
переключить значение Action (триггер)

Функция возвращает предыдущее значение.

Примечание:

mf.mmode не предназначена для использования в функции condition макроса (возвращает false).

result=mf.postmacro(func,...)

Функция помещает новый макрос в очередь для исполнения. При исполнении макроса будет вызвана функция func, которой будут переданы аргументы ...

Параметры:

func
function
…
0 или более Lua-величин

Возвращает:

result
boolean
E=mf.sleep(N)
Организация задержки в макросе на N миллисекунд. Отрицательное значение задержки считается ошибкой и функция возвращает 0.

Интроспекция

macro=mf.GetMacroCopy(index)

Функция mf.GetMacroCopy возвращает копию таблицы загруженного макроса или обработчика события по его индексу во внутреннем массиве (начиная от 1). Если индекс превышает размер массива, возвращается nil — таким образом можно определить конец массива.

Параметры:

index
integer

Возвращает:

macro
table или nil

Примечания:

  • Неактивные (выгруженные или удалённые) элементы имеют поле “disabled” ≡ true.
  • Отличить таблицу макроса от таблицы события можно по полю “area” типа string, которое присутствует только у макросов.

Содержимое глобальных таблиц API макроязыка можно просмотреть с помощью функции pairs, отдельно для функций и “свойств” таблицы.

На примере таблицы Editor:

for k,v in pairs(Editor) do .... end -- для функций

for k,v in pairs(Editor.properties) do .... end -- для свойств

Разное

N=Far.KeyBar_Show([Mode])

Позволяет управлять видимостью линейки функциональных клавиш.

Необязательный параметр Mode:

0
получить состояние видимости
1
показать линейку
2
скрыть линейку
3
изменить состояние видимости на обратное

Функция возвращает предыдущее состояние видимости линейки:

0
скрыта
1
показана
-1
в этой макрообласти линейка клавиш не найдена

Действие функции актуально только для текущих панелей, редакторов, вьюеров.

Например:

Macro {
  description="при погашенных панелях гасить и кейбар";
  area="Shell QView Info Tree"; key="Esc";
  flags="EmptyCommandLine";
  action=function()
    Keys("CtrlO")
    Far.KeyBar_Show(not APanel.Visible and 2 or 1)
  end;
}

Смотрите также:

Примеры

[LuaFAR manual]: [macroapi manual]: