Script editor

A Script (or interactive script) is a file containing several commands that are executed sequentially.

Working with scripts in Engee takes place in the Engee window Script Editor . To open the editor, click the icon in the workspace:

img36a

Working with scripts

Creating a script

To create a script, press + in the script editor and select the desired format:

img36c -> img36c 1

By default, Engee scripts are in ngscript format, but you can work with jl and ipynb format as well:

jl is the format of Julia scripts. The script editor supports refactoring and running scripts in this format;
ipynb is a universal Python scripting format. The script editor supports all available functionality on a level with ngscript.

You can create a script using file browser file browser 7 . Right-click in an empty field of the file window to bring up the context menu. From the menu, select Create и Script:

script saving

Opening an existing script

To open a script in a file browser window:

double-click with the left mouse button;
right-click to open the context menu and select Open:

Script Editor Sections

In the script editor, you can create a code cell or a text cell.

To create cells, move the mouse pointer to the upper edge of the script editor window to display the cell selection button:

+ Code - creates a new section with a code (code cell). In this cell all possibilities of writing code in programming language Engee are available.
+ Text - creates a new section with text (text cell). In this section you can add and format any description, pictures, tables, links, etc.

New sections can be added anywhere in the workspace of the script editor (e.g., at the beginning, end, or between two other sections).

Section with code

Let’s create a code section and look at its interface:

Run and advance - executes the code in this section.
Run to end - executes all sections with a code below the selected section.
Run before cell - executes all sections with a code above the selected section.
Change position of output - selects the position for output. Has two options:
1. 4.1. Code output on the right - Outputs the result on the right for a specific section.
2. 4.2. Hide code output - hides the result selection for a specific section.
Mask - adds a mask for the selected code cell (see details in the following table). Code cell masks).
Move down - moves the section one section down.
Move up - moves the section one up.
Copy - copies a section.
Paste - pastes a section.
Remove - deletes a section.

In a code cell you can also:

Execute the highlighted code section (PCM on the highlighted line or hotkey Shift+F7):
Execute the current line with the cursor (Ctrl+Shift+F5 on Windows/Linux or Shift+⌘+F5 on macOS).

Text section

Let’s create a section with text:

Double-click on the section to open the input field, now you can enter the desired text in the cell that appears. Markdown, LaTeX and HTML markup languages are used to format text. For more information about markup in a text cell, see Text markup in Engee.

Let’s look at the interface of the text section:

text interface script

Bold - bold text.
Italic - makes the highlighted text italicised.
Strikethrough - strikethrough the selected text.
Show/hide header - adds a heading using the grid character # or deletes it.
Add bullet list - adds two bulleted list items.
Add numeric list - adds two items to a numbered list.
Insert table - adds a table. The table can be edited in the section input field.
Insert quote - inserts a template for a quotation.
Insert link - inserts a template for a link.
Insert code section - inserts a template for code. This code cannot be executed because it is not specified in the code section and is for visual purposes only.
Insert image - opens your computer’s file system to select images.
Insert horizontal line - inserts a horizontal dividing line.

Similar to code sections in text cells, uses the following commands: move, copy, paste, and delete.

Hiding cells and content

To hide cells in the Engee script editor, a text cell must be marked as a paragraph using Markdown and have the appropriate level and location:

the cell must contain a Markdown-formatted header from level 1 to level 6 (, #, etc.).
a cell with a lower level header must be below the top level header.

interactive par 01

You can hide it in the script editor:

code cells (have the lowest heading level);
text cells without headers (also the lowest level);
text cells with lower level headings.

If a text cell with a first-level heading has, for example, 10 code cells below it, this forms one section that will be hidden. When the 11th cell appears - a new paragraph with a first-level heading or the same level as the first text cell - a new section starts.

The headings of text cells from the first to the sixth level form a Contents :

in scripts par

In the content you can:

Add a nested paragraph - adds a text cell with a title to the level above. For example, if a nested paragraph is added to a first level text cell (), it will become a second level cell (#). When the maximum nesting is reached (the last text cell has a sixth level heading) - the button is not available.
Run paragraph - starts execution of all cells with the code of the selected paragraph. If the paragraph does not contain any code cells - the button is unavailable.
Delete paragraph - deletes the selected paragraph. Headers and code cells nested in the paragraph section will not be deleted.

Starting/stopping scripts

To start or stop a script, click the Start or Stop button. The buttons are located on the start panel of the script:

To run the code section, click on the button Execute. The result will be displayed below the section:

You can collapse the code execution output into a more compact form in case it takes up too much space. To do this, use the Limit output button:

in long hide 1

To return the output to its previous state use the Disable output button.

To clear the results of executing code sections in the script, click on the icon Clear output icon on the script launch panel.

Saving the script

To save the script, click the icon Save icon on the script launch panel.

img5a

If you plan to open scripts written in Engee in third-party systems (e.g. Jupyter), it is recommended to change the extension of the saved script using the Engee file browser:

Autosave

The autosave feature allows you to automatically save changes to interactive scripts, preventing data loss. To enable this feature, open the script editor window or any interactive script, click the triplet in the upper right corner and enable autosave:

scripts autosaving 1

Three autosave options are available in the menu:

afterDelay - the script is automatically saved after a certain delay time. When this parameter is selected, the delay is 1000 ms by default.
onFocusChange - the script is automatically saved after the editor loses focus. This means that when switching to another Engee window, changes in the script editor will be saved;
onWindowChange - the script is automatically saved when switching from the browser tab on which Engee is open to another tab. This means that when you change the browser tab from Engee to any other tab, changes in the script editor will be saved.

Code cell masks

Interactive controls are often used for more convenient parameterization and visual representation of the code. These can be various data entry fields, lists, sliders, etc. In Engee such elements are implemented using code cell masks.

Working with code cell masks is described in detail in the following example Masking code cells of interactive scripts.

Code Cell Mask masks script pool 1 is a tool that turns variables in code cells of Engee scripts into interactive controls. Masking allows you to completely hide the code of the cells, while keeping them fully functional.

To create a code cell mask, hover over the code cell and select the following from the tools Mask masks script pool 1 и Add field:

masks script pool 2

Adding a field will open an interactive menu. Depending on the field type, the add menu changes its options (the available variable types change and/or additional settings appear). A total of four types are available:

Select (dropdown) is a dropdown list of options with a single choice. When you click on the dropdown list, you are given the option you want to select.
Drop-down list example
Create an empty code cell and add a drop-down list mask with the following settings:

After saving, the code cell will change its appearance:

The contents of the code cell will fill in the following code:
dropdown_variable = "1" # @param ["1","2","3"] {allow-input:true}
By modifying this code you can change the contents of the mask without accessing the tool Mask .
Input (input) is a window for inputting data.
Example of input field
Create an empty code cell and add an input field mask with the following settings:

Here playholder is the text that is displayed inside the input field until any data is entered. It is usually used to give a hint as to what information needs to be entered. For example, for a date field, Enter the date in the format YYYYY-MM-DD would work fine.

We get the following option:

The contents of the code cell will fill the following code:
date_of_birth = "2025-01-16" # @param {type:"date",placeholder:"Введите дату в формате ГГГГ-ММ-ДД"}
Based on the name of the variable, we need the date of birth, not today’s date (set automatically by the system), so let’s change the date to the correct one. You can change the date both in the mask and in the code cell itself, just by setting the correct date instead of the specified "2025-01-16".

By removing the mask date, you can see that the placeholder works correctly and improves the user experience:

Markdown - is a Markdown markup representation for implementing code masks.

masks script pool 5

Example Markdown

Create an empty code cell and add a Markdown mask with the following settings:

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)|Заглушка выходного порта.|

We get the following variant:

masks script pool 13

The contents of the code cell will fill the following code:

# @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 (slider) is a representation of a slider with selection of values from a specified range. Selection of a value from the range is realised by moving the slider along the scale.
Slider example
Create an empty code cell and add a slider mask with the following settings:

Get the following option:

The contents of the code cell will fill the following code:
уровень_громкости = 0 # @param {type:"slider",min:0,max:100,step:1}

To edit a superimposed mask, move the mouse cursor over it and click the icon masks script pool 15 . Since the code of masked cells is fully working - you can edit not only the mask, but also the cell code.

To add a new field, hide the code or hide the mask again use the context menu of the mask masks script pool 1 :

masks script pool 16

Creating masks without the editor interface

This section describes some features of masked cells syntax that may be useful in your practice. It is recommended to read this section even if you do not plan to create masks manually.

In some cases, it may be more convenient to create a mask without resorting to the mask creation context menu masks script pool 1 , so let’s look at this process in more detail.

To create masks manually, you need to recreate the syntax yourself, consisting of:

The name of the control. Some of the elements have their own parameters to configure the behaviour..;
A # comment and parameters starting with @.

The code cell mask controls are already described above, there are four of them in total. Each element has its own approach for manual creation. Let’s consider examples for each of them:

dropdown is a dropdown list of options with one option selected. When you click on the dropdown list, you are given the option you want to select.

Description of dropdown list types and subtypes

string is a drop-down list type that allows you to select one of the predefined string options. Such an interface element is often used to select a single value from a set of possible values represented as strings. It comes in two subtypes - editable and not_editable:
- string_editable is a subtype of the drop-down list that allows you to enter text to filter existing options. Example:
  dropdown_string_editable = "test3" # @param ["test1", "test2", "test3"] {allow-input:true}
- string_not_editable is a subtype of dropdown list that doesn’t allow text to be entered or edited. Example:
  dropdown_string_not_editable = "test2" # @param ["test1", "test2", "test3"]
raw is a type of drop-down list that allows you to use arbitrary and non-standard data as options. Unlike a standard drop-down list, which usually contains only strings, raw can include complex data structures such as numbers, lists, objects, etc.
- raw_editable is a subtype of drop-down list that allows arbitrary and non-standard data to be entered and edited. Example:
  dropdown_raw_editable = 1 # @param [1, "input_raw", "false", '"string"'] {type:"raw", allow-input:true}
- raw_not_editable is a subtype of dropdown list that doesn’t allow arbitrary and non-standard data to be entered and edited. Example:
  dropdown_raw_not_editable = 1 # @param [1, "input_raw", "false", '"string"'] {type:"raw"}

input is a window for entering data.

Description of input window types

You can use different types of input fields to collect information, and each type is suitable for a particular kind of data.

boolean is an input type that allows you to choose between two values: True (true) or False (false). Example:
```
input_boolean = False # @param {type:"boolean"}
```
date is an input type that allows you to select a date from a calendar. Example:
```
input_date = "2024-07-20" # @param {type:"date"}
```
integer is an input type that allows only integers to be entered. Values entered in the mask will be reflected in the code and vice versa. Example:
```
input_integer = 123 # @param {type:"integer"}
```
number is an input type that allows numeric values (including fractional numbers) to be entered. Example:
```
input_number = 10.0 # @param {type:"number"}
```
raw is an input type that allows arbitrary input of any data type (strings, lists, dictionaries and other objects). Example:
```
input_raw = input_string # @param {type:"raw"}
```
string is an input type that allows you to enter text data. Example:
```
input_string = "text" # @param {type:"string"}
```

slider is a representation of a slider (slider) with selection of values from a specified range. Selection of value from the range is realised by moving the slider along the scale.

Description of slider types

slider_integer - slider type, which allows selecting only integer values in the specified range.
```
slider_integer = 2 # @param {type:"slider", min:1, max:5, step:1}
```
slider_number is a slider type that allows you to select values, including fractional numbers, within a given range.
```
slider_number = 0.0346734 # @param {type:"slider", min:-1, max:1, step:0.00000001}
```

markdown is a markup representation of the Markdown language for implementing code masks.

Description of markdown features

The @markdown code mask is used to implement:

Headings

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

markdown mask 1

Tables

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

markdown mask 2

Lists:

Numbered

# @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

Labelled

# @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

Classic markup

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

markdown mask 5

Methods of programme control

Using public methods (see Public methods of programme management for details), Engee scripts can be controlled without resorting to the script editor interface. These commands are designed to work with script editor files and are invoked via engee.script. Let’s look at each of these methods:

@include - includes (embeds) script code instead of calling a macro.

For example, we have a script named new.ngscript, in which the code a = 1 is written. Let’s create another script new_1.ngscript, in which we refer to the first script by the absolute path via @include:

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

The result of the code execution of the first script a = 1 will be included in the second script and will be equal to 1.

The @include command and the code it embeds must not be in the same script. Otherwise, a cyclic dependency error will occur when @include must call itself.

edit - opens the script for editing.

Opens the script for editing at the specified path. If there is no script file, it is created automatically.

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

If an extension other than .ngscript is specified, it will throw an ErrorException("path should end with.ngscriptextension") error.

extract_code - extracts code at the specified path.

Extracts code from the script at the specified path. For example, for script new.ngscript with code a = 1:

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

Output:

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

Read more about other public methods used in scripts in the article Software control of modelling.

Script editor

Working with scripts

Creating a script

Opening an existing script

Script Editor Sections

Section with code

Text section

Hiding cells and content

Starting/stopping scripts

Saving the script

Autosave

Code cell masks

Creating masks without the editor interface

Methods of programme control

Useful links