Vnano System Plug-in Group
(org.vcssl.nano.plugin.system package)
Abstract
Plug-ins in this package/subpackages provide basic features available in scripts of the Vnano (VCSSL nano), e.g.: I/O features, utility features, and so on.
Features provided by these plug-ins is a subset of the VCSSL System Library which is a standard library of the VCSSL,
so same features are also available in scripts of the VCSSL by default.
List of Provided Plug-ins and Features
- SystemEnvironmentXnci1Plugin
-
Provides environment-related variables.
Variables: EOL / LF / CR - SystemDataTypeXnci1Plugin
-
Provides data-type-utility functions/variables.
Variables: INT_MAX / INT_MIN / FLOAT_MAX / FLOAT_MIN_ABS_NORMAL / FLOAT_MIN_ABS_DENORMAL / NAN / INF
Functions: nan(value) / inf(value) / length(array, dimIndex) / rank(array) - SystemTerminalIOXnci1Plugin
-
Provides I/O functions from/to the terminal.
Functions: print(...) / println(...) - SystemUserIOXnci1Plugin
-
Provides interactive I/O functions from/to the user.
Functions: popup(message) / alert(message) / confirm(message) / input(message) / input(message, defaultValue) - SystemFileIOXnci1Plugin
-
Provides I/O functions from/to files.
Variables: READ / WRITE / APPEND / READ_CSV / WRITE_CSV / APPEND_CSV / READ_TSV / WRITE_TSV / APPEND_TSV / READ_STSV
Functions: open(fileName, mode) / open(fileName, mode, encoding) / close(fileId) / flush(fileId) / write(fileId, ...) / writeln(fileId, ...) / read(fileId) / readln(fileId) / countln(fileId) / save(filePath, value) / load(filePath) / exists(filePath) / isdir(directoryPath) / listdir(directoryPath) / mkdir(directoryPath) / - SystemTimeXnci1Plugin
-
Provides time-utility functions.
Functions: time() / sleep(sleepTime) - SystemTerminationXnci1Plugin
-
Provides functions for terminating scripts.
Functions: exit() / exit(exitStatusCode) / error(errorMessage) - SystemTestXnci1Plugin
-
Provides utility functions for testing.
Functions: assert(expectedCondition)
License
All of the above plug-ins are released under CC0.
SystemEnvironmentXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemEnvironmentXnci1Plugin)
The plug-in providing environment-related variables.
Variables
| Variable | EOL |
|---|---|
| Value | Storing the end-of-line code depending on environment. |
| Data Type | string (constant) |
| Variable | LF |
|---|---|
| Value | Storing a kind of end-of-line code "LF". |
| Data Type | string (constant) |
| Variable | CR |
|---|---|
| Value | Storing a kind of end-of-line code "CR". |
| Data Type | string (constant) |
SystemDataTypeXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemDataTypeXnci1Plugin)
The plug-in providing data-type-utility functions/variables.
Variables
| Variable | INT_MAX |
|---|---|
| Value | Storing the maximum (positive) value in all representable values of "int" type. |
| Data Type | int (constant) |
| Variable | INT_MIN |
|---|---|
| Value | Storing the minimum (negative) value in all representable values of "int" type. |
| Data Type | int (constant) |
| Variable | FLOAT_MAX |
|---|---|
| Value | Storing the maximum (positive) value in all representable values of "float" type. |
| Data Type | float (constant) |
| Variable | FLOAT_MIN_ABS_NORMAL |
|---|---|
| Value | Storing the minimum absolute (positive, non-zero) value in all representable normal numbers of "float" type. |
| Data Type | float (constant) |
| Variable | FLOAT_MIN_ABS_DENORMAL |
|---|---|
| Value | Storing the minimum absolute (positive, non-zero) value in all representable numbers of "float" type containing denormal numbers. |
| Data Type | float |
| Variable | NAN |
|---|---|
| Value | Storing the value of "NaN". The "NaN" represents the special value as a result of invalid floating-point operations. Also, the NaN does not equal any values containing the NaN itself, so we can not check whether a value is NaN or not by comparing this value by "==" operation. For checking a value is nan or not, use nan(value) function. |
| Data Type | float (constant) |
| Variable | INF |
|---|---|
| Value | Storing the value of the (positive) infinity of "float" type. |
| Data Type | float (constant) |
Functions
| Function | nan(value) |
|---|---|
| Feature | Checks whether the passed value is the NaN or not. Not that the NaN does not equal any values containing the NaN itself, so we can not check whether a value is NaN or not by comparing this value by "==" operation. Therefore, use this function for checking it. |
| Singature | bool nan(float value) |
| Params | (float type) value: The value to be checked. |
| Return | (bool type) "true" if the passed value is the NaN, "false" if it isn't. |
| Example | print( nan(0.0/0.0) ); // true |
| Function | inf(value) |
|---|---|
| Feature | Checks whether the passed value is the (positive or negative) infinity. |
| Singature | bool inf(float value) |
| Params | (float type) value: The value to be checked. |
| Return | (bool type) "true" if the passed value is the (positive or negative) infinity, "false" if it isn't. |
| Example | print( inf(1.0/0.0) ); // true |
| Function | length(array, dimIndex) |
|---|---|
| Feature | Gets the length of the specified dimention as "dimIndex" of the specified array "array". |
| Signature | int length(any array[...], int dimIndex) |
| Params |
(any type, any arrayrank) array: The array you want to get the length of it.
(intŒ^) dimIndex: The index of the array-dimension you want to get the length on it (regarding the most left dimension as 0-th). |
| Return | (int type) The length on the specified dimension of the specified array. |
| Example | int a[10][11][12]; println( length(a,0) ); // 10 println( length(a,1) ); // 11 println( length(a,2) ); // 12 |
| Function | arrayrank(array) |
|---|---|
| Feature | Gets the number of dimensions (array rank) of the specified array. |
| Signature | int arrayrank(any array[...]) |
| Params | (any type, any rank) array: The array you want to get the number of dimensions of it. |
| Return | (int type) The number of dimensions of the specified array. |
| Example | int a[10][11][12]; print( arrayrank(a) ); // 3 |
SystemTerminalIOXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemTerminalIOXnci1Plugin)
The plug-in providing I/O functions from/to the terminal.
When the option "UI_MODE" of the script engine is set to "CUI",
I/O will be performed from/to the standard input/output.
When the option "UI_MODE" of the script engine is set to "GUI",
a window like a terminal will be launched,
and I/O will be performed from/to it.
Functions
| Function | print(...) |
|---|---|
| Feature | Outputs values to the terminal with delimiting by spaces (tabs). |
| Signature | void print(...) |
| Params | (any data-types, any ranks, any numbers) Values to be printed. |
| Return | None |
| Example | print( "Hello", 123, 4.56, true ); // Hello 123, 4.56, true |
| Function | println(...) |
|---|---|
| Feature | Outputs values to the terminal with delimiting by spaces (tabs), and go to the new line on the terminal. |
| Signature | void println(...) |
| Params | (any data-types, any ranks, any numbers) Values to be printed. |
| Return | None |
| Example | println( "Hello", 123, 4.56, true ); // Hello 123, 4.56, true (line feed) |
SystemUserIOXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemUserIOXnci1Plugin)
The plug-in providing interactive I/O functions from/to the user.
When the option "UI_MODE" of the script engine is set to "CUI",
I/O will be performed from/to the standard input/output.
When the option "UI_MODE" of the script engine is set to "GUI",
a pop-up window will be displayed,
and I/O will be performed interactively by user's actions on the window.
Functions
| Function | popup(message) |
|---|---|
| Feature | Displays a message or a value. |
| Signature | void popup(any message) |
| Params | (any type) message: The message or the value to be displayed. |
| Return | None |
| Example | popup( "Hello" ); |
| Function | alert(message) |
|---|---|
| Feature | Displays a message. Compared with "popup" function, the window title, behaviour, and so on are tuned for displaying warning messages. |
| Signature | void alert(string message) |
| Params | (string type) message: The message to be displayed. |
| Return | None |
| Example | alert( "Oops" ); |
| Function | confirm(message) |
|---|---|
| Feature | Displays a confirmation message, and asks for the answer in the form of: Yes (y) or No (n). |
| Signature | bool confirm(string message) |
| Params | (string type) message: The message to be displayed. |
| Return | (bool type) Returns true if the user has answered "Yes" (or inputted "y" on the CUI mode). |
| Example | bool isYes = confirm( "OK?" ); |
| Function | input(message) |
|---|---|
| Feature | Displays a message, and asks for input. |
| Signature | string[] input(string message) |
| Params | (string type) message: The message to be displayed. |
| Return | (string[] type) The inputted value. (The array-length is normally 1, so you can receive it by a scalar variable, if you want.) |
| Example | string inputtedValue[] = input( "Please input" ); |
| Function | input(message) |
|---|---|
| Feature | Displays a message, and asks for input. A default value can be specified by the second argument. |
| Signature | string[] input(string message, any defaultValue) |
| Params |
(string type) message: The message to be displayed.
(any type) defaultValue: The default value. |
| Return | (string[] type) The inputted value. (The array-length is normally 1, so you can receive it by a scalar variable, if you want.) |
| Example | string inputtedValue[] = input( "Please input", "defaultValue" ); |
SystemFileIOXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemFileIOXnci1Plugin)
Provides I/O functions from/to files.
Variables
| Variable | READ |
|---|---|
| Value | The value of "mode" parameter of open function, for reading contents from a texit file. |
| Data Type | string (constant) |
| Variable | WRITE |
|---|---|
| Value | The value of "mode" parameter of open function, for writing contents to a texit file. |
| Data Type | string (constant) |
| Variable | APPEND |
|---|---|
| Value | The value of "mode" parameter of open function, for appending contents a texit file, without deleting the current contents. |
| Data Type | string (constant) |
| Variable | READ_CSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for reading contents from a "numerical CSV" file. In the above, "numerical CSV" means the format that multiple numerical values are described in each line, delimited by commas: ",". Note that, it assumes that values don't contain commas or other special characters, and they are not enclosed by double-quatations. Hence, even if they are contained in values, no special handling will be performed to them. This mode reads the values, by splitting each line by commas simply. |
| Data Type | string (constant) |
| Variable | WRITE_CSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for writing contents to a "numerical CSV" file. In the above, "numerical CSV" means the format that multiple numerical values are described in each line, delimited by commas: ",". Note that, it assumes that values don't contain commas or other special characters, and they are not enclosed by double-quatations. Hence, even if they are contained in values, no special handling will be performed to them. This mode writes the values in a line, by inserting commas between them simply. |
| Data Type | string (constant) |
| Variable | APPEND_CSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for appending contents to a "numerical CSV" file, without deleting the current contents. In the above, "numerical CSV" means the format that multiple numerical values are described in each line, delimited by commas: ",". Note that, it assumes that values don't contain commas or other special characters, and they are not enclosed by double-quatations. Hence, even if they are contained in values, no special handling will be performed to them. This mode writes the values in a line, by inserting commas between them simply. |
| Data Type | string (constant) |
| Variable | READ_TSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for reading contents from a "numerical TSV" file. In the above, "numerical TSV" means the format that multiple numerical values are described in each line, delimited by tab characters (tabs). Note that, it assumes that values don't contain tabs or other special characters, and they are not enclosed by double-quatations. Hence, even if they are contained in values, no special handling will be performed to them. This mode reads the values, by splitting each line by tabs simply. |
| Data Type | string (constant) |
| Variable | WRITE_TSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for writing contents to a "numerical TSV" file. In the above, "numerical TSV" means the format that multiple numerical values are described in each line, delimited by tab characters (tabs). Note that, it assumes that values don't contain tabs or other special characters, and they are not enclosed by double-quatations. Hence, even if they are contained in values, no special handling will be performed to them. This mode writes the values in a line, by inserting tabs between them simply. |
| Data Type | string (constant) |
| Variable | APPEND_TSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for appending contents to a "numerical TSV" file, without deleting the current contents. In the above, "numerical TSV" means the format that multiple numerical values are described in each line, delimited by tab characters (tabs). Note that, it assumes that values don't contain tabs or other special characters, and they are not enclosed by double-quatations. Hence, even if they are contained in values, no special handling will be performed to them. This mode writes the values in a line, by inserting tabs between them simply. |
| Data Type | string (constant) |
| Variable | READ_STSV |
|---|---|
| Value |
The value of "mode" parameter of open function, for reading contents from a numerical "Spaces & Tabs Separated Values" file. In the above, "Spaces & Tabs Separated Values" means the format that multiple numerical values are described in each line, delimited by space or tab characters. Especially, as a delimiter, sometimes multiple consecutive spaces/tabs are used instead of one space/tab, for aligning positions of columns. Note that, the format name "Spaces & Tabs Separated Values" (STSV) is not general. It is the name used only in this document and related docs. However, even though it is not clear what we should call it as, this format is often used in fields in numerical calculations and data analysis. |
| Data Type | string (constant) |
Functions
| Function | open(fileName, mode) |
|---|---|
| Feature | Opens the specified file in the specified mode, and returns the file ID assigned to it. The character encoding will be set to UTF-8 automatically. |
| Signature | int open(string fileName, string mode) |
| Params |
(string type) fileName: The name of the path of the file to be opened.
(string type) mode: The mode representing what kind of I/O will be performed to the file: select from READ, WRITE, and so on. |
| Return |
(int type) The ID assigned to the opened file, necessary to specify when reading/writing contents from/to the opened file.
Note that, this file ID is different from the file ID assigned by OS. This file ID will be assigned in ascending order from 1, for the files opened in a script. (The same file ID may be reused after the file was closed.) |
| Example | int fileId = open("example.txt", READ); |
| Function | open(fileName, mode, encoding) |
|---|---|
| Feature | Opens the specified file in the specified mode and the encoding, and returns the file ID assigned to it. |
| Signature | int open(string fileName, string mode, string encoding) |
| Params |
(string type) fileName: The name of the path of the file to be opened.
(string type) mode: The mode representing what kind of I/O will be performed to the file: select from READ, WRITE, and so on. (string type) encoding: The encoding for reading/writing contents from/to the file (e.g.: "UTF-8", "Shift_JIS", and so on). |
| Return |
(int type) The ID assigned to the opened file, necessary to specify when reading/writing contents from/to the opened file.
Note that, this file ID is different from the file ID assigned by OS. This file ID will be assigned in ascending order from 1, for the files opened in a script. (The same file ID may be reused after the file was closed.) |
| Example | int fileId = open("example.txt", READ, "Shift_JIS"); |
| Function | close(fileId) |
|---|---|
| Feature | Closes the specified file. |
| Signature | void close(int fileId) |
| Params | (int type) fileId: The file ID of the file to be closed. (The file ID is the returned value of open function.) |
| Return | None |
| Example |
int fileId = open("example.txt", READ);
... close(fileId); |
| Function | flush(fileId) |
|---|---|
| Feature | Writes (flushes) the temporary stored contents in the writing-buffer, to the file. In most situation, it is not necessary to flush the buffer explicitly by this function, because the buffer will be flushed automatically when the file will be closed. This function is useful when, for example, your script keeps a file opened for a while, and you want to flush the buffer at the arbitrary timing. |
| Signature | void flush(int fileId) |
| Params | (int type) fileId: The file ID of the file to be flushed. (The file ID is the returned value of open function.) |
| Return | None |
| Example |
int fileId = open("example.txt", WRITE);
... flush(fileId); |
| Function | write(fileId, ...) |
|---|---|
| Feature | Writes the specified value(s) to the specified file. |
| Signature | void write(int fileId, ...) |
| Params |
(int type) fileId: The file ID of the file to which write values. (The file ID is the returned value of open function.)
(any number/type, after the above param) The value(s) to be written. |
| Return | None |
| Example |
int fileId = open("example.txt", WRITE);
... write(fileId, "abc", 123, 4.56, true); |
| Function | writeln(fileId, ...) |
|---|---|
| Feature | Writes the specified value(s) to the specified file, and goes to the next line. |
| Signature | void write(int fileId, ...) |
| Params |
(int type) fileId: The file ID of the file to which you write values. (The file ID is the returned value of open function.)
(any number/type, after the above param) The value(s) to be written. |
| Return | None |
| Example |
int fileId = open("example.txt", WRITE);
... writeln(fileId, "abc", 123, 4.56, true); |
| Function | read(fileId) |
|---|---|
| Feature | Reads all value(s) from the specified file. |
| Signature | string[] read(int fileId) |
| Params | (int type) fileId: The file ID of the file from which you read values. (The file ID is the returned value of open function.) |
| Return | (string[] type) In READ mode, the array of which length is 1, storing all content of the file, will be returned (In this case, you can store it to a scalar variable, by "=" operator simply). In READ_CSV / READ_TSV / READ_STSV modes, an array storing the whole content(s) of the file splitted by the delimiter will be returned. |
| Example |
int fileId = open("example.txt", READ);
... string contentInFile = read(fileId); |
| Function | readln(fileId) |
|---|---|
| Feature | Reads one line from the specified file. |
| Signature | string[] readln(int fileId) |
| Params | (int type) fileId: The file ID of the file from which you read values. (The file ID is the returned value of open function.) |
| Return | (string[] type) In READ mode, the array of which length is 1, storing the content of one line of the file, will be returned (In this case, you can store it to a scalar variable, by "=" operator simply). In READ_CSV / READ_TSV / READ_STSV modes, an array storing the content(s) of one line splitted by the delimiter will be returned. |
| Example |
int fileId = open("example.txt", READ);
... string contentInLine = readln(fileId); ( or ) int fileId = open("example.txt", READ_CSV); ... string valuesInLine[] = readln(fileId); |
| Function | countln(fileId) |
|---|---|
| Feature | Counts up the total number of lines in the specified file. Please note that, this function internally reads all lines from the file, and reopens the file in the same mode. Hence, if you use this function for the file from which some lines were already read, you will get incorrect result, and the reading state (e.g.: pointer to the line to be read next time) for the file will be reset. To prevent the above, use this function only just after opening the file. |
| Signature | int countln(int fileId) |
| Params | (int type) fileId: The file ID of the file of which lines should be counted up. (The file ID is the returned value of open function.) |
| Return | (int type) The total number of lines in the specified file. |
| Example |
int fileId = open("example.txt", READ);
int lineN = countln(fileId); |
| Function | save(filePath, value) |
|---|---|
| Feature | Opens the specified file, and writes the specified value, and closes the file. The character encoding will be set to UTF-8 by default. If "FILE_IO_ENCODING" option exists, the encoding will be set to its value. |
| Signature | void save(string filePath, any value) |
| Params |
(string type) filePath: The name or path of the file to which you write the value.
(any type) value: The value to be written. |
| Return | ‚È‚µ |
| Example | save("example.txt", 123); |
| Function | load(filePath) |
|---|---|
| Feature | Opens the specified file, and reads the whole content, and closes the file. The character encoding for the reading will be set to UTF-8 by default. If "FILE_IO_ENCODING" option exists, the encoding will be set to its value. |
| Signature | string load(string filePath) |
| Params | (string type) filePath: The name or path from which you read the content. |
| Return | (string type) The content read from the file. |
| Example | string content = read("example.txt"); |
| Function | exists(filePath) |
|---|---|
| Feature | Checks whether a file or a directory exists at the specified file path. |
| Signature | bool exists(string filePath) |
| Params | (string type) filePath: The file path to be checked. |
| Return | (bool type) Returns true if a file or a directory exists at the specified file path. |
| Example | bool result = exists("./temp/example.txt"); |
| Function | isdir(directoryPath) |
|---|---|
| Feature | Checks whether the element (file or directory) located at the specified path is a directory. |
| Signature | bool isdir(string directoryPath) |
| Params | (string type) directoryPath: The directory path to be checked. |
| Return | (bool type) Returns true if the element at the specified path is a directory. |
| Example | bool result = isdir("./temp/example_folder"); |
| Function | listdir(directoryPath) |
|---|---|
| Feature | Gets the names of all elements (files and subdirectories) in the specified directory. |
| Signature | string[] listdir(string directoryPath) |
| Params | (string type) directoryPath: The path of the directory of which names of elements should be gotten. |
| Return | (string[] type) The array storing names of the all elements in the specified directory. |
| Example | string elementNames[] = listdir("./temp/example_folder"); |
| Function | mkdir(directoryPath) |
|---|---|
| Feature | Creates the specified directory. Please note that, this function does not create the parent directory automatically, so the parent directory must already exist. If the parent directory does not exist, please create it at first, and then create the (sub)directory. Also, if the specified directory already exist, this function do nothing (does not raise an error). |
| Signature | void mkdir(string directoryPath) |
| Params | (string type) directoryPath: The path of the directory to be created. |
| Return | None |
| Example |
mkdir("./temp");
mkdir("./temp/example_folder"); mkdir("./temp/example_folder/example_folder2"); |
SystemTimeXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemTimeXnci1Plugin)
The plug-in providing time-utility functions
Functions
| Function | time() |
|---|---|
| Feature | Measures the elapsed time from the beginning of the execution of the current script, in the unit of millisecond. |
| Signature | int time() |
| Params | None |
| Return | (int type) The elapsed time from the beginning of the execution of the current script, in the unit of millisecond. |
| Example | int t = time(); print( t ); |
| Function | sleep(sleepTime) |
|---|---|
| Feature | Stops the execution of the script, during the specified time in the unit of millisecond. |
| Singature | void sleep( int sleepTime ) |
| Params | (int type) sleepTime: The time in the unit of millisecond, for which the script to be stopped. |
| Return | None |
| Example | sleep(1000); // Stops 1 second |
SystemTerminationXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemTerminationXnci1Plugin)
The plug-in providing functions for terminating scripts
Functions
| Function | exit() |
|---|---|
| Feature | Terminates the execution of the script without generating errors. |
| Signature | void exit() |
| Parameters | None |
| Return | None |
| Example | exit(); |
| Function | exit(exitStatusCode) |
|---|---|
| Feature | Terminates the execution of the script without generating errors, with specifying the exit status code. |
| Signature | void exit(int exitStatusCode) |
| Params | (int type) exitStatusCode: The exit status code (it is depends on implementations of the script engine and the host application that how it will be handled) |
| Return | None |
| Example | exit(1); |
| Function | error(errorMessage) |
|---|---|
| Feature | Terminates the execution of the script with generating an error having the specified message. |
| Signature | void error(string errorMessage) |
| Parameters | (string type) errorMessage: The content of the error message to be notified to the user of the script. |
| Return | None |
| Example | error( "something is wrong !" ); |
SystemTestXnci1Plugin
(org.vcssl.nano.plugin.system.xnci1.SystemTestXnci1Plugin)
The XNCI1 plug-in providing utility functions for testing.
Functions
| Function | assert(expectedCondition) |
|---|---|
| Feature | Do nothing if the value of the expected condition specified as an argument is "true", and generates an error if it is "false". |
| Signature | void assert( bool expectedCondition ) |
| Params | (bool type) expectedCondition: The value of the expected condition. |
| Return | None |
| Example | int x; x = 1; assert( 0 < x ); // OK x = -1; assert( 0 < x ) ; // Error |
