add utf8.escape, string.escape & reformat extensions.md

doc/en/scripting/builtins/libutf8.md

@@ -27,4 +27,7 @@ utf8.upper(text: str) -> str
 
 -- Converts a string to lowercase
 utf8.lower(text: str) -> str
+
+-- Escapes a string
+utf8.escape(text: str) -> str
 ```

doc/ru/scripting/builtins/libutf8.md

@@ -27,4 +27,7 @@ utf8.upper(text: str) -> str
 
 -- Переводит строку в нижний регистр
 utf8.lower(text: str) -> str
+
+-- Экранирует строку
+utf8.escape(text: str) -> str
 ```

doc/ru/scripting/extensions.md

@@ -4,92 +4,109 @@
 
 ## Расширения для table
 
-Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной
 ```lua
-function table.copy(t: table) -> table
+table.copy(t: table) -> table
 ```
 
-Возвращает количество пар в переданной таблице
+Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
+
 ```lua
-function table.count_pairs(t: table) -> integer
+table.count_pairs(t: table) -> integer
 ```
 
-Возвращает один элемент из переданной таблицы на случайной позиции
+Возвращает количество пар в переданной таблице.
+
 ```lua
-function table.random(t: table) -> object
+table.random(t: table) -> object
 ```
 
-Возвращает **true**, если **x** содержится в **t**
+Возвращает один элемент из переданной таблицы на случайной позиции.
+
 ```lua
-function table.has(t: table, x: object) -> bool
+table.has(t: table, x: object) -> bool
 ```
 
-Возвращает индекс обьекта **x** в **t**. Если переданный обьект не содержится в таблице, то функция вернёт значение **-1**
+Возвращает **true**, если **x** содержится в **t**.
+
 ```lua
-function table.index(t: table, x: object) -> integer
+table.index(t: table, x: object) -> integer
 ```
 
-Удаляет элемент **x** из **t**
+Возвращает индекс обьекта **x** в **t**. Если переданный обьект не содержится в таблице, то функция вернёт значение **-1**.
+
 ```lua
-function table.remove_value(t: table, x: object)
+table.remove_value(t: table, x: object)
 ```
 
-Конвертирует переданную таблицу в строку
+Удаляет элемент **x** из **t**.
+
 ```lua
-function table.tostring(t: table) -> string
+table.tostring(t: table) -> string
 ```
 
+Конвертирует переданную таблицу в строку.
+
 ## Расширения для string
 
-Разбивает строку **str** на части по указанному разделителю/выражению **separator** и возвращает результат ввиде таблицы из строк. Если **withpattern** равен **true**, то параметр **separator** будет определяться как регулярное выражение
 ```lua
-function string.explode(separator: string, str: string, withpattern: bool) -> table[string]
+string.explode(separator: string, str: string, withpattern: bool) -> table[string]
 ```
 
-Разбивает строку **str** на части по указанному разделителю **delimiter** и возвращает результат ввиде таблицы из строк
+Разбивает строку **str** на части по указанному разделителю/выражению **separator** и возвращает результат ввиде таблицы из строк. Если **withpattern** равен **true**, то параметр **separator** будет определяться как регулярное выражение.
+
 ```lua
-function string.split(str: string, delimiter: string) -> table[string]
+string.split(str: string, delimiter: string) -> table[string]
 ```
 
-Экранирует специальные символы в строке, такие как `()[]+-.$%^?*` в формате `%символ`. Символ `NUL` (`\0`) будет преобразован в `%z`
+Разбивает строку **str** на части по указанному разделителю **delimiter** и возвращает результат ввиде таблицы из строк.
+
 ```lua
-function string.pattern_safe(str: string)
+string.pattern_safe(str: string)
 ```
 
-Разбивает секунды на часы, минуты и миллисекунды и форматирует в **format** с следующим порядком параметров: `минуты, секунды, миллисекунды` и после возвращает результат. Если **format** не указан, то возвращает таблицу, где: **h** - hours, **m** - minutes, **s** - seconds, **ms** - milliseconds
+Экранирует специальные символы в строке, такие как `()[]+-.$%^?*` в формате `%символ`. Символ `NUL` (`\0`) будет преобразован в `%z`.
+
 ```lua
-function string.formatted_time(seconds: number, format: string) -> string | table
+string.formatted_time(seconds: number, format: string) -> string | table
 ```
 
-Заменяет все подстроки в **str**, равные **tofind** на **toreplace** и возвращает строку со всеми измененными подстроками
+Разбивает секунды на часы, минуты и миллисекунды и форматирует в **format** с следующим порядком параметров: `минуты, секунды, миллисекунды` и после возвращает результат. Если **format** не указан, то возвращает таблицу, где: **h** - hours, **m** - minutes, **s** - seconds, **ms** - milliseconds.
+
 ```lua
-function string.replace(str: string, tofind: string, toreplace: string) -> string
+string.replace(str: string, tofind: string, toreplace: string) -> string
+```
+
+Заменяет все подстроки в **str**, равные **tofind** на **toreplace** и возвращает строку со всеми измененными подстроками.
+
+```lua
+string.trim(str: string, char: string) -> string
 ```
 
 Удаляет все символы, равные **char** из строки **str** с левого и правого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.
