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.

`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 along the path in the editor path (including name and extension). If there is no such file, then an empty script file is created using the specified path and opened in the editor. If specified in path the extension is different from '.ngscript', then the function will return an error ErrorException("path should end with '.ngscript' extension").

Examples

# Opens the file.ngscript script in the Engee Script Editor
engee.script.edit( "file.ngscript" )

# engee.script.run — Function

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

Runs the script on the specified path. Returns the result of the last upper-level expression in the script.

Arguments

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

Examples

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

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

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

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

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

# The original array
a = Symbol[:bar, :baz]

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

# engee.script.@include — Macro

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

Inserts the contents of the specified script in the place of the macro call. In contrast to engee.script.run, which executes the script separately, a macro @include lexically substitutes the script code in place of the call.

If @include If it is used inside a code block (for example, inside a function), then 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: the absolute path to the script.

Examples

Consider the file foo.ngscript with a code cell:

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

This code cannot be executed directly via engee.script.run, until the variables are defined z and b. But with @include it can be embedded in a function where these variables are already defined:

function foo(z, b)

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

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

# The script is embedded in the `foo` function, 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 macro code @include substituting the code from foo.ngscript right into the function body foo therefore, variables from the script automatically refer to values from the scope of the function.

Software script management

script methods

Useful links

`script` methods