FAR Manager. Macros and whatnot.

Here you can discuss any topic concerning Far macro commands.
Post Reply
Acerbic
Posts: 80
Joined: Wed 07 Apr, 2010 12:30
Been thanked: 1 time

FAR Manager. Macros and whatnot.

Post by Acerbic » Tue 23 Apr, 2013 22:53

Revision 1.1
Gather round, boys and girls, for I am about to tell you a story.

Macro in your FAR Manager? It's more likely than you think.
The "macro" term is used loosely in Far to describe a broad range of user-made modifications of the application's behavior. For the sake of simplicity, let me divide them into several use cases:

1. Assigning hotkeys / remapping key bindings.
This is the simplest. You want one custom key (or combination with Ctrl, Shift, Alt modifiers) do what another key (combination) already does. It is one for one replacement.

2. Your typical macro. Press one key to emulate a sequence of many keys.
Its not much different from just a hot key. You press a key - it is treated as if you pressed some fixed predefined string of keys.

3. Script.
Now this is interesting. Script involves logic and decision making, not just some fixed reaction. A script has means to analyze current situation and affect Far Manager in non-trivial ways. Requires programming skills to create, but luckily the are many scripts already written and you may find one just fitting your needs.

4. Plugin.
Well, this is a moot point. With the course Far development is following now the gap between a complex script and a full fledged plugin is closing rapidly. As of right now, a script has most of functional capabilities a plugin has, it has access to both macro API and plugin API, in the latest builds a macro script can be started by an event, not just by a key pressed and so forth...

History and identification of obsolete.
FAR Manager has traveled a long way from its early versions and so did its macro capabilities. In Far1 and Far2 the configuration was stored in Windows registry, including macros. In Far3 configuration was moved to SQLite database files located in user's profile folder. But later it was decided that it would be better to allow users simpler access to macros and they were moved from a database to individual files (still inside user's profile folder). Also, parallel to moving macro definitions to external files, the macro language was changed to LUA.

In addition to that, there is a very popular plugin called "MacroLib". It provides extended macro features on top of built-in system. It used to overlay old macro language, but then switched to LUA as well. It always stored macros in external files.

So, what to look out for to spot outdated manuals / macro recipes?

1) *.reg files. Partial and full configurations were distributed as reg import files in times of Far1 and Far2. That included macros. No *.reg files are used by Far3 plugins or Far3 itself, but some old (ANSI) Far1 plugins can still use them. Any macros contained in them won't work in Far3.

2) *.farconfig files. Those are XML text files containing configurations for Far3. They are still used for other parts of configuration (coloring schemes and such) but not for macros anymore.

3) Old macro language. It contained keywords like "$IF" "$ELSE" - denoted by dollar sign.

4) Old MacroLib files *.fml - new MacroLib macro files use "fmlua" extension.

It is important to note that internal help in Far (called by "F1") is massively lagging behind development - hence this article.

What now?
At present, by means of storage macros fall in three groups.

1) Files of the built-in macro system. *.lua
Located in %FARPROFILE%/Macros/internal and %FARPROFILE%/Macros/scripts

2) MacroLib files *.fmlua.
By default are located within plugin's folder, but it can be configured to read macros from any user defined path (or several).

3) Other macro processing plugins. "Lua4Editor", for example. I don't know much about these, you are on your own here, folks.

Important warning! There are plugins written in LUA. These are something different from macros. They are legit plugins with all the things a "usual" plugin has (like being listed in plugins' menu "F11"). Except they are written in LUA and distributed as source files. They should not confuse you as they lie in their folders in %FARHOME%/Plugins

Conversion.
It is best to rewrite your macros in LUA from scratch. If they are few and simple, it won't take much effort. If they are complex, conversion is likely to fail to do it automatically. But if you are still interested in doing things hard way, there are few tools to help you. They were meant as quick fixes for transition period and aren't supported anymore, probably.

I. Far1, Far2 -> Far 3 2x3 perl converter
This tool is used to convert old configuration from registry to database. This includes macros.
The result will be a bunch of XML files containing far configurations and macros in the old language.

II. Translation from old language to the new one is done by Macro2Lua Converter plugin. The readme is in Russian, but here is an excerpt regarding main usage via command line
>M2L: convert <input file> <output file> [<syntax>]
where <syntax> is optional input format specifier and is one of following:
xml_file, xml_macros, xml_keymacros, xml_macro, fml_file, fml_macro, chunk, expression. General file format is the part before underscore, the specific section of a file is the part after underscore. "chunk" and "expression" are some kind of raw macro pieces of texts.
The result should be a XML file (<farconfig>...</farconfig>) with macros translated to LUA inside of it or a MacroLib fmlua file if original was *.fml and corresponding syntax was specified.

III. Far3 2927-3000 -> Far3 3001+
Now you need an older version of Far3 (pre3001). You import your macros to Far per usual command, then use a script provided in the following forum thread:
Macros have been moved from macros.db to files

Managing confusion.
While all macros are written in LUA, file contents are not interchangeable as of right now. It means that you can't rename X.fmlua to X.lua, move it to %FARPROFILE%/Macros/scripts and expect it to work. Likewise you can't just move files from /internal to /scripts.

Luckily, with few rules I am about to explain, you won't get lost in all of the LUA files lying around.

1) Don't touch your internals!
Files in %FARPROFILE%/Macros/internal are to be manipulated (created/edited/deleted) by FAR Manager itself. And while it is possible to edit them manually, better to leave them alone. Unless you really know what are you doing. Or just feeling adventurous.

