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 program management.

`script` methods

engee.script.edit
engee.script.run
engee.script.@include

# engee.script.edit — Function

engee.script.edit(path::String)

Opens the interactive script located at the path path (including the filename and extension). If no such file exists, an empty script file is created at the specified path and opened in the editor. If the extension specified in path differs from ‘.ngscript’, the function will return the error ‘ ErrorException("path should end with '.ngscript' extension")` ’.

Examples

# Opens the script file.ngscript in the Script Editor Engee
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 : the absolute path to the script.
isolate::Bool = false: if set to true, the script is executed in an isolated environment. By default, it is set to false. If set to false, the script is executed in the main user environment (the Main module). All variables declared globally or at the top level are preserved after execution. If set to true, the script runs in a temporary isolated environment. All variables created during execution are not retained after the script has finished.

Examples

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

x = 10
y = try
    push!(a, :foo)  # We try to add:foo to the existing array `a`
    5               # If everything is OK — we set y to 5
catch _
    3               # If an error occurred — we set y to 3
end
x + y               # We return the sum of x and y

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

a = Symbol[:bar, :baz]  # Original array
x = y = 0               # Variables before the script runs
(engee.script.run("foo.ngscript"), x, y, a)
# ⇒ (15, 10, 5, [:bar, :baz, :foo])
# The script modified the variables x and y, and also added :foo to the array a

When run in a sandboxed environment (isolate = true), the script will not affect external variables and the changes will not be saved:

# Original array
a = Symbol[:bar, :baz]

# Variables before the script was run
x = y = 0
(engee.script.run("foo.ngscript"; isolate = true), x, y, a)
# ⇒ (13, 0, 0, [:bar, :baz])
# The script did not affect external variables — the changes were not saved

# engee.script.@include — Macro

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

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

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

Arguments

path::String: the absolute path to the script.

Examples

Consider the file foo.ngscript containing the following code snippet:

if z > 10
    return z
else
    push!(b, z)      # Add the value `z` to the array `b`
    return maximum(b)
end

This code cannot be executed directly via engee.script.run until the variables z and b have been defined. However, using @include, it can be embedded within a function where these variables are already defined:

function foo(z, b)

# `z` and `b` the script will refer to the arguments of this function
engee.script.@include "foo.ngscript"
end

function bar(z)
# Original array
b = Int[3, 11]
(foo = foo(z, b), b = b)
end

# The script is embedded in the function `foo`, the variables `z` and `b` are substituted automatically
(bar(5), bar(15))
# ⇒ ((foo = 11, b = [3, 11, 5]), (foo = 15, b = [3, 11]))

In the code, the macro @include inserts the code from foo.ngscript directly into the body of the function foo, so variables from the script automatically refer to values within the function’s scope.

Software script management

script methods

Useful links

`script` methods