# Environment Module

The Environment provides base functions for all script interpreters. It is automatically loaded by any interpreter upon startup.

## Method Overview

Method | Description
--- | ---
execute() | Execute script code.
exit() | Terminates script execution immediately.
getModule() | Resolves a loaded module and returns the Java instance.
getScriptEngine() | Get the current script engine instance.
help() | Open help page on addressed topic.
include() | Include and execute a script file.
loadJar() | Add a jar file to the classpath.
loadModule() | Load a module.
print() | Write a message to the output stream of the script engine.
printError() | Write a message to the error stream of the script engine.
readInput() | Read a single line of data from the default input stream of the script engine.
wrap() | Wrap a java instance.

## Methods

### execute

Object execute(Object data) throws ExecutionException

Execute script code. This method executes script code directly in the running interpreter. Execution is done in the same thread as the caller thread.

data
  code to be interpreted

result of code execution

ExecutionException
  when execution of data fails

### exit

void exit([Object value]) throws ExitException

Terminates script execution immediately. Code following this command will not be executed anymore.

value
  return codeOptional: defaults to <rg.eclipse.ease.modules.ScriptParameter.nul>.

ExitException
  always

### getModule

Object getModule(String name)

Resolves a loaded module and returns the Java instance. Will only query previously loaded modules.

name
  name of the module to resolve

resolved module instance or `null`

### getScriptEngine

IScriptEngine getScriptEngine()

Get the current script engine instance.

IScriptEngine instance

### help

void help([String topic])

Open help page on addressed topic. If the given topic matches a method or field from a loaded module, the definition will be opened. If the topic is unknown, a search in the whole eclipse help will be launched.

topic
  help topic to open (typically a function name)Optional: defaults to <null>.

### include

Object include(String filename) throws ExecutionException

Include and execute a script file. Quite similar to eval(Object) a source file is opened and its content is executed. Multiple sources are available: "workspace://" opens a file relative to the workspace root, "project://" opens a file relative to the current project, "file://" opens a file from the file system. All other types of URIs are supported too (like http:// ...). You may also use absolute and relative paths as defined by your local file system.

filename
  name of file to be included

result of include operation

ExecutionException
  when included code fails

### loadJar

boolean loadJar(Object location) throws MalformedURLException

Add a jar file to the classpath. Contents of the jar can be accessed right after loading. location can be an URL, a path, a File or an IFile instance. Adding a jar location does not necessary mean that its classes can be accessed. If the source is not accessible, then its classes are not available for scripting, too.

location
  URL, Path, File or IFile

`true` when input could be converted to a URL

MalformedURLException
  invalid URL detected

### loadModule

Object loadModule(String moduleIdentifier, [boolean useCustomNamespace]) throws ExecutionException

Load a module. Loading a module generally enhances the script environment with new functions and variables. If a module was already loaded before, it gets refreshed and moved to the top of the module stack. When a module is loaded, all its dependencies are loaded too. So loading one module might change the whole module stack.

When not using a custom namespace all variables and functions are loaded to the global namespace, possibly overriding existing functions. In such cases the Java module instance is returned. When useCustomNamespace is used a dynamic script object is created and returned.In such cases the global namespace is not changed. The namespace behavior is also used for loading dependencies.

moduleIdentifier
  name of module to load
useCustomNamespace
  set to `true` if functions and constants should not be stored to the global namespace but to a custom objectOptional: defaults to <als>.

loaded module instance

ExecutionException
  when execution of wrapped module code fails

### print

void print([Object text], [boolean lineFeed])

Write a message to the output stream of the script engine.

text
  message to writeOptional: defaults to <>.
lineFeed
  `true` to add a line feed after the textOptional: defaults to <ru>.

### printError

void printError([Object text], [boolean printOnce])

Write a message to the error stream of the script engine.

text
  message to writeOptional: defaults to <>.
printOnce
  If `true`, the text in parameter will be printed only once and ignored in other calls of this method. If `false`, it will be printed in all cases.Optional: defaults to <als>.

### readInput

String readInput([boolean blocking]) throws IOException

Read a single line of data from the default input stream of the script engine. Depending on the blocking parameter this method will wait for user input or return immediately with available data.

blocking
  `true` results in a blocking call until data is available, `false` returns in any caseOptional: defaults to <ru>.

string data from input stream or `null`

IOException
  when reading on the input stream fails

### wrap

Object wrap(Object toBeWrapped, [boolean useCustomNamespace]) throws ExecutionException

Wrap a java instance. Will create accessors in the target language for methods and constants defined by the java instance toBeWrapped. If the instance contains annotations of type WrapToScript only these will be wrapped. If no annotation can be found, all public methods/constants will be wrapped. As some target languages might not support method overloading this might result in some methods not wrapped correctly.

toBeWrapped
  instance to be wrapped
useCustomNamespace
  set to `true` if functions and constants should not be stored to the global namespace but to the return value onlyOptional: defaults to <als>.

wrapped object instance or java class when put to global namespace

ExecutionException
  when execution of wrapped code fails