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

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

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

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

img36a

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

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

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

img36c

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

script saving

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

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

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

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

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

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

    img36b

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

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

Подробнее о разметке в текстовой ячейке читайте здесь.

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

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

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

    script editor 1

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

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

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

img52

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

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

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

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

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

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

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

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

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

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

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

Несколько примеров секций кода с базовыми конструкциями Julia представлены в статье Базовые конструкции.

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

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

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

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

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

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

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

    in scripts par

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

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

interactive scripts par 3

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

  • Добавить вложенный параграф 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 такие элементы реализуются с помощью масок кодовых ячеек.

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

Маски кодовых ячеек — это инструмент, который превращает переменные в кодовых ячейках скриптов Engee в интерактивные элементы управления. Для создания таких масок используется синтаксис из имени элемента управления, комментария # и параметра, начинающегося с @. Некоторые из элементов имеют свои параметры для настройки поведения.

В Engee реализованы следующие интерактивные элементы управления:

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.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. Базовые конструкции

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

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

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