Functions - Macros

Far Manager

previous page next page

Functions

Function list

You can use the following functions in the macro sequence:

Mathematical functions

Function Description

N=abs(N) Returns the absolute value of a numeric argument N.

N=max(N1,N2) Returns the maximal value of two numeric arguments N1 and N2.

N=min(N1,N2) Returns the minimal value of two numeric arguments N1 and N2.

N=mod(N1,N2) Division of N1 by the modulus N2.

N=int(V) Evaluates the V argument to a number.

String functions

Function Description

N=index(S1,S2) Returns the position of the first occurrence of the substring S2 within string S1, -1 otherwise.

N=rindex(S1,S2) Returns the position of the last occurrence of the substring S2 within string S1, -1 otherwise.

Result=replace(Str,Find,Replace[,Cnt]) Replace substing Find in Str with Replace, Cnt times (set Cnt to 0 or omit this parameter to replace all occurrences).
Returns the resulting string.

N=asc(S) Returns the code of character S.

S=chr(N) Returns the character for the code N.

S=itoa(N[,Radix]) Converts numeric value N to a string. Radix parameter defines the radix of the numerical representation for the number conversion. The valid Radix values are from 2 to 36. If Radix is omitted, base 10 is implied.

N=atoi(S[,Radix]) Converts string representation of a number N into a number. Radix parameter defines a radix to use during conversion of a string S. The valid Radix values are from 2 to 36.
If Radix is omitted, function tries to determine the correct value automatically.

N=len(V) Returns the length of the expression V. This function evaluates the value of V to a string and then returns the length of the string.

S=string(V) Converts the value of the expression V to a string.

S=substr(V,N1[,N2]) Returns the substring of the expression V beginning from position N1 with the length of N2.
If N2 parameter is omitted or equal to -1, function returns the substring from position N1 to the end of the string.
If N2 parameter is equal to 0, function returns empty string.

S=trim(V[,N]) Removes whitespace (spaces, tabs, line feeds, and carriage returns) from a string V: leading and trailing (N=0 or omitted), only leading (N=1), or only trailing (N=2).

S=lcase(S) Transforms the string S to lower-case.

S=ucase(S) Transforms the string S to upper-case.

S=date(format) Returns the current date/time according to the format format (See the $Date for the format description).
This function is similar to $Date macro-command but can also be used in expressions. The format argument is mandatory.

S=xlat(S) Returns the transliterated string.
This function is similar to $XLat macro command but can be used in expressions. Argument S is mandatory.

File functions

Function Description

S=fsplit(path,N)

Splits the path path into the components and returns theirs combination depending on the flag combination N:

Value	Description
0x00000001	Current drive in "C:" representation. For network shares - "\\server\share"
0x00000002	Rooted path in "\Program Files\Far\" representation
0x00000004	Name
0x00000008	Extension in ".EXT" representation or empty string, if there's no extension.

N=fexist(S) Checks if the file or folder S exists and returns 1 if true or 0 otherwise.
Usage of the '*' and '?' mask symbols is allowed in the S argument. In that case the function checks only the first occurrence of the file or folder.
This function does not work with the panels.

N=fattr(S)

Returns the file system attributes of the file or folder S

