K-Meleon
KMeleonWiki > Documentation > EndUserDocs > MacroLanguage
A line starting with # is a comment and is ignored.
# this is a comment
Variables are not declared explicitly, but must have a name starting with a dollar sign. A variable can either be global, accessible from any macro, or local to a specific macro. Before a variable can be used in an expression, it must be assigned a value. Integer and string values are available.
$x = 0; $y = "A text string";
Macro declarations consist of a macro name followed by a compound of statements enclosed in curly braces to execute for that macro. An optional assignment of a string value to 'menu' can be used to set the text shown when the macro is used in menus.
example { menu = "Menu text"; $x = 0; }
The following operators are available:
Operator | Meaning | Sample Statement | Integer Result |
= | assignement | $x = 7; | $x = 7 |
. | string concatenation | $x = 7 . 3; | $x = 73 |
+ | integer addition | $x = 7 + 3; | $x = 10 |
- | integer subtraction | $x = 7 - 3; | $x = 4 |
* | integer multiplication | $x = 7 * 3; | $x = 21 |
/ | integer division | $x = 7 / 3; | $x = 2 |
% | integer remainder | $x = 7 % 3; | $x = 1 |
== | equality | $x = 7 == 3; | $x = 0 |
!= | unequality | $x = 7 != 3; | $x = 1 |
<, <=, >, >= | string comparison | $x = 10 < 2 | $x = 1 |
<, <=, >, >= | integer comparison | $x = +10 > +2 | $x = 1 |
? : | conditional expression | $x = $y==1 ? 2:3; | $x = 2 if y equals 1, $x = 3 otherwise |
Parenthesis can be used to alter the evaluation order. By default, addition and subtraction have higher precedence than multiplication, division and remainder operations.
When needed, a variable is automatically converted from a string to an integer, or vice versa.
$x = 1 + "2"; $x = 3 $y = "The value of x is " . x; $y = "The value of x is 3"
Strings should be enclosed in double quotes although not required unless the string contains operators. A backslash is used to escape special characters:
\\ | backslash (\) |
\n | newline character |
\t | tabulator |
\" | quotation mark (") |
The string values "true" and "false" are recognized as boolean values and can be used in place of a conditional expression.
$z = "false"; $z ? $x = 1 : $x = 0; $x = 0 $z = "true"; $z ? $x = 1 : $x = 0; $x = 1
There is a number of predefined global variables to let K-Meleon macros access some global state information.
$ARG | Argument given from caller plugin (not from caller macro). |
$CHARSET | Character encoding used for the current page. Since 1.0. |
$FrameURL | URL for the current frame. |
$ImageURL | URL for the current image. |
$LinkURL | URL for the current link. |
$SelectedText | Selected text in the current page. Since 1.0. |
$TextZoom | Text zoom factor for the current page. Since 1.0. |
$TITLE | Title for the current page. |
$URL | URL for the current page. |
$URLBAR | Contents of the URL bar. Since 1.0. |
OnActivateWindow OnCloseGroup OnCloseWindow OnInit OnLoad OnOpenWindow OnQuit OnSetup OnStartup OnWMAppExit
Several statements can be lined up on the same line with a semicolon in between.
$x = 0; $y = "A text string";
Statements may not span several lines!
# THIS IS INVALID $error = 1 + 1;
open( URL );
Opens URL in the current browser window.
opennew( URL );
Opens URL in a new browser window.
openbg( URL );
Opens URL in a new background window.
$VALUE = getpref( TYPE, "user.preference.variable" );
Gets a user preference.
TYPE = BOOL | INT | STRING
setpref( TYPE, "user.preference.variable", VALUE );
Sets a user preference.
TYPE = BOOL | INT | STRING
togglepref( TYPE, "user.preference.variable", VALUE1, VALUE2, ... );
Toggles a user preference between a series of values (booleans always toggle between true and false).
TYPE = BOOL | INT | STRING
exec( COMMAND_LINE );
Executes an external program.
id( COMMAND_ID );
Sends a message ID to the current window. See the complete list of command IDs.
plugin( PLUGIN, COMMAND ); pluginmsg( PLUGIN, COMMAND, ARGS ); $REPLY = pluginmsgex( PLUGIN, COMMAND, ARGS, TYPE );
Runs a plugin command. The possible values of COMMAND, ARGS and TYPE depend on the specific plugin. See the complete list of plugin commands.
alert( MESSAGE [, TITLE [, ICON]] );
Shows a messagebox.
ICON = EXCLAIM | INFO | STOP | QUESTION
$RESULT = confirm( MESSAGE [, TITLE [, BUTTONS [, ICON]]] );
Shows a messagebox and asks for confirmation.
BUTTONS = RETRYCANCEL | YESNO | YESNOCANCEL | ABORTRETRYIGNORE
ICON = EXCLAIM | INFO | STOP | QUESTION
RESULT = OK | YES | NO |ABORT | RETRY | IGNORE | 0
$VALUE = prompt( MESSAGE [, TITLE [, DEFAULT_STRING]] );
Shows a modal 'prompt' dialog and returns a string value.
statusbar( TEXT );
Shows the message text on the status bar.
$TEXT = getclipboard();
Gets data from the clipboard.
setclipboard( TEXT );
Sets data to the clipboard.
$SUB = gensub( r, s, h, t );
Searches the target string t for matches of the string r. If h is a string beginning with g or G, then all matches of r are replace with s. Otherwise, h is a number indicating which match of r to replace. The modified string is returned.
$SUB = gsub( r, s, t );
Substitutes the string s for each substring matching the string r in the string t, and returns the modified string. This is equivalent to gensub( r, s, "G", t).
$SUB = sub( r, s, t );
Just like gsub(), but only the first matching substring is replaced. This is equivalent to gensub( r, s, 1, t).
$SUB = substr( s, i [, n] );
Returns the at most n-character substring of s starting at i. If n is omitted, the rest of s is used.
$I = index( s, t );
Returns the index of the string t in the string s, or -1 if t is not present.
$LEN = length( s );
Returns the length of the string s.
$BASE = basename( URL [, SUFFIX] );
Returns URL with any leading directory components removed. If specified, also remove a trailing SUFFIX.
$DIR = dirname( URL );
Returns URL with its trailing /component removed. If URL contains no '/', output '.' (meaning the current directory).
$HOST = hostname( URL );
Returns the hostname of the given URL.
macros( MACRO1 [,MACRO2 [,MACRO3 [...]]] );
Executes another macro. Multiple macro execution since 1.1.
&MACRO;
Equivalent to macros( MACRO ).
$CONTENT = readfile( PATH );
Returns the contents of the specified file (32 kB maximum). Only for little text files.
$VALUE = readkey( ROOT, PATH );
Returns the value of the specified registry key.
ROOT = HKLM | HKCU | HKCC | HKCR | HKU
$PATH = promptforfile( INITIAL_FOLDER, FILE_TYPE_DESCRIPTION, FILE_EXTENSION_PATTERN );
Prompts the user for a file, displaying only the files matching the pattern.
$PATH = promptforfolder( CAPTION [, INITIAL_FOLDER] );
Prompts the user for a folder.
injectJS( JS_CODE ); injectCSS( CSS_CODE );
Injects a JavaScript or a Cascading Style Sheet into the current page.
$VALID_URL = urlencode( TEXT );
Encodes TEXT for use in an URL.
$TRANSLATION = _( TEXT );
Replaces TEXT by the specified translation, if any.
while( CONDITION ) STATEMENT
Executes the STATEMENT while the CONDITION is true.
$PATH = getfolder( FOLDER_TYPE );
Returns the path of the specified folder.
FOLDER_TYPE = RootFolder | SettingsFolder | ProfileFolder | ResFolder | SkinFolder | MacroFolder | UserMacroFolder
setaccel( KEY, COMMAND);
Sets a keyboard accelerator for the specified command.
KEY: Key (combination) to use e.g. "CTRL ALT X".
COMMAND: Command ID or plugin command. If NULL, the accel is deleted.
setmenu( MENU_NAME, ITEM_TYPE [, LABEL [, COMMAND]] [, WHERE]);
Parameter | Type | Meaning |
MENU_NAME | string | Specifies the name of the addressed menu (required). |
ITEM_TYPE | predefined | Specifies the nature of the addressed item (required). Can be one of the strings: inline, popup, command, macro, separator. |
LABEL (1) | string | Specifies the name of the addressed item inside the addressed menu. |
COMMAND (2) | string | Specifies the command associated with the addressed item. |
WHERE (3) | string or integer string -1 n=0,1,2,... |
Specifies where to insert the addressed item. Insert before an item specified either by label or by command Insert at the end of the addressed menu Insert at position n of the addressed menu (1st position: 0) |
(1) LABEL must be specified for all item types except "separator". If LABEL is an empty string, this is a deletion.
(2) COMMAND must be specified for item types "command" and "macro". If COMMAND is an empty string and LABEL is not, this is a deletion.
(3) WHERE can be omitted for all item types except "separator" (-1 is the default).