Документация Engee

Редактор скриптов

Скрипт (или интерактивный скрипт) — это файл, содержащий несколько последовательно выполняющихся команд.

Работа со скриптами в Engee происходит в окне редактора скриптов interactive script icon. Чтобы открыть редактор, нажмите иконку в рабочем пространстве:

img36a

Работа со скриптами

Создание скрипта

Чтобы создать скрипт, нажмите + в редакторе скриптов и выберите нужный формат:

img36c → img36c 1

По умолчанию скрипты Engee имеют формат ngscript, однако можно работать и с форматом jl и ipynb:

  • jl — формат скриптов на языке Julia. Редактор скриптов поддерживает рефакторинг и запуск скриптов в этом формате;

  • ipynb — универсальный формат написания скриптов на языке Python. Редактор скриптов поддерживает весь доступный функционал на уровне с ngscript.

Можно создать скрипт с помощью файлового браузера file browser 7. Кликните правой кнопкой мыши в пустом поле окна файлов для вызова контекстного меню. В меню выберите Создать и Скрипт:

script saving

Открытие существующего скрипта

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

  • дважды нажмите левой кнопкой мыши;

  • правой кнопкой мыши откройте контекстное меню и выберите Открыть:

    img36b

Секции редактора скриптов

В редакторе скриптов можно создать кодовую или текстовую ячейки.

Для создания ячеек подведите указатель мыши к верхней кромке окна редактора скриптов для появления кнопки выбора ячейки:

  • + Код — создает новую секцию с кодом (кодовую ячейку). В этой ячейке доступны все возможности написания кода на языке программирования Engee.

  • + Текст — создает новую секцию с текстом (текстовая ячейка). В этой секции можно добавлять и форматировать любое описание, картинки, таблицы, ссылки и т.д.

    script editor 1

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

Секция с кодом

Создадим секцию с кодом и рассмотрим ее интерфейс:

img52

  1. Выполнить и перейти — выполняет код в данной секции.

  2. Выполнить до конца — выполняет все секции с кодом ниже выбранной секции.

  3. Выполнить до ячейки — выполняет все секции с кодом выше выбранной секции.

  4. Поменять положение результата работы кода — выбирает позицию для вывода. Имеет два варианта:

    1. 4.1. Вывод результата справа — выводит результат справа для конкретной секции.

    2. 4.2. Спрятать вывод результата — прячет выбор результата для конкретной секции.

  5. Маска — добавляет маску для выбранной кодовой ячейки (подробнее см. ниже).

  6. Переместить ниже — перемещает секцию на одну вниз.

  7. Переместить выше — перемещает секцию на одну вверх.

  8. Копировать — копирует секцию.

  9. Вставить — вставляет секцию.

  10. Удалить — удаляет секцию.

В кодовой ячейке также можно:

  • Выполнить выделенный участок кода (ПКМ по выделенной строке или горячая клавиша Shift+F7):

    code sting completion

  • Выполнить текущую строку с курсором (Ctrl+Shift+F5 на Windows/Linux или Shift+⌘+F5 на macOS).

Секция с текстом

Создадим секцию с текстом:

img44

Дважды кликнем по секции для открытия поля ввода, теперь можно вводить нужный текст в появившейся ячейке. Для форматирования текста используются языки разметки Markdown, LaTeX и HTML. Подробнее о разметке в текстовой ячейке читайте здесь.

Рассмотрим интерфейс текстовой секции:

text interface script

  1. Полужирный — выделяет текст полужирным шрифтом.

  2. Курсив — делает выделенный текст курсивом.

  3. Зачеркнутый — зачеркивает выделенный текст.

  4. Показать/скрыть заголовок — добавляет заголовок с помощью знака решетки # или удаляет его.

  5. Добавить маркированный список — добавляет два пункта маркированного списка.

  6. Добавить нумерованный список — добавляет два пункта нумерованного списка.

  7. Вставить таблицу — добавляет таблицу. Таблица может быть отредактирована в поле ввода секции.

  8. Вставить цитату — вставляет шаблон для цитаты.

  9. Вставить ссылку — вставляет шаблон для ссылки.

  10. Вставить секцию с кодом — вставляет шаблон для кода. Данный код не может быть выполнен, поскольку не задан в секции с кодом и служит только для визуального восприятия.

  11. Вставить картинку — открывает файловую систему вашего компьютера для выбора изображений.

  12. Вставить горизонтальную линию — вставляет горизонтальную разделительную линию.

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

Скрытие ячеек и содержание

Для скрытия ячеек в редакторе скриптов Engee, текстовая ячейка должна быть отмечена как параграф с помощью Markdown и иметь соответствующий уровень и расположение:

  • ячейка должна содержать заголовок в формате Markdown от 1 до 6 уровня (#, ## и т.д.).

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

interactive par 01

В редакторе скриптов можно скрыть:

  • кодовые ячейки (имеют наименьший уровень заголовка);

  • текстовые ячейки без заголовков (также наименьший уровень);

  • текстовые ячейки с заголовками более низкого уровня.

    interactive scripts par 3

Если у текстовой ячейки с заголовком первого уровня под ней находится, например, 10 кодовых ячеек — это образует одну секцию, которая будет скрыта. Когда появляется 11-я ячейка — новый параграф с заголовком первого уровня или такого же уровня, что и первая текстовая ячейка, то начинается новая секция.

Заголовки текстовых ячеек с первого по шестой уровень образуют Содержание content button 1:

in scripts par

В содержании можно:

  • Добавить вложенный параграф content button 2 — добавляет текстовую ячейку с заголовком на уровень выше. Например, если вложенный параграф добавляется к текстовой ячейке первого уровня (#), то он станет ячейкой второго уровня (##). При достижении максимальной вложенности (последняя текстовая ячейка имеет заголовок шестого уровня) — кнопка недоступна.

  • Запустить параграф content button 3 — запускает исполнение всех ячеек с кодом выбранного параграфа. Если параграф не содержит кодовых ячеек — кнопка недоступна.

  • Удалить параграф content button 4 — удаляет выбранный параграф. Заголовки и ячейки с кодом, вложенные в секцию параграфа, удалены не будут.

Запуск/остановка скриптов

Для запуска или остановки скрипта нажмите кнопку Пуск или Стоп. Кнопки находятся на панели запуска скрипта:

img53

Чтобы запустить секцию с кодом, нажмите на кнопку Выполнить. Результат отобразится ниже под секцией:

img 49 1

Можно свернуть вывод исполнения кода в более компактную форму в случае, если он занимает слишком много места. Для этого воспользуйтесь кнопкой Ограничить вывод colapse button:

in long hide 1

Чтобы вернуть вывод в прежнее состояние используйте кнопку Раскрыть вывод colapse button 2.

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

img62

Сохранение скрипта

Чтобы сохранить скрипт, нажмите иконку Сохранить на панели запуска скрипта.

img5a

Если планируется открытие скриптов, написанных в Engee, в сторонних системах (например, Jupyter), то рекомендуется изменить расширение сохраненного скрипта при помощи файлового браузера Engee:

img5 1

Автосохранение

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

scripts autosaving 1

В меню доступны три варианта автосохранения:

  1. afterDelay — скрипт автоматически сохраняется через определенное время задержки. При выборе этого параметра, задержка по умолчанию составляет 1000 мс.

  2. onFocusChange — скрипт автоматически сохраняется после потери фокуса редактором. Это означает, что при переключении на другое окно Engee, изменения в редакторе скриптов будут сохранены;

  3. onWindowChange — скрипт автоматически сохраняется при переключении с вкладки браузера, на которой открыт Engee, на другую вкладку. Это означает, что при смене вкладки браузера с Engee на любую другую, изменения в редакторе скриптов будут сохранены.

Маски кодовых ячеек

Для более удобной параметризации и наглядного представления кода зачастую используются интерактивные элементы управления. Ими могут выступать различные поля ввода данных, списки, слайдеры и т.д. В Engee такие элементы реализуются с помощью масок кодовых ячеек.

Работа с масками кодовых ячеек подробно рассмотрена в примере Маскирование кодовых ячеек интерактивных скриптов

Маска кодовых ячеек masks script pool 1 — это инструмент, который превращает переменные в кодовых ячейках скриптов Engee в интерактивные элементы управления. Наложение маски позволяет полностью скрыть код ячеек, при этом сохранив их полную работоспособность.

Для создания маски кодовой ячейки наведите курсор на кодовую ячейку и в инструментах выберите Маска masks script pool 1 и Добавить поле:

masks script pool 2

Добавление поля откроет интерактивное меню. В зависимости от типа поля, меню добавления меняет свои опции (меняются доступные типы переменной и/или появляются дополнительные настройки). Всего доступно четыре типа:

  • Выпадающий список (dropdown) — это выпадающий список опций с выбором одного варианта. При нажатии на выпадающий список дается выбрать нужный вариант.

    masks script pool 4

    Пример выпадающего списка

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

    masks script pool 7

    После сохранения кодовая ячейка сменит свой вид:

    masks script pool 8

    При этом содержимое кодовой ячейки заполнит следующий код:

    dropdown_variable = "1" # @param ["1","2","3"] {allow-input:true}

    Изменяя этот код можно менять содержимое маски без обращения к инструменту Маска masks script pool 1.

  • Поле ввода (input) — это окно для ввода данных.

    masks script pool 3

    Пример поля ввода

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

    masks script pool 9

    Здесь плейсхолдер — это текст, который отображается внутри поля ввода, пока не будут введены какие-либо данные. Обычно используется, чтобы дать подсказку о том, какую информацию нужно ввести. Например, для поля даты отлично подойдет вариант Введите дату в формате ГГГГ-ММ-ДД.

    Получим следующий вариант:

    masks script pool 10

    При этом содержимое кодовой ячейки заполнит следующий код:

    date_of_birth = "2025-01-16" # @param {type:"date",placeholder:"Введите дату в формате ГГГГ-ММ-ДД"}

    Исходя из названия переменной нам нужно дату рождения, а не сегодняшнюю дату (проставленную системой автоматически), поэтому поменяем дату на нужную. Поменять дату можно как в маске, так и в самой кодовой ячейке, просто выставив корректную дату вместо указанных "2025-01-16".

    При удалении даты маски можно увидеть, что плейсхолдер работает корректно и улучшает пользовательский опыт:

    masks script pool 11

  • Markdown — это представление разметки на языке Markdown для реализации кодовых масок.

    masks script pool 5

    Пример Markdown

    Создадим пустую кодовую ячейку и добавим маску Markdown со следующими настройками:

    masks script pool 12

    # Построение синусойды

Для построения простой синусойды используйте следующие блоки:

|Блоки в модели|Описание|
| --------- | -------- |
|[Sine wave](https://engee.com/helpcenter/stable/ru/base-lib-sources/sine-wave.html)|Генератор синусоидального сигнала.|
|[Terminator](https://engee.com/helpcenter/stable/ru/base-lib-sinks/terminator.html)|Заглушка выходного порта.|

    Получим следующий вариант:

    masks script pool 13

    При этом содержимое кодовой ячейки заполнит следующий код:

    # @markdown # Построение синусойды
# @markdown
# @markdown Для построения простой синуосойды используйте следующие блоки:
# @markdown
# @markdown |Блоки в модели|Описание|
# @markdown | --------- | -------- |
# @markdown |[Sine wave](https://engee.com/helpcenter/stable/ru/base-lib-sources/sine-wave.html)|Генератор синусоидального сигнала.|
# @markdown |[Terminator](https://engee.com/helpcenter/stable/ru/base-lib-sinks/terminator.html)|Заглушка выходного порта.|

  • Слайдер (slider) — это представление ползунка (слайдера) с выбором значений из заданного диапазона. Выбор значения из диапазона реализован перемещением ползунка по шкале.

    masks script pool 6

    Пример слайдера

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

    masks script pool 14

    Получим следующий вариант:

    masks script pool 15

    При этом содержимое кодовой ячейки заполнит следующий код:

    уровень_громкости = 0 # @param {type:"slider",min:0,max:100,step:1}

Для редактирования наложенной маски наведите на нее курсор мыши и нажмите иконку masks script pool 15. Поскольку код маскированных ячеек является полностью рабочим — можно редактировать не только маску, но и код ячейки.

Для добавления нового поля, скрытия кода или скрытия маски повторно воспользуйтесь контекстным меню маски masks script pool 1:

masks script pool 16

Создание масок без интерфейса редактора

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

В некоторых случаях может быть удобнее создавать маску не прибегая к контекстному меню создания маски masks script pool 1, поэтому рассмотрим этот процесс подробнее.

Для создания масок вручную нужно самостоятельно воссоздать синтаксис, состоящий из:

  • Имени элемента управления. Некоторые из элементов имеют свои параметры для настройки поведения.;

  • Комментария # и параметра, начинающегося с @.

Элементы управления масок кодовых ячеек уже описаны выше, их всего четыре. Для ручного создания каждого элемента свой собственный подход. Рассмотрим примеры для каждого из них:

dropdown — это выпадающий список опций с выбором одного варианта. При нажатии на выпадающий список дается выбрать нужный вариант.

Описание типов и подтипов выпадающего списка

  • string — тип выпадающего списка, который позволяет выбрать одну из заранее определенных строковых опций. Такой элемент интерфейса часто используется для выбора одного значения из множества возможных, представленных в виде строк. Бывает двух подтипов — editable и not_editable:

    • string_editable — подтип выпадающего списка, который позволяет вводить текст для фильтрации существующих опций. Пример:

      dropdown_string_editable = "test3" # @param ["test1", "test2", "test3"] {allow-input:true}

      dropdown string editable

    • string_not_editable — подтип выпадающего списка, который не позволяет вводить и редактировать текст. Пример:

      dropdown_string_not_editable = "test2" # @param ["test1", "test2", "test3"]

      dropdown string not editable

  • raw — это тип выпадающего списка, который позволяет использовать произвольные и нестандартные данные в качестве опций. В отличие от стандартного выпадающего списка, который обычно содержит только строки, raw может включать сложные структуры данных, такие как числа, списки, объекты и т.д.

    • raw_editable — подтип выпадающего списка, который позволяет вводить и редактировать произвольные и нестандратные данные. Пример:

      dropdown_raw_editable = 1 # @param [1, "input_raw", "false", '"string"'] {type:"raw", allow-input:true}

      dropdown raw editable

    • raw_not_editable — подтип выпадающего списка, который не позволяет вводить и редактировать произвольные и нестандратные данные. Пример:

      dropdown_raw_not_editable = 1 # @param [1, "input_raw", "false", '"string"'] {type:"raw"}

      dropdown raw not editable

input — это окно для ввода данных.

Описание типов окна ввода

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

  • boolean — это тип ввода, который позволяет выбирать между двумя значениями: True (истина) или False (ложь). Пример:

    input_boolean = False # @param {type:"boolean"}

    input boolean

  • date — это тип ввода, который позволяет выбрать дату из календаря. Пример:

    input_date = "2024-07-20" # @param {type:"date"}

    input date

  • integer — это тип ввода, который позволяет вводить только целые числа. Введенные в маске значения будут отражены в коде и наоборот. Пример:

    input_integer = 123 # @param {type:"integer"}

    input integer

  • number — это тип ввода, который позволяет вводить числовые значения (включая дробные числа). Пример:

    input_number = 10.0 # @param {type:"number"}

    input number

  • raw — это тип ввода, который позволяет вносить произвольные данные любого типа данных (строки, списки, словари и другие объекты). Пример:

    input_raw = input_string # @param {type:"raw"}

    input raw

  • string — это тип ввода, который позволяет вводить текстовые данные. Пример:

    input_string = "text" # @param {type:"string"}

    input string

slider — это представление ползунка (слайдера) с выбором значений из заданного диапазона. Выбор значения из диапазона реализован перемещением ползунка по шкале.

Описание типов слайдера

  • slider_integer — тип слайдера, который позволяет выбирать только целые значения в заданном диапазоне.

    slider_integer = 2 # @param {type:"slider", min:1, max:5, step:1}

    slider 2

  • slider_number — тип слайдера, который позволяет выбирать значения, включая дробные числа, в заданном диапазоне.

    slider_number = 0.0346734 # @param {type:"slider", min:-1, max:1, step:0.00000001}

    slider 1

markdown — это представление разметки на языке Markdown для реализации кодовых масок.

Описание возможностей markdown

С помощью кодовой маски @markdown реализуются:

  • Заголовки

    # @markdown # Заголовок первого уровня
# @markdown ## Заголовок второго уровня

    markdown mask 1

  • Таблицы

    # @markdown | Опция | Описание |
# @markdown | ----- | -------- |
# @markdown | текст |   текст  |

    markdown mask 2

  • Списки:

    • Нумерованные

      # @markdown 1. First item
# @markdown 2. Second item
# @markdown 3. Third item
# @markdown    1. Indented item
# @markdown    2. Indented item
# @markdown 4. Fourth item

      markdown mask 3

    • Маркированные

      # @markdown + Sub-lists are made by indenting 2 spaces:
# @markdown   - Marker character change forces new list start:
# @markdown     * Ac tristique libero volutpat at
# @markdown     * Facilisis in pretium nisl aliquet
# @markdown     - Nulla volutpat aliquam velit
# @markdown + Very easy!

      markdown mask 4

  • Классическая разметка

    # @markdown > Classic markup: :wink: :cry: :laughing: :yum:

    markdown mask 5

Методы программного управления

С помощью публичных методов engee.script можно управлять скриптами Engee не прибегая к интерфейсу редактора скриптов. Эти команды предназначены для работы с файлами редактора скриптов и вызываются через engee.script. Рассмотрим каждый из этих методов:

@include — включает (встраивает) код скрипта вместо вызова макроса.

Например, у нас есть скрипт с именем new.ngscript, в котором написан код — a = 1. Создадим другой скрипт new_1.ngscript, в котором обратимся к первому по абсолютному пути через @include:

engee.script.@include("/user/new.ngscript")

Результат выполнения кода первого скрипта a = 1 будет включен во второй скрипт и будет равен 1.

Команда @include и встраиваемый им код не должны находиться в одном скрипте. В ином случае возникнет ошибка циклической зависимости, когда @include должен вызвать сам себя.
edit — открывает скрипт на редактирование.

Открывает скрипт для редактирования по указанному пути. Если файла скрипта нет, то он создается автоматически.

engee.script.edit("/user/new.ngscript")
Если указано расширение иное от .ngscript, то выведет ошибку ErrorException("path should end with.ngscriptextension").
extract_code — извлекает код по указанному пути.

Извлекает код из скрипта по указанному пути. Например, для скрипта new.ngscript с кодом a = 1:

engee.script.extract_code("/user/new.ngscript")

Вывод:

:($(Expr(:toplevel, :(#= none:1 =#), :(a = 1))))

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

Полезные ссылки

  1. Разметка текста в Engee

  2. Публичные методы программного управления

  3. Программирование