Utils
Utils — системный модуль, собирающий часто нужные вспомогательные свойства и действия: работа с файловой системой, преобразование и кодирование данных, строковые операции, арифметика, доступ к JSON, полнотекстовый поиск, диагностика сервера и т. п. Подключается через REQUIRE Utils (System и Time тянутся автоматически).
Файловая система
Действия (ISTRING path, ...) работают на сервере по умолчанию; флаг isClient = TRUE (или отдельная клиентская перегрузка) выполняет ту же операцию на стороне клиента.
| Действие / свойство | Что делает |
|---|---|
listFiles[ISTRING, BOOLEAN, BOOLEAN] и перегрузки | перечисляет файлы в директории; пишет имя, признак директории, дату, размер в локальные свойства fileName, fileIsDirectory, fileModifiedDateTime, fileSize от INTEGER |
listFilesClient[…] | то же на клиенте |
fileExists[ISTRING] / fileExistsClient[ISTRING] | проверка существования; результат в fileExists[] |
mkdir[ISTRING] / mkdirClient[ISTRING] | создать директорию |
delete[ISTRING] / deleteClient[ISTRING] | удалить файл или директорию |
copy[ISTRING, ISTRING] / copyClient[…] | скопировать |
move[ISTRING, ISTRING] / moveClient[…] | переместить |
getFileSize[FILE] | размер файла в байтах в fileSize[] |
appendToFile[STRING, TEXT, STRING] | дописать строку в файл с указанной кодировкой |
Содержимое файлов и кодировки
| Свойство / действие | Что делает |
|---|---|
stringToFile[TEXT, STRING, STRING] → resultFile[] | сериализовать строку в FILE с указанной кодировкой и расширением |
fileToString[FILE, STRING] → resultString[] | прочитать FILE как строку |
linkToString[LINK] / richTextToString[RICHTEXT] | приведение ссылочного / форматированного текста к STRING |
readResource[STRING, BOOLEAN] → resource[] | прочитать ресурс из classpath |
readResourcePaths[STRING, BOOLEAN] → resourcePaths | список ресурсов, попадающих под шаблон |
readProperties[RAWFILE] → properties[STRING] | разобрать .properties-файл в свойство-словарь |
encode[…, STRING] / decode[STRING, STRING] | кодирование двоичных данных в STRING и обратно в RAWFILE; второй аргумент — способ кодирования (base64, hex, escape); PG encode($1,$2) / decode($1,$2) |
encodeBase64[…] / encodeBase64Unchunked[…] / decodeBase64[STRING] | base64 для RAWFILE, STRING, FILE, NAMEDFILE |
urlEncode[TEXT, TEXT] → urlEncoded[] / urlDecode[…] → urlDecoded[] | URL-кодирование с указанной кодировкой |
urlParse[] / urlFormat[] (через urlFormatted и urlParsed) | разбор URL на составляющие и обратная сборка |
escapeJSONValue[TEXT] / escapeXMLValue[TEXT] | экранирование строки для встраивания в JSON / XML |
Архивы
| Действие | Что делает |
|---|---|
zipping[STRING] <- file | накапливание файлов в архиве (STRING-путь внутри архива → содержимое) |
makeZipFile[BOOLEAN] → zipped[] | собрать архив; флаг — обнулять ли время файлов |
unzipping[] <- file | задать архив для распаковки |
makeUnzipFile[] → unzipped[STRING] | распаковать; результат: STRING-путь внутри архива → файл |
Консоль и сеть
| Действие | Что делает |
|---|---|
cmd[TEXT, TEXT, BOOLEAN, BOOLEAN] и перегрузки | запуск команды ОС; результат в cmdOut[] и cmdErr[] |
cmdClient[TEXT, BOOLEAN] / cmdClient[TEXT] | то же на клиенте |
ping[TEXT, BOOLEAN] / pingClient[TEXT] | проверка доступности хоста; ошибка в pingError[] |
Excel
| Свойство / действие | Что делает |
|---|---|
protectExcel[EXCELFILE, STRING] → protectedExcel[] | защита файла паролем |
mergeExcel[EXCELFILE, EXCELFILE] → mergedExcel[] | объединение двух файлов |
columnsCount[EXCELFILE, INTEGER] → columnsCount[] | число колонок на листе |
sheetNames[EXCELFILE] → sheetNames[INTEGER] | имена листов |
PDF и Word
| Свойство / действие | Что делает |
|---|---|
pagesCountPdf[PDFFILE] → pagesCountPdf[] | число страниц |
pdfToString[PDFFILE, BOOLEAN] | распознать текст из PDF |
wordToPdf[WORDFILE] | сконвертировать Word в PDF |
Строки
Почти все эти свойства объявлены через FORMULA и на PostgreSQL транслируются в одноимённую SQL-функцию или оператор. В строках, где свойство напрямую соответствует выражению PostgreSQL, оно приведено в конце описания после ; PG ($1, $2, … — параметры по порядку).
| Свойство | Что делает |
|---|---|
length[TEXT] | длина строки в символах; PG length($1) |
left[TEXT, INTEGER] / right[TEXT, INTEGER] | первые / последние n символов строки; при отрицательном n PostgreSQL отбрасывает последние / первые |n| символов; PG left($1,$2) / right($1,$2) |
substr[TEXT, INTEGER, INTEGER] / substrFrom[TEXT, INTEGER] | подстрока длиной len начиная с позиции from (отсчёт с 1) / подстрока от позиции from до конца строки; PG substring($1,$2,$3) / substring($1,$2) |
substring[STRING, STRING] | первая подстрока, совпавшая с POSIX-регулярным выражением; NULL, если совпадения нет; PG substring($1, $2) |
strpos[TEXT, TEXT] | позиция первого вхождения подстроки (отсчёт с 1); 0, если подстрока не найдена; PG strpos($1,$2) |
replace[TEXT, TEXT, TEXT] | замена всех вхождений from на to; PG replace($1,$2,$3) |
ltrim[…] / rtrim[…] / trim[TEXT] | срезание пробелов слева / справа / с обеих сторон; PG ltrim($1) / rtrim($1) / trim($1) |
ltrim[TEXT, TEXT] / rtrim[TEXT, TEXT] | срезание слева / справа любых символов, перечисленных во втором аргументе; PG ltrim($1,$2) / rtrim($1,$2) |
lpad[TEXT, INTEGER, TEXT] / rpad[…] | дополнение строкой fill слева / справа до длины len; если исходная строка длиннее len, она усекается; PG lpad($1,$2,$3) / rpad($1,$2,$3) |
repeat[TEXT, INTEGER] | повторение строки n раз; PG repeat($1,$2) |
startsWith[…] / istartsWith[…] / endsWith[…] | проверка начала / конца строки; i-форма — без учёта регистра; PG $1 LIKE $2||'%' / $1 LIKE '%'||$2 (для i-форм — ILIKE) |
isSubstring[…] / isISubstring[…] | вхождение подстроки с учётом / без учёта регистра; PG $1 LIKE '%'||$2||'%' (для isISubstring — ILIKE) |
isWordInCSV[…] | разбивает второй аргумент по запятой и проверяет точное совпадение первого аргумента с одним из элементов; PG string_to_array($2,',') + = ANY |
getWord[TEXT, TEXT, INTEGER] / wordCount[TEXT, TEXT] | getWord — фрагмент с номером p3 (с 1) после разбиения по разделителю, NULL при выходе за границы; wordCount — число фрагментов; PG (string_to_array($1,$2))[$3] / array_length(string_to_array($1,$2),1) |
splitPart[STRING, STRING, INTEGER] | num-й фрагмент (с 1) после разбиения по разделителю; пустая строка при выходе за границы; PG split_part($1,$2,$3) |
regexpReplace[STRING, STRING, STRING, STRING] | замена в source совпадений POSIX-шаблона pattern на replace; четвёртый аргумент — флаги (например g — заменять все вхождения, а не только первое); PG regexp_replace($1,$2,$3,$4) |
regexPatternMatch[TEXT, STRING] | соответствие строки POSIX-регулярному выражению с учётом регистра; PG — оператор ~ |
onlyDigits[TEXT] | признак, что строка (без крайних пробелов) состоит только из цифр; PG trim($1) ~ '^[0-9]*$' |
array[STRING, STRING, INTEGER] | табличная обёртка: разворачивает строку с разделителем в построчное множество значений; параметр row — итерационная переменная (как у array[JSON, INTEGER], см. ниже); PG unnest(string_to_array($1,$2)) |
Свойства-признаки (startsWith, endsWith, isSubstring, isWordInCSV, regexPatternMatch, onlyDigits и подобные) объявлены как FORMULA NULL BOOLEAN и возвращают TRUE, когда условие выполнено, и NULL в противном случае (а не FALSE) — по принятому в lsFusion соглашению для условий.
Для генерации идентификаторов и буфера обмена: generateUUID[] → generatedUUID[], generatePassword[INTEGER, BOOLEAN, BOOLEAN] → generatedPassword[], copyToClipboard[TEXT], а также cookie: getCookie[STRING] → cookie[], setCookie[STRING, STRING, JSON].
Числа
Часть свойств — обёртки над числовыми функциями PostgreSQL, часть — чистые арифметические формулы, не обращающиеся к функциям СУБД. В строках, где свойство соответствует выражению PostgreSQL, оно приведено в конце описания после ; PG.
| Свойство | Что делает |
|---|---|
abs[…] / delta[…, …] | модуль числа / модуль разности двух значений; PG abs($1) / abs($1-$2) |
min[…, …] / max[…, …] | минимум / максимум двух значений; вычисляются арифметически, без обращения к функциям СУБД; PG ($1+$2-abs($1-$2))/2 / ($1+$2+abs($1-$2))/2 |
floor[…] / floor[…, …] | округление вниз; форма с двумя аргументами — вниз до кратного шагу $2; PG floor($1) / floor($1/$2)*$2 |
ceil[…] / ceil[…, …] | округление вверх; форма с двумя аргументами — вверх до кратного шагу $2; PG ceiling($1) / ceiling($1/$2)*$2 |
round[…, …], roundM1 / round0 … round6 | округление значения, приведённого к numeric, до n знаков после запятой; n может быть отрицательным (roundM1 = round(…,-1)), round0…round6 фиксируют n от 0 до 6; PG round(CAST($1 AS numeric),$2) |
trunc[…, …] | усечение до n знаков после запятой без округления; PG trunc($1,$2) |
mod[…, …] / divideInteger[…, …] / divideIntegerNeg / divideIntegerRnd | остаток от деления; divideInteger — целочисленное деление, divideIntegerNeg — целочисленное деление с округлением к нулю для отрицательных, divideIntegerRnd — деление с округлением результата до целого; PG mod($1,$2) (остальные — приведения к integer и round) |
sqr[…] / sqrt[…] / power[…, …] | квадрат (без функции СУБД), квадратный корень, возведение в степень (результат — DOUBLE); PG $1*$1 / sqrt($1) / power($1,$2) |
ln[…] / exp[…] | натуральный логарифм (DOUBLE) / экспонента; PG ln($1) / exp($1) |
percent[…, …] / share[…, …] | процент от суммы / доля от целого в процентах; вычисляются арифметически, без обращения к функциям СУБД; PG $1*$2/100 / $1*100/$2 |
bitwiseAnd[…, …] / bitwiseOr[…, …] / bitwiseNot[…] | побитовые И / ИЛИ / НЕ над целыми; PG $1 & $2 / $1 | $2 / ~ $1 |
toInteger[…] / toNumeric[…] / toNumericNull[…] | разбор значения в INTEGER / NUMERIC[38,19]; при неразбираемом значении toInteger и toNumeric возвращают 0, а toNumericNull — NULL; PG convert_to_integer($1) / convert_to_numeric($1) / convert_to_numeric_null($1) — функции, создаваемые платформой в БД |
toChar[…, …] | форматирование числа или даты в строку по шаблону PostgreSQL; PG to_char($1,$2) |
Итерация
iterate[INTEGER, INTEGER, INTEGER] — рекурсивная развёртка диапазона целых от from до to. count[INTEGER, INTEGER] — частный случай: iterate(i, 1, count). См. аналогичный iterate для дат в Time.
Цвет
colorToHexString[COLOR] — представление цвета в виде '#RRGGBB': цвет приводится к целому и переводится в шестнадцатеричную строку функцией to_hex, затем отбрасываются первые два разряда (старший байт — компонента прозрачности) и добавляется префикс #; PG '#'||substring(to_hex($1::integer),3).
Полнотекстовый поиск
Обёртки над функциями полнотекстового поиска PostgreSQL. Доступны только на PostgreSQL.
| Свойство | Что делает |
|---|---|
toTsVector[STRING, STRING] / toTsVector[STRING] | построение TSVECTOR из текста по словарю: текст разбивается на нормализованные лексемы (первый аргумент приводится к regconfig); форма с одним аргументом использует словарь english; NULL-текст заменяется пустой строкой; PG to_tsvector($1::regconfig, coalesce($2,'')) |
toTsQuery[STRING, STRING] / toTsQuery[STRING] | построение TSQUERY: текст запроса разбирается в дерево лексем и операторов по словарю; форма с одним аргументом использует english; PG to_tsquery($1::regconfig, coalesce($2,'')) |
setWeight[TSVECTOR, STRING] | пометка всех лексем вектора весом-меткой 'A'–'D' (второй аргумент приводится к типу "char"); PG setweight($1, $2::"char") |
tsRank[TSVECTOR, TSQUERY] / tsRank[…, INTEGER] | рейтинг релевантности вектора запросу по частоте совпавших лексем (DOUBLE); третий аргумент — битовая маска нормализации по длине документа; PG ts_rank($1,$2) / ts_rank($1,$2,$3) |
tsRankCD[TSVECTOR, TSQUERY] / tsRankCD[…, INTEGER] | то же по модели cover density — по плотности совпадений, с учётом близости лексем; третий аргумент — маска нормализации; PG ts_rank_cd($1,$2) / ts_rank_cd($1,$2,$3) |
tsRankLN[TSVECTOR, TSQUERY, DOUBLE] | tsRank с логарифмической поправкой на длину вектора: tsRank(v,q) / (1 + ln(длина v) / ln(base)); составное свойство, не отдельная функция СУБД |
numNode[TSQUERY] | число узлов (лексем и операторов) в разобранном запросе; PG numnode($1) |
Свойства доступа к JSON
Этот раздел собирает обёртки над PostgreSQL-функциями jsonb_*, читающие значения из существующего JSON. Дополняют оператор JSON, который, наоборот, строит JSON из свойств или формы. Большинство объявлены через оператор FORMULA.
| Свойство | Что возвращает |
|---|---|
field[JSON, STRING] | значение по ключу как JSON; PG jsonb_extract_path($1,$2) |
field[JSON, STRING, STRING] | значение по пути из двух ключей как JSON; PG jsonb_extract_path($1,$2,$3) |
field[JSON, STRING, STRING, STRING] | значение по пути из трёх ключей как JSON; PG jsonb_extract_path($1,$2,$3,$4) |
fieldText[JSON, STRING] / […, STRING, STRING] / […, STRING, STRING, STRING] | то же, что field, но как STRING; PG jsonb_extract_path_text(…) |
array[JSON, INTEGER] | элемент массива по индексу как JSON; параметр-индекс — это и итерационная переменная; PG jsonb_array_elements($1) — разворачивает JSON-массив в набор строк |
arrayText[JSON, INTEGER] | то же, что array, но как STRING; PG jsonb_array_elements_text($1) |
arrayElement[JSON, INTEGER] | элемент массива по индексу с 1 как сырая строка (jsonb → text); PG ($1)->($2-1) (оператор ->) |
map[JSON, STRING] | значение для каждой пары ключ-значение JSON-объекта как JSON; параметр-ключ — итерационная переменная; PG jsonb_each($1) — разворачивает JSON-объект в набор пар ключ-значение |
mapText[JSON, STRING] | то же, что map, но как STRING; PG jsonb_each_text($1) |
merge[JSON, JSON] | рекурсивное слияние двух JSON: объекты сливаются по ключам рекурсивно, при конфликте неключевых значений побеждает значение из второго аргумента; PG jsonb_recursive_merge($1,$2) — функция платформы |
canonicalizeJSON[JSONFILE, BOOLEAN] / canonicalizeJSON[JSONFILE] → canonicalizedJSON[] | каноническая нормализация JSON-файла; короткая форма эквивалентна canonicalizeJSON(file, TRUE) (закодировать unicode-символы); действие (INTERNAL), не функция СУБД |
field[JSON, STRING ...] и fieldText[JSON, STRING ...] — скалярные обёртки над jsonb_extract_path и jsonb_extract_path_text. Возвращают значение по указанному пути из одного, двух или трёх ключей. Различаются только классом результата: field отдаёт JSON для дальнейшей композиции (например, передать результат в array или в следующий field), fieldText сразу даёт STRING. Для путей глубже трёх ключей используется композиция field от field.
array[JSON, INTEGER] и arrayText[JSON, INTEGER] — табличные обёртки над jsonb_array_elements и jsonb_array_elements_text. Параметр INTEGER row не упоминается в SQL-тексте, поэтому платформа сама проставляет в него номер строки через ROW_NUMBER() OVER () — специальный shortcut для не-параметризованного INTEGER-параметра с именем row. На практике параметр играет двойную роль: индекс для прямого обращения (array(j, 1) — первый элемент) и итерационная переменная в выражениях вроде array(j, INTEGER o), где o объявлен на месте и пробегает все индексы массива.
map[JSON, STRING] и mapText[JSON, STRING] — табличные обёртки над jsonb_each и jsonb_each_text, отдающие пары (ключ, значение) JSON-объекта. Параметр STRING key не упомянут в SQL-тексте и потому становится колонкой ключа результата; имя key совпадает с именем колонки в результате jsonb_each.
arrayElement[JSON, INTEGER] — отдельный шорткат для прямого доступа по индексу. Реализован через PG-оператор ->, на входе ожидает 1-based индекс и сам сдвигает его к 0-based. Возвращает STRING — текстовое представление jsonb. Полезен для логирования и отладки, когда нужен сырой вид элемента, а не разобранное значение.
Локальные файловые свойства
Удобные пустые LOCAL-свойства для каждого типового файлового класса: file[], wordFile[], imageFile[], pdfFile[], dbfFile[], rawFile[], excelFile[], textFile[], csvFile[], htmlFile[], jsonFile[], xmlFile[], tableFile[]. Подходят как промежуточные буферы для импорта / экспорта без объявления собственных LOCAL.
Журналирование
printToLog[TEXT, STRING, STRING] и его перегрузки пишут сообщение в лог сервера. Параметры — текст сообщения, имя логгера (по умолчанию 'system') и уровень (по умолчанию 'info').
Диалоговые формы
dialogString, dialogDate, dialogInteger, dialogNumeric — готовые однообъектные формы для запроса у пользователя значения соответствующего класса. Используются как DIALOG dialog<...> OBJECTS ... INPUT DO { ... }.
Среда выполнения
serverAvailableProcessors[], serverFreeMemoryMB[], serverTotalMemoryMB[], serverMaxMemoryMB[] — заполняются действием readServerMemory[]. Показывают параметры JVM сервера: количество доступных процессоров и три характеристики кучи.
Язык
- Оператор
JSON— построение JSON-значения из свойств или формы. - Оператор
FORMULA— синтаксис, через который объявлены большинство свойств модуля. - Оператор
IMPORT— чтение JSON-файла в форму или черезFIELDS … DO.
Связано
System modules— общий список модулей платформы.Custom formula (FORMULA)— механизм, через который объявлены большинство свойств модуля.Time— отдельный модуль работы со временем.