common/fileio

File I/O helpers for the Total Control scripting system.

This module provides two primitives:

• fileBinaryReader(path) — returns the file’s binary content as an array of unsigned bytes
• fileTextReader(path, charset='UTF-8') — returns the file as an array of text lines

Both functions return undefined on failure and set the global error string
(retrievable via lastError()), enabling consistent error handling inside
scripts and test harnesses.

Features

• Binary read: get the full file as an array of numbers (0–255), suitable for checksums,
  protocol building, or low-level assertions.
• Text read: decode using a specified charset (e.g., "UTF-8", "GBK") and receive
  a string[] where each entry corresponds to a line.
• Robust errors: argument validation and IO exceptions are surfaced via setError(...).
• NIO-backed: uses java.nio.file.Files and java.nio.charset.Charset under the hood.

Usage Example

var { fileBinaryReader, fileTextReader } = require("sigma/common/fileio");

// 1) Read a file as raw bytes (unsigned 0–255)
var bytes = fileBinaryReader("E:\\File\\image.bin");
if (bytes !== undefined) {
  print("Byte length: " + bytes.length);
  print("First byte: " + bytes[0]);
} else {
  print("Binary read failed: " + lastError());
}

// 2) Read a UTF-8 text file as lines
var lines = fileTextReader("E:\\File\\readme.txt"); // defaults to UTF-8
if (lines !== undefined) {
  for (let i = 0; i < lines.length; i++) print((i + 1) + ": " + lines[i]);
} else {
  print("Text read failed: " + lastError());
}

// 3) Read a GBK-encoded text file
var linesGbk = fileTextReader("E:\\File\\log_gbk.txt", "GBK");
if (linesGbk === undefined) print("GBK read failed: " + lastError());

Integration

• This module runs on the host PC (not on Android devices) and does not
  attach any methods to Device/DeviceArray.
• It is safe to use in any script context that has access to Java interop.

Functions

// Example: Read a text file in binary format
var ret = fileBinaryReader("E:\\File\\test.txt");

if (ret != 0 && ret !== undefined) {
    print("Congratulations, this API executes successfully.\nReturn value: \n");
    for (let i = 0; i < ret.length; ++i) {
        print(ret[i]);
    }
} else {
    print("Sorry! " + lastError() + "\nReturn value: " + ret);
}

// Operation Result (if file content is "Hello， world！"):
Congratulations, this API executes successfully.
Return value:
72
101
108
108
111
239
188
140
32
119
111
114
108
100
239
188
129

// Example: Read a UTF-8 encoded file
var ret = fileTextReader("E:\\File\\test.txt");
if (ret != 0 && ret !== undefined) {
    print("Congratulations, this API executes successfully.\nReturn value: \n");
    for (let i = 0; i < ret.length; ++i) {
        print(ret[i]);
    }
} else {
    print("Sorry! " + lastError() + "\nReturn value: " + ret);
}

// Operation Result (if file content is "Hello， world！"):
Congratulations, this API executes successfully.
Return value:
Hello， world！