Синтаксис

Общие положения

Места применения кода

Код применяется для вычисления значений полей, для выполнения действий и для определения форматирования полей, строк и таблицы.

Также коды используются при дублировании строк и вызове панелей в селектах.

Код может храниться как текст в поле и быть вызван при исполнении другого кода с передачей ему необходимых параметров функцией exec.

Возврат результата работы кода

Код обрабатывается построчно, значение возвращается из строки начинающейся с = : независимо от ее расположения.

= : 10 + 10

// Результат: 20

Обращения

Варианты обращения к значениям

$ — строка кода.
# — значение ячейки.
$# — переменная внутри кода.
#$ — значение ячейки, определенной кодом.
$$ — вызывает строку кода, которую определил другой код. Изящный способ ветвления!
@ — обращение к нестрочным полям в других таблицах.

Обращение к значениям строк внутри кода

Обращение к значению строки кода осуществляется через $codename.

Именование строки осуществляется как codename:. Имена строк регистрозависимы и могут состоять из латинских букв, цифр и нижнего подчеркивания.

Для визуального обозначения порядка вызова строк кода или иерархичности можно использовать табуляции. Так же поддерживаются однострочные комментарии начинающиеся с //.

= : $code1 + $code2
    // Комментарий
    code1: 10
    code2: 10

// Результат: 20

Обращение к значениям полей

Обращение к значению поля текущей таблицы осуществляется через #fieldname. Значение полей берется в момент начала выполнения кода.

Обращение к полям в другой таблице осуществляется через функции вида select.

Если выполнение кода идет в поле строчной части таблицы, и значение берется из поля строчной части, то значение берется из текущей строки.

Обращения из секции код — обращение возможно только к полям, вычисленным в соответствии с порядком пересчета до расчета поля в котором исполняется код.
Обращения из секций код действия, код селекта, форматирование ячейки, строки, таблицы и кода графиков — обращение возможно к любым полям.

Обращение к предыдущему значению

При выполнении изменений в поле возможно обращение к предыдущему значению через #old.fieldname. Это работает в кодах и кодах действия.

В момент создания строки или таблицы #old.fieldname равен пустоте.

Предыдущее значение — это то значение, с которым поле вошло в текущий цикл пересчета в соответствии с единицей пересчета.

Обращение к отображению для Селектов

Обращение к отображаемому значению, а не к основанию поля для селекта и селект-дерева осуществляется через #s.fieldname.

Получение значений зафиксированных полей

Возможно получить признак фиксирования значения для полей с кодами — true или false используя #h.fieldname.

Для зафиксированных полей можно получить расчетное значение через #c.fieldname.

Определить кодом name поля

Возможно обращение к полю, определенному строкой кода при помощи #$whatfield. Таким образом значение в строке whatfield: будет определять name поля из которого брать данные.

Уровень вложенности для Селект-дерева

Обращение #l.name_field может быть использовано для любого поля селект-дерево — возвращает уровень вложенности значения в поле.

Подробнее про tree-view ⟶

id	fieldname1	fieldname2
1	10 (C=5) [HAND]	15

example1: #fieldname1 + #fieldname2

// Результат: 25

example2: #h.fieldname1

// Результат: true

example3: #c.fieldname1

// Результат: 5

example4: #$whatfield

    whatfield: "fieldname2"

// Результат: 10

Сокращенное обращение

Для обращения к нестрочным полям в другой таблице используется сокращенное обращение @tablename.header_or_footer_fieldname.

@ — это короткое написание селекта. @ не будет взята при начале выполнения кода как #field_name, а будет взята в порядке своей очереди.

Если обращение идет к строчной части таблицы, то используется такие записи:

@table.field[#value] аналогично:

=: select(table: 'table'; field: 'field'; where: 'id' = #value)

@table.field[[#value]] аналогично:

=: selectList(table: 'table'; field: 'field'; where: 'id' = #value)

@table.field.where[#value] аналогично:

=: select(table: 'table'; field: 'field'; where: 'where' = #value)

@table.field.where[[#value]] аналогично:

=: selectList(table: 'table'; field: 'field'; where: 'where' = #value)

Такие обращения могут быть использованы внутри функций:


=: select(table: 'table'; cycle: @cycles.id.status[#status]; field: 'field')

Обращение к элементу списка

Обращение $list[1], #listfieldname[1], $list[$#iterator] или $list[$codename] вернет значение элемента списка аналогично функции listitem.

Номер или ключ элемента списка внутри квадратных скобок могут быть обозначены всеми возможными способами.

Если элемента с запрошенным ключом не окажется - выражение вернет null.

Если структура, к которой вы обращаетесь содержит технические символы или символы вне латинского алфавита, то путь внутри скобок должен быть заключен в кавычки!

$list["Представление"], #listfieldname["Ссылка"], $list["date.settings"] или $list["so$iska"]

// Через функцию:
example1: listitem(list: $list1; item: 1)

list1: listcreate(item: "A"; item: "B"; item: "C") 

// Результат: "B"

// Через быстрый вызов:
example2: $list2[1]

list2: listcreate(item: "A"; item: "B"; item: "C") 

//Результат: "B"

Подобным образом можно обратиться к вложенным элементам на произвольной глубине:

id	fieldname3
1	["b", "c"]

example3: strAdd(str: $code3_1[0]; str: #fieldname3[1]; str: $code3_2[test])

 code3_1: listCreate(item: "a"; item: "b")
 code3_2: rowCreate(field: "test" = "z")

// Результат: "acz"

example4: $code4[0][test]

 code4: listCreate(item: $row4)
    row4: rowCreate(field: "test" = "abc")

//Результат: "abc"

Обращение к секции (колонке) списка

Похожим образом работает обращение к секции. Если вам необходимо получить список по ключу из списка ассоциированных массивов, то помимо функции listSection можно использовать синтаксическую запись $row[[key]], #rowfieldname[[key]], $row[[$#key]] или $row[[$key]].

example5: $listList[[1]]
    listList: listCreate(item: $l1; item: $l2)
        l1: listCreate(item: 1; item: 2; item: 3)
        l2: listCreate(item: 4; item: 5; item: 6)

// Результат: [2,5]

Функции

Вызов функции в коде

Скобки являются признаком функции.

Параметры функций могут определяться в любом порядке. В ряде случаев порядок параметров внутри функции определяет возвращаемый ей результат.

Хорошей практикой является размещение параметров функции в том порядке, в котором они указаны в автозаполнении функции, а также соблюдение пробельных интервалов.

ВСЕ ПАРАМЕТРЫ ФУНКЦИИ ДОЛЖНЫ БЫТЬ ЗАПОЛНЕНЫ. ЕСЛИ ПАРАМЕТР НЕ ИСПОЛЬЗОВАН — ОН ДОЛЖЕН БЫТЬ УДАЛЕН!

tablename

id	fieldname1	fieldname2
1	10	10

example1: select(table: 'tablename'; field: 'fieldname1'; where: 'id' = 1)

// Результат: 10

Желтым — обозначены name-параметры в которые передаются name полей или таблиц (в зависимости от параметра). Name может быть передан любым способом. Если он указывается вручную, то при наборе в одинарных кавычках '' будет срабатывать механизм поиска name в текущей схеме базы данных.
Жирным — обозначены обязательные параметры функции.
Подчеркнутым — обозначены множественные параметры, которые могут быть указаны в вызове функции несколько раз. Порядок вызова важен, так-как выборки и сортировки будут применены именно в том порядке, в котором они будут указаны в вызове функции.

ФУНКЦИЯ НЕ МОЖЕТ БЫТЬ ВЫЗВАНА ВНУТРИ ДРУГОЙ ФУНКЦИИ — ЭТО ДЕЛАЕТСЯ ЧЕРЕЗ ОТДЕЛЬНУЮ СТРОКУ!

example2: select(table: 'tablename'; field: 'fieldname1'; where: 'price' = $what_id)

    what_id: round(num: #price; type: "up"; step: 1; dectimal: 0)

// Результат: 10

Автозаполнение функций

При наборе функции осуществляется ее поиск в базе функций.
При постановке скобки ( или ) после названия функции она автоматически заполняется.
При постановке ; и начале ввода следующего параметра осуществляется поиск доступных параметров.
При наборе названий в одинарных кавычках '' осуществляется поиск поля в таблице источнике.
При постановке вместо открывающей скобки / или ; осуществляется поиск параметра. Последующий параметр также ищется через / или ;. В конце набора при постановке скобки ( или ) синтаксис автоматически заменяется на валидный.

Хоткеи

TAB — переводит на следующий параметр функции.
SHIFT + TAB — если курсор стоит перед закрывающей ;, то будет выделен следующий параметр до закрывающей ;.
SHIFT + TAB — если курсор стоит в любом другом месте параметра, то будет выделен текущий параметр включая ;.
Для Mac аналогичным хоткеем является OPT+TAB.

Переменные

Переменные внутри кода

Такие переменные существуют только при выполнении конкретного кода внутри одной итерации вычисления.

Эти переменные могут определятся некоторыми функциями, например var или while.

Для обращения к ним используется $#paramname.

Существует список зарезервированных переменных, возвращающих определенные значения:

$#ntn — возвращает name текущей таблицы.
$#nci — возвращает номер текущего цикла.
$#nth — возвращает hash текущей таблицы. (только для временных таблиц).
$#lc — возвращает пустой список.

$#nd — возвращает текущую дату в Y-m-d.

example2: dateAdd(date: $#nd; days: 10; format: "Y-m-d")

// Результат: "2019-08-10"

$#ndt — возвращает текущую дату в Y-m-d H:i.
$#ndts — возвращает текущее время с секундами Y-m-d H:i:s.
$#nu - возвращает id текущего пользователя.
$#nr — возвращает список id ролей текущего пользователя.
$#nfv — возвращает значение текущего поля (неприменимо в секции код).
$#onfv — возвращает предыдущее значение текущего поля.
$#ids — возвращает список id строк, выбранных галочками (доступна только в коде-действия Кнопок).
$#nh — возвращает текущий хост.
$#nf — возвращает name текущего поля.
$#nti — возвращает id текущей таблицы.
$#nl — возвращает специальный символ переноса строки.
$#duplicatedId — возвращает id строки, с которой было осуществлено дублирование (только для секции КОД при добавлении во вставляемой строке при дублировании). В противном случае возвращает 0.
$#ih — доступна только в строке добавлния. Позволяет передать хэш строки добавления во временную таблицу и потом из нее вернуть данные в поле строки добавления используя параметр hash функции set. Или выполнить set в поле строки добавления без вызова временной таблицы. Используется в строке добавления совместно с параметром поля buttonActiveOnInsert.
$#rows — доступна только в коде форматирования и в коде графиков — возвращает rowlist с содержимым строк, отображаемых на странице.
$#changes — переменная доступная только в коде-действия таблицы. Информация об изменившихся полях в таблице в виде row:
- deleted — id удаленных строк.
- restored — id восстановленных строк.
- added — id добавленных строк.
- changed — row ключами которого являются id измененных строк, а значениями список из name полей измененных в строке.
- reorderedIds — id строк с измененным порядком по n.
Пример получения списка id строк, в которых произошло изменение в поле field_1:
```
=: rowKeys(row: $listf)
        listf: listFilter(list: $#changes[changed]; key: "value" = "field_1")
```
$#slPro — только в PRO. Переменная доступна только в коде действия Кнопки аналогично $#ids. получает выделенные мышкой поля аналогично структуре $#changes.
$#kanban — доступна только в panel-view в режиме канбан при выполнении h_kanban_html_code.
Переменные в коде могут создаваться функциями:

example1: while(action: $set; limit: 10)
    set: var(name: "count"; value: $plus; default: 0)
        plus: $#count + 1

// Результат: 10

Глобальные и процессные переменные

Глобальные переменные

Глобальная переменная может быть записана функцией globVar.

Доступна из любого кода.

Вызывается — @$name_glob_var

При запросе переменной через globVar может быть установлена блокировка запроса для использования в конкурентных процессах, проверяющих и изменяющий значение переменной.

Например если false то устанавливаем true и по завершении процесса меняем на false. Если true, то ничего не делаем. В момент проверки и записи true может вклиниться конкурирующий процесс и записать true, таким образом будут исполняться два процесса, хотя второй должен был быть отклонен.

Что бы этого избежать при запросе значения устанавливается блокировка, которая снимается по истечении указанного времени, либо при записи переменной или запросе ее значения с передачей block: false.

Блокировка на чтение работает только для запросов, устанавливающих или снимающих блокировку чрез параметр block. При получении переменной @$name_glob_var ее значение будет возвращено сразу.

Переменная записывается сразу вне транзакционной модели!

Запись вне транзакционной модели может привести к залипанию переменной в случаях, когда процесс стартовал и переменная была установлена, а потом транзакция откатилась.

Рекомендуется использовать вместе с tryCatch — в этом случае в catch записывается обнуление переменной или установку ее в стартовое значение, которое произойдет если транзакция будет отменена.

Процессные переменные

Процессная переменная может быть записана функцией procVar.

Доступна из любого кода.

Вызывается — $@name_proc_var.

Существует только в рамках одного процесса php.

При закрытии iframe по параметру Кнопки Закрыть после выполнения процесс завершается и происходит refresh таблицы в окне ниже. Тк это новый процесс, то при выполнении кодов форматирования таблицы в нижнем окне заданная ранее переменная будет равна пустоте!

Передача переменных в строку кода

Используя конструкцию $codename{var: "varname" = value} можно передать значение value переменной varname в строку codename и дальше.

varname тоже может быть задан кодом.

example1: strAdd(str: $code1{var: "fruit" = "apple"}; str: " and "; str: $code1{var: "fruit" = "banana"})
    code1: strAdd(str: "green "; str: $#fruit)

// Результат: "green apple and green banana"

Таким образом можно обрабатывать элементы массива:

example2: $split{var: "fruits" = $code2}

 split: if(condition: $#fruits != $#lc; then: $str1; else: "")
    str1: strAdd(str: $#fruits[0]; str: ", "; str: $split{var: "fruits" = $fruitsCut})
        fruitsCut: listCut(list: $#fruits; cut: "first"; num: 1)

code2: listCreate(item: "apple"; item: "banana"; item: "lemon")

// Результат: "apple, banana, lemon, "
// Данный пример приведен здесь как пример, эта конкретная операция выполняется функцией listJoin().

Можно передать несколько переменных через ; — $code1{var: "fruit" = "apple"; var: "type" = "2"}

Порядок вычисления

Порядок вычисления строк кода

Вычисление осуществляется от секции = : в порядке каскадного обращения к значениям других строк слева направо.

Если к одной строке идет несколько обращений она будет рассчитана столько раз, сколько к ней обратились.

1.| = : $code1 + $code2 + $code2

2.| code1: 10 / 2
3.| code2: 10 * 2

// Результат: 45
// Количество раз вычислений:
// Строка 1 — 1 раз
// Строка 2 — 1 раз
// Строка 3 — 2 раза

При стандартном обращении к значению строки кода codename: оно рассчитывается при каждом обращении.

Для того, что бы рассчитать значение один раз и сократить требуемые на расчет ресурсы процессора необходимо использовать ~codename:.

tablename h_fieldname = 1

example2: while(action: $set2; limit: 10)
set2: var(name: "count"; value: $plus2; default: 0)
plus2: $#count + $step2
~step2: select(table: 'tablename'; field: 'h_fieldname')

// Результат 10
// Строка step2: будет вычислена только один раз при первом обращении.
// При отсутствии ~ перед step2: select() будет выполнен 10 раз.

На обращениях к значениям полей #fieldname можно не экономить, они самые быстрые.

Будьте внимательны при использовании ~ в циклических вычислениях так-как можно по ошибке зафиксировать результат вычисления первого цикла.

Порядок математических операций в строке

В Totum математические операции выполняются в последовательности записи слева направо. Скобки не учитываются, так как являются принадлежностью функций.

ВНИМАНИЕ: по умолчанию порядок выполнения отличается от принятой математической записи! Скобки для математических операций не используются, так как являются признаком функций.

example1: 10 + 10 / 2

// Результат: 10

// Код для реализации математической записи (32 + 10) / 2 = 21 будет выглядеть так:

example2: $sum / 2
    sum: 32 + 10

// Результат: 21

MATH — математический порядок

Для того, чтобы произвести вычисление так, как это принято в математике, используется следующая запись:


example3: math`$A3 + $B3 / 2`

A3: 10
B3: 10

// Результат: 15

math можно использовать и внутри функций:


example4: if(condition: math`$A4 + $B4 / 2` = 15; then: true; else: false)

A4: 10
B4: 10

// Результат: true

MATH обрабатывает скобки как часть математической формулы:

example5: math`2 / ($A5 + $B5)`

A5: 10
B5: 10

// Результат: 0.1

Типы

Типы данных

5 — целое число или десятичная дробь. Знаком десятичного деления в кодах является . (точка). При вводе, в поле можно использовать , — при сохранении запятая будет преобразована в точку.
"str" — utf-8 строковое значение, желательно не рассчитывать на большие значения, так-как полностью передается в веб-интерфейс. При заполнении через интерфейс не содержит переводов строки.
true, false — булевы значения.
'name' — name-параметр. Аналогичен строке, используется в коде с одинарными кавычками, на которые срабатывают подсказки автоматического заполнения.
"" — пустая строка или пустота.
null — пустое значение. Не может быть введено вручную, но может быть результатом работы некоторых функций и полей.
[] — пустой список. Является результатом работы функций, некоторых полей и быстрой переменной $#lc.

Типы хранения данных

Одно значение — самый простой тип хранения.
- Например:
```
"mouse" или 5 или true или false
```
Список значений — упорядоченный список значений с числовыми ключами.
- Таблица в одну колонку и несколько строк, у каждой строки номер.
- Ключи идут от 0 с шагом в 1.
- Например
```
[1,2,3,4,5]
```
Ассоциированный массив — объект вида ключи-значения.
- Одна строка из таблицы с несколькими колонками.
- Например:
```
{"data":"Строковые интервалы","type":"Тип","version":"Версия 1"}
```
Список ассоциированных списков — список объектов вида ключ-значение.
- Таблица с несколькими строками и несколькими колонками.
- Строки нумеруются от 0 с шагом в 1.
- Колонки обозначаются буквенно-числовыми ключами.
- Например:
```
[{"data":null,"type":"Расчетная в дереве"},{"data": null,"type": "Расчетная в цикле"}]
```

Операторы

Операторы сравнения

= — равно или пересечение.
!= — не равно или отсутствие пересечения. Набирается как ! + =.
> — больше.
< — меньше.
>= — больше или равно. Набирается как > + =.
<= — меньше или равно. Набирается как < + =.
== — полностью равно для списков, ассоциированных массивов и списков ассоциированных массивов. Набирается как = + =.
!== — полностью неравно для списков, ассоциированных массивов и списков ассоциированных массивов. Набирается как ! + = + =.

По результатам сравнений есть отдельный раздел документации!

Математические операторы

+ — сложение.
- — вычитание.
* — умножение.
/ — деление.
^ — степень.

Разное

Логическая конструкция cond

cond: cond`($A=1 && $B=1) || ($A=2 && $B=2)`
A: "..."
B: "..."

Возвращает true или false.

&& — и.
|| — или.

Скобки — группировка. Пример выше читается как: «Если A=1 и B=1 или A=2 и B=2 тогда true».

Может быть использована внутри функций:

cond_2: if(condition: cond`$line_1 != 0 || $line_2 != 0`; then: 100; else: 0)

line_1: 10
line_2: 0

// Результат = 100.

Конкатенация строк

Конкатенация выполняется функцией strAdd или сахаром str:

str: str`"#" + $#nfv ++ "—" ++ #field`

// Результат: #34 — закрыт

+ — склеивает без пробела.
++ — склеивает добавляя пробел.

Текстовое включение в код

Если вам нужно включить в код часть текста с переносами строк, то это можно сделать таким образом:

=: $text_in_code

```text_in_code:text
Some text in this section.

With automatic lines separators.
```

Если вы хотите, что бы эта секция была подсвечена как totum-код то надо указать так:

=: $code

```code:totum
=: set(table: 'table_name'; field: 'field_name' = $some_value)

some_value: 10
```

Переменные внутри этого блока кода и названия строк не будут пересекаться с переменными и строками в хостовом коде.

QROW в where-параметрах

В where параметрах функций может быть использована специальная конструкция qrow, которая позволяет задать различные условия поиска для БД.

=: select(table: $#ntn; field: 'id'; where: qrow`'field_1' > 100 || 'field_2' = true`)

qrow поддерживает операторы:

&& — И
|| — ИЛИ
() — группировка

Операторы сравнения аналогичны операторам остальной системы.

Name-параметры указываются в одинарных кавычках 'field_1'

В сравнении 'field_1' > 100 обязательно должен быть использован один name-параметр.

Name-параметры могут быть использованы в обоих сторонах сравнения 'field_1' > 'field_2' — выбрать строки где field_1 > field_2.

Пример с группировкой:

=: select(table: $#ntn; field: 'id'; where: qrow`'(field_1' > 100 && 'field_3' = true) || 'field_2' = true`)

// field_1 больше 100 и field_3 = true или field_2 равно true

На одном уровне операторы должны быть одинаковыми!

Это ошибочный пример:

=: select(table: $#ntn; field: 'id'; where: qrow`'(field_1' > 100 && 'field_3' = true) || 'field_2' = true && filed_4 = false`)

// Результат ОШБК! тк на верхнем уровне используются II и &&

Правильно будет:

=: select(table: $#ntn; field: 'id'; where: qrow`'((field_1' > 100 && 'field_3' = true) || 'field_2' = true) && filed_4 = false`)

// (field_1 больше 100 и field_3 = true или field_2 равно true) и filed_4 = false

По прежнему может быть использовано несколько where, они работают в режиме И:

=: select(table: $#ntn; field: 'id'; where: qrow`'(field_1' > 100 && 'field_3' = true) || 'field_2' = true`; where: 'filed_4' = false)

// (field_1 больше 100 и field_3 = true или field_2 равно true) и filed_4 = false

ВАЖНО!

Если у вас в сравнениях используется id в режиме И то запрос будет исполняться сильно быстрее, если поставить это условие в отдельный where вперед

=: select(table: $#ntn; field: 'id'; where: 'id' != #id; where: qrow`'(field_1' > 100 && 'field_3' = true) || 'field_2' = true`)

// id не равно id текущей строки и (field_1 больше 100 и field_3 = true или field_2 равно true)

⟵ сюда туда ⟶