Japanese English

Specifications of Vnano Engine

This page is the specification document of VnanoEngine class, Options, and so on.


Engine Methods

The following is the list of all methods of Vnano Engine (org.vcssl.nano.VnanoEngine class).

Signature void activate()
Description

Activates this engine. By this activation, the engine become available for executing scripts.

By default, the engine is activated automatically just before executing a script. However, when "AUTOMATIC_ACTIVATION_ENABLED" option is set to FALSE, the engine is NOT activated automatically. In such case, activate the engine manually at suitable timing (for details, see the description of "AUTOMATIC_ACTIVATION_ENABLED" option).

In this activation step, initialization procedures of all connected plug-ins (implemented as initializeForExecution() method in each plug-in) are processed. Hence, required time of this method depends on the number of the connected plug-ins, and implementations of them.

Parameters None
Return None
Exception VnanoException: Thrown when any error has occurred in the initialization procedure of any plug-in.
Signature void deactivate()
Description

Deactivates this engine. This deactivation canceles the state of the engine which is "activated" for executing scripts. It also performs some finalization procedures.

By default, the engine is deactivated automatically just after executing a script. However, when "AUTOMATIC_ACTIVATION_ENABLED" option is set to FALSE, the engine is NOT deactivated automatically. In such case, deactivate the engine manually at suitable timing (for details, see the description of "AUTOMATIC_ACTIVATION_ENABLED" option).

In this deactivation step, finalization procedures of all connected plug-ins (implemented as finalizeForTermination() method in each plug-in) are processed. Hence, required time of this method depends on the number of the connected plug-ins, and implementations of them.

Parameters None
Return None
Exception VnanoException: Thrown when any error has occurred in the finalization procedure of any plug-in.
Signature Object executeScript(String script)
Description Executes an expression or script code specified as an argument.
Parameters script: An expression or script code to be executed
Return The evaluated value of the expression, or the last expression statement in script code. If there is no evaluated value, returns null.
Exception VnanoException: Thrown when any error has detected for the content or the processing of the script.
Signature void terminateScript()
Description

Terminates the currently running script as soon as possible.

To be precise, the VirtualMachine (which is processing instructions compiled from the script) in the engine will be terminated after when the processing of a currently executed instruction has been completed, without processing remained instructions. Usually it ends in a moment, but sometimes it takes time. For example, it can't end while external function provided by a plug-in is being executed.

Also, if you used this method, call "resetTerminator()" method before the next execution of a new script, otherwise the next execution will end immediately without processing any instructions (By this behavior, even when a termination-request and an execution-request from another thread are conflict, the execution will be terminated certainly).

Parameters None
Return None
Exception

VnanoException: Thrown when any error has detected for the content or the processing of the script.

Note that, if any exceptions occurred on the finalization processes of the connected plug-ins, it will be throws by the currently running executeScript(String script) method, not by this method. This method throws the exception only when it failed requesting the termination.

Signature boolean isTerminatorEnabled()
Description Returns whether the "terminator" which is the feature to terminate scripts, is enabled. Internally, this method checks the value of "TERMINATOR_ENABLED" option (disabled by default) and returns it.
Parameters None
Return None
Exception None
Signature void resetTerminator()
Description Resets the engine which had terminated by terminateScript() method, for processing new scripts.
Parameters None
Return None
Exception VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which isTerminatorEnabled() returns false.
Signature void connectPlugin(String bindingName, Object plugin)
Description Connects various types of plug-ins which provides external functions/variables and so on.
Parameters

bindingName: A name in scripts of the variable/function/namespace provided by the connected plug-in. If the passed argument contains a white space or a character "(", the content after it will be ignored. Also, you can specify "___VNANO_AUTO_KEY" for using a valid value generated automatically.

plugin: The plug-in providing external function/variable and so on. As the type of plug-ins, java.lang.reflect.Field and Method, java.lang.Class and Object, org.vcssl.connect.ExternalVariableConnectorInterface1, ExternalFunctionConnectorInterface1, ExternalNamespaceConnectorInterface1, and PermissionAuthorizerConnectorInterface1 are available.

Return None
Exception VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which isTerminatorEnabled() returns false.
Signature void disconnectAllPlugins()
Description Disconnects all plug-ins.
Parameters None
Return None
Exception VnanoException: Thrown when an exception occurred on the finalization of the plug-in to be disconnected.
Signature void includeLibraryScript(String libraryScriptName, String libraryScriptContent)
Description Add a library script which will be "include"-ed at the head of a executed script.
Parameters