2) MacroLib files are always named *.fmlua, so you can never confuse them with native script files, even if you configured the MacroLib so they are located in the same directory.

3) User-made native script files are located in %FARPROFILE%/Macros/scripts and are named *.lua. They are read at Far launch, but you can make Far to re-read the folder via command line (more on that later).

So, only (2) and (3) are in user's management and they are different in names, location and internal structure.

But there are similarities too.
1) Both MacroLib and native macros have a concept of "Area of execution" - basically, a broad condition limiting macro effect. Typical are "Editor" - when editor is open, "Shell" - when file panels are in focus, etc...

2) In addition to general area, some more conditions might be specified for activation of a macro. Like passive panel being visible, command line not being empty and similar. These conditions/flags are legacy carried over from times when macro language was primitive and things like that were hard to check in script itself. Alternatives are being developed (like custom function conditionals in native scripts) but there is no sign that old flags will be abandoned yet.

3) And finally, there are two flags that control execution of the macro itself. One is to disable/enable intermediate visual output during macro execution (reduces flicker of menus and dialogs being open/closed, for example), another is to control if plugins can intercept keyboard events generated by macro. No other macro can intercept current macro while it is executing - so you don't have to worry about nasty macro interferences.

Out of the box.
In the beginning of time the macro language was ugly and everyone was sad. And few of the developers raised their voices: "Look! There in the great outside lies shiny LUA. Let us take it for ourselves, let us bind it to our manager and then we won't be suffering dollar-signed keywords no more." And so they did. And night turned day, and day turned night, and the Moon died and was born again as they tinkered and meddled and compiled and debugged. Seasons passed by, but finally, the day has come and their labor was over.
And they stood proud among men and shouted: "Behold this LuaMacro plugin! We can rework our ugly macros into LUA, we have the technology now. But wait! There's more: we can write plugins in LUA as well, if we desire so." And everyone rejoiced.
And gathered developers of Far and saw what their brethren did, and saw that it was good. So good in fact, they put the new plugin in the core package and abandoned their old ways of macros.

So, native macro capabilities are provided by LuaMacro plugin, which is distributed with Far itself as part of its core package. The plugin has no configuration dialog, but has a list of commands to manipulate it:
  • lm: unload - Far forgets all macros. They are still on disk and can be loaded back with next command.
  • lm: load - makes Far discard all macros and then re-read them from directories anew.
  • lm: post <sequence>|@<filename> - executes a macro code immediately. Either a "raw" piece of code typed in command line, or same raw code saved in a file. File name is prefixed with "@" symbol.
  • lm: check <sequence>|@<filename> - same as above. Except the macro is not executed but checked for syntax errors.
  • lm: save - saves changes made to "internal" macro files. Useful if you have "Auto save setup" option turned off.
When "load" and "unload" operations are concerned, only native macros are affected. I.e. those *.lua that are located in /internal/ and /scripts/ . MacroLib macros are not touched. List of all currently loaded native macros is available in Far built-in help "F1". That part of help is not translated to English yet, and its not very convenient in operation anyway. Check this macro out though.

Note. "lm:" commands are similar to ones provided by FarCommands plugin via "macro:" and "far:macro " prefixes. There was a difference in that FarCommands used "<" symbol to specify filename, but now it supports both "<" and "@" for this.

It is time now to explain why some macros are put in /internal/ and others in /scripts/. Its fairly simple - "internal" is a codename for "recorded" and all the recoded macros go there. More on recorded macros is in the "Hotkeys / Macro use case" chapter.
User-made macros are to be placed in /scripts/. Sadly, there's no comprehensible manual on how to write them. One is reduced to scavenging for bits and pieces of knowledge by perusing Far's changelog and dissecting macros written by others (SimSU macro pack for example, topic in Russian forum: viewtopic.php?f=15&t=7075). Here is a script for the Editor that pastes a macro template on "Ctrl+F11" by Shmuel: InsertMacro.lua.7z