Attribute	Description
0x00000001	FILE_ATTRIBUTE_READONLY. The file or folder is read-only. Applications can read the file but cannot write to it or delete it. In the case of a folder, applications cannot delete it.
0x00000002	FILE_ATTRIBUTE_HIDDEN. The file or folder is hidden. It is not included in an ordinary directory listing.
0x00000004	FILE_ATTRIBUTE_SYSTEM. The file or folder is part of the operating system or is used exclusively by the operating system.
0x00000010	FILE_ATTRIBUTE_DIRECTORY. This is a folder.
0x00000020	FILE_ATTRIBUTE_ARCHIVE. The file or folder is an archive file. Applications use this attribute to mark files for backup or removal.
0x00000080	FILE_ATTRIBUTE_NORMAL. The file or folder has no other attributes set. This attribute is valid only if used alone.
0x00000100	FILE_ATTRIBUTE_TEMPORARY. The file is being used for temporary storage. File systems avoid writing data back to mass storage if sufficient cache memory is available, because often the application deletes the temporary file shortly after the handle is closed. In that case, the system can entirely avoid writing the data. Otherwise, the data will be written after the handle is closed.
0x00000200	FILE_ATTRIBUTE_SPARSE_FILE. The file is a sparse file.
0x00000400	FILE_ATTRIBUTE_REPARSE_POINT. The file or folder has an associated reparse point.
0x00000800	FILE_ATTRIBUTE_COMPRESSED. The file or folder is compressed. For a file, this means that all of the data in the file is compressed. For a folder, this means that compression is the default for newly created files and subdirectories.
0x00001000	FILE_ATTRIBUTE_OFFLINE. The data of the file is not immediately available. This attribute indicates that the file data has been physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute.
0x00002000	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED. The file or directory is not be indexed by the content indexing service.
0x00004000	FILE_ATTRIBUTE_ENCRYPTED. The file or folder is encrypted. For a file, this means that all data in the file is encrypted. For a folder, this means that encryption is the default for newly created files and subdirectories.
0x00010000	FILE_ATTRIBUTE_VIRTUAL. A file is a virtual file.

if file system object does not exist this function returns -1.
Usage of the '*' and '?' mask symbols is allowed in the S argument. In that case the function checks only the first occurrence of the file or folder.
This function does not work with the panels.

Panel

Function Description

N=panel.fexist(panelType,S) Checks if the file or folder S exists in the active (panelType=0) or the passive (panelType=1) panel (returns 1 if true or 0 otherwise).
Usage of the '*' and '?' mask symbols is allowed in the S argument. In that case the function checks only the first occurrence of the file or folder.
This function works only with the panels.

N=panel.fattr(panelType,S)

Returns the file system attributes of the file or folder S from the active (panelType=0) or the passive (panelType=1) panel.

Attribute	Description
0x00000001	FILE_ATTRIBUTE_READONLY. The file or folder is read-only. Applications can read the file but cannot write to it or delete it. In the case of a folder, applications cannot delete it.
0x00000002	FILE_ATTRIBUTE_HIDDEN. The file or folder is hidden. It is not included in an ordinary directory listing.
0x00000004	FILE_ATTRIBUTE_SYSTEM. The file or folder is part of the operating system or is used exclusively by the operating system.
0x00000010	FILE_ATTRIBUTE_DIRECTORY. This is a folder.
0x00000020	FILE_ATTRIBUTE_ARCHIVE. The file or folder is an archive file. Applications use this attribute to mark files for backup or removal.
0x00000080	FILE_ATTRIBUTE_NORMAL. The file or folder has no other attributes set. This attribute is valid only if used alone.
0x00000100	FILE_ATTRIBUTE_TEMPORARY. The file is being used for temporary storage. File systems avoid writing data back to mass storage if sufficient cache memory is available, because often the application deletes the temporary file shortly after the handle is closed. In that case, the system can entirely avoid writing the data. Otherwise, the data will be written after the handle is closed.
0x00000200	FILE_ATTRIBUTE_SPARSE_FILE. The file is a sparse file.
0x00000400	FILE_ATTRIBUTE_REPARSE_POINT. The file or folder has an associated reparse point.
0x00000800	FILE_ATTRIBUTE_COMPRESSED. The file or folder is compressed. For a file, this means that all of the data in the file is compressed. For a folder, this means that compression is the default for newly created files and subdirectories.
0x00001000	FILE_ATTRIBUTE_OFFLINE. The data of the file is not immediately available. This attribute indicates that the file data has been physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute.
0x00002000	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED. The file or directory is not be indexed by the content indexing service.
0x00004000	FILE_ATTRIBUTE_ENCRYPTED. The file or folder is encrypted. For a file, this means that all data in the file is encrypted. For a folder, this means that encryption is the default for newly created files and subdirectories.
0x00010000	FILE_ATTRIBUTE_VIRTUAL. A file is a virtual file.

V=panelitem(panelType,itemIndex,propIndex)

