Manual:Scripting

Scripting language manual

lala

Line structure

RouterOS script is divided into number of command lines.

Command line

RouterOS console uses following command syntax:
[prefix] [path] command [uparam] [param=[value]] .. [param=[value]]

• [prefix] - ":" or "/" character which indicates if command is ICE or path. May or may not be required.
• [path] - relative path to the desired menu level. May or may not be required.
• command - one of the commands available at the specified menu level.
• [uparam] - unnamed parameter, must be specified if command requires it.
• [params] - sequence of named parameters followed by respective values

The end of command line is represented by the token “;” or NEWLINE. Sometimes “;” or NEWLINE is not required to end the command line.

Single command inside (), [] or {} does not require any end of command character. End of command is determined by content of whole script

:if ( true ) do={ :put "lala" }

Each command line inside another command line starts and ends with square brackets "[ ]" (command concatenation).

:put [/ip route get [find gateway=1.1.1.1]];  

Notice that code above contains three command lines:

• :put
• /ip route get
• find gateway=1.1.1.1

Command line can be constructed from more than one physical line by following line joining rules.

Physical Line

A physical line is a sequence of characters terminated by an end-of-line (EOL) sequence. Any of the standard platform line termination sequences can be used:

• unix – ASCII LF;
• windows – ASCII CR LF;
• mac – ASCII CR;

Standard C conventions for new line characters can be used ( the \n character).

Comments