MacroLib.
This is what all the cool kids use. MacroLib is a plugin that provides somewhat extended functionality to macros. It is built on top of native macro system, so 99% of the code working for "regular" macro will work for MacroLib as well.
Project's main page: http://code.google.com/p/far-plugins/wiki/MacroLib, download page: http://code.google.com/p/far-plugins/do ... q=MacroLib, documentation (Russian): http://code.google.com/p/far-plugins/wiki/FML.
MacroLib files are named *.fmlua and are located in one or several directories designated by user in configuration dialog. The dialog allows you to update macros from disk and shows you a very neat list of all macros currently loaded with ability to sort, filter, run a macro from the list.

MacroLib used to have many advantages over built-in system, but nowadays Far has caught up for the most part and is ahead in some experimental things (like events). However, there are two things *.fmlua scripts have over *.lua ones.
1) You can use modifiers to your assigned hotkeys, such as "Hold" (macro is invoked after the key was held for a certain period of time), "Double"(on double click or double key tap), "Release" (macro is called on key being released, rather than being pressed).
2) You frame your macro code in double curly brackets for extra swag {{ }}.

Hotkey / Macro use case.
Can't get used to saving edited file by "F2"? Too lazy to run through menus every time you want to view your current Folder Shortcuts? Then this chapter is for YOU. This chapter covers a very simple usage of Far macros - redefining hotkeys for existing actions and creating hotkeys for actions that don't have them by default.
The easiest way to do said things is by using "Recorded Macro" feature. The Far Manager has an ability to record your actions (keyboard events) and assign them to a specific key, pressing which will replay your actions. This function is in there from Far1 and is explained in "F1" Help, but I will rehash it for you anyway.
You start recording by pressing "Ctrl+." (Control key plus dot key) or "CtrlShift+.", a little red "R" letter appears in the top-left corner and your following key presses will be recorded. You continue to use Far as usual, doing things you want to be put in the macro, or just pressing one key you want to be remapped. Then you finish recording by pressing "Ctrl+." or "CtrlShift+." again. Then you will be asked for a key to which this macro will be assigned, you can select one from a drop-down list with a mouse or just press the desired combination, then "Enter". At this moment an optional dialog might appear to configure additional parameters of you macro.

So,
1. "Ctrl+." or "CtrlShift+."
2. Do stuff on record.
3. "Ctrl+." or "CtrlShift+."
4. Select a desired key to assign to.
5. (optional) Configuration dialog.

If you finish recording with "CtrlShift+." on step 3 you will be shown a dialog on step 5. Otherwise you won't be. To know more about this dialog, press "F1" while in there, its covered in the Help.
Starting the recording with "CtrlShift+." puts a "NoSendKeysToPlugins" flag on your macro, which means that during macro playback plugins won't be able to react to keyboard events generated by this macro - it forces plugins to ignore this macro in that regard.

If you made a mistake in your macro during recording you may interrupt the recording by usual "Ctrl+." and then hit "Esc" when asked about desired key.
If you select a key that is already taken by a macro, you will be asked if you want to overwrite previous macro. This means you cannot have two recorded macros on the same key in the same area of execution. You can, however, have one for each area (one in Editor, one in Viewer, etc.)
If you need to delete a macro you previously recorded, you create an empty macro for the key you want to free: "Ctrl+.", "Ctrl+.", the key. Then select "yes" to confirm deletion.

If you have "F9"->"Options"->"System Settings"->"Auto save setup" option turned on, then every change to your recorded macros (creation, modification, deletion) will be immediately saved to files. Otherwise you can use lm: save command to save your recorded macros or press "Shift+F9" to save full setup.
If you want to know what macros are already recorded, you can navigate to %FARPROFILE%/Macros/internal. It is possible delete macros in there, just don't forget to use lm: load command to update, or restart Far.

Example: lets bind a hotkey to "File associations" menu.
0. (preparation) Make sure you are in the Shell area of Far, its where two panels with files and folders are.
1. Press "Ctrl+." and make sure the red "R" letter appeared.
2. Press "F9" to move input focus to Far's menu (usually is the top line of the window), then "c" for commands, then "a". Now, if done right the "File associations" menu is on screen.
3. Press "Ctrl+."again, a little "Define macro" box should pop up. Press "Ctrl+Shift+a" and confirm that corresponding key code appeared in the box ("CtrlShiftA").
4. Press "Enter" and enjoy a new quality of life improvement you just created for yourself. Now every time you press "Ctrl+Shift+a" combo in Far shell, the menu will instantly appear.