Queries the information for the panel element itemIndex from the active (panelType=0) or passive (panelType=1) panel. propIndex can be one of the following values:

Value	Type	Description
0	String	File or folder name
1	String	File or folder short name
2	Number	File attributes
3	String	Creation date/time
4	String	Last access date/time
5	String	Last modification date/time
6	Number	Size
7	Number	Packed size
8	Number	"Is selected?"
9	Number	Number of the hardlinks
10	Number	SortGroup
11	String	Diz-text
12	String	Owner
13	Number	CRC32
14	Number	Position of the element while reading from the file system

Date/time is returned in the DD.MM.YYYY HH:MM:SS format. The values order and the delimiters are determined according to the regional settings. To receive information on the current file (under cursor) itemIndex should be set to 0.

N=panel.setpos(panelType,fileName)

Positions the cursor on the element with name fileName on the active (panelType=0) or passive (panelType=1) panel.
Returns the position of the element or 0 if there is no such element.
For example, the following macro creates a directory named after the current date in YYYYMMDD format or positions the cursor on this directory if it already exists.

%dt=date("%Y%m0%d");
$If (fexist(%dt))
  panel.SetPos(0,%dt)
$Else
  F7 $Text %dt Enter
$End

N=panel.setpath(panelType,pathName[,fileName])

In the active (panelType=0) or passive (panelType=1) panel changes folder to pathName and sets the cursor on the element with name fileName (if fileName parameter was specified).
Returns 1 if folder was changed successfully and 0 if folder does not exist.
For example, in the active panel change folder to "C:\WINDOWS", in the passive panel to "C:\Program Files", make left panel the active one and set cursor to "FAR" folder:

$if(APanel.Left) CtrlU $End
panel.SetPath(1,"C:\\WINDOWS")
panel.SetPath(0,"C:\\Program Files","FAR")

N=panel.setposidx(panelType,indexItem) Positions the cursor on the element with index indexItem on the active (panelType=0) or the passive (panelType=1) panel.
Returns element position or 0 if such element does not exist.

Control functions

Function Description

V=iif(Cond,True,False) Conditional function. If condition Cond is true then True-expression is returned, False-expression otherwise.

Execution environment

Function Description

V=akey(N) Returns the name or code of the key combination that was used to call this macro. N = 0 - key code is returned, N = 1 - key name is returned.
See example in the full description $AKey

S=env(V)

Returns the value of an environment variable V, for instance:

$if (Env("FARLANG") == "English") ...do something... $end

B=msave(S)

Stores the value of a global variable with the name S to the Vars area. Returns 0 in case of failure.
Example:

%%GlobalVars="Foo Bar"; %a=msave("%%GlobalVars");

V=clip(Cmd[,S])

Allows to perform miscellaneous manipulations on the Clipboard in accordance with the Cmd command:

Cmd	Description
0	Returns data from the Clipboard; the S parameter is ignored; in case of error returns 0
1	Put the string S to the Clipboard; in case of error returns 0
2	Add the string S to the Clipboard; in case of error returns 0
3	Copy the Windows Clipboard to the internal clipboard buffer; the S parameter is ignored; in case of error returns 0
4	Copy the internal clipboard buffer to the Windows Clipboard; the S parameter is ignored; in case of error returns 0

For example, put to the Clipboard a list of selected files in the CSV format (name and size):

Clip(1,"Name;Size\r\n")
Home
$While(!APanel.Eof)
  $If(!APanel.Folder && PanelItem(0,0,8))
     Clip(2,PanelItem(0,0,0)+";"+PanelItem(0,0,6)+"\r\n")
  $End
  Down
$End

See $IClip, IClip.

V=flock(Nkey,NState)

Toggles Lock keys state (NumLock, CapsLock, and ScrollLock).
Key Nkey:

Nkey	Description
0	NumLock
1	CapsLock
2	ScrollLock

State NState:

NState	Description
-1	get key state
0	toggle key to off
1	toggle key to on
2	toggle key to reverse state