A comment starts with a hash character (#) and ends at the end of the physical line. Whitespace or any other symbols are not allowed before hash symbol. Comments are ignored by syntax. If (#) character appear inside string it is not considered a comment.

Example

# this is a comment
 # bad comment
:global a; # bad comment

:global myStr "lala # this is not a comment"

Line joining

Two or more physical lines may be joined into logical lines using backslash character (\). A line ending in a backslash cannot carry a comment. A backslash does not continue a comment. A backslash does not continue a token except for string literals. A backslash is illegal elsewhere on a line outside a string literal.

Example

:if ($a = true \
      and $b=false) do={ :put “$a $b”; }

:if ($a = true \      # bad comment
      and $b=false) do={ :put “$a $b”; }

# comment \
    continued – invalid  (syntax error)

Whitespace between tokens

Whitespace can be used to separate tokens. Whitespace is necessary between two tokens only if their concatenation could be interpreted as a different token. Example:

{ 
   :local a true; :local b false;	
# whitespace is not required	
   :put (a&&b); 
# whitespace is required
   :put (a and b); 	
}

Whitespace are not allowed

• between '<parameter>='
• between 'from=' 'to=' 'step=' 'in=' 'do=' 'else='

Example:

#incorrect:
:for i from = 1 to = 2 do = { :put $i }
#correct syntax:
:for i from=1 to=2 do={ :put $i }
:for i from= 1 to= 2 do={ :put $i }	

#incorrect
/ip route add gateway = 3.3.3.3
#correct
/ip route add gateway=3.3.3.3

Scopes

something about scopes { lalala }

Keywords

The following words are keywords and cannot be used as variable and function names:

and       or        not       in

Delimiters

The following tokens serve as delimiters in the grammar:

()  []  {}  :   ;   $   / 

Data types

RouterOS scripting language has following data types:

Type	Description
number	- 64bit signed integer, possible hexadecimal input;
boolean	- values can bee true or false;
string	- character sequence;
IP	- IP address;
internal ID	- hexadecimal value prefixed by '*' sign. Each menu item has assigned unique number - internal ID;
time	- date and time value;
array	- sequence of values organized in an array;
nil	- default variable type if no value is assigned;

Constant Escape Sequences

Following escape sequences can be used to define certain special character within string:

\"	- double quote
\\	- backslash
\n	- newline
\r	- carriage return
\t	- horizontal tab
\$
\?
\_	- space
\a	- BEL (0x07)
\a	- backspace (0x08)
\f	- form feed (0xFF)
\v	- vertical tab
\xx	- hex value

Example

:put "\48\45\4C\4C\4F\r\nThis\r\nis\r\na\r\ntest";

which will show on display
HELLO
This
is
a
test


Operators

lala

Arithmetic Operators

Usual arithmetic operators are supported in RouterOS scripting language

Opearator	Description	Example
"+"	binary addition	:put (3+4);
"-"	binary subtraction	:put (1-6);
"*"	binary multiplication	:put (4*5);
"/"	binary division	:put (10/2);
"-"	unary negation	{ :local a 1; :put (-a); }

Relational Operators

Opearator	Description	Example
"<"	less	:put (3<4);
">"	greater	:put (3>4);
"="	equal	:put (2=2);
"<="	less or equal
">="	greater or equal
"!="	not equal

Logical Operators

Opearator	Description	Example
“!” , “not”	logical NOT	:put (!true);
“&&” , “and”	logical AND	:put (true&&true)
“||” , “or”	logical OR	:put (true||false);

Bitwise Operators

Bitwise operators are working on number and ip address data types.

Opearator	Description	Example
“~”	bit inversion	:put (~0.0.0.0)
“|”	bitwise OR. Performs logical OR operation on each pair of corresponding bits. In each pair the result is “1” if one of bits or both bits are “1”, otherwise the result is “0”.
“^”	bitwise XOR. The same as OR, but the result in each position is “1” if two bits are not equal, and “0” if bits are equal.
“&”	bitwise AND. In each pair the result is “1” if first and second bit is “1”. Otherwise the result is “0”.
“<<”	left shift by given amount of bits
“>>”	right shift by given amount of bits

Concatenation Operators

Opearator	Description	Example
“.”	concatenates two strings	:put (“concatenate” . “ “ . “string”);
“,”	concatenates two arrays or adds element to array	:put ({1;2;3} , 5 );

Other Operators

Opearator	Description	Example
“[]”	command substitution	:put [ :len "my test string"; ];
“()”	sub expression operator	:put ( "value is " . (4+5));
“->”	access operator	(object)->(key)
“$”	substitution operator	:global a 5; :put $a;

Variables

Scripting language has two types of variables:

• global - accessible from all current users scripts, defined by global keyword;
• local - accessible only within the current scope, defined by local keyword.

Every variable, except for built in RouterOS variables, must be declared before usage by local or global keywords. Undefined variables will be marked as undefined and will result in compilation error. Example:

# following code will result in compilation error, because myVar is used without declaration
:set myVar "my value";
:put $myVar

Correct code:

:local myVar;
:set myVar "my value";
:put $myVar;

Valid characters in variable names are letters and digits. If variable name contains any other character, then variable name should be put in double quotes. Example:

:local myVar;  #valid variable name
:local my-var; #invalid variable name
:global "my-var"; #valid because double quoted

If variable is initially defined without value then variable data type is set to nil, otherwise data type is determined automatically by scripting engine. Sometimes conversion from one data type to another is required. It can be achieved using data conversion commands. Example:

#convert string to array
:local myStr "1,2,3,4,5";
:put [:typeof $myStr];
:local myArr [:toarray $myStr];
:put [:typeof $myArr]

Commands

Global commands

Every global command should start with ":" token, otherwise it will be treated as variable.

Command	Syntax	Description	Example
/		go to root menu
..		go back by one menu level
?		list all available menu commands and brief descriptions
global	:global <var> [<value>]	define global variable	:global myVar "something"; :put $myVar;
local	:local <var> [<value>]	define local variable	{ :local myLocalVar "I am local"; :put $myVar; }
beep	:beep <freq> <length>	beep built in speaker
delay	:delay <time>	do nothing for a given period of time
put	:put <expression>	put supplied argument to console
len	:len <expression>	return string length or array element count	:put [:len "length=8"];
typeof	:typeof <var>	return data type of variable	:put [:typeof 4];
pick	:pick <var> <start>[<end>]	return range of elements or substring. If end position is not specified, will return all elements from given position to end of string or array.	:put [:pick "abcde" 1 3]
log	:log <topic> <message>	write message to system log. Available topics are system logging	:log info "Hello from script";
time	:time <expression>	return interval of time needed to execute command	:put [:time {:for i from=1 to=10 do={ :delay 100ms }}];
set	:set <var> [<value>]	assign value to declared variable. Ja set bez veertiibas tad typof ir 'nil' vajadzetu but nothing.	:global a; :set a true;
find	:find <arg> <arg> <start>	return position of substring or array element	:put [:find "abc" "a" -1]; #kaapeec -1?? jaabuut 0
environment	:environment print <start>	print initialized variable information	:global myVar true; :environment print;
terminal		terminal related commands
error	:error <output>	generate console error
parse	:parse <expression>	parse string and return parsed console commands. (parsees arii LUA)
resolve	:resolve <arg>	return IP address of given DNS name	:put [:resolve "www.google.lv"];
toarray	:toarray <var>	convert variable to array
tobool	:tobool <var>	convert variable to boolean
toid	:toid <var>	convert variable to internal ID
toip	:toip <var>	convert variable to IP address
toip6	:toip <var>	convert variable to IPv6 address
tonum	:tonum <var>	convert variable to integer
tostr	:tostr <var>	convert variable to string
totime	:totime <var>	convert variable to time
break	:break	It terminates the nearest enclosing loop. If a for loop is terminated by break, the loop control target keeps its current value. break may only occur syntactically nested in a for or while loop.
continue	:continue	It continues with the next cycle of the nearest enclosing loop. continue may only occur syntactically nested in a for or while loop.

Menu specific commands

Common commands

Following commands available from most sub-menus:

Command	Syntax	Description
add	add <param>=<value>..<param>=<value>	add new item
remove	remove <id>	remove selected item
enable	enable <id>	enable selected item
disable	disable <id>	disable selected item
set	set <id> <param>=<value>..<param>=<value>	change selected items parameter, more than one parameter can be specified at the time
get	get <id> <param>=<value>	get selected items parameter value
print	print <param><param>=[<value>]	print menu items. Output depends on print parameters specified. Most common print parameters are described here
export	export [file=<value>]	export configuration from current menu and its sub-menus (if present). If file parameter is specified output will be written to file with extension '.rsc', otherwise output will be printed to console. Exported commands can be imported by import command
edit	edit <id> <param>	edit selected items property in built-in text editor
find	find <expression>	find items by given expression.

import

Import command is available from root menu and is used to import configuration from files created by export command or written manually by hand.

print parameters

Loops and conditional statements

Loops

Command	Syntax	Description
do..while	:do { <commands> } while=( <conditions> ); :while ( <conditions> ) do={ <commands> };	execute commands until given condition is met.
for	:for <var> from=<int> to=<int> step=<int> do={ <commands> }	execute commands over a given number of iterations
foreach	:foreach <var> in=<array> do={ <commands> };	execute commands for each elements in list

Conditional statement

Command	Syntax	Description
if	:if(<condition>) do={<commands>} else={<commands>} <expression>	If a given condition is true then execute commands in the do block, otherwise execute commands in the else block if specified.

Example:

{
   :local myBool true;
   :if ($myBool = false) do={ :put "value is false" } else={ :put "value is true" }
}

Command syntax

something will be written here, maybe