Script use case.
"Script" is a program that runs within/by other program (as opposed to one run by CPU/OS). Scripts in Far evolved from macros to a point when macros themselves are considered primitive cases of scripting. Being programs, scripts require "Programming / Coding" skill to be created, therefore, if you intend to use Far to its fullest potential you might want to invest few skill points in it on your next level up. Alternatively, you can utilize macros written by someone else - just copy the files in appropriate folders.
As mentioned before, Far uses LUA language for scripting. From within the script you have access to
1) Far (plugin) API - functions of Far that are available to plugins.
2) Far macro API - some specific functions that were available in old language. These overlap "Plugin API" to some extend and considered legacy API. Better use "Plugin API" where possible.
3) Custom functions exported by plugins - some plugins export their functions to be called from macro. Those depend on plugin being installed and loaded, of course.
4) LUA libraries - native to LUA (see language manual) plus few libraries additionally shipped with LuaFar ("bit64", "win" - gate to Win API, Selene Unicode)
5) Far UI - you can control Far simply by issuing keyboard/mouse commands to it. Why bother finding a function that will open Editor for file under cursor when you can just send "F4" to Far?

Your main source of information about Far APIs is in %FARHOME%\Encyclopedia files. Lets look at them.
  • "FarEncyclopedia.ru.chm" - includes (1) and (2), in Russian. Macro API is outdated (pre-LUA). There's an online version too: http://api.farmanager.com/ru/
  • "luafar_manual.chm" - originally a LuaFar plugin manual (writing plugins in LUA), but we can use it in scripts too. Covers (1) in LUA in English. Very spartan - most of the functions have no textual descriptions, only input parameters and result values (implies ability to read "FarEncyclopedia.ru.chm"). For the most part it is not a problem though, functions' names are self-descriptive.
  • "macroapi_manual.chm" - mapping of (2) to LUA. Again, almost no descriptions.
Damn, its kinda depressing, ain't it? Luckily for you, I have a magical artifact that will allow you to understand Russian: abracadabra. Paste a link to Russian website or text fragment and hit "Enter".
And Acerbic saves the day once again! You are welcome.

To sum it up: you will use "luafar_manual.chm" in conjunction with translated online encyclopedia for Far plugin API reference and "macroapi_manual.chm" in conjunction with this link for Macro API reference.
I found this script very helpful: lua_explorer. It allows you to browse Lua tables/values/functions soup available to LUA script. Thread on the forum.

Native or MacroLib?
MacroLib.

Sample script.
Here's a little demonstration of what you can do in MacroLib: "RCtrl Folder shortcuts.fmlua"


User avatar
t-rex
Страшный и ужасный
Posts: 4871
Joined: Tue 15 Mar, 2005 16:17
Location: Tel-Aviv
Contact:

Re: FAR Manager. Macros and whatnot.

Post by t-rex » Tue 23 Apr, 2013 23:08

Nice job!

Shmuel
Posts: 5164
Joined: Thu 23 Mar, 2006 21:36
Location: Israel
Has thanked: 15 times
Been thanked: 145 times

Re: FAR Manager. Macros and whatnot.

Post by Shmuel » Wed 24 Apr, 2013 08:19

Acerbic
Excellent work! Thank you for sharing it!
If you don't mind, I'd ask your permission to reproduce it in macroapi_manual.chm. Please contact me privately if you prefer.
lm: save - I don't have a clue.
It is related to manually recorded macros ("keyboard macros") that are kept in Macros\internal directory. They can be created, modified or deleted via Ctrl<.> If you want to make those changes permanent, you either do lm:save (saves only recorded macros) or ShiftF9 (saves the whole configuration).

User avatar
HaRT
Moderator
Posts: 8048
Joined: Tue 30 Aug, 2005 17:21
Location: Санкт-Петербург
Has thanked: 67 times
Been thanked: 100 times

Re: FAR Manager. Macros and whatnot.

Post by HaRT » Wed 24 Apr, 2013 08:56