libraryScriptName: Names of the library script (displayed in error messages)

libraryScriptContent: Contents (code) of the library script

Return None
Exception VnanoException: Thrown when incorrect somethings have been detected for the specified library.
Signature void unincludeAllLibraryScripts()
Description Uninclude all library scripts.
Parameters None
Return None
Exception No Exceptions will not be thrown on the current implementation, but it requires to be "catch"-ed for keeping compatibility in future.
Signature void setOptionMap(Map<String,Object> optionMap)
Description

Sets options, by a Map (option map) storing names and values of options you want to set.

Type of the option map is Map<String,Object>, and its keys represents option names. For details, see Option Items section.

Parameters optionMap: The Map (option map) storing names and values of options
Return None
Exception VnanoException: Thrown if invalid option settings is detected.
Signature boolean hasOptionMap()
Description Returns whether getOptionMap() method can return a Map.
Parameters None
Return Returns true if getOptionMap() method can return a Map.
Exception None
Signature Map<String,Object> getOptionMap()
Description Gets the Map (option map) storing names and values of options.
Parameters None
Return The Map (option map) storing names and values of options
Exception VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which hasOptionMap() returns false.
Signature void setPermissionMap(Map<String, String> permissionMap)
Description

Sets permissions, by a Map (permission map) storing names and values of permission items you want to set.

Type of the permission map is Map<String,String>, and its keys represents names of permission items. For details, see Permission Items section.

Parameters permissionMap: The Map (permission map) storing names and values of permission items
Return None
Exception VnanoException: Thrown if invalid permission settings is detected.
Signature boolean hasPermissionMap()
Description Returns whether getPermissionMap() method can return a Map.
Parameters None
Return Returns true if getPermissionMap() method can return a Map.
Exception None
Signature Map<String,String> getPermissionMap()
Description Gets the Map (permission map) storing names and values of permission items.
Parameters None
Return The Map (permission map) storing names and values of permission items.
Exception VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which hasPermissionMap() returns false.
Signature boolean hasPerformanceMap()
Description Returns whether getPerformanceMap() method can return a Map. Internally, this method checks the value of "PERFORMANCE_MONITOR_ENABLED" option (disabled by default) and returns it.
Parameters None
Return Returns true if getPerformanceMap() method can return a Map.
Exception None
Signature Map<String, Object> getPerformanceMap()
Description

Gets the Map (performance map) storing names and values of performance monitoring items.

Note that, when some measured values for some monitoring items don't exist (e.g.: when any scripts are not running, or running but their performance values are not measualable yet), the returned performance map does not contain values for such monitoring items, so sometimes the returned performance map is incomplete (missing values for some items) or empty. Please be careful of the above point when you "get" measured performance values from the returned performance map.

Parameters None
Return The Map (performance map) storing names and values of performance monitoring items
Exception VnanoFatalException (Unchecked Exception): Thrown if this method is called in a state in which hasPerformanceMap() returns false.

Engine Options

The following is the list of all available options of Vnano Engine. The type of names is "String". Also, "Env." in the "Default Value" column means "Environment Dependent".

Name Type of Value Default Value Description
LOCALE java.util.
Locale
Env. The locale to switch the language of error messages.
MAIN_SCRIPT_NAME String "main script" The name of the execution target script.
MAIN_SCRIPT_DIRECTORY String "." The path of the directory (folder) in which the execution target script is locating.
EVAL_INT_LITERAL_AS_FLOAT Boolean FALSE An option to regard integer literals as float type in the execution/evaluation target expressions and scripts (excepting library scripts).
EVAL_ONLY_EXPRESSION Boolean FALSE An option to restrict types of available statements in the execution target scripts (excepting library scripts) to only "expression".
EVAL_ONLY_FLOAT Boolean FALSE An option to restrict available data types of operators/operands in the execution target scripts (excepting library scripts) to only "float".
ACCELERATOR_ENABLED Boolean TRUE An option to enable/disable the Accelerator (org.vcssl.nano.vm.accelerator.Accelerator), which is the high-speed virtual processor implementation in the VM.
ACCELERATOR_OPTIMIZATION_LEVEL Integer 3

An option to control the optimization level of processing in the Accelerator. The value is:

0: Dont't optimize.

1: Optimize data accesses for reducing overhead costs (e.g.: caching operand/operated values).