In Windows 95/98/Me the function can change only CapsLock and ScrollLock states. Windows NT family (NT/2000/XP/...) has no such restriction.
The function is unstable (computer may freeze) and should be used carefully. For example, macro with CtrlCapsLock hot key (switching between windows) should be wrapped in certain way:

CtrlShiftTab
%a=flock(1,-1)&1;
$while((flock(1,-1)&1)==%a)
  sleep(50)
  flock(1,2)
$end

N=sleep(N) Pause macro execution for N milliseconds. Negative sleep time is considered to be an error and the function returns 0.

V=waitkey([N, [T]]) Waits until a key is pressed and returns its name (T=0) or value (T=1). When time to wait N (milliseconds) is up, function returns an empty string (T=0) or 0 (T=1). If N is omitted or is equal to 0, function will wait for key press infinitely.

S=key(V) Converts parameter V into the string equivalent of the key name.
If V is a string, its correctness is checked and returned back, if V is a number, it is converted into the string equivalent of the key name.
Function returns empty string in case of any errors.

N=eval(S[,T])

"Play back" (T=0) or check (T=1) macro sequence defined in the string S. If S contains syntax errors, the sequence will not be played.
FAR compiles sequence S.
For playback mode (T=0): if there are no errors, state of the current macro is preserved, and sequence Sbegins execution. After playing S, suspended macro continues its work.

If the sequence S compilation was successful, function returns 0, otherwise error code is returned:

Error	Description
1	Unrecognized keyword 'keyword'
2	Unrecognized function 'function'
3	Incorrect number of arguments for function 'function'
4	Unexpected $Else
5	Unexpected $End
6	Unexpected end of source string
7	Expected 'keyword'
8	Bad Hex Control Char
9	Bad Control Char
10	Variable Expected 'Variable'
11	Expression Expected
12	Zero-length macro

Local variables are common for both the current macro and the macro executed by eval.

For example, by pressing F10 we want to open an Explorer window with the current folder on the active panel, command line contents should be saved.
We set 2 string variables, in the Vars area, containing a macro sequence for saving and restoring the command line:

%%CmdSave=$If (!CmdLine.Empty) %Flg_Cmd=1;
          %CmdCurPos=CmdLine.ItemCount-CmdLine.CurPos+1;
          %CmdVal=CmdLine.Value; Esc $End

%%CmdRestore=$If (%Flg_Cmd==1) $Text %CmdVal
          %Flg_Cmd=0; %Num=%CmdCurPos;
          $While (%Num!=0) %Num=%Num-1; CtrlS $End $End

then we set the following macro to F10:

$If (APanel.Visible && (!APanel.Plugin || (!APanel.Bof &&(APanel.OPIFlags & 0x20))))
  Eval(%%CmdSave)
  $If (APanel.Current == "..")
    .
    ShiftEnter
  $Else
    "%SystemRoot%\\explorer.exe /select,"
    $If (Apanel.LFN)
      CtrlN
    $End
    CtrlEnter
    $If (!Apanel.LFN)
      CtrlN
    $End
    Enter
  $End
  Eval(%%CmdRestore)
$End

User interaction

Function Description

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

Shows up the message box with the Text and the Title. Lines in the Text argument should be delimited by '\n'.
Flags can be a combination of the following values:

Flags	Description
0x00000001	Use the 'Warning' color scheme (usually white text on red background).
0x00000008	Show the message lower by two lines.
0x00000010	Use the left alignment for the message strings (align to center of not specified).
0x00010000	Show the <Ok> button.
0x00020000	Show the <Ok> and <Cancel> buttons.
0x00030000	Show the <Abort>, <Retry> and <Ignore> buttons.
0x00040000	Show the <Yes> and <No> buttons.
0x00050000	Show the <Yes>, <No> and <Cancel> buttons.
0x00060000	Show the <Retry> and <Cancel> buttons.

If the Flags argument is 0 (or omitted) then standard message box is displayed with the <Ok> button.
The return value is the number of the button the user selected (1 for the first, 2 for the second, etc.), if user canceled the message the result will be 0.

S=prompt("Title"[,"Prompt"[,flags[, "Src"[, "History"]]]])