Acerbic
Good job!
Here are a few points I'd like to note:
0. First and foremost, as this text is likely to evolve and probably to be reposted, it would be great to have it revision-controlled (or at least assigned an explicit revision number). That would allow for much easier update tracking.
1. When you talk of files being located in user profile, a notice would be useful that (a) it's not necessarily the same as Windows user profile and (b) it can be configured in far.exe.ini.
2. REG files are still used in FAR3 for FAR1 plugins which are supported out of the box.
3. > I'm not sure if this flag is operational though, as I was not able to confirm it with tests.
The easiest way to check is to have a plugin in the Editor that intercepts keypresses — e.g. [ESC] catches Home for many source code file types. Without the flag in question, the macro will work exactly as if the keys are being pressed by a user; with the flag, the Home key being sent will work as if no plugin handles it.
4. A couple of typos: “%FARPROFILE%/Macros/scriptsand” — missing whitespace; “functions of Far that are available to plugins” — missing ‘s’.

Once again, thank you for composing this guide!
Фар есть инструмент, а не нянька. © 2009 DrKnS

Acerbic
Posts: 80
Joined: Wed 07 Apr, 2010 12:30
Been thanked: 1 time

Re: FAR Manager. Macros and whatnot.

Post by Acerbic » Wed 24 Apr, 2013 17:11

Thanks to everyone for feedback.

@ Shmuel, HaRt
Valid points. I updated the text according to your suggestions, except I decided to keep profile management off it. Its only tangentially related and the post is big as it is. Anyhow, as long as %FARPROFILE% variable is used to locate it, an exact placement is not too relevant.

pepak
Posts: 328
Joined: Sun 13 Jul, 2008 11:18
Has thanked: 3 times
Been thanked: 9 times

Re: FAR Manager. Macros and whatnot.

Post by pepak » Sat 27 Apr, 2013 12:59

Excellent. Far Macros are one of the areas that I barely touched in the fifteen years I am using FAR, so this is very useful. If there ever is a follow-up, even better - I am very interested in designing my own macros.

Acerbic
Posts: 80
Joined: Wed 07 Apr, 2010 12:30
Been thanked: 1 time

Re: FAR Manager. Macros and whatnot.

Post by Acerbic » Mon 29 Apr, 2013 02:13

What kind of follow-up would you be interested in? The idea behind this thread was to give 101 intro into what macros are and what can they do for you. I will try to update it if any major change is to happen with Far macro system. The only feature it is lacking is coverage of event-triggered macros, mostly because I myself am at a loss in that area.

pepak
Posts: 328
Joined: Sun 13 Jul, 2008 11:18
Has thanked: 3 times
Been thanked: 9 times

Re: FAR Manager. Macros and whatnot.

Post by pepak » Mon 29 Apr, 2013 05:12

A 101 in "How to create your own LUA macros" :-)

User avatar
John Doe
Бюрократ
Posts: 11127
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 12 times
Been thanked: 72 times

Re: FAR Manager. Macros and whatnot.

Post by John Doe » Tue 29 Apr, 2014 09:10

Acerbic wrote:Native or MacroLib?
MacroLib.
I agree that long time ago MacroLib had a lot of advantages over standard macros.
And even now MacroLib keep some advantages: there are more ways to bind macros: hold key, release key, single/doubleclick.
But that's almost all.

And there is one disadvantage of MacroLib: macrofile may contain many macros, but each macro has it's own state: local variables are not shared between macros.
If you think that it's not a big deal then you are wrong: it is very important.

Sure, MacroLib has some ways to overcome this limitation.
- "macrosubstitutions" allow to define functions that is shared between macros (or other functions).
- to share variables between macros AND to keep their state between launches you can use global variables, prefixed with "_G."
It looks weird and inconvenient for me, and may lead to unobvious errors: you may define completely unrelated vars in different macrofiles, but if their names are the same - you are in trouble.

Author is aware of mentioned limitations, and technically it's not too hard to fix them all.
But I doubt that it will happen.

User avatar
John Doe
Бюрократ
Posts: 11127
Joined: Wed 27 Apr, 2005 20:42
Has thanked: 12 times
Been thanked: 72 times

Re: FAR Manager. Macros and whatnot.

Post by John Doe » Tue 29 Apr, 2014 09:32

acerbic
In your article there are some files directly linked.
It's better to link to corresponding forum topics instead, to let your readers to follow updates.
Acerbic wrote:Sadly, there's no comprehensible manual on how to write them. One is reduced to scavenging for bits and pieces of knowledge by perusing Far's changelog and dissecting macros written by others (SimSU macro pack for example
It's bad idea to advice SimSU macros for dissection, because every one of them contains much "overhead" (I mean that non trivial techniques to interoperate with other macros, to load user settings, etc).

BTW, may be it's time to update the article itself, e.g. there are important changes in LuaMacro and manuals:
- English version of macroapi_manual.en.chm (there are now links to Encyclopedia describing all old function, still in Russian)
- lm:post prefix is gone, you should use lua: instead

Post Reply

Return to “Macro Commands Discussions”