+
 ```lua
-function string.trim(str: string, char: string) -> string
+string.trim_left(str: string, char: string) -> string
 ```
 
 Удаляет все символы, равные **char** из строки **str** с левого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.
+
 ```lua
-function string.trim_left(str: string, char: string) -> string
+string.trim_right(str: string, char: string) -> string
 ```
 
 Удаляет все символы, равные **char** из строки **str** с правого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.
+
 ```lua
-function string.trim_right(str: string, char: string) -> string
+string.starts_with(str: string, start: string) -> bool
 ```
 
 Возвращает **true**, если строка **str** начинается на подстроку **start**
+
 ```lua
-function string.starts_with(str: string, start: string) -> bool
+string.ends_with(str: string, endStr: string) -> bool
 ```
 
 Возвращает **true**, если строка **str** заканчивается на подстроку **endStr**
-```lua
-function string.ends_with(str: string, endStr: string) -> bool
-```
 
 Также важно подметить, что все выше перечисленные функции, расширяющие **string** можно использовать как мета-методы на экземплярах строк, т.е.: 
 
@@ -103,39 +120,51 @@ end
 
 Также функции `string.lower` и `string.upper` переопределены на `utf8.lower` и `utf8.upper`
 
+```lua
+string.escape(str: string) -> string
+```
+
+Экранирует строку. Является псевдонимом `utf8.escape`.
+
 ## Расширения для math
 
-Ограничивает число **_in** по лимитам **low** и **high**. Т.е.: Если **_in** больше чем **high** - вернётся **high**, если **_in** меньше чем **low** - вернётся **low**. В противном случае вернётся само число
 ```lua
-function math.clamp(_in, low, high)
+math.clamp(_in, low, high)
 ```
 
-Возвращает случайное дробное число в диапазоне от **low** до **high**
+Ограничивает число **_in** по лимитам **low** и **high**. Т.е.: Если **_in** больше чем **high** - вернётся **high**, если **_in** меньше чем **low** - вернётся **low**. В противном случае вернётся само число.
+
 ```lua
-function math.rand(low, high)
+math.rand(low, high)
 ```
 
+Возвращает случайное дробное число в диапазоне от **low** до **high**.
+
 ## Дополнительные глобальные функции
 
 В этом же скрипте также определены и другие глобальные функции которые доступны для использования. Ниже их список
 
 
-Возвращает **true**, если переданная таблица является массивом, тоесть если каждый ключ это целое число больше или равное единице и если каждый ключ следует за прошлым
 ```lua
-function is_array(x: table) -> bool
+is_array(x: table) -> bool
 ```
 
-Разбивает путь на две части и возвращает их: входную точку и путь к файлу
+Возвращает **true**, если переданная таблица является массивом, тоесть если каждый ключ это целое число больше или равное единице и если каждый ключ следует за прошлым.
+
 ```lua
 function parse_path(path: string) -> string, string
 ```
 
-Вызывает функцию **func** **iters** раз, передавая ей аргументы `...`, а после выводит в консоль время в микросекундах, которое прошло с момента вызова **timeit**
+Разбивает путь на две части и возвращает их: входную точку и путь к файлу.
+
 ```lua
 function timeit(iters: integer, func: func, ...)
 ```
 
-Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в **timesec**. Функция может быть использована только внутри корутины
+Вызывает функцию **func** **iters** раз, передавая ей аргументы `...`, а после выводит в консоль время в микросекундах, которое прошло с момента вызова **timeit**.
+
 ```lua
 function sleep(timesec: number)
 ```
+
+Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в **timesec**. Функция может быть использована только внутри корутины.

res/scripts/stdmin.lua

@@ -162,6 +162,7 @@ end
 
 string.lower = utf8.lower
 string.upper = utf8.upper
+string.escape = utf8.escape
 
 local meta = getmetatable("")
 

src/logic/scripting/lua/libs/libutf8.cpp

@@ -94,6 +94,11 @@ static int l_encode(lua::State* L) {
     return lua::pushlstring(L, bytes, count);
 }
 
+static int l_escape(lua::State* L) {
+    auto string = lua::require_lstring(L, 1);
+    return lua::pushstring(L, util::escape(string));
+}
+
 const luaL_Reg utf8lib[] = {
     {"tobytes", lua::wrap<l_tobytes>},
     {"tostring", lua::wrap<l_tostring>},
@@ -103,5 +108,6 @@ const luaL_Reg utf8lib[] = {
     {"upper", lua::wrap<l_upper>},
     {"lower", lua::wrap<l_lower>},
     {"encode", lua::wrap<l_encode>},
+    {"escape", lua::wrap<l_escape>},
     {NULL, NULL}
 };

src/util/stringutil.cpp

@@ -7,8 +7,7 @@
 #include <sstream>
 #include <stdexcept>
 
-// TODO: finish
+std::string util::escape(std::string_view s) {
-std::string util::escape(const std::string& s) {
     std::stringstream ss;
     ss << '"';
     size_t pos = 0;

src/util/stringutil.hpp

@@ -8,7 +8,7 @@
 
 namespace util {
     /// @brief Function used for string serialization in text formats
-    std::string escape(const std::string& s);
+    std::string escape(std::string_view s);
 
     /// @brief Function used for error messages
     std::string quote(const std::string& s);