# Built in function library

**URL:** <https://forum.mikrotik.com/t/built-in-function-library/117288>\
**Category:** Scripting\
**Created:** [March 8, 2018, 2:56pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288 "2018-03-08T14:56:50Z")\
**Posts on this page:** 20\
**Page:** 6

<div class="post-metadata">

**Author:** ![mrz](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/mrz/32/308_2.png) [@mrz](https://forum.mikrotik.com/u/mrz)\
**Post date:** [January 5, 2022, 10:23am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/101 "2022-01-05T10:23:17Z")

</div>

In RouterOS number is an integer.

Integer division yields an integer result. You can use the remainder operator, %, which yields the remainder after integer division. Thus, 10 % 3 yields 1.

---

<div class="post-metadata">

**Author:** ![xenuc](https://forum.mikrotik.com/letter_avatar/xenuc/32/6_449c533f586939b6e5f246632a46421f.png) [@xenuc](https://forum.mikrotik.com/u/xenuc)\
**Post date:** [January 5, 2022, 6:57pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/102 "2022-01-05T18:57:01Z")

</div>

JSON encode and parse please!

---

<div class="post-metadata">

**Author:** ![Frozer](https://forum.mikrotik.com/letter_avatar/frozer/32/6_449c533f586939b6e5f246632a46421f.png) [@Frozer](https://forum.mikrotik.com/u/Frozer)\
**Post date:** [January 20, 2022, 7:39am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/103 "2022-01-20T07:39:46Z")

</div>

1. uppercase, lowercase
2. str\_replace
3. Access a variable by value from another variable
4. break cycles

What I remembered. I will add the topic to bookmarks, I will add it in fact when I write the next script.

By the way, when will you expand the window for inserting scripts through WinBox? Many of my scripts do not fit in it and I go through “7 circles of hell” to add… o need to add include function. Time passes, memory is added, processors are more powerful, but the limitations are the same …

---

<div class="post-metadata">

**Author:** ![tomaskir](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/tomaskir/32/957_2.png) [@tomaskir](https://forum.mikrotik.com/u/tomaskir)\
**Post date:** [January 20, 2022, 3:56pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/104 "2022-01-20T15:56:56Z")

</div>

1. Most of my personal issues with ROS scripting are when it comes to string parsing and string manipulation. Gives how ROS scripting is used, these are some of the most used functions, and currently they lack of lot of utility functions.

:strleft - return a number of characters of the string (from the left)  
:strright - return a number of characters of the string (from the right)  
:strreplace - replace some characters in string

These would be super useful to avoid having to deal with "find and :pick all the time for simple string manipulation. And replace is just missing completely.

1. Next, the loops in ROS scripting are completely missing functionality to affect their code-flow.

:break - break out of a :for and :foreach, etc. loops  
:continue - the usual concept of :continue in loops

1. Time and date manipulation. This is just not handled at all. For example, this script shows how to nicely deal with time/date increases: [http://forum.mikrotik.com/t/dates-manipulation-module/113640/1](http://forum.mikrotik.com/t/dates-manipulation-module/113640/1) Having the ability to natively do time/date manipulation would super useful. Here is an example using the function linked above:

```plaintext
:local targetDate [$addDate date=[/system clock get date] days=3]

```

I would much prefer a :todate function which would format a string as a date, and allow for easy operations. Something like this working natively would be lovely:

```plaintext
:local targetDate ([/system clock get date] + [:todate "3d"])

```

1. Finally, I would really like to get access to why an error occurred in on-error blocks. Here is what I would love:

```plaintext
:do {  
    # things
} on-error e do={
  :put "Failed, reason: $e"
};

```

---

<div class="post-metadata">

**Author:** ![msatter](https://forum.mikrotik.com/letter_avatar/msatter/32/6_449c533f586939b6e5f246632a46421f.png) [@msatter](https://forum.mikrotik.com/u/msatter)\
**Post date:** [January 20, 2022, 4:43pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/105 "2022-01-20T16:43:41Z")

</div>

Replace and remove in string: [http://forum.mikrotik.com/t/built-in-function-library/117288/63](http://forum.mikrotik.com/t/built-in-function-library/117288/63)

---

<div class="post-metadata">

**Author:** ![Amm0](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/amm0/32/1630_2.png) [@Amm0](https://forum.mikrotik.com/u/Amm0)\
**Post date:** [January 20, 2022, 8:20pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/106 "2022-01-20T20:20:54Z")

</div>

To follow up on @tomaskir great suggestions…

> [@](#):
>
> 1. […] string parsing and string manipulation. […] would be super useful to avoid having to deal with "find and :pick all the time for simple string manipulation. And replace is just missing completely.

One alternative to adding a bunch of new :str\_X\_ things, is full support regular expressions, specifically capture groups and replace. Thought is a “:regex” command might be able to encompose a lot of use cases. Idea being it would return an ROS array with the “matches” returned from the regex groups defined in the match= regular expression provided, based on data in from=

```plaintext
:global mystr "blah, blah, blah"
:global matches [:regex match=/blah/ from=$mystr multiline greedy global]
:put [:typeof $matches]
# array
:put $matches                       
# blah;blah;blah
:put [:len $matches] 
# 3

```

For string substitution,

```plaintext
:global replacedstring [:regex find="blah" replace="hello" from=$mystr]
:put [:typeof $replacedstring]
# string

```

Basically have some light version of “sed” and “awk” be nice. Regex isn’t for the faint of heart, but neither is BGP which supports regex in V7. Thinking it at least be cleaner script code than “[:strright [:strleft $x] 3” .

> [@](#):
>
> 1. Next, the loops in ROS scripting are completely missing functionality to affect their code-flow.
> 
> :break - break out of a :for and :foreach, etc. loops  
> :continue - the usual concept of :continue in loops

Yup this comes up which then requires more complex conditional logic to avoid needing it…

> [@](#):
>
> 1. Time and date manipulation. This is just not handled at all.

Here perhaps another possible simplification is a wrapper around GNU date, so perhaps “:datestr” that wraps it? The “modern” date in Linux support some humanizing options that pretty handy in /bin/sh script, see this [gdate cheatsheet](https://michaelcurrin.github.io/dev-cheatsheets/cheatsheets/shell/commands/date/gnu-date.html) for example.  
  
  
The options just follow the man pages, except with the ROS “=” method, so follow Bash shell usage a Linux date:

```plaintext
# returns the "7th day of last month"  
bash> gdate --date "-1 month" +"%Y-%m-07" 
# 2021-12-07

```

be the following in ROS, with added format=

```plaintext
[user@ROS]> :datestr date="-1 month" format="+\"%Y-%m-07\""
# 2021-12-07

```

As more sophisticated version of “:datestr” also have an “as-value” that get the current Mikrotik “time” type (e.g. [weeks ago from 1970-epoch time](http://forum.mikrotik.com/t/time-parsing-in-7-1/154185/3)).

> 1. Finally, I would really like to get access to why an error occurred in on-error blocks. Here is what I would love:
> 
> ```plaintext
> 
> ```

:do {  
# things  
} on-error e do={  
:put “Failed, reason: $e”  
};

```auto
>

That's a good one, and since "$e" likely be a string, a "_simple_ string find" operation from your 1 above is also needed with it :wink:.
```

---

<div class="post-metadata">

**Author:** ![tomaskir](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/tomaskir/32/957_2.png) [@tomaskir](https://forum.mikrotik.com/u/tomaskir)\
**Post date:** [January 20, 2022, 10:39pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/107 "2022-01-20T22:39:58Z")

</div>

> [@](#):
>
> > 1. Finally, I would really like to get access to why an error occurred in on-error blocks. Here is what I would love:
> > 
> > ```plaintext
> > 
> > ```
> 
> :do {  
> # things  
> } on-error e do={  
> :put “Failed, reason: $e”  
> };
> 
> ```auto
> >
> 
> That's a good one, and since "$e" likely be a string, a "_simple_ string find" operation from your 1 above is also needed with it :wink:.
> 
> ```

Yes, $e could be a string. RouterOS commands already output an error message (string) when they fail, having access to that would be lovely for debug purposes. You could however easily imagine a more complex usecase. $e could be a more elaborate object, which could give you access to more failure data. For example:

$e-\>errorMessage - contains the error message string  
$e-\>command - command which caused an error, useful if multiple commands in :do block  
$e-\>lineNumber - on which line in the script the issue occured  
etc.

---

<div class="post-metadata">

**Author:** ![pe1chl](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/pe1chl/32/55588_2.png) [@pe1chl](https://forum.mikrotik.com/u/pe1chl)\
**Post date:** [January 20, 2022, 10:47pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/108 "2022-01-20T22:47:02Z")

</div>

The problem with line/pos number reporting is that all scripts are first compiled into a P-code (a stack language) which is then executed.  
By the time an error occurs in some function, the processor does not know to what source line this corresponds (both text and linenumber).

---

<div class="post-metadata">

**Author:** ![Amm0](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/amm0/32/1630_2.png) [@Amm0](https://forum.mikrotik.com/u/Amm0)\
**Post date:** [January 20, 2022, 11:48pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/109 "2022-01-20T23:48:24Z")

</div>

> [@](#):
>
> The problem with line/pos number reporting is that all scripts are first compiled into a P-code (a stack language) which is then executed.  
> By the time an error occurs in some function, the processor does not know to what source line this corresponds (both text and linenumber).

Not to be pedantic, but that’s not quite true in all contexts. Certainly System\>Script/Schedule and functions created using :global get converted into the

```plaintext
 \(evl(...

```

stuff on save/:set. But in the context of an “import”, ROS seem to know the context of the line number being executed.

```plaintext
import verbose=yes

```

Now even that doesn’t help with functions. An error in a function, will only show the line number of the calling location, not the line number of the error with the function’s code.

But on-error with _string_ – which seems readily knowable since it’s printed to terminal – be a step in the right direction.

Since it’s a new year, I’ll add another plea for

> [@xenuc](#):
>
> JSON encode and parse please!

Ideally with [JSON to/from ROS array support](https://forum.mikrotik.com/posting.php?mode=quote&p=907116#pr893975).

---

<div class="post-metadata">

**Author:** ![pe1chl](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/pe1chl/32/55588_2.png) [@pe1chl](https://forum.mikrotik.com/u/pe1chl)\
**Post date:** [January 21, 2022, 8:33am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/110 "2022-01-21T08:33:06Z")

</div>

> [@](#):
>
> > [@](#):
> >
> > The problem with line/pos number reporting is that all scripts are first compiled into a P-code (a stack language) which is then executed.  
> > By the time an error occurs in some function, the processor does not know to what source line this corresponds (both text and linenumber).
> 
> Not to be pedantic, but that’s not quite true in all contexts. Certainly System\>Script/Schedule and functions created using :global get converted into the
> 
> ```plaintext
> \(evl(...
> 
> ```
> 
> stuff on save/:set. But in the context of an “import”, ROS seem to know the context of the line number being executed.

For language syntax errors that are detected while compiling the script the line number when it is encountered is known.  
But when a syntactically correct script encounters a runtime error during execution, the line number (and character position) of the original source line isn’t known.

It is like using a compiled language like C on a computer. When you compile the code, the compiler shows the line number of your syntax errors.  
But when you run it and encounter an error like division by zero or dereferencing a NULL pointer, the line number isn’t printed with the error.

Of course it would be possible to introduce “debugging info” in the form of special instructions that maintain a “current line number” register in the P-code interpreter that is printed when a runtime error occurs, but it is extra effort and it has not been done.

---

<div class="post-metadata">

**Author:** ![Chupaka](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/chupaka/32/215_2.png) [@Chupaka](https://forum.mikrotik.com/u/Chupaka)\
**Post date:** [January 21, 2022, 7:07pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/111 "2022-01-21T19:07:02Z")

</div>

> [@](#):
>
> o need to add include function.

Declare your functions in a script, then execute that script from another script to “include” necessary functio(s): [https://wiki.mikrotik.com/wiki/Manual:Scripting#Functions](https://wiki.mikrotik.com/wiki/Manual:Scripting#Functions)

---

<div class="post-metadata">

**Author:** ![jr0dd](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/jr0dd/32/1844_2.png) [@jr0dd](https://forum.mikrotik.com/u/jr0dd)\
**Post date:** [January 27, 2022, 4:31am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/112 "2022-01-27T04:31:26Z")

</div>

json parsing seems to be the consensus in here and definitely has my vote. or maybe on devices with more storage just give us the ability to use bash, curl & jq 😮

---

<div class="post-metadata">

**Author:** ![Amm0](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/amm0/32/1630_2.png) [@Amm0](https://forum.mikrotik.com/u/Amm0)\
**Post date:** [February 14, 2022, 10:49pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/113 "2022-02-14T22:49:04Z")

</div>

While this seems like nascent, or at least low moving, topic… Did run into another missing built-in function: zip/unzip and/or tar/gzip support.

The container package seems internally deal with TAR files, so be nice if this was exposed for scripting. Basically be handy to some **:compress** and **:deflate** function. Or, perhaps an option to /file that do similar.

---

<div class="post-metadata">

**Author:** ![giulianoz](https://forum.mikrotik.com/letter_avatar/giulianoz/32/6_449c533f586939b6e5f246632a46421f.png) [@giulianoz](https://forum.mikrotik.com/u/giulianoz)\
**Post date:** [August 15, 2022, 8:12am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/114 "2022-08-15T08:12:59Z")

</div>

I too would love to see curl/jq as built-ins 🙂

---

<div class="post-metadata">

**Author:** ![mada3k](https://forum.mikrotik.com/letter_avatar/mada3k/32/6_449c533f586939b6e5f246632a46421f.png) [@mada3k](https://forum.mikrotik.com/u/mada3k)\
**Post date:** [January 15, 2023, 3:43pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/115 "2023-01-15T15:43:47Z")

</div>

Creating a new file and appending input from CLI. Adding a new public ssh key as file, and importing it to a user. Today it has to be done via SCP/SFTP, then imported.

For example:

> /file add name=“user.pub” content=“ssh-rsa XXXXXXXXXXXXXXXXXXXXX”

---

<div class="post-metadata">

**Author:** ![Sertik](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/sertik/32/2663_2.png) [@Sertik](https://forum.mikrotik.com/u/Sertik)\
**Post date:** [July 17, 2023, 1:01pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/116 "2023-07-17T13:01:16Z")

</div>

> We are considering to add commonly used functions as built-in.  
> What functions would you like to see?  
> For example, MD5hash, random number generator and so on.

Please fix the “third function call” error at last. For example, we have a function:

```plaintext
:local myFunc do {:log info "Hello world !"}

```

If we call it with the shell twice in a row, it will be executed three times!

```plaintext
[$myFunc]
[$myFunc]

```

Hello world !  
Hello world !  
Hello world !  
  
  
If we make a call without a wrapper , this error does not occur:

```plaintext
$myFunc
$myFunc

```

Hello world !  
Hello world !

If the function is called to perform :put, there will be gaps:

[http://forum.mikrotik.com/t/frequent-empty-variables-in-scripts-turned-out-to-be-bug/168049/1](http://forum.mikrotik.com/t/frequent-empty-variables-in-scripts-turned-out-to-be-bug/168049/1)

Interestingly, subsequent calls after the second are processed normally:

```plaintext
[$myFunc]
[$myFunc]
[$myFunc]

```

Hello world !  
Hello world !  
Hello world !  
Hello world !

---

<div class="post-metadata">

**Author:** ![Sertik](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/sertik/32/2663_2.png) [@Sertik](https://forum.mikrotik.com/u/Sertik)\
**Post date:** [July 17, 2023, 1:13pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/117 "2023-07-17T13:13:26Z")

</div>

As for the built-in functions, I will refrain from speaking for now, but what I would like is that it would be possible **to create sections in the script repository** , so that it would be possible to store scripts not in a common huge list. After all, the number of scripts in the repository of a modern router can be impressive. And you could call it by specifying the path

```plaintext
/system/script/myScript1/run script1
/system/script/myScript2/add script2
/system/script/myScript1/remove script1

```

Yes, this will entail the need to rewrite many scripts, but now the situation is the best for introducing folders into the repositories, when many scripts are already being rewritten for Ros7. Yes, it’s not clear how to make scripts located in different sections see and be able to run each other … But, probably, this could be somehow solved. this should have been done from the very beginning.

**In the end, for the system, the scripts, as they were stored, can be stored in one common section, but for the user they could be seen in separate subsections / folders**

It would also speed up script browsing in Winbox when outputting a section of say 15 scripts is much faster than outputting 500.

---

<div class="post-metadata">

**Author:** ![mike548141](https://forum.mikrotik.com/letter_avatar/mike548141/32/6_449c533f586939b6e5f246632a46421f.png) [@mike548141](https://forum.mikrotik.com/u/mike548141)\
**Post date:** [July 24, 2023, 8:19am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/118 "2023-07-24T08:19:00Z")

</div>

Some ideas  
**Syntax checking**  
A big one for me would not be a new function, but making scripting easier across everyting using the Mikrotik platform.  
RouterOS on a CHR virtual device does not have /system/routerboard/ in the CLI so a script will give a syntax error when it trys to load the script into memory i.e. pre-execution. Similarly most routerboard hardware devices do not have /system/hardware/ so they will give a syntax error on load if that is referenced anywhere in the script file.  
The script has logic to avoid running the wrong commands on certain devices but the script will not execute because it will fail syntax checking. Currently I get around this by parsing the commands in dispute so they do not get validated until they are executed, but frankly thats pretty ugly.

The simple answer to me (but there are probably better ideas) would be to have the same CLI structure irresepctive of the device. For example I can call :put [/system/routerboard/get routerboard;]; and get a false if it were a CHR.

**Filesystem**  
Some basic file and directory handling like mkdir, I work around that using /tool fetch but would prefer not to have too.

Ta

---

<div class="post-metadata">

**Author:** ![msatter](https://forum.mikrotik.com/letter_avatar/msatter/32/6_449c533f586939b6e5f246632a46421f.png) [@msatter](https://forum.mikrotik.com/u/msatter)\
**Post date:** [July 24, 2023, 9:20am UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/119 "2023-07-24T09:20:15Z")

</div>

@mike548141 When you have commands that could not work on every device then you can avoid errors by using **do {} on-error={}**

```plaintext
:do { /system/hardware } on-error={ :error "error: script not executable on this device " }

```

```plaintext
:do { /system/hardware } on-error={ :log "error: script X not executable on this device " }

```

---

<div class="post-metadata">

**Author:** ![Amm0](https://forum.mikrotik.com/user_avatar/forum.mikrotik.com/amm0/32/1630_2.png) [@Amm0](https://forum.mikrotik.com/u/Amm0)\
**Post date:** [July 24, 2023, 3:17pm UTC](https://forum.mikrotik.com/t/built-in-function-library/117288/120 "2023-07-24T15:17:32Z")

</div>

> [@](#):
>
> **Filesystem**  
> Some basic file and directory handling like mkdir, I work around that using /tool fetch but would prefer not to have too.

There is now “/file/add name=” in the latest V7’s. Directories kinda fake in RouterOS as they are constructed from the “/” in the name= … so still need to create _some_ file. But /file/add avoids awkward syntax, still not “mkdir” … but better than /tool/fetch for this.

Now they could add a “/file/add name=mydir **type=directory** ” that least get what looks to be a empty directory in winbox and /file/print. But… directory are automatically created whenever you need a file, without any need for them to exist (e.g. why no “mkdir”).

[Previous page](https://forum.mikrotik.com/t/built-in-function-library/117288.md?page=5)

[Next page](https://forum.mikrotik.com/t/built-in-function-library/117288.md?page=7)