2: In addition to the above, optimize instructions with keeping code structures (e.g.: join multiple instructions by reordering them).

3: In addition to the above, optimize with modifying code structures (e.g.: inline expansion).

TERMINATOR_ENABLED Boolean FALSE

An option to enable/disable the feature for terminating a running script.

If you enable this option, you become to able to terminate a running script BY OPERATION OF THE SCRIPT ENGINE, but the maximum numerical operating speed (and so on) may decreases slightly. Probably, for most cases, users hardly can recognize the decreasing of the operating speed caused by this option. However, for highly optimized numerical computation scripts, the operating speed may decrease about 10% or more. Note that, the script will be terminated when all procedures in the script completed, or when any errors occurred in the script, or when exit() function is called in the script, regardless whether this option is enabled or disabled.

PERFORMANCE_MONITOR_ENABLED Boolean FALSE

An option to enable/disable the performance monitor.

If you enable this option, you become to get performance monitoring values of the engine, but the maximum numerical operating speed (and so on) may decreases to some extent. Probably, for most cases, decreasing of the operating speed caused by this option is not so heavy. However, for highly optimized numerical computation scripts, the operating speed may decrease about 25% or more.

DUMPER_ENABLED Boolean FALSE An option to dump states and intermediate representations in the compiler, VM, etc.
DUMPER_TARGET String "ALL"

Specify the target of to dump. Values are the followings:

"ALL": Dump all contents.

"INPUTTED_CODE": Dump the inutted script code.

"PREPROCESSED_CODE": Dump pre-processed script code, from which comments are removed.

"TOKEN": Dump tokens, which are output of the LexicalAnalyzer.

"PARSED_AST": Dump the Abstract Syntax Tree (AST), which is the output of the Parser.

"ANALYZED_AST": Dump the semantic-analyzed AST, which is the output of the SemanticAnalyzer.

"ASSEMBLY_CODE": Dump the VRIL code, which is the compilation result, output of the CodeGenerator.

"OBJECT_CODE": Dump the VM object code (unoptimized), which is output of the Assembler.

"ACCELERATOR_CODE": Dump optimized instructions for the Accelerator, which are output of the AcceleratorOptimizationUnit.

"ACCELERATOR_STATE": Dump the internal state (dispatchments of execution units, and so on) of the Accelerator.

DUMPER_STREAM java.io.
PrintStream
System.out Specify the stream to output dumped contents.
RUNNING_ENABLED Boolean TRUE

An option to switch whether execute script or don't.

This option might be useful when you want to dump the compiled result for debugging but don't want to run it.

AUTOMATIC_ACTIVATION_ENABLED Boolean TRUE

An option to switch whether activate/deactivate the Vnano engine automatically before/after executing a script ("automatic activation" feature).

This option is enabled by default so that users can execute scripts any time. However, activations/deactivations of the engine entail some overhead costs. Especially when the engine repetitively executes scripts in high frequency, this "activation costs" may result serious degradation of processing speed, if this option is enabled. In such case, disable this option, and activate/deactivate the engine manually at suitable timing (typically before/after a set of repetitive executions).

UI_MODE String "GUI"

Specify the mode of UI for inputting/outputting values and so on.

As the value, specify "GUI" or "CUI". The default value is "GUI", but it will be set to "CUI" automatically when you execute the Vnano engine in the command-line mode.

This option is referred by I/O plug-ins if they are connected.

ENVIRONMENT_EOL String Env.

Specify the default line-feed code on the environment.

This option is referred by plug-ins providing environment-dependent values, if they are connected.

FILE_IO_EOL String Env.

Specify the default line-feed code for file I/O.

This option is referred by I/O plug-ins if they are connected.

TERMINAL_IO_EOL String Env.

Specify the default line-feed code for terminal I/O.

This option is referred by I/O plug-ins if they are connected.

FILE_IO_ENCODING String "UTF-8"

Specify the name of the default encoding for writing to / reading files in scripts.

This option is referred by I/O plug-ins if they are connected.

STDIN_STREAM Java.io.
InputStream
System.in

Specify the stream for standard input used when the option TERMINAL_IO_UI is set to "CUI".

This option is referred by I/O plug-ins if they are connected.

STDOUT_STREAM Java.io.
PrintStream
System.out

Specify the stream for standard output used when the option TERMINAL_IO_UI is set to "CUI".

This option is referred by I/O plug-ins if they are connected.

STDERR_STREAM Java.io.
PrintStream
System.err