Function allows to enter one text string.
Parameters: Title - dialog caption, Prompt - prompt for input, Src - initial input string value, History - input history name
Flags can be the set of these values (similar to FIB_* constants):

Flag	Description
0x00000001	the function will return empty string if the input string is empty.
0x00000002	entered text is represented by `'*'` on the screen, used for passwords input
0x00000004	after a successful input, any environment variables within the input string will be replaced by their values in the resulting string S, e.g. if the user entered '`%TEMP%`', then S will contain '`C:\TEMP`'.
0x00000008	if Src is empty and History is not empty, then do not initialize the input line from the history.
0x00000010	display a separator and the [OK] and [Cancel] buttons below the input line. The dialog will grow by 2 lines.
0x00000020	the ampersand character will not be shown in the prompt string but can instead be used to define a hotkey.

Function returns a string entered by user.
For example, ask for password and show it:

%s=prompt("Password","Input password:",0x02); $Text %s

Control elements

Function Description

N=checkhotkey(S[,Pos])

Function checks and gets the position of the element (starting from Pos), which contains hot key S. If S is an empty string, then function will return the position of the element without hot keys.
Returns: -1 - if called from the wrong area (MainMenu, Menu, Disks, UserMenu, and Dialog), 0 - nothing was nound, > 0 - if menu/dialog/list contains hot key S.

For example, in the plugin menu (F11), hot key '7' is defined for S&R plugin. Macro sequence for the editor

F11 $if (checkhotkey("7")) 7 1 $else Esc AltF7 $end

will call the plugin if hot key is defined, or standard Search dialog, if hot key is not defined.

S=gethotkey(N) Returns the hot key S for item N, if the item has a hot key and the current "object" is a menu. Otherwise 0 is returned.
N - item position beginning with 1 (0 - current item).

N=Menu.Select(S[,N])

In the menu, places cursor to the first item that contains S substring. String is searched according to the mode N:

Mode	Description
0	string is S
1	string begins with S
2	string ends with S
3	string contains S

Search is case-insensitive. If item is not found, does nothing.
Returns: -1=Error - if called not from the menu, 0=Placement error (item is absent or disabled), otherwise returns menu item position.

F11 $if(Menu.Select("Advanced compare",0) > 0) Enter $end

If N parameter is omitted, full string coincidence is assumed.

V=Dlg.GetValue(ID,Type)

Get misc. values of the current dialog.
ID - dialog element number (elements are numbered starting with 1; 0 - is the dialog windows itself).
Type - type of the value to get, depending on the type of the element. For the dialog windows itself (ID=0) the following values are allowed:

Type	Var type	Description
0	Number	Number of elements in the dialog
2	Number	X1
3	Number	Y1
4	Number	X2
5	Number	Y2
6	Number	ID of the current element that has the keyboard focus

For dialog elements the following values are allowed:

Type	Var type	Element	Description
0	Number	CheckBox	State of the checkbox
0	Number	RadioButtons	State of the radio button
0	String	ListBox	Value of the current list item
0	String	ComboBox	Value of the current list item
0	String	Other	Textual value (the FarDialogItem.Data field)
1	Number	All	Element type
2	Number	All	X1 relative to the dialog window
3	Number	All	Y1 relative to the dialog window
4	Number	All	X2 relative to the dialog window
5	Number	All	Y2 relative to the dialog window
6	Number	All	does the element has focus?
7	Number	CheckBox	State of the checkbox
7	Number	RadioButtons	State of the radio button
7	String	ListBox	Current position in the list (first list item = 1)
7	String	ComboBox	Current position in the list (first list item = 1)
7	Number	Other	0
8	Number	All	Element flags
9	Number	All	A flag that specifies that the given dialog element is the "default element".
10	String	Other	Textual value (the FarDialogItem.Data field)

Returns -1 if ID is bigger than the number of elements in the dialog or the value of Type is not supported.

V=Editor.Set(Idx,Var)

Change settings of the current editor instance.

