Software script management

All engee.script programme control methods are presented here. For an introduction to engee methods, please refer to the article Public methods of programme management.

Methods of `Engee.script`.

Engee.Script.edit
Engee.Script.run
Engee.Script.@include

# Engee.Script.edit — Function

engee.script.edit(path::String)

Opens notepad for editing. If an extension other than .ngscript is specified, it displays the error ErrorException("path should end with .ngscript extension"). If the file does not exist, it is created.

Example

# Открыть скрипт `file.ngscript` в Редакторе скриптов
engee.Script.edit( "file.ngscript" )

# Engee.Script.run — Function

engee.script.run(path::String; isolate::Bool = false)

Runs the script at the specified path. Returns the result of the last top-level expression in the script.

Arguments

path::String: absolute path to the script.
isolate::Bool = false: (optional) if true, the script is executed in an isolated environment. The default is false. If isolate = false, the script is executed in the main user environment (Main module). All variables declared globally or at the top level are preserved after execution. With isolate = true, the script is executed in a temporary isolated environment. All variables created at runtime are not saved after the script terminates.

Example

Consider the file foo.ngscript with a single code cell:

x = 10
y = try
    push!(a, :foo)  # Пытаемся добавить :foo в существующий массив `a`
    5               # Если все хорошо — присваиваем y значение 5
catch _
    3               # Если произошла ошибка — присваиваем y значение 3
end
x + y               # Возвращаем сумму x и y

Execution in a user environment (isolate = false) will change the variables x and y, and add :foo to the array а:

a = Symbol[:bar, :baz]  # Исходный массив
x = y = 0               # Переменные до запуска скрипта
(engee.script.run("foo.ngscript"), x, y, a)
# ⇒ (15, 10, 5, [:bar, :baz, :foo])
# Скрипт изменил переменные x и y, а также добавил :foo в массив a

When executed in an isolated environment (isolate = true) the script will not affect the external variables and the changes will not be saved:

a = Symbol[:bar, :baz]  # Исходный массив
x = y = 0               # Переменные до запуска скрипта
(engee.script.run("foo.ngscript"; isolate = true), x, y, a)
# ⇒ (13, 0, 0, [:bar, :baz])
# Скрипт не повлиял на внешние переменные — изменения не сохранились

# Engee.Script.@include — Macro

engee.script.@include(path::String)

Inserts the contents of the specified script in the place where the macro is called. Unlike engee.script.run, which executes the script separately, the @include macro lexically inserts the script code at the call point.

If @include is used inside a block of code (for example, inside a function), variables in the script that are not declared as global will be interpreted in the lexical environment where the macro call is located. This allows, for example, to use variables from an external function inside the included script - the script will see them as local variables of the current scope.

Arguments

path::String: absolute path to the script.

Example

Consider the file foo.ngscript with a code cell:

if z > 10
    return z
else
    push!(b, z)      # Добавляем значение z в массив b
    return maximum(b)
end

This code cannot be executed directly through engee.script.run, unless the variables z and b are defined. But from @include it can be embedded into a function where these variables are already defined:

function foo(z, b)
# `z` и `b` из скрипта будут ссылаться на аргументы этой функции
engee.script.@include "foo.ngscript"
end

function bar(z)
b = Int[3, 11]     # Исходный массив
(foo = foo(z, b), b = b)
end

(bar(5), bar(15))
# ⇒ ((foo = 11, b = [3, 11, 5]), (foo = 15, b = [3, 11]))
# Скрипт встроен в функцию `foo`, переменные `z` и `b` подставлены автоматически

In the code, the macro @include substitutes the code from foo.ngscript directly into the body of the function foo, so the variables from the script automatically reference values from the scope of the function.