Specify the stream for standard error output when the option TERMINAL_IO_UI is set to "CUI".

This option is referred by I/O plug-ins if they are connected.

Permission Items

The following is the list of permission items. The type of names is "String". The type of values is also "String", and it takes either "DENY", "ALLOW", or "ASK". A permission value "ASK" means that: "determine whether allow or deny by asking the user". By defailt, all values are set to "DENY".

Name Description
PROGRAM_EXIT The permission to exit the currently executed program (script).
PROGRAM_RESET The permission to reset/restart the currently executed program (script).
PROGRAM_CHANGE The permission to change the currently executed program (script).
SYSTEM_PROCESS The permission to execute commands or other programs through the Operating System and so on.
DIRECTORY_CREATE The permission to create a new directory (folder).
DIRECTORY_DELETE The permission to delete a directory (folder).
DIRECTORY_LIST The permission to get the list of files in a directory (folder).
FILE_CREATE The permission to create a new file.
FILE_DELETE The permission to delete a file.
FILE_WRITE The permission to write contents of a file.
FILE_READ The permission to read contents of a file.
FILE_OVERWRITE The permission to overwrite contents of a file.
FILE_INFORMATION_CHANGE The permission to change information (last modified date, and so on) of a file.
ALL The name of the meta item representing all permission items.
NONE The name of the meta item representing no permission item.
DEFAULT

The name of the meta item storing the default permission value.

For permission items of which values are not specified explicitly, a default value (e.g. "DENY") will be set automatically. You can change that default value by setting the value to this meta permission item. For example, if you set the value "ASK" to this permission item "DEFAULT", the script engine will ask to the user when non-specified permissions are required.


Japanese English
Index
[an error occurred while processing this directive]
News From RINEARN
* VCSSL is developed by RINEARN.

Behind the Scenes of Creating an Assistant AI (Part 1: Fundamental Knowledge)
2024-10-07 - The first part of a series on how to create an Assistant AI. In this article, we introduce the essential knowledge you need to grasp before building an Assistant AI. What exactly is an LLM-based AI? What is RAG? And more.

Launching an Assistant AI to Support Software Usage!
2024-09-20 - We've launched an Assistant AI that answers questions about how to use RINEARN software and helps with certain tasks. Anyone with a ChatGPT account can use it for free. We'll explain how to use it.

Software Updates: Command Expansion in RINEARN Graph, and English Support in VCSSL
2024-02-05 - We updated our apps. This updates include "Enhancing the Command-Line Features of RINEARN Graph" and "Adding English Support to VCSSL." Delves into each of them!

Inside the Repetitive Execution Speedup Impremented in Vnano Ver.1.1
2024-01-17 - Delves into the update in Vnano 1.1 from a developer's viewpoint, providing detailed insights into the specific improvements made to the internal structure of the script engine.

Scripting Engine Vnano Ver.1.1 Released: Dramatic Speed Improvement for Repetitive Executions of the Same Content
2023-12-22 - Released the Vnano script engine Ver.1.1. In this version, we've made significant enhancements in processing speed by reducing the overhead of handling requests. Explains the details.

RINEARN Graph 3D Updated and Next Version (Ver.6) Development Has Begun!
2023-09-04 - We have released RINEARN Graph 3D Ver.5.6.34. In addition, we have initiated the development of the next major version, Ver.6! Details inside.

Commitment to Significantly Expand English Documentation with AI Assistance - Presenting a Behind-the-Scenes Look at the Actual Workflow
2023-05-28 - We have decided to expand our English documentation by leveraging AI technologies such as ChatGPT. We will provide a detailed explanation of our initiative.

Update to RINEARN Graph 3D: Enhanced API-related Features and More
2023-05-18 - We recently released the latest version of RINEARN Graph 3D, Ver.5.6.32. Explains the details of this update.

Updated Contents
Circular Wave Animation

Draws the circular wave as 3D animation, under the specified wave parameters.
2022-12-14
Sine Wave Animation

Draws the sine wave as animation, under the specified wave parameters.
2022-11-26
Tool For Converting Units of Angles: Degrees and Radians

A GUI tool for converting the angle in degrees into radians, or radians into degrees.
2022-11-22
Connector Fatal Exception - Specification
The unchecked exception thrown when errors have occurred, caused by incorrect implementations (might be bugs).
2022-09-26
Connector Exception - Specification
The checked exception thrown when errors have occurred, cause by expected normal problems.
2022-09-26