Index	Var Type	Description
0	Number	Tab size
1	Number	Expand tabs
2	Number	Persistent blocks
3	Number	Del removes blocks
4	Number	Autoindent
5	Number	Autodetect character table
6	Number	Create new files in WIN encoding
7	Number	Cursor beyond end of line
8	Number	BackSpace behaviour (TechInfo #13)
9	Number	Representation of the character under cursor in the status line (TechInfo #32)
10	Number	Save file position
11	Number	Save bookmarks
12	String	Word delimiters (TechInfo #1)
13	Number	EditorF7Rules (TechInfo #18)
14	Number	AllowEmptySpaceAfterEof (TechInfo #67)

The value of Var can be -1, in this case the function will not change any settings and will return the current state of the option.
Returns the previous value of the option or -1 if wrong arguments are given.
For example, a macro that moves the selected block one line down:

$IClip CtrlX %a=Editor.Set(2,1); Down CtrlV %a=Editor.Set(2,%a);

V=Editor.Sel(Action[,Opt])

Function allows manipulations with blocks in the text (in editor, input strings in dialogs, command line).

Action

Description

get parameters of the current block

Opt	Description
0	return the string number of the block start
1	return the position number of string of the block start
2	return the string number of the block end
3	return the position number of string of the block end
4	return the type of highlighted block: 0 - block is not highlighted, 1 - regular block, 2 - vertical block (alternative way is Editor.State)

place cursor within current block (block state is not changed during cursor placement)

Opt	Description
0	place cursor to the start of the highlighted block
1	place cursor to the end of the highlighted block

set block positions

Opt	Description
0	set block start position
1	set block end position

Позицией начала/конца блока считается текущая позиция курсора. Блок помечается только после указания конечной позиции (Opt=1), с ранее выделенного блока пометка снимается. Если позиция начала и конца блока совпадают, то эта операция равносильна снятию пометки блока.

установка позиций вертикального блока

Opt	Description
0	отметить позицию начала вертикального блока
1	отметить позицию конца вертикального блока

снять выделение с блока
Параметр Opt игнорируется.
Всегда возвращается 1.

В случае ошибки (в т.ч. функция вызвана не из "редактора") возвращаемое значение равно 0, иначе 1. Для Action=0 возвращается запрошенное значение.
Например, повторим некоторые сочетания клавиш из Turbo-сред (макрос на сочетание Ctrl-K):

%k=waitkey(0,1);
$if(%k==B || %k==b || %k==CtrlB)
  editor.sel(2,0)
$else
  $if(%k==K || %k==k || %k==CtrlK)
    editor.sel(2,1)
  $else
    $if((%k==C || %k==c || %k==CtrlC) && Selected)
      CtrlC
    $else
      $if((%k==Y || %k==y || %k==CtrlY) && Selected)
        CtrlD
      $else
        eval("F1")
      $end
    $end
  $end
$end

Bookmarks

Function Description

N=BM.Add() Добавить текущие параметры закладки и обрезать хвост

N=BM.Clear() Clear all bookmarks

N=BM.Del([Idx]) Удалить закладку с указанным индексом Idx (нумерация начинается с 1). Если параметр Idx не указан или равен 0 - удаляется текущая закладка.

N=BM.Get(Idx,M)

Получить параметры закладки с индексом Idx (нумерация начинается с 1), Idx=0 - текущая закладка.
M parameter can have these values:

Type	Description
0	координаты строки (начиная с 1)
1	координаты колонки (начиная с 1)
2	позиция, соответствующая первому видимому символу текста на экране слева
3	номер строки, соответствующей первой видимой строке текста на экране

N=BM.Next() Jump to the next bookmark

N=BM.Prev() Jump to the previous bookmark

N=BM.Stat([M])

Get bookmark information.
M parameter can have these values:

Type	Description
0	current number of bookmarks

Bookmark handling example:

Notes

Bookmark functions BM.XXX() are available only within the editor.
Function arguments given in square brackets may be omitted. See default values in function description.
It is impossible to use macro-language elements while recording a macro in a usual way. Macro-language elements can be added to the sequence only by editing the registry manually or by using special applications or FAR plugins.

previous page start next page